LIBTTAr_TTA_ENCODE(3)

NAME
libttaR_tta_encode, libttaR_tta_decode - a reentrant TTA codec

SYNOPSIS
#include <libttaR.h>
enum LibTTAr_EncRetVal libttaR_tta_encode(
    uint8_t *restrict dest,
    const int32_t *restrict src,
    struct LibTTAr_CodecState_Priv *restrict priv,
    struct LibTTAr_CodecState_User *restrict user,
    const struct LibTTAr_EncMisc *restrict misc
);
enum LibTTAr_DecRetVal libttaR_tta_decode(
    int32_t *restrict dest,
    const uint8_t *restrict src,
    struct LibTTAr_CodecState_Priv *restrict priv,
    struct LibTTAr_CodecState_User *restrict user,
    const struct LibTTAr_DecMisc *restrict misc
);

DESCRIPTION
libttaR_tta_encode(3) encodes a whole or partial TTA frame. libttaR_tta_decode(3) decodes a whole or partial TTA frame.

  Arguments
*dest
    The destination buffer. Needs to be padded with at least libttaR_ttabuf_safety_margin(3) bytes when encoding.
*src
    The source buffer. Needs to be padded with at least libttaR_ttabuf_safety_margin(3) bytes when decoding. When encoding, the int32_t PCM data must be within the range of an integer that matches misc->samplebytes (8, 16, or 24-bit). See libttaR_pcm_read(3).
*priv
    The codec's private state. The struct is opaque and needs to be allocated and properly aligned (LIBTTAr_CODECSTATE_PRIV_ALIGN) with the size from libttaR_codecstate_priv_size(3).
*user
    The codec's user readable state. Must be initialized with LIBTTAr_CODECSTATE_USER_INIT before the first call for a new frame.
    struct LibTTAr_CodecState_User {
        uint32_t    ncalls_codec;
        uint32_t    crc;
        size_t      ni32;
        size_t      ni32_total;
        size_t      nbytes_tta;
        size_t      nbytes_tta_total;
    };
    ncalls_codec:
        The number of completed calls to the codec function. (OK or FAIL; errors will return before processing data.)
    crc:
        The frame CRC.
    ni32:
        The number of int32_t PCM read/written for the last call.
    ni32_total:
        The total number of int32_t PCM read/written across all calls for the current frame.
    nbytes_tta:
        The number of TTA bytes written/read for the last call.
    nbytes_tta_total:
        The total number of TTA bytes written/read across all calls for the current frame.
*misc
    Other values/properties.
    struct LibTTAr_EncMisc {
        size_t                      dest_len;
        size_t                      src_len;
        size_t                      ni32_target;
        size_t                      ni32_perframe;
        enum LibTTAr_SampleBytes    samplebytes;
        unsigned int                nchan;
    };
    struct LibTTAr_DecMisc {
        size_t                      dest_len;
        size_t                      src_len;
        size_t                      ni32_target;
        size_t                      nbytes_tta_target;
        size_t                      ni32_perframe;
        size_t                      nbytes_tta_perframe;
        enum LibTTAr_SampleBytes    samplebytes;
        unsigned int                nchan;
    };
    dest_len:
        The length of the destination buffer.
    src_len:
        The length of the source buffer.
    ni32_target:
        The target number of int32_t PCM from the src/dest buffer to encode/decode. Must be evenly divisible by misc->nchan.
    nbytes_tta_target:
        The target number of TTA bytes from the src buffer to decode.
    ni32_perframe:
        The total number of uncoded int32_t per TTA frame. See libttaR_nsamples_perframe_tta1(3).
    nbytes_tta_perframe:
        The total number of encoded bytes in the current TTA frame.
    samplebytes:
        The number of bytes per samples in the originally sized PCM.
        enum LibTTAr_SampleBytes {
            LIBTTAr_SAMPLEBYTES_1   = 1u,
            LIBTTAr_SAMPLEBYTES_2   = 2u,
            LIBTTAr_SAMPLEBYTES_3   = 3u
        };
    nchan:
        The number of audio channels in the PCM.

  Warning
*priv, *user, misc->nchan, misc->ni32_perframe, and misc->nbytes_tta_perframe should not be modified between consecutive calls for the same frame, unless you know what you are doing.

RETURN VALUE
enum LibTTAr_EncRetVal {
    LIBTTAr_ERV_OK_DONE         = /* =0 */,
    LIBTTAr_ERV_OK_AGAIN        = /* >0 */,
    LIBTTAr_ERV_FAIL_OVERFLOW   = /* >0 */,
    LIBTTAr_ERV_INVAL_RANGE     = /* <0 */,
    LIBTTAr_ERV_INVAL_TRUNC     = /* <0 */,
    LIBTTAr_ERV_INVAL_BOUNDS    = /* <0 */,
    LIBTTAr_ERV_INVAL_ALIGN     = /* <0 */,
    LIBTTAr_ERV_MISCONFIG       = /* <0 */
};
enum LibTTAr_DecRetVal {
    LIBTTAr_DRV_OK_DONE         = /* =0 */,
    LIBTTAr_DRV_OK_AGAIN        = /* >0 */,
    LIBTTAr_DRV_FAIL_DECODE     = /* >0 */,
    LIBTTAr_DRV_FAIL_OVERFLOW   = /* >0 */,
    LIBTTAr_DRV_INVAL_RANGE     = /* <0 */,
    LIBTTAr_DRV_INVAL_TRUNC     = /* <0 */,
    LIBTTAr_DRV_INVAL_BOUNDS    = /* <0 */,
    LIBTTAr_DRV_INVAL_ALIGN     = /* <0 */,
    LIBTTAr_DRV_MISCONFIG       = /* <0 */
};

Success
    LIBTTAr_ERV_OK_DONE, LIBTTAr_DRV_OK_DONE
        The frame finished coding.
    LIBTTAr_ERV_OK_AGAIN, LIBTTAr_DRV_OK_AGAIN
        The frame did not finish coding. The buffers and misc values should be adjusted for another call.

Failure
    If one of the following is returned, user and priv are likely in a corrupted, unrecoverable state. LIBTTAr_DRV_FAIL_DECODE
        The frame finished decoding, but (user->nbytes_tta_total != misc->nbytes_tta_perframe), or the frame did not finish decoding, but (user->nbytes_tta_total > misc->nbytes_tta_perframe). This would be caused by either corrupted or malformed TTA data. The absense of this value does not guarantee that the data was correctly decoded, only that the "correct" number of bytes was read. There is a check in the rice decoder to stop after reading so many bytes, but it does not return an error, it just stops reading the current code and then continues (for performance reasons). It should be possible to construct an invalid TTA frame (with a good CRC) that could get the decoder to read the "correct" number of bytes.
    LIBTTAr_ERV_FAIL_OVERFLOW, LIBTTAr_DRV_FAIL_OVERFLOW
        An integer value (user size_t) overflowed. It would probably be caused by improperly setting the parameters or state.

Error (<0)
If an error is returned, then no data was processed.
    LIBTTAr_ERV_INVAL_RANGE, LIBTTAr_DRV_INVAL_RANGE
        Some misc value is 0 or a bad enum value. On a (likely) 32-bit system, this could be returned if misc->nchan is too large (libttaR_ttabuf_safety_margin(3) overflow).
    LIBTTAr_ERV_INVAL_TRUNC, LIBTTAr_DRV_INVAL_TRUNC
        The last sample is truncated. (misc->ni32_target % misc->nchan != 0)
    LIBTTAr_ERV_INVAL_BOUNDS, LIBTTAr_DRV_INVAL_BOUNDS
        Some misc value would cause a bounds issue.
    LIBTTAr_ERV_INVAL_ALIGN, LIBTTAr_DRV_INVAL_ALIGN
        A pointer/buffer (priv) is not properly aligned.
    LIBTTAr_ERV_MISCONFIG, LIBTTAr_DRV_MISCONFIG
        The library was misconfigured when built. See libttaR_test_nchan(3).
    The debug build of the library may abort instead of returning an error.

ATTRIBUTES
Both are MT-Safe.

EXAMPLES
Read the following functions in the library source code for usage examples.
    libttaR/src/cli/modes/mode_encode_loop.c :: enc_frame_encode() libttaR/src/cli/modes/mode_decode_loop.c :: dec_frame_decode()

SEE ALSO
libttaR_pcm_read(3), libttaR_pcm_write(3), libttaR_crc32(3), libttaR_misc(3)

AUTHOR
Shane Seelig
    Developer