Setting fine_priority for skipped bands
[opus.git] / libcelt / celt.h
index 6076ce3..fddef5a 100644 (file)
@@ -1,5 +1,7 @@
-/* (C) 2007-2008 Jean-Marc Valin, CSIRO
-   (C) 2008 Gregory Maxwell */
+/* Copyright (c) 2007-2008 CSIRO
+   Copyright (c) 2007-2009 Xiph.Org Foundation
+   Copyright (c) 2008 Gregory Maxwell 
+   Written by Jean-Marc Valin and Gregory Maxwell */
 /**
   @file celt.h
   @brief Contains all the functions for encoding and decoding audio
@@ -51,7 +53,7 @@ extern "C" {
 #define EXPORT
 #endif
 
-#define _celt_check_int(x) (((void)((x) == (celt_int32_t)0)), (celt_int32_t)(x))
+#define _celt_check_int(x) (((void)((x) == (celt_int32)0)), (celt_int32)(x))
 #define _celt_check_mode_ptr_ptr(ptr) ((ptr) + ((ptr) - (CELTMode**)(ptr)))
 
 /* Error codes */
@@ -70,7 +72,7 @@ extern "C" {
 /** An encoder or decoder structure is invalid or already freed */
 #define CELT_INVALID_STATE    -6
 /** Memory allocation has failed */
-#define CELT_ALLOC_FAIL    -6
+#define CELT_ALLOC_FAIL       -7
 
 /* Requests */
 #define CELT_GET_MODE_REQUEST    1
@@ -93,8 +95,15 @@ extern "C" {
 #define CELT_RESET_STATE_REQUEST        8
 #define CELT_RESET_STATE       CELT_RESET_STATE_REQUEST
 
-/** GET the frame size used in the current mode */
-#define CELT_GET_FRAME_SIZE   1000
+#define CELT_SET_VBR_CONSTRAINT_REQUEST 10
+#define CELT_SET_VBR_CONSTRAINT(x)       CELT_SET_VBR_CONSTRAINT_REQUEST, _celt_check_int(x)
+
+#define CELT_SET_START_BAND_REQUEST    10000
+#define CELT_SET_START_BAND(x) CELT_SET_START_BAND_REQUEST, _celt_check_int(x)
+
+#define CELT_SET_END_BAND_REQUEST    10001
+#define CELT_SET_END_BAND(x) CELT_SET_END_BAND_REQUEST, _celt_check_int(x)
+
 /** GET the lookahead used in the current mode */
 #define CELT_GET_LOOKAHEAD    1001
 /** GET the sample rate used in the current mode */
@@ -132,13 +141,12 @@ typedef struct CELTMode CELTMode;
     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 96000 Hz)
- @param channels Number of channels
  @param frame_size Number of samples (per channel) to encode in each 
                    packet (even values; 64 - 512)
  @param error Returned error code (if NULL, no error will be returned)
  @return A newly created mode
 */
-EXPORT CELTMode *celt_mode_create(celt_int32_t Fs, int frame_size, int *error);
+EXPORT CELTMode *celt_mode_create(celt_int32 Fs, int frame_size, int *error);
 
 /** Destroys a mode struct. Only call this after all encoders and 
     decoders using this mode are destroyed as well.
@@ -147,20 +155,25 @@ EXPORT CELTMode *celt_mode_create(celt_int32_t Fs, int frame_size, int *error);
 EXPORT void celt_mode_destroy(CELTMode *mode);
 
 /** Query information from a mode */
-EXPORT int celt_mode_info(const CELTMode *mode, int request, celt_int32_t *value);
+EXPORT int celt_mode_info(const CELTMode *mode, int request, celt_int32 *value);
 
 /* Encoder stuff */
 
+EXPORT int celt_encoder_get_size(const CELTMode *mode, int channels);
 
 /** 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)
+ @param channels Number of channels
+ @param error Returns an error code
  @return Newly created encoder state.
 */
 EXPORT CELTEncoder *celt_encoder_create(const CELTMode *mode, int channels, int *error);
 
+EXPORT CELTEncoder *celt_encoder_init(CELTEncoder *st, const CELTMode *mode, int channels, int *error);
+
 /** Destroys a an encoder state.
  @param st Encoder state to be destroyed
  */
@@ -168,47 +181,39 @@ EXPORT void celt_encoder_destroy(CELTEncoder *st);
 
 /** Encodes a frame of audio.
  @param st Encoder state
- @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 
+ @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.
- *          This may alias pcm. 
+ *          frame_size samples per channel.
  @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". Will be the same as 
+ @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);
+EXPORT int celt_encode_float(CELTEncoder *st, const float *pcm, int frame_size, 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. 
- @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.
- *                         This may alias pcm. 
+ @param pcm PCM audio in signed 16-bit format (native endian). There must be
+ *          exactly frame_size samples per channel.
  @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". Will be the same as 
+ @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);
+EXPORT int celt_encode(CELTEncoder *st, const celt_int16 *pcm, int frame_size, unsigned char *compressed, int nbCompressedBytes);
 
 /** Query and set encoder parameters 
  @param st Encoder state
@@ -220,15 +225,20 @@ EXPORT int celt_encoder_ctl(CELTEncoder * st, int request, ...);
 
 /* Decoder stuff */
 
+EXPORT int celt_decoder_get_size(const CELTMode *mode, int channels);
 
 /** 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)
+ @param channels Number of channels
+ @param error Returns an error code
  @return Newly created decoder state.
  */
 EXPORT CELTDecoder *celt_decoder_create(const CELTMode *mode, int channels, int *error);
 
+EXPORT CELTDecoder *celt_decoder_init(CELTDecoder *st, const CELTMode *mode, int channels, int *error);
+
 /** Destroys a a decoder state.
  @param st Decoder state to be destroyed
  */
@@ -243,7 +253,7 @@ EXPORT void celt_decoder_destroy(CELTDecoder *st);
             returned here in float format. 
  @return Error code.
    */
-EXPORT int celt_decode_float(CELTDecoder *st, const unsigned char *data, int len, float *pcm);
+EXPORT int celt_decode_float(CELTDecoder *st, const unsigned char *data, int len, float *pcm, int frame_size);
 
 /** Decodes a frame of audio.
  @param st Decoder state
@@ -254,7 +264,7 @@ EXPORT int celt_decode_float(CELTDecoder *st, const unsigned char *data, int len
             returned here in 16-bit PCM format (native endian). 
  @return Error code.
  */
-EXPORT int celt_decode(CELTDecoder *st, const unsigned char *data, int len, celt_int16_t *pcm);
+EXPORT int celt_decode(CELTDecoder *st, const unsigned char *data, int len, celt_int16 *pcm, int frame_size);
 
 /** Query and set decoder parameters
    @param st Decoder state
@@ -265,9 +275,13 @@ EXPORT int celt_decode(CELTDecoder *st, const unsigned char *data, int len, celt
 EXPORT int celt_decoder_ctl(CELTDecoder * st, int request, ...);
 
 
-/*  @} */
+/** Returns the English string that corresponds to an error code
+ * @param error Error code (negative for an error, 0 for success
+ * @return Constant string (must NOT be freed)
+ */
+EXPORT const char *celt_strerror(int error);
 
-const char *celt_strerror(int error);
+/*  @} */
 
 
 #ifdef __cplusplus