Doxygen...
authorjmvalin <jmvalin@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Fri, 13 Sep 2002 20:08:27 +0000 (20:08 +0000)
committerjmvalin <jmvalin@0101bb08-14d6-0310-b084-bc0e0c8e3800>
Fri, 13 Sep 2002 20:08:27 +0000 (20:08 +0000)
git-svn-id: http://svn.xiph.org/trunk/speex@3909 0101bb08-14d6-0310-b084-bc0e0c8e3800

libspeex/speex.h
libspeex/speex_bits.h
libspeex/speex_header.h

index 2d99d3e..69d6ee7 100644 (file)
@@ -30,52 +30,105 @@ extern "C" {
 #endif
 
 /* Values allowed for *ctl() requests */
-#define SPEEX_SET_ENH 0 /**< Set enhancement on/off (decoder only) */
-#define SPEEX_GET_ENH 1 /**< Get enhancement state (decoder only) */
+
+/** Set enhancement on/off (decoder only) */
+#define SPEEX_SET_ENH 0
+/** Get enhancement state (decoder only) */
+#define SPEEX_GET_ENH 1
+
 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
-#define SPEEX_GET_FRAME_SIZE 3 /**< Obtain frame size used by encoder/decoder */
-#define SPEEX_SET_QUALITY 4 /**< Set quality value */
-#define SPEEX_GET_QUALITY 5 /**< Get current quality setting */
-#define SPEEX_SET_MODE 6 /**< Set sub-mode to use */
-#define SPEEX_GET_MODE 7 /**< Get current sub-mode in use */
-#define SPEEX_SET_LOW_MODE 8 /**< Set low-band sub-mode to use (wideband only)*/
-#define SPEEX_GET_LOW_MODE 9 /**< Get current low-band mode in use (wideband only)*/
+/** Obtain frame size used by encoder/decoder */
+#define SPEEX_GET_FRAME_SIZE 3
+
+/** Set quality value */
+#define SPEEX_SET_QUALITY 4
+/** Get current quality setting */
+#define SPEEX_GET_QUALITY 5
+
+/** Set sub-mode to use */
+#define SPEEX_SET_MODE 6
+/** Get current sub-mode in use */
+#define SPEEX_GET_MODE 7
+
+/** Set low-band sub-mode to use (wideband only)*/
+#define SPEEX_SET_LOW_MODE 8
+/** Get current low-band mode in use (wideband only)*/
+#define SPEEX_GET_LOW_MODE 9
+
+/** Set high-band sub-mode to use (wideband only)*/
 #define SPEEX_SET_HIGH_MODE 10
+/** Get current high-band mode in use (wideband only)*/
 #define SPEEX_GET_HIGH_MODE 11
+
+/** Set VBR on (1) or off (0) */
 #define SPEEX_SET_VBR 12
+/** Get VBR status (1 for on, 0 for off) */
 #define SPEEX_GET_VBR 13
+
+/** Set quality value for VBR encoding (0-10) */
 #define SPEEX_SET_VBR_QUALITY 14
+/** Get current quality value for VBR encoding (0-10) */
 #define SPEEX_GET_VBR_QUALITY 15
+
+/** Set complexity of the encoder (0-10) */
 #define SPEEX_SET_COMPLEXITY 16
+/** Get current complexity of the encoder (0-10) */
 #define SPEEX_GET_COMPLEXITY 17
+
 /*Would be SPEEX_SET_FRAME_SIZE, but it's (currently) invalid*/
+/** Get current bit-rate used by the encoder or decoder */
 #define SPEEX_GET_BITRATE 19
 
 
 /* Preserving compatibility:*/
+/** Equivalent to SPEEX_SET_ENH */
 #define SPEEX_SET_PF 0
+/** Equivalent to SPEEX_GET_ENH */
 #define SPEEX_GET_PF 1
 
 
 /* Values allowed for mode queries */
+/** Query the frame size of a mode */
 #define SPEEX_MODE_FRAME_SIZE 0
+
+/** Query the size of an encoded frame for a particular sub-mode */
 #define SPEEX_SUBMODE_BITS_PER_FRAME 1
 
 
+/** Number of defined modes in Speex */
 #define SPEEX_NB_MODES 2
 
 struct SpeexMode;
 
+
 /* Prototypes for mode function pointers */
+
+/** Encoder state initialization function */
 typedef void *(*encoder_init_func)(struct SpeexMode *mode);
+
+/** Encoder state destruction function */
 typedef void (*encoder_destroy_func)(void *st);
+
+/** Main encoding function */
 typedef void (*encode_func)(void *state, float *in, SpeexBits *bits);
+
+/** Function for controlling the encoder options */
+typedef void (*encoder_ctl_func)(void *state, int request, void *ptr);
+
+/** Decoder state initialization function */
 typedef void *(*decoder_init_func)(struct SpeexMode *mode);
+
+/** Decoder state destruction function */
 typedef void (*decoder_destroy_func)(void *st);
+
+/** Main decoding function */
 typedef int  (*decode_func)(void *state, SpeexBits *bits, float *out);
-typedef void (*encoder_ctl_func)(void *state, int request, void *ptr);
+
+/** Function for controlling the decoder options */
 typedef void (*decoder_ctl_func)(void *state, int request, void *ptr);
 
+
+/** Query function for a mode */
 typedef void (*mode_query_func)(void *mode, int request, void *ptr);
 
 /** Struct defining a Speex mode */ 
@@ -166,7 +219,7 @@ void *speex_decoder_init(SpeexMode *mode);
 
 /** Frees all resources associated to an existing decoder state.
  *
- * @param decoder state to be destroyed
+ * @param state State to be destroyed
  */
 void speex_decoder_destroy(void *state);
 
index 66b6ce6..4fd4fb8 100644 (file)
@@ -27,6 +27,7 @@
 extern "C" {
 #endif
 
+/** Maximum size of the bit-stream (for fixed-size allocation) */
 #define MAX_BYTES_PER_FRAME 1000
 
 /** Bit-packing data structure representing (part of) a bit-stream. */
@@ -50,7 +51,7 @@ void speex_bits_destroy(SpeexBits *bits);
 /** Resets bits to initial value (just after initialization, erasing content)*/
 void speex_bits_reset(SpeexBits *bits);
 
-/** Rewind the bit-stream to beginning (ready for read) without erasing content*/
+/** Rewind the bit-stream to the beginning (ready for read) without erasing the content */
 void speex_bits_rewind(SpeexBits *bits);
 
 /** Initializes the bit-stream from the data in an area of memory */
@@ -66,6 +67,7 @@ void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len);
 /** Write the content of a bit-stream to an area of memory */
 int speex_bits_write(SpeexBits *bits, char *bytes, int max_len);
 
+/** Like speex_bits_write, but writes only the complete bytes in the stream. Also removes the written bytes from the stream */
 int speex_bits_write_whole_bytes(SpeexBits *bits, char *bytes, int max_len);
 
 /** Append bits to the bit-stream
@@ -75,16 +77,44 @@ int speex_bits_write_whole_bytes(SpeexBits *bits, char *bytes, int max_len);
  */
 void speex_bits_pack(SpeexBits *bits, int data, int nbBits);
 
+/** Interpret the next bits in the bit-stream as a signed integer
+ *
+ * @param bits Bit-stream to operate on
+ * @param nbBits Number of bits to interpret
+ * @return A signed integer represented by the bits read
+ */
 int speex_bits_unpack_signed(SpeexBits *bits, int nbBits);
 
+/** Interpret the next bits in the bit-stream as an unsigned integer
+ *
+ * @param bits Bit-stream to operate on
+ * @param nbBits Number of bits to interpret
+ * @return An unsigned integer represented by the bits read
+ */
 unsigned int speex_bits_unpack_unsigned(SpeexBits *bits, int nbBits);
 
+/** Returns the number of bytes in the bit-stream, including the last one even if it is not "full"
+ *
+ * @param bits Bit-stream to operate on
+ * @return Number of bytes in the stream
+ */
 int speex_bits_nbytes(SpeexBits *bits);
 
+/** Same as speex_bits_unpack_unsigned, but without modifying the cursor position */
 unsigned int speex_bits_peek_unsigned(SpeexBits *bits, int nbBits);
 
+/** Get the value of the next bit in the stream, without modifying the
+ * "cursor" position 
+ * 
+ * @param bits Bit-stream to operate on
+ */
 int speex_bits_peek(SpeexBits *bits);
 
+/** Advances the position of the "bit cursor" in the stream 
+ *
+ * @param bits Bit-stream to operate on
+ * @param n Number of bits to advance
+ * */
 void speex_bits_advance(SpeexBits *bits, int n);
 
 #ifdef __cplusplus
index fe09d11..2fd3db6 100644 (file)
@@ -29,8 +29,11 @@ extern "C" {
 #endif
 
 struct SpeexMode;
+
+/** Maximum number of characters for encoding the Speex version number in the header */
 #define SPEEX_HEADER_VERSION_LENGTH 20
 
+/** Current version of the Speex header */
 #define SPEEX_HEADER_VERSION -1
 
 /** Speex header info for file-based formats */