annotate osx/include/opus/opus_projection.h @ 169:223a55898ab9 tip default

Add null config files
author Chris Cannam <cannam@all-day-breakfast.com>
date Mon, 02 Mar 2020 14:03:47 +0000
parents 4664ac0c1032
children
rev   line source
cannam@154 1 /* Copyright (c) 2017 Google Inc.
cannam@154 2 Written by Andrew Allen */
cannam@154 3 /*
cannam@154 4 Redistribution and use in source and binary forms, with or without
cannam@154 5 modification, are permitted provided that the following conditions
cannam@154 6 are met:
cannam@154 7
cannam@154 8 - Redistributions of source code must retain the above copyright
cannam@154 9 notice, this list of conditions and the following disclaimer.
cannam@154 10
cannam@154 11 - Redistributions in binary form must reproduce the above copyright
cannam@154 12 notice, this list of conditions and the following disclaimer in the
cannam@154 13 documentation and/or other materials provided with the distribution.
cannam@154 14
cannam@154 15 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
cannam@154 16 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
cannam@154 17 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
cannam@154 18 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
cannam@154 19 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
cannam@154 20 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
cannam@154 21 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
cannam@154 22 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
cannam@154 23 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
cannam@154 24 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
cannam@154 25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
cannam@154 26 */
cannam@154 27
cannam@154 28 /**
cannam@154 29 * @file opus_projection.h
cannam@154 30 * @brief Opus projection reference API
cannam@154 31 */
cannam@154 32
cannam@154 33 #ifndef OPUS_PROJECTION_H
cannam@154 34 #define OPUS_PROJECTION_H
cannam@154 35
cannam@154 36 #include "opus_multistream.h"
cannam@154 37
cannam@154 38 #ifdef __cplusplus
cannam@154 39 extern "C" {
cannam@154 40 #endif
cannam@154 41
cannam@154 42 /** @cond OPUS_INTERNAL_DOC */
cannam@154 43
cannam@154 44 /** These are the actual encoder and decoder CTL ID numbers.
cannam@154 45 * They should not be used directly by applications.c
cannam@154 46 * In general, SETs should be even and GETs should be odd.*/
cannam@154 47 /**@{*/
cannam@154 48 #define OPUS_PROJECTION_GET_DEMIXING_MATRIX_GAIN_REQUEST 6001
cannam@154 49 #define OPUS_PROJECTION_GET_DEMIXING_MATRIX_SIZE_REQUEST 6003
cannam@154 50 #define OPUS_PROJECTION_GET_DEMIXING_MATRIX_REQUEST 6005
cannam@154 51 /**@}*/
cannam@154 52
cannam@154 53
cannam@154 54 /** @endcond */
cannam@154 55
cannam@154 56 /** @defgroup opus_projection_ctls Projection specific encoder and decoder CTLs
cannam@154 57 *
cannam@154 58 * These are convenience macros that are specific to the
cannam@154 59 * opus_projection_encoder_ctl() and opus_projection_decoder_ctl()
cannam@154 60 * interface.
cannam@154 61 * The CTLs from @ref opus_genericctls, @ref opus_encoderctls,
cannam@154 62 * @ref opus_decoderctls, and @ref opus_multistream_ctls may be applied to a
cannam@154 63 * projection encoder or decoder as well.
cannam@154 64 */
cannam@154 65 /**@{*/
cannam@154 66
cannam@154 67 /** Gets the gain (in dB. S7.8-format) of the demixing matrix from the encoder.
cannam@154 68 * @param[out] x <tt>opus_int32 *</tt>: Returns the gain (in dB. S7.8-format)
cannam@154 69 * of the demixing matrix.
cannam@154 70 * @hideinitializer
cannam@154 71 */
cannam@154 72 #define OPUS_PROJECTION_GET_DEMIXING_MATRIX_GAIN(x) OPUS_PROJECTION_GET_DEMIXING_MATRIX_GAIN_REQUEST, __opus_check_int_ptr(x)
cannam@154 73
cannam@154 74
cannam@154 75 /** Gets the size in bytes of the demixing matrix from the encoder.
cannam@154 76 * @param[out] x <tt>opus_int32 *</tt>: Returns the size in bytes of the
cannam@154 77 * demixing matrix.
cannam@154 78 * @hideinitializer
cannam@154 79 */
cannam@154 80 #define OPUS_PROJECTION_GET_DEMIXING_MATRIX_SIZE(x) OPUS_PROJECTION_GET_DEMIXING_MATRIX_SIZE_REQUEST, __opus_check_int_ptr(x)
cannam@154 81
cannam@154 82
cannam@154 83 /** Copies the demixing matrix to the supplied pointer location.
cannam@154 84 * @param[out] x <tt>unsigned char *</tt>: Returns the demixing matrix to the
cannam@154 85 * supplied pointer location.
cannam@154 86 * @param y <tt>opus_int32</tt>: The size in bytes of the reserved memory at the
cannam@154 87 * pointer location.
cannam@154 88 * @hideinitializer
cannam@154 89 */
cannam@154 90 #define OPUS_PROJECTION_GET_DEMIXING_MATRIX(x,y) OPUS_PROJECTION_GET_DEMIXING_MATRIX_REQUEST, x, __opus_check_int(y)
cannam@154 91
cannam@154 92
cannam@154 93 /**@}*/
cannam@154 94
cannam@154 95 /** Opus projection encoder state.
cannam@154 96 * This contains the complete state of a projection Opus encoder.
cannam@154 97 * It is position independent and can be freely copied.
cannam@154 98 * @see opus_projection_ambisonics_encoder_create
cannam@154 99 */
cannam@154 100 typedef struct OpusProjectionEncoder OpusProjectionEncoder;
cannam@154 101
cannam@154 102
cannam@154 103 /** Opus projection decoder state.
cannam@154 104 * This contains the complete state of a projection Opus decoder.
cannam@154 105 * It is position independent and can be freely copied.
cannam@154 106 * @see opus_projection_decoder_create
cannam@154 107 * @see opus_projection_decoder_init
cannam@154 108 */
cannam@154 109 typedef struct OpusProjectionDecoder OpusProjectionDecoder;
cannam@154 110
cannam@154 111
cannam@154 112 /**\name Projection encoder functions */
cannam@154 113 /**@{*/
cannam@154 114
cannam@154 115 /** Gets the size of an OpusProjectionEncoder structure.
cannam@154 116 * @param channels <tt>int</tt>: The total number of input channels to encode.
cannam@154 117 * This must be no more than 255.
cannam@154 118 * @param mapping_family <tt>int</tt>: The mapping family to use for selecting
cannam@154 119 * the appropriate projection.
cannam@154 120 * @returns The size in bytes on success, or a negative error code
cannam@154 121 * (see @ref opus_errorcodes) on error.
cannam@154 122 */
cannam@154 123 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_projection_ambisonics_encoder_get_size(
cannam@154 124 int channels,
cannam@154 125 int mapping_family
cannam@154 126 );
cannam@154 127
cannam@154 128
cannam@154 129 /** Allocates and initializes a projection encoder state.
cannam@154 130 * Call opus_projection_encoder_destroy() to release
cannam@154 131 * this object when finished.
cannam@154 132 * @param Fs <tt>opus_int32</tt>: Sampling rate of the input signal (in Hz).
cannam@154 133 * This must be one of 8000, 12000, 16000,
cannam@154 134 * 24000, or 48000.
cannam@154 135 * @param channels <tt>int</tt>: Number of channels in the input signal.
cannam@154 136 * This must be at most 255.
cannam@154 137 * It may be greater than the number of
cannam@154 138 * coded channels (<code>streams +
cannam@154 139 * coupled_streams</code>).
cannam@154 140 * @param mapping_family <tt>int</tt>: The mapping family to use for selecting
cannam@154 141 * the appropriate projection.
cannam@154 142 * @param[out] streams <tt>int *</tt>: The total number of streams that will
cannam@154 143 * be encoded from the input.
cannam@154 144 * @param[out] coupled_streams <tt>int *</tt>: Number of coupled (2 channel)
cannam@154 145 * streams that will be encoded from the input.
cannam@154 146 * @param application <tt>int</tt>: The target encoder application.
cannam@154 147 * This must be one of the following:
cannam@154 148 * <dl>
cannam@154 149 * <dt>#OPUS_APPLICATION_VOIP</dt>
cannam@154 150 * <dd>Process signal for improved speech intelligibility.</dd>
cannam@154 151 * <dt>#OPUS_APPLICATION_AUDIO</dt>
cannam@154 152 * <dd>Favor faithfulness to the original input.</dd>
cannam@154 153 * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
cannam@154 154 * <dd>Configure the minimum possible coding delay by disabling certain modes
cannam@154 155 * of operation.</dd>
cannam@154 156 * </dl>
cannam@154 157 * @param[out] error <tt>int *</tt>: Returns #OPUS_OK on success, or an error
cannam@154 158 * code (see @ref opus_errorcodes) on
cannam@154 159 * failure.
cannam@154 160 */
cannam@154 161 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusProjectionEncoder *opus_projection_ambisonics_encoder_create(
cannam@154 162 opus_int32 Fs,
cannam@154 163 int channels,
cannam@154 164 int mapping_family,
cannam@154 165 int *streams,
cannam@154 166 int *coupled_streams,
cannam@154 167 int application,
cannam@154 168 int *error
cannam@154 169 ) OPUS_ARG_NONNULL(4) OPUS_ARG_NONNULL(5);
cannam@154 170
cannam@154 171
cannam@154 172 /** Initialize a previously allocated projection encoder state.
cannam@154 173 * The memory pointed to by \a st must be at least the size returned by
cannam@154 174 * opus_projection_ambisonics_encoder_get_size().
cannam@154 175 * This is intended for applications which use their own allocator instead of
cannam@154 176 * malloc.
cannam@154 177 * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
cannam@154 178 * @see opus_projection_ambisonics_encoder_create
cannam@154 179 * @see opus_projection_ambisonics_encoder_get_size
cannam@154 180 * @param st <tt>OpusProjectionEncoder*</tt>: Projection encoder state to initialize.
cannam@154 181 * @param Fs <tt>opus_int32</tt>: Sampling rate of the input signal (in Hz).
cannam@154 182 * This must be one of 8000, 12000, 16000,
cannam@154 183 * 24000, or 48000.
cannam@154 184 * @param channels <tt>int</tt>: Number of channels in the input signal.
cannam@154 185 * This must be at most 255.
cannam@154 186 * It may be greater than the number of
cannam@154 187 * coded channels (<code>streams +
cannam@154 188 * coupled_streams</code>).
cannam@154 189 * @param streams <tt>int</tt>: The total number of streams to encode from the
cannam@154 190 * input.
cannam@154 191 * This must be no more than the number of channels.
cannam@154 192 * @param coupled_streams <tt>int</tt>: Number of coupled (2 channel) streams
cannam@154 193 * to encode.
cannam@154 194 * This must be no larger than the total
cannam@154 195 * number of streams.
cannam@154 196 * Additionally, The total number of
cannam@154 197 * encoded channels (<code>streams +
cannam@154 198 * coupled_streams</code>) must be no
cannam@154 199 * more than the number of input channels.
cannam@154 200 * @param application <tt>int</tt>: The target encoder application.
cannam@154 201 * This must be one of the following:
cannam@154 202 * <dl>
cannam@154 203 * <dt>#OPUS_APPLICATION_VOIP</dt>
cannam@154 204 * <dd>Process signal for improved speech intelligibility.</dd>
cannam@154 205 * <dt>#OPUS_APPLICATION_AUDIO</dt>
cannam@154 206 * <dd>Favor faithfulness to the original input.</dd>
cannam@154 207 * <dt>#OPUS_APPLICATION_RESTRICTED_LOWDELAY</dt>
cannam@154 208 * <dd>Configure the minimum possible coding delay by disabling certain modes
cannam@154 209 * of operation.</dd>
cannam@154 210 * </dl>
cannam@154 211 * @returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes)
cannam@154 212 * on failure.
cannam@154 213 */
cannam@154 214 OPUS_EXPORT int opus_projection_ambisonics_encoder_init(
cannam@154 215 OpusProjectionEncoder *st,
cannam@154 216 opus_int32 Fs,
cannam@154 217 int channels,
cannam@154 218 int mapping_family,
cannam@154 219 int *streams,
cannam@154 220 int *coupled_streams,
cannam@154 221 int application
cannam@154 222 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(5) OPUS_ARG_NONNULL(6);
cannam@154 223
cannam@154 224
cannam@154 225 /** Encodes a projection Opus frame.
cannam@154 226 * @param st <tt>OpusProjectionEncoder*</tt>: Projection encoder state.
cannam@154 227 * @param[in] pcm <tt>const opus_int16*</tt>: The input signal as interleaved
cannam@154 228 * samples.
cannam@154 229 * This must contain
cannam@154 230 * <code>frame_size*channels</code>
cannam@154 231 * samples.
cannam@154 232 * @param frame_size <tt>int</tt>: Number of samples per channel in the input
cannam@154 233 * signal.
cannam@154 234 * This must be an Opus frame size for the
cannam@154 235 * encoder's sampling rate.
cannam@154 236 * For example, at 48 kHz the permitted values
cannam@154 237 * are 120, 240, 480, 960, 1920, and 2880.
cannam@154 238 * Passing in a duration of less than 10 ms
cannam@154 239 * (480 samples at 48 kHz) will prevent the
cannam@154 240 * encoder from using the LPC or hybrid modes.
cannam@154 241 * @param[out] data <tt>unsigned char*</tt>: Output payload.
cannam@154 242 * This must contain storage for at
cannam@154 243 * least \a max_data_bytes.
cannam@154 244 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
cannam@154 245 * memory for the output
cannam@154 246 * payload. This may be
cannam@154 247 * used to impose an upper limit on
cannam@154 248 * the instant bitrate, but should
cannam@154 249 * not be used as the only bitrate
cannam@154 250 * control. Use #OPUS_SET_BITRATE to
cannam@154 251 * control the bitrate.
cannam@154 252 * @returns The length of the encoded packet (in bytes) on success or a
cannam@154 253 * negative error code (see @ref opus_errorcodes) on failure.
cannam@154 254 */
cannam@154 255 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_projection_encode(
cannam@154 256 OpusProjectionEncoder *st,
cannam@154 257 const opus_int16 *pcm,
cannam@154 258 int frame_size,
cannam@154 259 unsigned char *data,
cannam@154 260 opus_int32 max_data_bytes
cannam@154 261 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
cannam@154 262
cannam@154 263
cannam@154 264 /** Encodes a projection Opus frame from floating point input.
cannam@154 265 * @param st <tt>OpusProjectionEncoder*</tt>: Projection encoder state.
cannam@154 266 * @param[in] pcm <tt>const float*</tt>: The input signal as interleaved
cannam@154 267 * samples with a normal range of
cannam@154 268 * +/-1.0.
cannam@154 269 * Samples with a range beyond +/-1.0
cannam@154 270 * are supported but will be clipped by
cannam@154 271 * decoders using the integer API and
cannam@154 272 * should only be used if it is known
cannam@154 273 * that the far end supports extended
cannam@154 274 * dynamic range.
cannam@154 275 * This must contain
cannam@154 276 * <code>frame_size*channels</code>
cannam@154 277 * samples.
cannam@154 278 * @param frame_size <tt>int</tt>: Number of samples per channel in the input
cannam@154 279 * signal.
cannam@154 280 * This must be an Opus frame size for the
cannam@154 281 * encoder's sampling rate.
cannam@154 282 * For example, at 48 kHz the permitted values
cannam@154 283 * are 120, 240, 480, 960, 1920, and 2880.
cannam@154 284 * Passing in a duration of less than 10 ms
cannam@154 285 * (480 samples at 48 kHz) will prevent the
cannam@154 286 * encoder from using the LPC or hybrid modes.
cannam@154 287 * @param[out] data <tt>unsigned char*</tt>: Output payload.
cannam@154 288 * This must contain storage for at
cannam@154 289 * least \a max_data_bytes.
cannam@154 290 * @param [in] max_data_bytes <tt>opus_int32</tt>: Size of the allocated
cannam@154 291 * memory for the output
cannam@154 292 * payload. This may be
cannam@154 293 * used to impose an upper limit on
cannam@154 294 * the instant bitrate, but should
cannam@154 295 * not be used as the only bitrate
cannam@154 296 * control. Use #OPUS_SET_BITRATE to
cannam@154 297 * control the bitrate.
cannam@154 298 * @returns The length of the encoded packet (in bytes) on success or a
cannam@154 299 * negative error code (see @ref opus_errorcodes) on failure.
cannam@154 300 */
cannam@154 301 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_projection_encode_float(
cannam@154 302 OpusProjectionEncoder *st,
cannam@154 303 const float *pcm,
cannam@154 304 int frame_size,
cannam@154 305 unsigned char *data,
cannam@154 306 opus_int32 max_data_bytes
cannam@154 307 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
cannam@154 308
cannam@154 309
cannam@154 310 /** Frees an <code>OpusProjectionEncoder</code> allocated by
cannam@154 311 * opus_projection_ambisonics_encoder_create().
cannam@154 312 * @param st <tt>OpusProjectionEncoder*</tt>: Projection encoder state to be freed.
cannam@154 313 */
cannam@154 314 OPUS_EXPORT void opus_projection_encoder_destroy(OpusProjectionEncoder *st);
cannam@154 315
cannam@154 316
cannam@154 317 /** Perform a CTL function on a projection Opus encoder.
cannam@154 318 *
cannam@154 319 * Generally the request and subsequent arguments are generated by a
cannam@154 320 * convenience macro.
cannam@154 321 * @param st <tt>OpusProjectionEncoder*</tt>: Projection encoder state.
cannam@154 322 * @param request This and all remaining parameters should be replaced by one
cannam@154 323 * of the convenience macros in @ref opus_genericctls,
cannam@154 324 * @ref opus_encoderctls, @ref opus_multistream_ctls, or
cannam@154 325 * @ref opus_projection_ctls
cannam@154 326 * @see opus_genericctls
cannam@154 327 * @see opus_encoderctls
cannam@154 328 * @see opus_multistream_ctls
cannam@154 329 * @see opus_projection_ctls
cannam@154 330 */
cannam@154 331 OPUS_EXPORT int opus_projection_encoder_ctl(OpusProjectionEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
cannam@154 332
cannam@154 333
cannam@154 334 /**@}*/
cannam@154 335
cannam@154 336 /**\name Projection decoder functions */
cannam@154 337 /**@{*/
cannam@154 338
cannam@154 339 /** Gets the size of an <code>OpusProjectionDecoder</code> structure.
cannam@154 340 * @param channels <tt>int</tt>: The total number of output channels.
cannam@154 341 * This must be no more than 255.
cannam@154 342 * @param streams <tt>int</tt>: The total number of streams coded in the
cannam@154 343 * input.
cannam@154 344 * This must be no more than 255.
cannam@154 345 * @param coupled_streams <tt>int</tt>: Number streams to decode as coupled
cannam@154 346 * (2 channel) streams.
cannam@154 347 * This must be no larger than the total
cannam@154 348 * number of streams.
cannam@154 349 * Additionally, The total number of
cannam@154 350 * coded channels (<code>streams +
cannam@154 351 * coupled_streams</code>) must be no
cannam@154 352 * more than 255.
cannam@154 353 * @returns The size in bytes on success, or a negative error code
cannam@154 354 * (see @ref opus_errorcodes) on error.
cannam@154 355 */
cannam@154 356 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_projection_decoder_get_size(
cannam@154 357 int channels,
cannam@154 358 int streams,
cannam@154 359 int coupled_streams
cannam@154 360 );
cannam@154 361
cannam@154 362
cannam@154 363 /** Allocates and initializes a projection decoder state.
cannam@154 364 * Call opus_projection_decoder_destroy() to release
cannam@154 365 * this object when finished.
cannam@154 366 * @param Fs <tt>opus_int32</tt>: Sampling rate to decode at (in Hz).
cannam@154 367 * This must be one of 8000, 12000, 16000,
cannam@154 368 * 24000, or 48000.
cannam@154 369 * @param channels <tt>int</tt>: Number of channels to output.
cannam@154 370 * This must be at most 255.
cannam@154 371 * It may be different from the number of coded
cannam@154 372 * channels (<code>streams +
cannam@154 373 * coupled_streams</code>).
cannam@154 374 * @param streams <tt>int</tt>: The total number of streams coded in the
cannam@154 375 * input.
cannam@154 376 * This must be no more than 255.
cannam@154 377 * @param coupled_streams <tt>int</tt>: Number of streams to decode as coupled
cannam@154 378 * (2 channel) streams.
cannam@154 379 * This must be no larger than the total
cannam@154 380 * number of streams.
cannam@154 381 * Additionally, The total number of
cannam@154 382 * coded channels (<code>streams +
cannam@154 383 * coupled_streams</code>) must be no
cannam@154 384 * more than 255.
cannam@154 385 * @param[in] demixing_matrix <tt>const unsigned char[demixing_matrix_size]</tt>: Demixing matrix
cannam@154 386 * that mapping from coded channels to output channels,
cannam@154 387 * as described in @ref opus_projection and
cannam@154 388 * @ref opus_projection_ctls.
cannam@154 389 * @param demixing_matrix_size <tt>opus_int32</tt>: The size in bytes of the
cannam@154 390 * demixing matrix, as
cannam@154 391 * described in @ref
cannam@154 392 * opus_projection_ctls.
cannam@154 393 * @param[out] error <tt>int *</tt>: Returns #OPUS_OK on success, or an error
cannam@154 394 * code (see @ref opus_errorcodes) on
cannam@154 395 * failure.
cannam@154 396 */
cannam@154 397 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusProjectionDecoder *opus_projection_decoder_create(
cannam@154 398 opus_int32 Fs,
cannam@154 399 int channels,
cannam@154 400 int streams,
cannam@154 401 int coupled_streams,
cannam@154 402 unsigned char *demixing_matrix,
cannam@154 403 opus_int32 demixing_matrix_size,
cannam@154 404 int *error
cannam@154 405 ) OPUS_ARG_NONNULL(5);
cannam@154 406
cannam@154 407
cannam@154 408 /** Intialize a previously allocated projection decoder state object.
cannam@154 409 * The memory pointed to by \a st must be at least the size returned by
cannam@154 410 * opus_projection_decoder_get_size().
cannam@154 411 * This is intended for applications which use their own allocator instead of
cannam@154 412 * malloc.
cannam@154 413 * To reset a previously initialized state, use the #OPUS_RESET_STATE CTL.
cannam@154 414 * @see opus_projection_decoder_create
cannam@154 415 * @see opus_projection_deocder_get_size
cannam@154 416 * @param st <tt>OpusProjectionDecoder*</tt>: Projection encoder state to initialize.
cannam@154 417 * @param Fs <tt>opus_int32</tt>: Sampling rate to decode at (in Hz).
cannam@154 418 * This must be one of 8000, 12000, 16000,
cannam@154 419 * 24000, or 48000.
cannam@154 420 * @param channels <tt>int</tt>: Number of channels to output.
cannam@154 421 * This must be at most 255.
cannam@154 422 * It may be different from the number of coded
cannam@154 423 * channels (<code>streams +
cannam@154 424 * coupled_streams</code>).
cannam@154 425 * @param streams <tt>int</tt>: The total number of streams coded in the
cannam@154 426 * input.
cannam@154 427 * This must be no more than 255.
cannam@154 428 * @param coupled_streams <tt>int</tt>: Number of streams to decode as coupled
cannam@154 429 * (2 channel) streams.
cannam@154 430 * This must be no larger than the total
cannam@154 431 * number of streams.
cannam@154 432 * Additionally, The total number of
cannam@154 433 * coded channels (<code>streams +
cannam@154 434 * coupled_streams</code>) must be no
cannam@154 435 * more than 255.
cannam@154 436 * @param[in] demixing_matrix <tt>const unsigned char[demixing_matrix_size]</tt>: Demixing matrix
cannam@154 437 * that mapping from coded channels to output channels,
cannam@154 438 * as described in @ref opus_projection and
cannam@154 439 * @ref opus_projection_ctls.
cannam@154 440 * @param demixing_matrix_size <tt>opus_int32</tt>: The size in bytes of the
cannam@154 441 * demixing matrix, as
cannam@154 442 * described in @ref
cannam@154 443 * opus_projection_ctls.
cannam@154 444 * @returns #OPUS_OK on success, or an error code (see @ref opus_errorcodes)
cannam@154 445 * on failure.
cannam@154 446 */
cannam@154 447 OPUS_EXPORT int opus_projection_decoder_init(
cannam@154 448 OpusProjectionDecoder *st,
cannam@154 449 opus_int32 Fs,
cannam@154 450 int channels,
cannam@154 451 int streams,
cannam@154 452 int coupled_streams,
cannam@154 453 unsigned char *demixing_matrix,
cannam@154 454 opus_int32 demixing_matrix_size
cannam@154 455 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
cannam@154 456
cannam@154 457
cannam@154 458 /** Decode a projection Opus packet.
cannam@154 459 * @param st <tt>OpusProjectionDecoder*</tt>: Projection decoder state.
cannam@154 460 * @param[in] data <tt>const unsigned char*</tt>: Input payload.
cannam@154 461 * Use a <code>NULL</code>
cannam@154 462 * pointer to indicate packet
cannam@154 463 * loss.
cannam@154 464 * @param len <tt>opus_int32</tt>: Number of bytes in payload.
cannam@154 465 * @param[out] pcm <tt>opus_int16*</tt>: Output signal, with interleaved
cannam@154 466 * samples.
cannam@154 467 * This must contain room for
cannam@154 468 * <code>frame_size*channels</code>
cannam@154 469 * samples.
cannam@154 470 * @param frame_size <tt>int</tt>: The number of samples per channel of
cannam@154 471 * available space in \a pcm.
cannam@154 472 * If this is less than the maximum packet duration
cannam@154 473 * (120 ms; 5760 for 48kHz), this function will not be capable
cannam@154 474 * of decoding some packets. In the case of PLC (data==NULL)
cannam@154 475 * or FEC (decode_fec=1), then frame_size needs to be exactly
cannam@154 476 * the duration of audio that is missing, otherwise the
cannam@154 477 * decoder will not be in the optimal state to decode the
cannam@154 478 * next incoming packet. For the PLC and FEC cases, frame_size
cannam@154 479 * <b>must</b> be a multiple of 2.5 ms.
cannam@154 480 * @param decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band
cannam@154 481 * forward error correction data be decoded.
cannam@154 482 * If no such data is available, the frame is
cannam@154 483 * decoded as if it were lost.
cannam@154 484 * @returns Number of samples decoded on success or a negative error code
cannam@154 485 * (see @ref opus_errorcodes) on failure.
cannam@154 486 */
cannam@154 487 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_projection_decode(
cannam@154 488 OpusProjectionDecoder *st,
cannam@154 489 const unsigned char *data,
cannam@154 490 opus_int32 len,
cannam@154 491 opus_int16 *pcm,
cannam@154 492 int frame_size,
cannam@154 493 int decode_fec
cannam@154 494 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
cannam@154 495
cannam@154 496
cannam@154 497 /** Decode a projection Opus packet with floating point output.
cannam@154 498 * @param st <tt>OpusProjectionDecoder*</tt>: Projection decoder state.
cannam@154 499 * @param[in] data <tt>const unsigned char*</tt>: Input payload.
cannam@154 500 * Use a <code>NULL</code>
cannam@154 501 * pointer to indicate packet
cannam@154 502 * loss.
cannam@154 503 * @param len <tt>opus_int32</tt>: Number of bytes in payload.
cannam@154 504 * @param[out] pcm <tt>opus_int16*</tt>: Output signal, with interleaved
cannam@154 505 * samples.
cannam@154 506 * This must contain room for
cannam@154 507 * <code>frame_size*channels</code>
cannam@154 508 * samples.
cannam@154 509 * @param frame_size <tt>int</tt>: The number of samples per channel of
cannam@154 510 * available space in \a pcm.
cannam@154 511 * If this is less than the maximum packet duration
cannam@154 512 * (120 ms; 5760 for 48kHz), this function will not be capable
cannam@154 513 * of decoding some packets. In the case of PLC (data==NULL)
cannam@154 514 * or FEC (decode_fec=1), then frame_size needs to be exactly
cannam@154 515 * the duration of audio that is missing, otherwise the
cannam@154 516 * decoder will not be in the optimal state to decode the
cannam@154 517 * next incoming packet. For the PLC and FEC cases, frame_size
cannam@154 518 * <b>must</b> be a multiple of 2.5 ms.
cannam@154 519 * @param decode_fec <tt>int</tt>: Flag (0 or 1) to request that any in-band
cannam@154 520 * forward error correction data be decoded.
cannam@154 521 * If no such data is available, the frame is
cannam@154 522 * decoded as if it were lost.
cannam@154 523 * @returns Number of samples decoded on success or a negative error code
cannam@154 524 * (see @ref opus_errorcodes) on failure.
cannam@154 525 */
cannam@154 526 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_projection_decode_float(
cannam@154 527 OpusProjectionDecoder *st,
cannam@154 528 const unsigned char *data,
cannam@154 529 opus_int32 len,
cannam@154 530 float *pcm,
cannam@154 531 int frame_size,
cannam@154 532 int decode_fec
cannam@154 533 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
cannam@154 534
cannam@154 535
cannam@154 536 /** Perform a CTL function on a projection Opus decoder.
cannam@154 537 *
cannam@154 538 * Generally the request and subsequent arguments are generated by a
cannam@154 539 * convenience macro.
cannam@154 540 * @param st <tt>OpusProjectionDecoder*</tt>: Projection decoder state.
cannam@154 541 * @param request This and all remaining parameters should be replaced by one
cannam@154 542 * of the convenience macros in @ref opus_genericctls,
cannam@154 543 * @ref opus_decoderctls, @ref opus_multistream_ctls, or
cannam@154 544 * @ref opus_projection_ctls.
cannam@154 545 * @see opus_genericctls
cannam@154 546 * @see opus_decoderctls
cannam@154 547 * @see opus_multistream_ctls
cannam@154 548 * @see opus_projection_ctls
cannam@154 549 */
cannam@154 550 OPUS_EXPORT int opus_projection_decoder_ctl(OpusProjectionDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
cannam@154 551
cannam@154 552
cannam@154 553 /** Frees an <code>OpusProjectionDecoder</code> allocated by
cannam@154 554 * opus_projection_decoder_create().
cannam@154 555 * @param st <tt>OpusProjectionDecoder</tt>: Projection decoder state to be freed.
cannam@154 556 */
cannam@154 557 OPUS_EXPORT void opus_projection_decoder_destroy(OpusProjectionDecoder *st);
cannam@154 558
cannam@154 559
cannam@154 560 /**@}*/
cannam@154 561
cannam@154 562 /**@}*/
cannam@154 563
cannam@154 564 #ifdef __cplusplus
cannam@154 565 }
cannam@154 566 #endif
cannam@154 567
cannam@154 568 #endif /* OPUS_PROJECTION_H */