From 29095379a19a1c1ab1759d1ac04e0811b2234a0e Mon Sep 17 00:00:00 2001
From: Gregory Maxwell <greg@xiph.org>
Date: Fri, 9 Sep 2011 14:24:49 -0400
Subject: [PATCH] Documentation updates.
---
doc/draft-ietf-codec-opus.xml | 18 +++--
libcelt/opus_defines.h | 129 +++++++++++++++++-----------------
2 files changed, 72 insertions(+), 75 deletions(-)
diff --git a/doc/draft-ietf-codec-opus.xml b/doc/draft-ietf-codec-opus.xml
index 12676b3a1..65f75fef3 100644
--- a/doc/draft-ietf-codec-opus.xml
+++ b/doc/draft-ietf-codec-opus.xml
@@ -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], fh[k], ft), with
0 <= fl[k] < fh[k] <= ft <= 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
diff --git a/libcelt/opus_defines.h b/libcelt/opus_defines.h
index 839de89d0..3282ac0d8 100644
--- a/libcelt/opus_defines.h
+++ b/libcelt/opus_defines.h
@@ -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);
/**@}*/
--
GitLab