diff options
author | Gregory Maxwell <greg@xiph.org> | 2009-02-17 05:29:15 +0300 |
---|---|---|
committer | Gregory Maxwell <greg@xiph.org> | 2009-02-17 05:29:15 +0300 |
commit | f0d6e319031ceee8300a7f3b37c316011b9cb973 (patch) | |
tree | 980886c98d1218a812f522e2aa8c943ba4ebd1f5 | |
parent | 54547f16d50033d9ab904114e9fad82fe2a02d21 (diff) |
API documentation updates.v0.5.2
-rw-r--r-- | libcelt/celt.h | 47 |
1 files changed, 28 insertions, 19 deletions
diff --git a/libcelt/celt.h b/libcelt/celt.h index 251007b..889e594 100644 --- a/libcelt/celt.h +++ b/libcelt/celt.h @@ -114,8 +114,8 @@ typedef struct CELTMode CELTMode; are destroyed as well. @param Fs Sampling rate (32000 to 96000 Hz) @param channels Number of channels - @param frame_size Number of samples (per channel) to encode in each packet (64 - 512) - @param lookahead Extra latency (in samples per channel) in addition to the frame size (between 32 and frame_size). The larger that value, the better the quality (at the expense of latency) + @param frame_size Number of samples (per channel) to encode in each packet (even values; 64 - 512) + @param lookahead Extra latency (in samples per channel) in addition to the frame size (between 32 and frame_size). @param error Returned error code (if NULL, no error will be returned) @return A newly created mode */ @@ -148,36 +148,44 @@ EXPORT void celt_encoder_destroy(CELTEncoder *st); /** Encodes a frame of audio. @param st Encoder state - @param pcm PCM audio in signed float format. There must be - * exactly frame_size samples per channel. The input data is - * overwritten by a copy of what the remote decoder would decode. + @param pcm PCM audio in float format, with a normal range of ±1.0. + * Samples with a range beyond ±1.0 are supported but will be clipped by + * decoders using the integer API and should only be used if it is known that + * the far end supports extended dynmaic range. There must be exactly + * frame_size samples per channel. @param optional_synthesis If not NULL, the encoder copies the audio signal that * the decoder would decode. It is the same as calling the * decoder on the compressed data, just faster. - @param compressed The compressed data is written here - @param nbCompressedBytes Number of bytes to use for compressing the frame + * This may alias pcm. + @param compressed The compressed data is written here. This may not alias pcm or + * optional_synthesis. + @param nbCompressedBytes Maximum number of bytes to use for compressing the frame * (can change from one frame to another) - @return Number of bytes written to "compressed". Should be the same as - * "nbCompressedBytes" unless the stream is VBR. If negative, an error - * has occurred (see error codes). It is IMPORTANT that the length returned - * be somehow transmitted to the decoder. Otherwise, no decoding is possible. + @return Number of bytes written to "compressed". Will be the same as + * "nbCompressedBytes" unless the stream is VBR and will never be larger. + * If negative, an error has occurred (see error codes). It is IMPORTANT that + * the length returned be somehow transmitted to the decoder. Otherwise, no + * decoding is possible. */ EXPORT int celt_encode_float(CELTEncoder *st, const float *pcm, float *optional_synthesis, unsigned char *compressed, int nbCompressedBytes); + /** Encodes a frame of audio. @param st Encoder state @param pcm PCM audio in signed 16-bit format (native endian). There must be - * exactly frame_size samples per channel. The input data is - * overwritten by a copy of what the remote decoder would decode. + * exactly frame_size samples per channel. @param optional_synthesis If not NULL, the encoder copies the audio signal that * the decoder would decode. It is the same as calling the * decoder on the compressed data, just faster. - @param compressed The compressed data is written here - @param nbCompressedBytes Number of bytes to use for compressing the frame + * This may alias pcm. + @param compressed The compressed data is written here. This may not alias pcm or + * optional_synthesis. + @param nbCompressedBytes Maximum number of bytes to use for compressing the frame * (can change from one frame to another) - @return Number of bytes written to "compressed". Should be the same as - * "nbCompressedBytes" unless the stream is VBR. If negative, an error - * has occurred (see error codes). It is IMPORTANT that the length returned - * be somehow transmitted to the decoder. Otherwise, no decoding is possible. + @return Number of bytes written to "compressed". Will be the same as + * "nbCompressedBytes" unless the stream is VBR and will never be larger. + * If negative, an error has occurred (see error codes). It is IMPORTANT that + * the length returned be somehow transmitted to the decoder. Otherwise, no + * decoding is possible. */ EXPORT int celt_encode(CELTEncoder *st, const celt_int16_t *pcm, celt_int16_t *optional_synthesis, unsigned char *compressed, int nbCompressedBytes); @@ -215,6 +223,7 @@ EXPORT void celt_decoder_destroy(CELTDecoder *st); @return Error code. */ EXPORT int celt_decode_float(CELTDecoder *st, unsigned char *data, int len, float *pcm); + /** Decodes a frame of audio. @param st Decoder state @param data Compressed data produced by an encoder |