Include the doc dir in DIST_SUBDIRS instead of EXTRA_DIST
[opus.git] / include / opus_multistream.h
1 /* Copyright (c) 2011 Xiph.Org Foundation
2    Written by Jean-Marc Valin */
3 /*
4    Redistribution and use in source and binary forms, with or without
5    modification, are permitted provided that the following conditions
6    are met:
7
8    - Redistributions of source code must retain the above copyright
9    notice, this list of conditions and the following disclaimer.
10
11    - Redistributions in binary form must reproduce the above copyright
12    notice, this list of conditions and the following disclaimer in the
13    documentation and/or other materials provided with the distribution.
14
15    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
17    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
18    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
19    OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
22    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
23    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
24    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
27
28 /**
29  * @file opus_multistream.h
30  * @brief Opus reference implementation multistream API
31  */
32
33 #ifndef OPUS_MULTISTREAM_H
34 #define OPUS_MULTISTREAM_H
35
36 #include "opus.h"
37
38 #ifdef __cplusplus
39 extern "C" {
40 #endif
41
42 typedef struct OpusMSEncoder OpusMSEncoder;
43 typedef struct OpusMSDecoder OpusMSDecoder;
44
45 #define __opus_check_encstate_ptr(ptr) ((ptr) + ((ptr) - (OpusEncoder**)(ptr)))
46 #define __opus_check_decstate_ptr(ptr) ((ptr) + ((ptr) - (OpusDecoder**)(ptr)))
47
48 #define OPUS_MULTISTREAM_GET_ENCODER_STATE_REQUEST 5120
49 #define OPUS_MULTISTREAM_GET_DECODER_STATE_REQUEST 5122
50
51 #define OPUS_MULTISTREAM_GET_ENCODER_STATE(x,y) OPUS_MULTISTREAM_GET_ENCODER_STATE_REQUEST, __opus_check_int(x), __opus_check_encstate_ptr(y)
52 #define OPUS_MULTISTREAM_GET_DECODER_STATE(x,y) OPUS_MULTISTREAM_GET_DECODER_STATE_REQUEST, __opus_check_int(x), __opus_check_decstate_ptr(y)
53
54 /** Allocate and initialize a multistream encoder state object.
55  *  Call opus_multistream_encoder_destroy() to release
56  *  this object when finished. */
57 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSEncoder *opus_multistream_encoder_create(
58       opus_int32 Fs,            /**< Sampling rate of input signal (Hz) */
59       int channels,             /**< Number of channels in the input signal */
60       int streams,              /**< Total number of streams to encode from the input */
61       int coupled_streams,      /**< Number of coupled (stereo) streams to encode */
62       const unsigned char *mapping, /**< Encoded mapping between channels and streams */
63       int application,          /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
64       int *error                /**< Error code */
65 ) OPUS_ARG_NONNULL(5);
66
67 /** Initialize an already allocated multistream encoder state. */
68 OPUS_EXPORT int opus_multistream_encoder_init(
69       OpusMSEncoder *st,        /**< Encoder state */
70       opus_int32 Fs,            /**< Sampling rate of input signal (Hz) */
71       int channels,             /**< Number of channels in the input signal */
72       int streams,              /**< Total number of streams to encode from the input */
73       int coupled_streams,      /**< Number of coupled (stereo) streams to encode */
74       const unsigned char *mapping, /**< Encoded mapping between channels and streams */
75       int application           /**< Coding mode (OPUS_APPLICATION_VOIP/OPUS_APPLICATION_AUDIO) */
76 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
77
78 /** Returns length of the data payload (in bytes) or a negative error code */
79 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode(
80     OpusMSEncoder *st,          /**< Encoder state */
81     const opus_int16 *pcm,      /**< Input signal as interleaved samples. Length is frame_size*channels */
82     int frame_size,             /**< Number of samples per frame of input signal */
83     unsigned char *data,        /**< Output buffer for the compressed payload (no more than max_data_bytes long) */
84     opus_int32 max_data_bytes   /**< Allocated memory for payload; don't use for controlling bitrate */
85 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
86
87 /** Returns length of the data payload (in bytes) or a negative error code. */
88 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_encode_float(
89       OpusMSEncoder *st,        /**< Encoder state */
90       const float *pcm,         /**< Input signal interleaved in channel order. length is frame_size*channels */
91       int frame_size,           /**< Number of samples per frame of input signal */
92       unsigned char *data,      /**< Output buffer for the compressed payload (no more than max_data_bytes long) */
93       opus_int32 max_data_bytes /**< Allocated memory for payload; don't use for controlling bitrate */
94 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(2) OPUS_ARG_NONNULL(4);
95
96 /** Gets the size of an OpusMSEncoder structure.
97   * @returns size
98   */
99 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_encoder_get_size(
100       int streams,              /**< Total number of coded streams */
101       int coupled_streams       /**< Number of coupled (stereo) streams */
102 );
103
104 /** Deallocate a multstream encoder state */
105 OPUS_EXPORT void opus_multistream_encoder_destroy(OpusMSEncoder *st);
106
107 /** Get or set options on a multistream encoder state */
108 OPUS_EXPORT int opus_multistream_encoder_ctl(OpusMSEncoder *st, int request, ...) OPUS_ARG_NONNULL(1);
109
110 /** Allocate and initialize a multistream decoder state object.
111  *  Call opus_multistream_decoder_destroy() to release
112  *  this object when finished. */
113 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT OpusMSDecoder *opus_multistream_decoder_create(
114       opus_int32 Fs,            /**< Sampling rate to decode at (Hz) */
115       int channels,             /**< Number of channels to decode */
116       int streams,              /**< Total number of coded streams in the multistream */
117       int coupled_streams,      /**< Number of coupled (stereo) streams in the multistream */
118       const unsigned char *mapping, /**< Stream to channel mapping table */
119       int *error                /**< Error code */
120 ) OPUS_ARG_NONNULL(5);
121
122 /** Intialize a previously allocated decoder state object. */
123 OPUS_EXPORT int opus_multistream_decoder_init(
124       OpusMSDecoder *st,        /**< Encoder state */
125       opus_int32 Fs,            /**< Sample rate of input signal (Hz) */
126       int channels,             /**< Number of channels in the input signal */
127       int streams,              /**< Total number of coded streams */
128       int coupled_streams,      /**< Number of coupled (stereo) streams */
129       const unsigned char *mapping  /**< Stream to channel mapping table */
130 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(6);
131
132 /** Returns the number of samples decoded or a negative error code */
133 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode(
134     OpusMSDecoder *st,          /**< Decoder state */
135     const unsigned char *data,  /**< Input payload. Use a NULL pointer to indicate packet loss */
136     opus_int32 len,             /**< Number of bytes in payload */
137     opus_int16 *pcm,            /**< Output signal, samples interleaved in channel order . length is frame_size*channels */
138     int frame_size,             /**< Number of samples per frame of input signal */
139     int decode_fec              /**< Flag (0/1) to request that any in-band forward error correction data be */
140                                 /**< decoded. If no such data is available the frame is decoded as if it were lost. */
141 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
142
143 /** Returns the number of samples decoded or a negative error code */
144 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT int opus_multistream_decode_float(
145     OpusMSDecoder *st,          /**< Decoder state */
146     const unsigned char *data,  /**< Input payload buffer. Use a NULL pointer to indicate packet loss */
147     opus_int32 len,             /**< Number of payload bytes in data */
148     float *pcm,                 /**< Buffer for the output signal (interleaved iin channel order). length is frame_size*channels */
149     int frame_size,             /**< Number of samples per frame of input signal */
150     int decode_fec              /**< Flag (0/1) to request that any in-band forward error correction data be */
151                                 /**< decoded. If no such data is available the frame is decoded as if it were lost. */
152 ) OPUS_ARG_NONNULL(1) OPUS_ARG_NONNULL(4);
153
154 /** Gets the size of an OpusMSDecoder structure.
155   * @returns size
156   */
157 OPUS_EXPORT OPUS_WARN_UNUSED_RESULT opus_int32 opus_multistream_decoder_get_size(
158       int streams,              /**< Total number of coded streams */
159       int coupled_streams       /**< Number of coupled (stereo) streams */
160 );
161
162 /** Get or set options on a multistream decoder state */
163 OPUS_EXPORT int opus_multistream_decoder_ctl(OpusMSDecoder *st, int request, ...) OPUS_ARG_NONNULL(1);
164
165 /** Deallocate a multistream decoder state object */
166 OPUS_EXPORT void opus_multistream_decoder_destroy(OpusMSDecoder *st);
167
168 #ifdef __cplusplus
169 }
170 #endif
171
172 #endif /* OPUS_MULTISTREAM_H */