Add basic {GET,SET}_LSB_DEPTH API tests.
[opus.git] / include / opus_defines.h
index 50ff16c..14d5e5e 100644 (file)
@@ -15,8 +15,8 @@
    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-   A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
-   CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+   A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
+   OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
@@ -39,7 +39,7 @@
 extern "C" {
 #endif
 
-/** @defgroup errorcodes Error codes
+/** @defgroup opus_errorcodes Error codes
  * @{
  */
 /** No error @hideinitializer*/
@@ -65,16 +65,51 @@ extern "C" {
 
 #if defined(__GNUC__) && defined(OPUS_BUILD)
 # define OPUS_EXPORT __attribute__ ((visibility ("default")))
-#elif defined(WIN32)
+#elif defined(WIN32) && !defined(__MINGW32__)
 # ifdef OPUS_BUILD
 #   define OPUS_EXPORT __declspec(dllexport)
 # else
-#   define OPUS_EXPORT __declspec(dllimport)
+#   define OPUS_EXPORT
 # endif
 #else
 # define OPUS_EXPORT
 #endif
 
+# if !defined(OPUS_GNUC_PREREQ)
+#  if defined(__GNUC__)&&defined(__GNUC_MINOR__)
+#   define OPUS_GNUC_PREREQ(_maj,_min) \
+ ((__GNUC__<<16)+__GNUC_MINOR__>=((_maj)<<16)+(_min))
+#  else
+#   define OPUS_GNUC_PREREQ(_maj,_min) 0
+#  endif
+# endif
+
+#if (!defined(__STDC_VERSION__) || (__STDC_VERSION__ < 199901L) )
+# if OPUS_GNUC_PREREQ(3,0)
+#  define OPUS_RESTRICT __restrict__
+# elif (defined(_MSC_VER) && _MSC_VER >= 1400)
+#  define OPUS_RESTRICT __restrict
+# else
+#  define OPUS_RESTRICT
+# endif
+#else
+# define OPUS_RESTRICT restrict
+#endif
+
+/**Warning attributes for opus functions
+  * NONNULL is not used in OPUS_BUILD to avoid the compiler optimizing out
+  * some paranoid null checks. */
+#if defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4)
+# define OPUS_WARN_UNUSED_RESULT __attribute__ ((__warn_unused_result__))
+#else
+# define OPUS_WARN_UNUSED_RESULT
+#endif
+#if !defined(OPUS_BUILD) && defined(__GNUC__) && OPUS_GNUC_PREREQ(3, 4)
+# define OPUS_ARG_NONNULL(_x)  __attribute__ ((__nonnull__(_x)))
+#else
+# define OPUS_ARG_NONNULL(_x)
+#endif
+
 /** These are the actual Encoder CTL ID numbers.
   * They should not be used directly by applications. */
 #define OPUS_SET_APPLICATION_REQUEST         4000
@@ -105,6 +140,10 @@ extern "C" {
 /* #define OPUS_RESET_STATE 4028 */
 #define OPUS_GET_FINAL_RANGE_REQUEST         4031
 #define OPUS_GET_PITCH_REQUEST               4033
+#define OPUS_SET_GAIN_REQUEST                4034
+#define OPUS_GET_GAIN_REQUEST                4045
+#define OPUS_SET_LSB_DEPTH_REQUEST           4036
+#define OPUS_GET_LSB_DEPTH_REQUEST           4037
 
 /* Macros to trigger compilation errors when the wrong types are provided to a CTL */
 #define __opus_check_int(x) (((void)((x) == (opus_int32)0)), (opus_int32)(x))
@@ -112,15 +151,15 @@ extern "C" {
 #define __opus_check_uint_ptr(ptr) ((ptr) + ((ptr) - (opus_uint32*)(ptr)))
 /** @endcond */
 
-/** @defgroup ctlvalues Pre-defined values for CTL interface
-  * @see genericctls,encoderctls
+/** @defgroup opus_ctlvalues Pre-defined values for CTL interface
+  * @see opus_genericctls, opus_encoderctls
   * @{
   */
 /* Values for the various encoder CTLs */
 #define OPUS_AUTO                           -1000 /**<Auto/default setting @hideinitializer*/
 #define OPUS_BITRATE_MAX                       -1 /**<Maximum bitrate @hideinitializer*/
 
-/** Best for "standard" VoIP/videoconference applications where listening quality and intelligibility matter most
+/** Best for most VoIP/videoconference applications where listening quality and intelligibility matter most
  * @hideinitializer */
 #define OPUS_APPLICATION_VOIP                2048
 /** Best for broadcast/high-fidelity application where the decoded audio should be as close as possible to the input
@@ -141,8 +180,27 @@ extern "C" {
 /**@}*/
 
 
-/** @defgroup encoderctls Encoder related CTLs
-  * @see genericctls,opusencoder
+/** @defgroup opus_encoderctls Encoder related CTLs
+  *
+  * These are convenience macros for use with the \c opus_encode_ctl
+  * interface. They are used to generate the appropriate series of
+  * arguments for that call, passing the correct type, size and so
+  * on as expected for each particular request.
+  *
+  * Some usage examples:
+  *
+  * @code
+  * int ret;
+  * ret = opus_encoder_ctl(enc_ctx, OPUS_SET_BANDWIDTH(OPUS_AUTO));
+  * if (ret != OPUS_OK) return ret;
+  *
+  * int rate;
+  * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&rate));
+  *
+  * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE);
+  * @endcode
+  *
+  * @see opus_genericctls, opus_encoder
   * @{
   */
 
@@ -152,7 +210,7 @@ extern "C" {
   * @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
+/** 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)
@@ -166,7 +224,7 @@ extern "C" {
   * @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
+/** 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)
@@ -181,7 +239,7 @@ extern "C" {
   * @param[in] x <tt>int</tt>:   0; 1 (default)
   * @hideinitializer */
 #define OPUS_SET_VBR(x) OPUS_SET_VBR_REQUEST, __opus_check_int(x)
-/** Gets the encoder's VBR configuration, @see OPUS_SET_VBR
+/** 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)
@@ -209,12 +267,18 @@ extern "C" {
   * @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
+/** 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)
 
-/** Configures the encoder's maximum bandpass allowed, @see OPUS_GET_MAX_BANDWIDTH
+/** Configures the maximum bandpass that the encoder will select automatically.
+  * Applications should normally use this instead of \a OPUS_SET_BANDWIDTH
+  * (leaving that set to the default, \c OPUS_AUTO). This allows the
+  * application to set an upper bound based on the type of input it is
+  * providing, but still gives the encoder the freedom to reduce the bandpass
+  * when the bitrate becomes too low, for better overall quality.
+  * @see OPUS_GET_MAX_BANDWIDTH
   * The supported values are:
   *  - OPUS_BANDWIDTH_NARROWBAND     4kHz passband
   *  - OPUS_BANDWIDTH_MEDIUMBAND     6kHz passband
@@ -225,12 +289,18 @@ extern "C" {
   * @hideinitializer */
 #define OPUS_SET_MAX_BANDWIDTH(x) OPUS_SET_MAX_BANDWIDTH_REQUEST, __opus_check_int(x)
 
-/** Gets the encoder's configured maximum bandpass allowed, @see OPUS_SET_MAX_BANDWIDTH
+/** Gets the encoder's configured maximum bandpass allowed. @see OPUS_SET_MAX_BANDWIDTH
   * @param[out] x <tt>int*</tt>: Bandwidth value
   * @hideinitializer */
 #define OPUS_GET_MAX_BANDWIDTH(x) OPUS_GET_MAX_BANDWIDTH_REQUEST, __opus_check_int_ptr(x)
 
-/** Configures the encoder's bandpass, @see OPUS_GET_BANDWIDTH
+/** Sets the encoder's bandpass to a specific value.
+  * This prevents the encoder from automatically selecting the bandpass based
+  * on the available bitrate. If an application knows the bandpass of the input
+  * audio it is providing, it should normally use \a OPUS_SET_MAX_BANDWIDTH
+  * instead, which still gives the encoder the freedom to reduce the bandpass
+  * when the bitrate becomes too low, for better overall quality.
+  * @see OPUS_GET_BANDWIDTH
   * The supported values are:
   *  - OPUS_AUTO (default)
   *  - OPUS_BANDWIDTH_NARROWBAND     4kHz passband
@@ -251,7 +321,7 @@ extern "C" {
   * @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
   * @hideinitializer */
@@ -263,10 +333,12 @@ extern "C" {
   * The supported values are:
   *  - OPUS_APPLICATION_VOIP Process signal for improved speech intelligibility
   *  - OPUS_APPLICATION_AUDIO Favor faithfulness to the original input
+  *  - OPUS_APPLICATION_RESTRICTED_LOWDELAY Configure the minimum possible coding delay
+  *
   * @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
   * @hideinitializer */
@@ -293,7 +365,7 @@ extern "C" {
   * @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
   * @hideinitializer */
@@ -307,7 +379,7 @@ extern "C" {
   * @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.
   * @hideinitializer */
@@ -319,15 +391,44 @@ extern "C" {
   * @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
   * @hideinitializer */
 #define OPUS_GET_DTX(x) OPUS_GET_DTX_REQUEST, __opus_check_int_ptr(x)
 /**@}*/
 
-/** @defgroup genericctls Generic CTLs
-  * @see opus_encoder_ctl,opusencoder,opusdecoder
+/** @defgroup opus_genericctls Generic CTLs
+  *
+  * These macros are used with the \c opus_decoder_ctl and
+  * \c opus_encoder_ctl calls to generate a particular
+  * request.
+  *
+  * When called on an \c OpusDecoder they apply to that
+  * particular decoder instance. When called on an
+  * \c OpusEncoder they apply to the corresponding setting
+  * on that encoder instance, if present.
+  *
+  * Some usage examples:
+  *
+  * @code
+  * int ret;
+  * opus_int32 pitch;
+  * ret = opus_decoder_ctl(dec_ctx, OPUS_GET_PITCH(&pitch));
+  * if (ret == OPUS_OK) return ret;
+  *
+  * opus_encoder_ctl(enc_ctx, OPUS_RESET_STATE);
+  * opus_decoder_ctl(dec_ctx, OPUS_RESET_STATE);
+  *
+  * opus_int32 enc_bw, dec_bw;
+  * opus_encoder_ctl(enc_ctx, OPUS_GET_BANDWIDTH(&enc_bw));
+  * opus_decoder_ctl(dec_ctx, OPUS_GET_BANDWIDTH(&dec_bw));
+  * if (enc_bw != dec_bw) {
+  *   printf("packet bandwidth mismatch!\n");
+  * }
+  * @endcode
+  *
+  * @see opus_encoder, opus_decoder_ctl, opus_encoder_ctl, opus_decoderctls, opus_encoderctls
   * @{
   */
 
@@ -353,19 +454,56 @@ extern "C" {
   * e.g. time stretching/shortening. If the last frame was not voiced, or if the
   * pitch was not coded in the frame, then zero is returned.
   *
+  * This CTL is only implemented for decoder instances.
+  *
   * @param[out] x <tt>opus_int32*</tt>: pitch period at 48 kHz (or 0 if not available)
   *
   * @hideinitializer */
 #define OPUS_GET_PITCH(x) OPUS_GET_PITCH_REQUEST, __opus_check_int_ptr(x)
 
-/** Gets the encoder's configured bandpass or the decoder's last bandpass, @see OPUS_SET_BANDWIDTH
+/** Gets the encoder's configured bandpass or the decoder's last 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)
 
+/** Configures the depth of signal being encoded.
+  * This is a hint which helps the encoder identify silence and near-silence.
+  * The supported values are between 8 and 24 (default)
+  * @param[in] x <tt>opus_int32</tt>:   Input precision
+  * @hideinitializer */
+#define OPUS_SET_LSB_DEPTH(x) OPUS_SET_LSB_DEPTH_REQUEST, __opus_check_int(x)
+/** Gets the encoder's configured signal depth. @see OPUS_SET_LSB_DEPTH
+  *
+  * @param[out] x <tt>opus_int32*</tt>: Input precision
+  * @hideinitializer */
+#define OPUS_GET_LSB_DEPTH(x) OPUS_GET_LSB_DEPTH_REQUEST, __opus_check_int_ptr(x)
+/**@}*/
+
+/** @defgroup opus_decoderctls Decoder related CTLs
+  * @see opus_genericctls, opus_encoderctls, opus_decoder
+  * @{
+  */
+
+/** Configures decoder gain adjustment.
+  * Scales the decoded output by a factor specified in Q8 dB units.
+  * This has a maximum range of -32768 to 32767 inclusive, and returns
+  * OPUS_BAD_ARG otherwise. The default is zero indicating no adjustment.
+  * This setting survives decoder reset.
+  *
+  * gain = pow(10, x/(20.0*256))
+  *
+  * @param[in] x <tt>opus_int32</tt>:   Amount to scale PCM signal by in Q8 dB units.
+  * @hideinitializer */
+#define OPUS_SET_GAIN(x) OPUS_SET_GAIN_REQUEST, __opus_check_int(x)
+/** Gets the decoder's configured gain adjustment. @see OPUS_SET_GAIN
+  *
+  * @param[out] x <tt>opus_int32*</tt>: Amount to scale PCM signal by in Q8 dB units.
+  * @hideinitializer */
+#define OPUS_GET_GAIN(x) OPUS_GET_GAIN_REQUEST, __opus_check_int_ptr(x)
+
 /**@}*/
 
-/** @defgroup libinfo Opus library information functions
+/** @defgroup opus_libinfo Opus library information functions
   * @{
   */