From 8c19b030df0bc6195db8f6b60f4908beb6a3ca97 Mon Sep 17 00:00:00 2001 From: Jean-Marc Valin Date: Wed, 20 Feb 2008 15:53:15 +1100 Subject: [PATCH] Changed _new() to _create() in the API. Added some documentation on how to use the API. --- libcelt/celt.c | 4 +- libcelt/celt.h | 119 ++++++++++++++++++++++++++++++++++++--------- libcelt/testcelt.c | 4 +- tools/celtdec.c | 2 +- tools/celtenc.c | 2 +- 5 files changed, 102 insertions(+), 29 deletions(-) diff --git a/libcelt/celt.c b/libcelt/celt.c index 086cfef1..ae7e54c8 100644 --- a/libcelt/celt.c +++ b/libcelt/celt.c @@ -83,7 +83,7 @@ struct CELTEncoder { -CELTEncoder *celt_encoder_new(const CELTMode *mode) +CELTEncoder *celt_encoder_create(const CELTMode *mode) { int i, N, B, C, N4; CELTEncoder *st; @@ -442,7 +442,7 @@ struct CELTDecoder { int last_pitch_index; }; -CELTDecoder *celt_decoder_new(const CELTMode *mode) +CELTDecoder *celt_decoder_create(const CELTMode *mode) { int i, N, B, C, N4; CELTDecoder *st; diff --git a/libcelt/celt.h b/libcelt/celt.h index f655825f..ad29f43e 100644 --- a/libcelt/celt.h +++ b/libcelt/celt.h @@ -38,51 +38,124 @@ extern "C" { #endif +/* Error codes */ #define CELT_OK 0 #define CELT_BAD_ARG -1 #define CELT_INVALID_MODE -2 #define CELT_INTERNAL_ERROR -3 #define CELT_CORRUPTED_DATA -4 +/* Requests */ #define CELT_GET_FRAME_SIZE 1000 #define CELT_GET_LOOKAHEAD 1001 #define CELT_GET_NB_CHANNELS 1002 - + +/** State of the encoder. One encoder state is needed for each stream. It is + initialised once at the beginning of the stream. Do *not* re-initialise + the state for every frame */ typedef struct CELTEncoder CELTEncoder; + +/** State of the decoder. One decoder state is needed for each stream. It is + initialised once at the beginning of the stream. Do *not* re-initialise + the state for every frame */ typedef struct CELTDecoder CELTDecoder; +/** The mode contains all the information necessary to create an encoder. Both + the encoder and decoder need to be initialised with exactly the same mode, + otherwise the quality will be very bad */ typedef struct CELTMode CELTMode; -/*extern const CELTMode *celt_mono; -extern const CELTMode *celt_stereo; -extern const CELTMode *celt_ld51;*/ - +/* To be removed soon */ #define celt_mono celt_mode_create(44100, 1, 256, 128, NULL) #define celt_stereo celt_mode_create(44100, 2, 256, 128, NULL) - -/* Encoder stuff */ -CELTMode *celt_mode_create(int Fs, int channels, int frame_size, int lookahead, int *error); -void celt_mode_destroy(CELTMode *mode); - -CELTEncoder *celt_encoder_new(const CELTMode *mode); - -void celt_encoder_destroy(CELTEncoder *st); - -int celt_encode(CELTEncoder *st, celt_int16_t *pcm, unsigned char *compressed, int nbCompressedBytes); - -/* Decoder stuff */ - -CELTDecoder *celt_decoder_new(const CELTMode *mode); - -void celt_decoder_destroy(CELTDecoder *st); - -int celt_decode(CELTDecoder *st, unsigned char *data, int len, celt_int16_t *pcm); /* Mode calls */ + +/** Creates a new mode struct. This will be passed to an encoder or decoder. + The mode MUST NOT BE DESTROYED until the encoders and decoders that use it + are destroyed as well. + @param Fs Sampling rate (32000 to 64000 Hz) + @param channels Number of channels + @param frame_size Number of samples (per channel) to encode in each packet (64 - 256) + @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 error Returned error code (if NULL, no error will be returned) + @return A newly created mode +*/ +CELTMode *celt_mode_create(int Fs, int channels, int frame_size, int lookahead, int *error); + +/** Destroys a mode struct. Only call this after all encoders and decoders + using this mode are destroyed as well. + @param mode Mode to be destroyed +*/ +void celt_mode_destroy(CELTMode *mode); + +/** Query information from a mode */ int celt_mode_info(const CELTMode *mode, int request, celt_int32_t *value); + + +/* Encoder stuff */ + +/** Creates a new encoder state. Each stream needs its own encoder state (can't + be shared across simultaneous streams). + @param mode Contains all the information about the characteristics of the stream + (must be the same characteristics as used for the decoder) + @return Newly created encoder state. +*/ +CELTEncoder *celt_encoder_create(const CELTMode *mode); + +/** Destroys a an encoder state. + @param mode Encoder state to be destroyed + */ +void celt_encoder_destroy(CELTEncoder *st); + +/** 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. + @param compressed The compressed data is written here + @param nbCompressedBytes 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 occured (see error codes). It is IMPORTANT that the length returned + be somehow transmitted to the decoder. Otherwise, no decoding is possible. +*/ +int celt_encode(CELTEncoder *st, celt_int16_t *pcm, unsigned char *compressed, int nbCompressedBytes); + + + +/* Decoder stuff */ + +/** Creates a new decoder state. Each stream needs its own decoder state (can't + be shared across simultaneous streams). + @param mode Contains all the information about the characteristics of the + stream (must be the same characteristics as used for the encoder) + @return Newly created decoder state. + */ +CELTDecoder *celt_decoder_create(const CELTMode *mode); + +/** Destroys a a decoder state. + @param mode Decoder state to be destroyed + */ +void celt_decoder_destroy(CELTDecoder *st); + +/** Decodes a frame of audio. + @param st Decoder state + @param data Compressed data produced by an encoder + @param len Number of bytes to read from "data". This MUST be exactly the number + of bytes returned by the encoder. Using a larger value WILL NOT WORK. + @param pcm One frame (frame_size samples per channel) of decoded PCM will be + returned here. + @return Error code. + */ +int celt_decode(CELTDecoder *st, unsigned char *data, int len, celt_int16_t *pcm); + + + #ifdef __cplusplus } #endif diff --git a/libcelt/testcelt.c b/libcelt/testcelt.c index f2d779d0..ce1c9591 100644 --- a/libcelt/testcelt.c +++ b/libcelt/testcelt.c @@ -97,8 +97,8 @@ int main(int argc, char *argv[]) } /* Use mode4 for stereo and don't forget to change the value of CHANNEL above */ - enc = celt_encoder_new(mode); - dec = celt_decoder_new(mode); + enc = celt_encoder_create(mode); + dec = celt_decoder_create(mode); celt_mode_info(mode, CELT_GET_FRAME_SIZE, &frame_size); celt_mode_info(mode, CELT_GET_NB_CHANNELS, &channels); diff --git a/tools/celtdec.c b/tools/celtdec.c index 9e991165..95c999ea 100644 --- a/tools/celtdec.c +++ b/tools/celtdec.c @@ -308,7 +308,7 @@ static CELTDecoder *process_header(ogg_packet *op, celt_int32_t enh_enabled, cel return NULL; } - st = celt_decoder_new(mode); + st = celt_decoder_create(mode); if (!st) { fprintf (stderr, "Decoder initialization failed.\n"); diff --git a/tools/celtenc.c b/tools/celtenc.c index cced9592..15898aa9 100644 --- a/tools/celtenc.c +++ b/tools/celtenc.c @@ -476,7 +476,7 @@ int main(int argc, char **argv) header.rate, mode->bitrate, mode->modeName);*/ /*Initialize CELT encoder*/ - st = celt_encoder_new(mode); + st = celt_encoder_create(mode); if (strcmp(outFile,"-")==0) {