From f40285212c1423b056563c1ca0655e6e59a00016 Mon Sep 17 00:00:00 2001
From: Ralph Giles <giles@mozilla.com>
Date: Thu, 22 Mar 2012 13:29:04 -0700
Subject: [PATCH] Improve decoder_create documentation.
The parameter descriptions look like they were copied
from encoder_create. Update them for the decode side
and repeat the clarifications about what sample rates
are allowed and what they mean.
---
include/opus.h | 16 ++++++++++++----
1 file changed, 12 insertions(+), 4 deletions(-)
diff --git a/include/opus.h b/include/opus.h
index bd15b8538..adf7548bf 100644
--- a/include/opus.h
+++ b/include/opus.h
@@ -333,9 +333,17 @@ typedef struct OpusDecoder OpusDecoder;
OPUS_EXPORT int opus_decoder_get_size(int channels);
/** Allocates and initializes a decoder state.
- * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
- * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
+ * @param [in] Fs <tt>opus_int32</tt>: Sample rate to decode at (Hz)
+ * @param [in] channels <tt>int</tt>: Number of channels (1/2) to decode
* @param [out] error <tt>int*</tt>: OPUS_OK Success or @ref errorcodes
+ *
+ * Internally Opus stores data at 48000 Hz, so that should be the default
+ * value for Fs. However, the decoder can efficiently decode to buffers
+ * at 8, 12, 16, and 24 kHz so if for some reason the caller cannot use
+ * data at the full sample rate, or knows the compressed data doesn't
+ * use the full frequency range, it can request decoding at a reduced
+ * rate. Likewise, the decoder is capable of filling in either mono or
+ * interleaved stereo pcm buffers, at the caller's request.
*/
OPUS_EXPORT OpusDecoder *opus_decoder_create(
opus_int32 Fs,
@@ -348,8 +356,8 @@ OPUS_EXPORT OpusDecoder *opus_decoder_create(
* This is intended for applications which use their own allocator instead of malloc. @see opus_decoder_create,opus_decoder_get_size
* To reset a previously initialized state use the OPUS_RESET_STATE CTL.
* @param [in] st <tt>OpusDecoder*</tt>: Decoder state.
- * @param [in] Fs <tt>opus_int32</tt>: Sampling rate of input signal (Hz)
- * @param [in] channels <tt>int</tt>: Number of channels (1/2) in input signal
+ * @param [in] Fs <tt>opus_int32</tt>: Sampling rate to decode to (Hz)
+ * @param [in] channels <tt>int</tt>: Number of channels (1/2) to decode
* @retval OPUS_OK Success or @ref errorcodes
*/
OPUS_EXPORT int opus_decoder_init(
--
GitLab