Documentation updates.
authorGregory Maxwell <greg@xiph.org>
Fri, 9 Sep 2011 18:24:49 +0000 (14:24 -0400)
committerGregory Maxwell <greg@xiph.org>
Fri, 9 Sep 2011 18:24:49 +0000 (14:24 -0400)
doc/draft-ietf-codec-opus.xml
libcelt/opus_defines.h

index 12676b3..65f75fe 100644 (file)
@@ -758,11 +758,11 @@ may be active.
 bit-    +-------+   |  |       |    |conversion|    v
 stream  | Range |---+  +-------+    +----------+  /---\  audio
 ------->|decoder|                                 | + |------>
-        |       |---+  +-------+                  \---/
-        +-------+   |  | CELT  |                    ^
-                    +->|decoder|--------------------+
-                       |       |
-                       +-------+
+        |       |---+               +-------+     \---/
+        +-------+   |               | CELT  |       ^
+                    +-------------->|decoder|-------+
+                                    |       |
+                                    +-------+
 ]]>
 </artwork>
 </figure>
@@ -808,8 +808,6 @@ Raw bits are only used in the CELT layer.
 Each symbol coded by the range coder is drawn from a finite alphabet and coded
  in a separate "context", which describes the size of the alphabet and the
  relative frequency of each symbol in that alphabet.
-Opus only uses static contexts.
-They are not adapted to the statistics of the data as it is coded.
 </t>
 <t>
 Suppose there is a context with n symbols, identified with an index that ranges
@@ -818,8 +816,8 @@ The parameters needed to encode or decode a symbol in this context are
  represented by a three-tuple (fl[k],&nbsp;fh[k],&nbsp;ft), with
  0&nbsp;&lt;=&nbsp;fl[k]&nbsp;&lt;&nbsp;fh[k]&nbsp;&lt;=&nbsp;ft&nbsp;&lt;=&nbsp;65535.
 The values of this tuple are derived from the probability model for the
- symbol, represented by traditional "frequency counts" (although, since Opus
- uses static contexts, these are not updated as symbols are decoded).
+ symbol, represented by traditional "frequency counts". Because Opus
+ uses static contexts these are not updated as symbols are decoded.
 Let f[i] be the frequency of symbol i.
 Then the three-tuple corresponding to symbol k is given by
 </t>
@@ -4160,7 +4158,7 @@ decode the trim value using the inverse CDF {127, 126, 124, 119, 109, 87, 41, 19
 
 <t>For 10 ms and 20 ms frames using short blocks and that have at least LM+2 bits left prior to
 the allocation process, then one anti-collapse bit is reserved in the allocation process so it can
-be decoded later. Following the the anti-collapse reservation, one bit is reserved for skip is available.</t>
+be decoded later. Following the the anti-collapse reservation, one bit is reserved for skip if available.</t>
 
 <t>For stereo frames, bits are reserved for intensity stereo and for dual stereo. Intensity stereo 
 requires ilog2(end-start) bits. Those bits are reserved if there is enough bits left. Following this, one
index 839de89..3282ac0 100644 (file)
@@ -39,7 +39,7 @@
 extern "C" {
 #endif
 
-/** \defgroup errorcodes Error codes
+/** @defgroup errorcodes Error codes
  * @{
  */
 /** No error @hideinitializer*/
@@ -60,7 +60,7 @@ extern "C" {
 #define OPUS_ALLOC_FAIL       -7
 /**@}*/
 
-/** \cond OPUS_INTERNAL_DOC */
+/** @cond OPUS_INTERNAL_DOC */
 /**Export control for opus functions */
 
 #if defined(__GNUC__) && defined(OPUS_BUILD)
@@ -108,14 +108,14 @@ extern "C" {
 #define __opus_check_int(x) (((void)((x) == (opus_int32)0)), (opus_int32)(x))
 #define __opus_check_int_ptr(ptr) ((ptr) + ((ptr) - (opus_int32*)(ptr)))
 #define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr)))
-/** \endcond */
+/** @endcond */
 
-/** \defgroup encoderctls Encoder related CTLs
-  * @see [opus_encoder_ctl]
+/** @defgroup encoderctls Encoder related CTLs
+  * @see opus_encoder_ctl
   * @{
   */
-/** \cond DOXYGEN_EXCLUDE */
-/* Values for the varrious encoder CTLs */
+/** @cond DOXYGEN_EXCLUDE */
+/* Values for the various encoder CTLs */
 #define OPUS_AUTO                           -1000 /**<Auto bitrate @hideinitializer*/
 #define OPUS_BITRATE_MAX                       -1 /**<Maximum bitrate @hideinitializer*/
 
@@ -130,17 +130,17 @@ extern "C" {
 #define OPUS_BANDWIDTH_WIDEBAND              1103 /**< 8kHz bandpass @hideinitializer*/
 #define OPUS_BANDWIDTH_SUPERWIDEBAND         1104 /**<12kHz bandpass @hideinitializer*/
 #define OPUS_BANDWIDTH_FULLBAND              1105 /**<20kHz bandpass @hideinitializer*/
-/** \endcond */
+/** @endcond */
 
 /** Configures the encoder's computational complexity.
   * The supported range is 0-10 inclusive with 10 representing the highest complexity.
   * The default value is inconsistent between modes
   * @todo Complexity is inconsistent between modes
-  * \param[in] x <tt>int</tt>:   0-10, inclusive
+  * @param[in] x <tt>int</tt>:   0-10, inclusive
   * @hideinitializer */
 #define OPUS_SET_COMPLEXITY(x) OPUS_SET_COMPLEXITY_REQUEST, __opus_check_int(x)
-/** Gets the encoder's complexity configuration, @see [OPUS_SET_COMPLEXITY]
-  * \param[out] x <tt>int*</tt>: 0-10, inclusive
+/** Gets the encoder's complexity configuration, @see OPUS_SET_COMPLEXITY
+  * @param[out] x <tt>int*</tt>: 0-10, inclusive
   * @hideinitializer */
 #define OPUS_GET_COMPLEXITY(x) OPUS_GET_COMPLEXITY_REQUEST, __opus_check_int_ptr(x)
 
@@ -150,11 +150,11 @@ extern "C" {
   * The value OPUS_BITRATE_MAX can be used to cause the codec to use as much rate
   * as it can, which is useful for controlling the rate by adjusting the output
   * buffer size.
-  * \param[in] x <tt>opus_int32</tt>:   bitrate in bits per second.
+  * @param[in] x <tt>opus_int32</tt>:   bitrate in bits per second.
   * @hideinitializer */
 #define OPUS_SET_BITRATE(x) OPUS_SET_BITRATE_REQUEST, __opus_check_int(x)
-/** Gets the encoder's bitrate configuration, @see [OPUS_SET_BITRATE]
-  * \param[out] x <tt>opus_int32*</tt>: bitrate in bits per second.
+/** Gets the encoder's bitrate configuration, @see OPUS_SET_BITRATE
+  * @param[out] x <tt>opus_int32*</tt>: bitrate in bits per second.
   * @hideinitializer */
 #define OPUS_GET_BITRATE(x) OPUS_GET_BITRATE_REQUEST, __opus_check_int_ptr(x)
 
@@ -165,11 +165,11 @@ extern "C" {
   * The configured bitrate may not be met exactly because frames must
   * be an integer number of bytes in length.
   * @warning Only the MDCT mode of Opus can provide hard CBR behavior.
-  * \param[in] x <tt>int</tt>:   0 (default); 1
+  * @param[in] x <tt>int</tt>:   0 (default); 1
   * @hideinitializer */
 #define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x)
-/** Gets the encoder's VBR configuration, @see [OPUS_SET_VBR]
-  * \param[out] x <tt>int*</tt>: 0; 1
+/** Gets the encoder's VBR configuration, @see OPUS_SET_VBR
+  * @param[out] x <tt>int*</tt>: 0; 1
   * @hideinitializer */
 #define OPUS_GET_VBR(x) OPUS_GET_VBR_REQUEST, __opus_check_int_ptr(x)
 
@@ -182,22 +182,22 @@ extern "C" {
   *  Speech mode ignores it completely, hybrid mode may fail to obey it
   *  if the LPC layer uses more bitrate than the constraint would have
   *  permitted.
-  * \param[in] x <tt>int</tt>:   0; 1 (default)
+  * @param[in] x <tt>int</tt>:   0; 1 (default)
   * @hideinitializer */
 #define OPUS_SET_VBR_CONSTRAINT(x) OPUS_SET_VBR_CONSTRAINT_REQUEST, __opus_check_int(x)
-/** Gets the encoder's constrained VBR configuration @see [OPUS_SET_VBR_CONSTRAINT]
-  * \param[out] x <tt>int*</tt>: 0; 1
+/** Gets the encoder's constrained VBR configuration @see OPUS_SET_VBR_CONSTRAINT
+  * @param[out] x <tt>int*</tt>: 0; 1
   * @hideinitializer */
 #define OPUS_GET_VBR_CONSTRAINT(x) OPUS_GET_VBR_CONSTRAINT_REQUEST, __opus_check_int_ptr(x)
 
 /** Configures mono/stereo forcing in the encoder.
   * This is useful when the caller knows that the input signal is currently a mono
   * source embedded in a stereo stream.
-  * \param[in] x <tt>int</tt>:   OPUS_AUTO (default); 1 (forced mono); 2 (forced stereo)
+  * @param[in] x <tt>int</tt>:   OPUS_AUTO (default); 1 (forced mono); 2 (forced stereo)
   * @hideinitializer */
 #define OPUS_SET_FORCE_CHANNELS(x) OPUS_SET_FORCE_CHANNELS_REQUEST, __opus_check_int(x)
-/** Gets the encoder's forced channel configuration, @see [OPUS_SET_FORCE_CHANNELS]
-  * \param[out] x <tt>int*</tt>: OPUS_AUTO; 0; 1
+/** Gets the encoder's forced channel configuration, @see OPUS_SET_FORCE_CHANNELS
+  * @param[out] x <tt>int*</tt>: OPUS_AUTO; 0; 1
   * @hideinitializer */
 #define OPUS_GET_FORCE_CHANNELS(x) OPUS_GET_FORCE_CHANNELS_REQUEST, __opus_check_int_ptr(x)
 
@@ -208,12 +208,12 @@ extern "C" {
   *  - OPUS_BANDWIDTH_MEDIUMBAND     6kHz passband
   *  - OPUS_BANDWIDTH_WIDEBAND       8kHz passband
   *  - OPUS_BANDWIDTH_SUPERWIDEBAND 12kHz passband
-  *  - OPUS_BANDWIDTH_FULLBAND      24kHz passband
-  * \param[in] x <tt>int</tt>:   Bandwidth value
+  *  - OPUS_BANDWIDTH_FULLBAND      20kHz passband
+  * @param[in] x <tt>int</tt>:   Bandwidth value
   * @hideinitializer */
 #define OPUS_SET_BANDWIDTH(x) OPUS_SET_BANDWIDTH_REQUEST, __opus_check_int(x)
-/** Gets the encoder's configured bandpass, @see [OPUS_SET_BANDWIDTH]
-  * \param[out] x <tt>int*</tt>: Bandwidth value
+/** Gets the encoder's configured bandpass, @see OPUS_SET_BANDWIDTH
+  * @param[out] x <tt>int*</tt>: Bandwidth value
   * @hideinitializer */
 #define OPUS_GET_BANDWIDTH(x) OPUS_GET_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
 
@@ -223,12 +223,12 @@ extern "C" {
   *  - OPUS_SIGNAL_AUTO (default)
   *  - OPUS_SIGNAL_VOICE
   *  - OPUS_SIGNAL_MUSIC
-  * \param[in] x <tt>int</tt>:   Signal type
+  * @param[in] x <tt>int</tt>:   Signal type
   * @hideinitializer */
 #define OPUS_SET_SIGNAL(x) OPUS_SET_SIGNAL_REQUEST, __opus_check_int(x)
-/** Gets the encoder's configured signal type, @see [OPUS_SET_SIGNAL]
+/** Gets the encoder's configured signal type, @see OPUS_SET_SIGNAL
   *
-  * \param[out] x <tt>int*</tt>: Signal type
+  * @param[out] x <tt>int*</tt>: Signal type
   * @hideinitializer */
 #define OPUS_GET_SIGNAL(x) OPUS_GET_SIGNAL_REQUEST, __opus_check_int_ptr(x)
 
@@ -239,12 +239,12 @@ extern "C" {
   * ultimately expected to bias an automatic signal classifier, but it currently
   * just shifts the static bitrate to mode mapping around a little bit.
   *
-  * \param[in] x <tt>int</tt>:   Voice percentage in the range 0-100, inclusive.
+  * @param[in] x <tt>int</tt>:   Voice percentage in the range 0-100, inclusive.
   * @hideinitializer */
 #define OPUS_SET_VOICE_RATIO(x) OPUS_SET_VOICE_RATIO_REQUEST, __opus_check_int(x)
-/** Gets the encoder's configured voice ratio value, @see [OPUS_SET_VOICE_RATIO]
+/** Gets the encoder's configured voice ratio value, @see OPUS_SET_VOICE_RATIO
   *
-  * \param[out] x <tt>int*</tt>:  Voice percentage in the range 0-100, inclusive.
+  * @param[out] x <tt>int*</tt>:  Voice percentage in the range 0-100, inclusive.
   * @hideinitializer */
 #define OPUS_GET_VOICE_RATIO(x) OPUS_GET_VOICE_RATIO_REQUEST, __opus_check_int_ptr(x)
 
@@ -253,15 +253,26 @@ extern "C" {
   * The supported values are:
   *  - OPUS_APPLICATION_VOIP Process signal for improved speech intelligibility
   *  - OPUS_APPLICATION_AUDIO Favor faithfulness to the original input
-  * \param[in] x <tt>int</tt>:     Application value
+  * @param[in] x <tt>int</tt>:     Application value
   * @hideinitializer */
 #define OPUS_SET_APPLICATION(x) OPUS_SET_APPLICATION_REQUEST, __opus_check_int(x)
-/** Gets the encoder's configured application, @see [OPUS_SET_APPLICATION]
+/** Gets the encoder's configured application, @see OPUS_SET_APPLICATION
   *
-  * \param[out] x <tt>int*</tt>:   Application value
+  * @param[out] x <tt>int*</tt>:   Application value
   * @hideinitializer */
 #define OPUS_GET_APPLICATION(x) OPUS_GET_APPLICATION_REQUEST, __opus_check_int_ptr(x)
 
+/** Configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay.
+  * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
+  * The setting can only be changed right after initialization or after a reset and changes the lookahead.
+  * @param[in] x <tt>int</tt>:   0 (default); 1 (lowdelay)
+  * @hideinitializer */
+#define OPUS_SET_RESTRICTED_LOWDELAY(x) OPUS_SET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int(x)
+/** Gets the encoder's forced channel configuration, @see OPUS_SET_RESTRICTED_LOWDELAY
+  * @param[out] x <tt>int*</tt>: 0; 1
+  * @hideinitializer */
+#define OPUS_GET_RESTRICTED_LOWDELAY(x) OPUS_GET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int_ptr(x)
+
 /** Gets the total samples of delay added by the entire codec.
   * This can be queried by the encoder and then the provided number of samples can be
   * skipped on from the start of the decoder's output to provide time aligned input
@@ -273,19 +284,19 @@ extern "C" {
   * version to version, or even depend on the encoder's initial configuration.
   * Applications needing delay compensation should call this CTL rather than
   * hard-coding a value.
-  * \param[out] x <tt>int*</tt>:   Number of lookahead samples
+  * @param[out] x <tt>int*</tt>:   Number of lookahead samples
   * @hideinitializer */
 #define OPUS_GET_LOOKAHEAD(x) OPUS_GET_LOOKAHEAD_REQUEST, __opus_check_int_ptr(x)
 
 /** Configures the encoder's use of inband forward error correction.
   * @note This is only applicable to the LPC layer
   *
-  * \param[in] x <tt>int</tt>:   FEC flag, 0 (disabled) is default
+  * @param[in] x <tt>int</tt>:   FEC flag, 0 (disabled) is default
   * @hideinitializer */
 #define OPUS_SET_INBAND_FEC(x) OPUS_SET_INBAND_FEC_REQUEST, __opus_check_int(x)
-/** Gets encoder's configured use of inband forward error correction, @see [OPUS_SET_INBAND_FEC]
+/** Gets encoder's configured use of inband forward error correction, @see OPUS_SET_INBAND_FEC
   *
-  * \param[out] x <tt>int*</tt>: FEC flag
+  * @param[out] x <tt>int*</tt>: FEC flag
   * @hideinitializer */
 #define OPUS_GET_INBAND_FEC(x) OPUS_GET_INBAND_FEC_REQUEST, __opus_check_int_ptr(x)
 
@@ -294,30 +305,30 @@ extern "C" {
   * at the expense of quality at a given bitrate in the lossless case, but greater quality
   * under loss.
   *
-  * \param[in] x <tt>int</tt>:   Loss percentage in the range 0-100, inclusive.
+  * @param[in] x <tt>int</tt>:   Loss percentage in the range 0-100, inclusive.
   * @hideinitializer */
 #define OPUS_SET_PACKET_LOSS_PERC(x) OPUS_SET_PACKET_LOSS_PERC_REQUEST, __opus_check_int(x)
-/** Gets the encoder's configured packet loss percentage, @see [OPUS_SET_PACKET_LOSS_PERC]
+/** Gets the encoder's configured packet loss percentage, @see OPUS_SET_PACKET_LOSS_PERC
   *
-  * \param[out] x <tt>int*</tt>: Loss percentage in the range 0-100, inclusive.
+  * @param[out] x <tt>int*</tt>: Loss percentage in the range 0-100, inclusive.
   * @hideinitializer */
 #define OPUS_GET_PACKET_LOSS_PERC(x) OPUS_GET_PACKET_LOSS_PERC_REQUEST, __opus_check_int_ptr(x)
 
 /** Configures the encoder's use of discontinuous transmission.
   * @note This is only applicable to the LPC layer
   *
-  * \param[in] x <tt>int</tt>:   DTX flag, 0 (disabled) is default
+  * @param[in] x <tt>int</tt>:   DTX flag, 0 (disabled) is default
   * @hideinitializer */
 #define OPUS_SET_DTX(x) OPUS_SET_DTX_REQUEST, __opus_check_int(x)
-/** Gets encoder's configured use of discontinuous transmission, @see [OPUS_SET_DTX]
+/** Gets encoder's configured use of discontinuous transmission, @see OPUS_SET_DTX
   *
-  * \param[out] x <tt>int*</tt>:  DTX flag
+  * @param[out] x <tt>int*</tt>:  DTX flag
   * @hideinitializer */
 #define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x)
 /**@}*/
 
-/** \defgroup genericctls Generic CTLs
-  * @see [opus_encoder_ctl,opus_decoder_ctl]
+/** @defgroup genericctls Generic CTLs
+  * @see opus_encoder_ctl,opus_decoder_ctl
   * @{
   */
 
@@ -333,39 +344,27 @@ extern "C" {
   * The encoder and decoder state should be identical after coding a payload
   * (assuming no data corruption or software bugs)
   *
-  * \param[out] x <tt>opus_int32*</tt>: Entropy coder state
+  * @param[out] x <tt>opus_int32*</tt>: Entropy coder state
   *
   * @hideinitializer */
 #define OPUS_GET_FINAL_RANGE(x) OPUS_GET_FINAL_RANGE_REQUEST, __opus_check_uint_ptr(x)
 
-/** Configures low-delay mode that disables the speech-optimized mode in exchange for slightly reduced delay.
-  * This is useful when the caller knows that the speech-optimized modes will not be needed (use with caution).
-  * The setting can only be changed right after initialization or after a reset.
-  * \param[in] x <tt>int</tt>:   0 (default); 1 (lowdelay)
-  * @hideinitializer */
-#define OPUS_SET_RESTRICTED_LOWDELAY(x) OPUS_SET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int(x)
-/** Gets the encoder's forced channel configuration, @see [OPUS_SET_RESTRICTED_LOWDELAY]
-  * \param[out] x <tt>int*</tt>: 0; 1
-  * @hideinitializer */
-#define OPUS_GET_RESTRICTED_LOWDELAY(x) OPUS_GET_RESTRICTED_LOWDELAY_REQUEST, __opus_check_int_ptr(x)
-
-
 /**@}*/
 
-/** \defgroup libinfo Opus library information functions
+/** @defgroup libinfo Opus library information functions
   * @{
   */
 
 /** Converts an opus error code into a human readable string.
   *
-  * \param[in] error <tt>int</tt>: Error number
-  * \retval Error string
+  * @param[in] error <tt>int</tt>: Error number
+  * @retval Error string
   */
 OPUS_EXPORT const char *opus_strerror(int error);
 
 /** Gets the libopus version string.
   *
-  * \retval Version string
+  * @retval Version string
   */
 OPUS_EXPORT const char *opus_get_version_string(void);
 /**@}*/