1/*
2 * Copyright (c) 2006 Michael Niedermayer <michaelni@gmx.at>
3 * Copyright (c) 2008 Peter Ross
4 *
5 * This file is part of FFmpeg.
6 *
7 * FFmpeg is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * FFmpeg is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with FFmpeg; if not, write to the Free Software
19 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
20 */
21
22#ifndef AVUTIL_CHANNEL_LAYOUT_H
23#define AVUTIL_CHANNEL_LAYOUT_H
24
25#include <stdint.h>
26#include <stdlib.h>
27
28#include "version.h"
29#include "attributes.h"
30
31/**
32 * @file
33 * @ingroup lavu_audio_channels
34 * Public libavutil channel layout APIs header.
35 */
36
37
38/**
39 * @defgroup lavu_audio_channels Audio channels
40 * @ingroup lavu_audio
41 *
42 * Audio channel layout utility functions
43 *
44 * @{
45 */
46
47enum AVChannel {
48 /// Invalid channel index
49 AV_CHAN_NONE = -1,
50 AV_CHAN_FRONT_LEFT,
51 AV_CHAN_FRONT_RIGHT,
52 AV_CHAN_FRONT_CENTER,
53 AV_CHAN_LOW_FREQUENCY,
54 AV_CHAN_BACK_LEFT,
55 AV_CHAN_BACK_RIGHT,
56 AV_CHAN_FRONT_LEFT_OF_CENTER,
57 AV_CHAN_FRONT_RIGHT_OF_CENTER,
58 AV_CHAN_BACK_CENTER,
59 AV_CHAN_SIDE_LEFT,
60 AV_CHAN_SIDE_RIGHT,
61 AV_CHAN_TOP_CENTER,
62 AV_CHAN_TOP_FRONT_LEFT,
63 AV_CHAN_TOP_FRONT_CENTER,
64 AV_CHAN_TOP_FRONT_RIGHT,
65 AV_CHAN_TOP_BACK_LEFT,
66 AV_CHAN_TOP_BACK_CENTER,
67 AV_CHAN_TOP_BACK_RIGHT,
68 /** Stereo downmix. */
69 AV_CHAN_STEREO_LEFT = 29,
70 /** See above. */
71 AV_CHAN_STEREO_RIGHT,
72 AV_CHAN_WIDE_LEFT,
73 AV_CHAN_WIDE_RIGHT,
74 AV_CHAN_SURROUND_DIRECT_LEFT,
75 AV_CHAN_SURROUND_DIRECT_RIGHT,
76 AV_CHAN_LOW_FREQUENCY_2,
77 AV_CHAN_TOP_SIDE_LEFT,
78 AV_CHAN_TOP_SIDE_RIGHT,
79 AV_CHAN_BOTTOM_FRONT_CENTER,
80 AV_CHAN_BOTTOM_FRONT_LEFT,
81 AV_CHAN_BOTTOM_FRONT_RIGHT,
82 AV_CHAN_SIDE_SURROUND_LEFT, ///< +90 degrees, Lss, SiL
83 AV_CHAN_SIDE_SURROUND_RIGHT, ///< -90 degrees, Rss, SiR
84 AV_CHAN_TOP_SURROUND_LEFT, ///< +110 degrees, Lvs, TpLS
85 AV_CHAN_TOP_SURROUND_RIGHT, ///< -110 degrees, Rvs, TpRS
86
87 AV_CHAN_BINAURAL_LEFT = 61,
88 AV_CHAN_BINAURAL_RIGHT,
89
90 /** Channel is empty can be safely skipped. */
91 AV_CHAN_UNUSED = 0x200,
92
93 /** Channel contains data, but its position is unknown. */
94 AV_CHAN_UNKNOWN = 0x300,
95
96 /**
97 * Range of channels between AV_CHAN_AMBISONIC_BASE and
98 * AV_CHAN_AMBISONIC_END represent Ambisonic components using the ACN system.
99 *
100 * Given a channel id `<i>` between AV_CHAN_AMBISONIC_BASE and
101 * AV_CHAN_AMBISONIC_END (inclusive), the ACN index of the channel `<n>` is
102 * `<n> = <i> - AV_CHAN_AMBISONIC_BASE`.
103 *
104 * @note these values are only used for AV_CHANNEL_ORDER_CUSTOM channel
105 * orderings, the AV_CHANNEL_ORDER_AMBISONIC ordering orders the channels
106 * implicitly by their position in the stream.
107 */
108 AV_CHAN_AMBISONIC_BASE = 0x400,
109 // leave space for 1024 ids, which correspond to maximum order-32 harmonics,
110 // which should be enough for the foreseeable use cases
111 AV_CHAN_AMBISONIC_END = 0x7ff,
112};
113
114enum AVChannelOrder {
115 /**
116 * Only the channel count is specified, without any further information
117 * about the channel order.
118 */
119 AV_CHANNEL_ORDER_UNSPEC,
120 /**
121 * The native channel order, i.e. the channels are in the same order in
122 * which they are defined in the AVChannel enum. This supports up to 63
123 * different channels.
124 */
125 AV_CHANNEL_ORDER_NATIVE,
126 /**
127 * The channel order does not correspond to any other predefined order and
128 * is stored as an explicit map. For example, this could be used to support
129 * layouts with 64 or more channels, or with empty/skipped (AV_CHAN_UNUSED)
130 * channels at arbitrary positions.
131 */
132 AV_CHANNEL_ORDER_CUSTOM,
133 /**
134 * The audio is represented as the decomposition of the sound field into
135 * spherical harmonics. Each channel corresponds to a single expansion
136 * component. Channels are ordered according to ACN (Ambisonic Channel
137 * Number).
138 *
139 * The channel with the index n in the stream contains the spherical
140 * harmonic of degree l and order m given by
141 * @code{.unparsed}
142 * l = floor(sqrt(n)),
143 * m = n - l * (l + 1).
144 * @endcode
145 *
146 * Conversely given a spherical harmonic of degree l and order m, the
147 * corresponding channel index n is given by
148 * @code{.unparsed}
149 * n = l * (l + 1) + m.
150 * @endcode
151 *
152 * Normalization is assumed to be SN3D (Schmidt Semi-Normalization)
153 * as defined in AmbiX format $ 2.1.
154 */
155 AV_CHANNEL_ORDER_AMBISONIC,
156 /**
157 * Number of channel orders, not part of ABI/API
158 */
159 FF_CHANNEL_ORDER_NB
160};
161
162
163/**
164 * @defgroup channel_masks Audio channel masks
165 *
166 * A channel layout is a 64-bits integer with a bit set for every channel.
167 * The number of bits set must be equal to the number of channels.
168 * The value 0 means that the channel layout is not known.
169 * @note this data structure is not powerful enough to handle channels
170 * combinations that have the same channel multiple times, such as
171 * dual-mono.
172 *
173 * @{
174 */
175#define AV_CH_FRONT_LEFT (1ULL << AV_CHAN_FRONT_LEFT )
176#define AV_CH_FRONT_RIGHT (1ULL << AV_CHAN_FRONT_RIGHT )
177#define AV_CH_FRONT_CENTER (1ULL << AV_CHAN_FRONT_CENTER )
178#define AV_CH_LOW_FREQUENCY (1ULL << AV_CHAN_LOW_FREQUENCY )
179#define AV_CH_BACK_LEFT (1ULL << AV_CHAN_BACK_LEFT )
180#define AV_CH_BACK_RIGHT (1ULL << AV_CHAN_BACK_RIGHT )
181#define AV_CH_FRONT_LEFT_OF_CENTER (1ULL << AV_CHAN_FRONT_LEFT_OF_CENTER )
182#define AV_CH_FRONT_RIGHT_OF_CENTER (1ULL << AV_CHAN_FRONT_RIGHT_OF_CENTER)
183#define AV_CH_BACK_CENTER (1ULL << AV_CHAN_BACK_CENTER )
184#define AV_CH_SIDE_LEFT (1ULL << AV_CHAN_SIDE_LEFT )
185#define AV_CH_SIDE_RIGHT (1ULL << AV_CHAN_SIDE_RIGHT )
186#define AV_CH_TOP_CENTER (1ULL << AV_CHAN_TOP_CENTER )
187#define AV_CH_TOP_FRONT_LEFT (1ULL << AV_CHAN_TOP_FRONT_LEFT )
188#define AV_CH_TOP_FRONT_CENTER (1ULL << AV_CHAN_TOP_FRONT_CENTER )
189#define AV_CH_TOP_FRONT_RIGHT (1ULL << AV_CHAN_TOP_FRONT_RIGHT )
190#define AV_CH_TOP_BACK_LEFT (1ULL << AV_CHAN_TOP_BACK_LEFT )
191#define AV_CH_TOP_BACK_CENTER (1ULL << AV_CHAN_TOP_BACK_CENTER )
192#define AV_CH_TOP_BACK_RIGHT (1ULL << AV_CHAN_TOP_BACK_RIGHT )
193#define AV_CH_STEREO_LEFT (1ULL << AV_CHAN_STEREO_LEFT )
194#define AV_CH_STEREO_RIGHT (1ULL << AV_CHAN_STEREO_RIGHT )
195#define AV_CH_WIDE_LEFT (1ULL << AV_CHAN_WIDE_LEFT )
196#define AV_CH_WIDE_RIGHT (1ULL << AV_CHAN_WIDE_RIGHT )
197#define AV_CH_SURROUND_DIRECT_LEFT (1ULL << AV_CHAN_SURROUND_DIRECT_LEFT )
198#define AV_CH_SURROUND_DIRECT_RIGHT (1ULL << AV_CHAN_SURROUND_DIRECT_RIGHT)
199#define AV_CH_LOW_FREQUENCY_2 (1ULL << AV_CHAN_LOW_FREQUENCY_2 )
200#define AV_CH_TOP_SIDE_LEFT (1ULL << AV_CHAN_TOP_SIDE_LEFT )
201#define AV_CH_TOP_SIDE_RIGHT (1ULL << AV_CHAN_TOP_SIDE_RIGHT )
202#define AV_CH_BOTTOM_FRONT_CENTER (1ULL << AV_CHAN_BOTTOM_FRONT_CENTER )
203#define AV_CH_BOTTOM_FRONT_LEFT (1ULL << AV_CHAN_BOTTOM_FRONT_LEFT )
204#define AV_CH_BOTTOM_FRONT_RIGHT (1ULL << AV_CHAN_BOTTOM_FRONT_RIGHT )
205#define AV_CH_SIDE_SURROUND_LEFT (1ULL << AV_CHAN_SIDE_SURROUND_LEFT )
206#define AV_CH_SIDE_SURROUND_RIGHT (1ULL << AV_CHAN_SIDE_SURROUND_RIGHT )
207#define AV_CH_TOP_SURROUND_LEFT (1ULL << AV_CHAN_TOP_SURROUND_LEFT )
208#define AV_CH_TOP_SURROUND_RIGHT (1ULL << AV_CHAN_TOP_SURROUND_RIGHT )
209#define AV_CH_BINAURAL_LEFT (1ULL << AV_CHAN_BINAURAL_LEFT )
210#define AV_CH_BINAURAL_RIGHT (1ULL << AV_CHAN_BINAURAL_RIGHT )
211
212/**
213 * @}
214 * @defgroup channel_mask_c Audio channel layouts
215 * @{
216 * */
217#define AV_CH_LAYOUT_MONO (AV_CH_FRONT_CENTER)
218#define AV_CH_LAYOUT_STEREO (AV_CH_FRONT_LEFT|AV_CH_FRONT_RIGHT)
219#define AV_CH_LAYOUT_2POINT1 (AV_CH_LAYOUT_STEREO|AV_CH_LOW_FREQUENCY)
220#define AV_CH_LAYOUT_2_1 (AV_CH_LAYOUT_STEREO|AV_CH_BACK_CENTER)
221#define AV_CH_LAYOUT_SURROUND (AV_CH_LAYOUT_STEREO|AV_CH_FRONT_CENTER)
222#define AV_CH_LAYOUT_3POINT1 (AV_CH_LAYOUT_SURROUND|AV_CH_LOW_FREQUENCY)
223#define AV_CH_LAYOUT_4POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_CENTER)
224#define AV_CH_LAYOUT_4POINT1 (AV_CH_LAYOUT_4POINT0|AV_CH_LOW_FREQUENCY)
225#define AV_CH_LAYOUT_2_2 (AV_CH_LAYOUT_STEREO|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
226#define AV_CH_LAYOUT_QUAD (AV_CH_LAYOUT_STEREO|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
227#define AV_CH_LAYOUT_5POINT0 (AV_CH_LAYOUT_SURROUND|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
228#define AV_CH_LAYOUT_5POINT1 (AV_CH_LAYOUT_5POINT0|AV_CH_LOW_FREQUENCY)
229#define AV_CH_LAYOUT_5POINT0_BACK (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
230#define AV_CH_LAYOUT_5POINT1_BACK (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_LOW_FREQUENCY)
231#define AV_CH_LAYOUT_6POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_CENTER)
232#define AV_CH_LAYOUT_6POINT0_FRONT (AV_CH_LAYOUT_2_2|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
233#define AV_CH_LAYOUT_HEXAGONAL (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_BACK_CENTER)
234#define AV_CH_LAYOUT_3POINT1POINT2 (AV_CH_LAYOUT_3POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
235#define AV_CH_LAYOUT_6POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_CENTER)
236#define AV_CH_LAYOUT_6POINT1_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_BACK_CENTER)
237#define AV_CH_LAYOUT_6POINT1_FRONT (AV_CH_LAYOUT_6POINT0_FRONT|AV_CH_LOW_FREQUENCY)
238#define AV_CH_LAYOUT_7POINT0 (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
239#define AV_CH_LAYOUT_7POINT0_FRONT (AV_CH_LAYOUT_5POINT0|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
240#define AV_CH_LAYOUT_7POINT1 (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
241#define AV_CH_LAYOUT_7POINT1_WIDE (AV_CH_LAYOUT_5POINT1|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
242#define AV_CH_LAYOUT_7POINT1_WIDE_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
243#define AV_CH_LAYOUT_5POINT1POINT2 (AV_CH_LAYOUT_5POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
244#define AV_CH_LAYOUT_5POINT1POINT2_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
245#define AV_CH_LAYOUT_OCTAGONAL (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_CENTER|AV_CH_BACK_RIGHT)
246#define AV_CH_LAYOUT_CUBE (AV_CH_LAYOUT_QUAD|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT)
247#define AV_CH_LAYOUT_5POINT1POINT4_BACK (AV_CH_LAYOUT_5POINT1POINT2|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT)
248#define AV_CH_LAYOUT_7POINT1POINT2 (AV_CH_LAYOUT_7POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
249#define AV_CH_LAYOUT_7POINT1POINT4_BACK (AV_CH_LAYOUT_7POINT1POINT2|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT)
250#define AV_CH_LAYOUT_7POINT2POINT3 (AV_CH_LAYOUT_7POINT1POINT2|AV_CH_TOP_BACK_CENTER|AV_CH_LOW_FREQUENCY_2)
251#define AV_CH_LAYOUT_9POINT1POINT4_BACK (AV_CH_LAYOUT_7POINT1POINT4_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
252#define AV_CH_LAYOUT_9POINT1POINT6 (AV_CH_LAYOUT_9POINT1POINT4_BACK|AV_CH_TOP_SIDE_LEFT|AV_CH_TOP_SIDE_RIGHT)
253#define AV_CH_LAYOUT_HEXADECAGONAL (AV_CH_LAYOUT_OCTAGONAL|AV_CH_WIDE_LEFT|AV_CH_WIDE_RIGHT|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT|AV_CH_TOP_BACK_CENTER|AV_CH_TOP_FRONT_CENTER|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
254#define AV_CH_LAYOUT_BINAURAL (AV_CH_BINAURAL_LEFT|AV_CH_BINAURAL_RIGHT)
255#define AV_CH_LAYOUT_STEREO_DOWNMIX (AV_CH_STEREO_LEFT|AV_CH_STEREO_RIGHT)
256#define AV_CH_LAYOUT_22POINT2 (AV_CH_LAYOUT_9POINT1POINT6|AV_CH_BACK_CENTER|AV_CH_LOW_FREQUENCY_2|AV_CH_TOP_FRONT_CENTER|AV_CH_TOP_CENTER|AV_CH_TOP_BACK_CENTER|AV_CH_BOTTOM_FRONT_CENTER|AV_CH_BOTTOM_FRONT_LEFT|AV_CH_BOTTOM_FRONT_RIGHT)
257
258#define AV_CH_LAYOUT_7POINT1_TOP_BACK AV_CH_LAYOUT_5POINT1POINT2_BACK
259
260enum AVMatrixEncoding {
261 AV_MATRIX_ENCODING_NONE,
262 AV_MATRIX_ENCODING_DOLBY,
263 AV_MATRIX_ENCODING_DPLII,
264 AV_MATRIX_ENCODING_DPLIIX,
265 AV_MATRIX_ENCODING_DPLIIZ,
266 AV_MATRIX_ENCODING_DOLBYEX,
267 AV_MATRIX_ENCODING_DOLBYHEADPHONE,
268 AV_MATRIX_ENCODING_NB
269};
270
271/**
272 * @}
273 */
274
275/**
276 * An AVChannelCustom defines a single channel within a custom order layout
277 *
278 * Unlike most structures in FFmpeg, sizeof(AVChannelCustom) is a part of the
279 * public ABI.
280 *
281 * No new fields may be added to it without a major version bump.
282 */
283typedef struct AVChannelCustom {
284 enum AVChannel id;
285 char name[16];
286 void *opaque;
287} AVChannelCustom;
288
289/**
290 * An AVChannelLayout holds information about the channel layout of audio data.
291 *
292 * A channel layout here is defined as a set of channels ordered in a specific
293 * way (unless the channel order is AV_CHANNEL_ORDER_UNSPEC, in which case an
294 * AVChannelLayout carries only the channel count).
295 * All orders may be treated as if they were AV_CHANNEL_ORDER_UNSPEC by
296 * ignoring everything but the channel count, as long as av_channel_layout_check()
297 * considers they are valid.
298 *
299 * Unlike most structures in FFmpeg, sizeof(AVChannelLayout) is a part of the
300 * public ABI and may be used by the caller. E.g. it may be allocated on stack
301 * or embedded in caller-defined structs.
302 *
303 * AVChannelLayout can be initialized as follows:
304 * - default initialization with {0}, followed by setting all used fields
305 * correctly;
306 * - by assigning one of the predefined AV_CHANNEL_LAYOUT_* initializers;
307 * - with a constructor function, such as av_channel_layout_default(),
308 * av_channel_layout_from_mask() or av_channel_layout_from_string().
309 *
310 * The channel layout must be uninitialized with av_channel_layout_uninit()
311 *
312 * Copying an AVChannelLayout via assigning is forbidden,
313 * av_channel_layout_copy() must be used instead (and its return value should
314 * be checked)
315 *
316 * No new fields may be added to it without a major version bump, except for
317 * new elements of the union fitting in sizeof(uint64_t).
318 */
319typedef struct AVChannelLayout {
320 /**
321 * Channel order used in this layout.
322 * This is a mandatory field.
323 */
324 enum AVChannelOrder order;
325
326 /**
327 * Number of channels in this layout. Mandatory field.
328 */
329 int nb_channels;
330
331 /**
332 * Details about which channels are present in this layout.
333 * For AV_CHANNEL_ORDER_UNSPEC, this field is undefined and must not be
334 * used.
335 */
336 union {
337 /**
338 * This member must be used for AV_CHANNEL_ORDER_NATIVE, and may be used
339 * for AV_CHANNEL_ORDER_AMBISONIC to signal non-diegetic channels.
340 * It is a bitmask, where the position of each set bit means that the
341 * AVChannel with the corresponding value is present.
342 *
343 * I.e. when (mask & (1 << AV_CHAN_FOO)) is non-zero, then AV_CHAN_FOO
344 * is present in the layout. Otherwise it is not present.
345 *
346 * @note when a channel layout using a bitmask is constructed or
347 * modified manually (i.e. not using any of the av_channel_layout_*
348 * functions), the code doing it must ensure that the number of set bits
349 * is equal to nb_channels.
350 */
351 uint64_t mask;
352 /**
353 * This member must be used when the channel order is
354 * AV_CHANNEL_ORDER_CUSTOM. It is a nb_channels-sized array, with each
355 * element signalling the presence of the AVChannel with the
356 * corresponding value in map[i].id.
357 *
358 * I.e. when map[i].id is equal to AV_CHAN_FOO, then AV_CH_FOO is the
359 * i-th channel in the audio data.
360 *
361 * When map[i].id is in the range between AV_CHAN_AMBISONIC_BASE and
362 * AV_CHAN_AMBISONIC_END (inclusive), the channel contains an ambisonic
363 * component with ACN index (as defined above)
364 * n = map[i].id - AV_CHAN_AMBISONIC_BASE.
365 *
366 * map[i].name may be filled with a 0-terminated string, in which case
367 * it will be used for the purpose of identifying the channel with the
368 * convenience functions below. Otherwise it must be zeroed.
369 */
370 AVChannelCustom *map;
371 } u;
372
373 /**
374 * For some private data of the user.
375 */
376 void *opaque;
377} AVChannelLayout;
378
379/**
380 * Macro to define native channel layouts
381 *
382 * @note This doesn't use designated initializers for compatibility with C++ 17 and older.
383 */
384#define AV_CHANNEL_LAYOUT_MASK(nb, m) \
385 { /* .order */ AV_CHANNEL_ORDER_NATIVE, \
386 /* .nb_channels */ (nb), \
387 /* .u.mask */ { m }, \
388 /* .opaque */ NULL }
389
390/**
391 * @name Common pre-defined channel layouts
392 * @{
393 */
394#define AV_CHANNEL_LAYOUT_MONO AV_CHANNEL_LAYOUT_MASK(1, AV_CH_LAYOUT_MONO)
395#define AV_CHANNEL_LAYOUT_STEREO AV_CHANNEL_LAYOUT_MASK(2, AV_CH_LAYOUT_STEREO)
396#define AV_CHANNEL_LAYOUT_2POINT1 AV_CHANNEL_LAYOUT_MASK(3, AV_CH_LAYOUT_2POINT1)
397#define AV_CHANNEL_LAYOUT_2_1 AV_CHANNEL_LAYOUT_MASK(3, AV_CH_LAYOUT_2_1)
398#define AV_CHANNEL_LAYOUT_SURROUND AV_CHANNEL_LAYOUT_MASK(3, AV_CH_LAYOUT_SURROUND)
399#define AV_CHANNEL_LAYOUT_3POINT1 AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_3POINT1)
400#define AV_CHANNEL_LAYOUT_4POINT0 AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_4POINT0)
401#define AV_CHANNEL_LAYOUT_4POINT1 AV_CHANNEL_LAYOUT_MASK(5, AV_CH_LAYOUT_4POINT1)
402#define AV_CHANNEL_LAYOUT_2_2 AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_2_2)
403#define AV_CHANNEL_LAYOUT_QUAD AV_CHANNEL_LAYOUT_MASK(4, AV_CH_LAYOUT_QUAD)
404#define AV_CHANNEL_LAYOUT_5POINT0 AV_CHANNEL_LAYOUT_MASK(5, AV_CH_LAYOUT_5POINT0)
405#define AV_CHANNEL_LAYOUT_5POINT1 AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_5POINT1)
406#define AV_CHANNEL_LAYOUT_5POINT0_BACK AV_CHANNEL_LAYOUT_MASK(5, AV_CH_LAYOUT_5POINT0_BACK)
407#define AV_CHANNEL_LAYOUT_5POINT1_BACK AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_5POINT1_BACK)
408#define AV_CHANNEL_LAYOUT_6POINT0 AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_6POINT0)
409#define AV_CHANNEL_LAYOUT_6POINT0_FRONT AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_6POINT0_FRONT)
410#define AV_CHANNEL_LAYOUT_3POINT1POINT2 AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_3POINT1POINT2)
411#define AV_CHANNEL_LAYOUT_HEXAGONAL AV_CHANNEL_LAYOUT_MASK(6, AV_CH_LAYOUT_HEXAGONAL)
412#define AV_CHANNEL_LAYOUT_6POINT1 AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_6POINT1)
413#define AV_CHANNEL_LAYOUT_6POINT1_BACK AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_6POINT1_BACK)
414#define AV_CHANNEL_LAYOUT_6POINT1_FRONT AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_6POINT1_FRONT)
415#define AV_CHANNEL_LAYOUT_7POINT0 AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_7POINT0)
416#define AV_CHANNEL_LAYOUT_7POINT0_FRONT AV_CHANNEL_LAYOUT_MASK(7, AV_CH_LAYOUT_7POINT0_FRONT)
417#define AV_CHANNEL_LAYOUT_7POINT1 AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_7POINT1)
418#define AV_CHANNEL_LAYOUT_7POINT1_WIDE AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_7POINT1_WIDE)
419#define AV_CHANNEL_LAYOUT_7POINT1_WIDE_BACK AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_7POINT1_WIDE_BACK)
420#define AV_CHANNEL_LAYOUT_5POINT1POINT2 AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_5POINT1POINT2)
421#define AV_CHANNEL_LAYOUT_5POINT1POINT2_BACK AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_5POINT1POINT2_BACK)
422#define AV_CHANNEL_LAYOUT_OCTAGONAL AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_OCTAGONAL)
423#define AV_CHANNEL_LAYOUT_CUBE AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_CUBE)
424#define AV_CHANNEL_LAYOUT_5POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(10, AV_CH_LAYOUT_5POINT1POINT4_BACK)
425#define AV_CHANNEL_LAYOUT_7POINT1POINT2 AV_CHANNEL_LAYOUT_MASK(10, AV_CH_LAYOUT_7POINT1POINT2)
426#define AV_CHANNEL_LAYOUT_7POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(12, AV_CH_LAYOUT_7POINT1POINT4_BACK)
427#define AV_CHANNEL_LAYOUT_7POINT2POINT3 AV_CHANNEL_LAYOUT_MASK(12, AV_CH_LAYOUT_7POINT2POINT3)
428#define AV_CHANNEL_LAYOUT_9POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(14, AV_CH_LAYOUT_9POINT1POINT4_BACK)
429#define AV_CHANNEL_LAYOUT_9POINT1POINT6 AV_CHANNEL_LAYOUT_MASK(16, AV_CH_LAYOUT_9POINT1POINT6)
430#define AV_CHANNEL_LAYOUT_HEXADECAGONAL AV_CHANNEL_LAYOUT_MASK(16, AV_CH_LAYOUT_HEXADECAGONAL)
431#define AV_CHANNEL_LAYOUT_BINAURAL AV_CHANNEL_LAYOUT_MASK(2, AV_CH_LAYOUT_BINAURAL)
432#define AV_CHANNEL_LAYOUT_STEREO_DOWNMIX AV_CHANNEL_LAYOUT_MASK(2, AV_CH_LAYOUT_STEREO_DOWNMIX)
433#define AV_CHANNEL_LAYOUT_22POINT2 AV_CHANNEL_LAYOUT_MASK(24, AV_CH_LAYOUT_22POINT2)
434
435#define AV_CHANNEL_LAYOUT_7POINT1_TOP_BACK AV_CHANNEL_LAYOUT_5POINT1POINT2_BACK
436
437#define AV_CHANNEL_LAYOUT_AMBISONIC_FIRST_ORDER \
438 { /* .order */ AV_CHANNEL_ORDER_AMBISONIC, \
439 /* .nb_channels */ 4, \
440 /* .u.mask */ { 0 }, \
441 /* .opaque */ NULL }
442/** @} */
443
444struct AVBPrint;
445
446/**
447 * Get a human readable string in an abbreviated form describing a given channel.
448 * This is the inverse function of @ref av_channel_from_string().
449 *
450 * @param buf pre-allocated buffer where to put the generated string
451 * @param buf_size size in bytes of the buffer.
452 * @param channel the AVChannel whose name to get
453 * @return amount of bytes needed to hold the output string, or a negative AVERROR
454 * on failure. If the returned value is bigger than buf_size, then the
455 * string was truncated.
456 */
457int av_channel_name(char *buf, size_t buf_size, enum AVChannel channel);
458
459/**
460 * bprint variant of av_channel_name().
461 *
462 * @note the string will be appended to the bprint buffer.
463 */
464void av_channel_name_bprint(struct AVBPrint *bp, enum AVChannel channel_id);
465
466/**
467 * Get a human readable string describing a given channel.
468 *
469 * @param buf pre-allocated buffer where to put the generated string
470 * @param buf_size size in bytes of the buffer.
471 * @param channel the AVChannel whose description to get
472 * @return amount of bytes needed to hold the output string, or a negative AVERROR
473 * on failure. If the returned value is bigger than buf_size, then the
474 * string was truncated.
475 */
476int av_channel_description(char *buf, size_t buf_size, enum AVChannel channel);
477
478/**
479 * bprint variant of av_channel_description().
480 *
481 * @note the string will be appended to the bprint buffer.
482 */
483void av_channel_description_bprint(struct AVBPrint *bp, enum AVChannel channel_id);
484
485/**
486 * This is the inverse function of @ref av_channel_name().
487 *
488 * @return the channel with the given name
489 * AV_CHAN_NONE when name does not identify a known channel
490 */
491enum AVChannel av_channel_from_string(const char *name);
492
493/**
494 * Initialize a custom channel layout with the specified number of channels.
495 * The channel map will be allocated and the designation of all channels will
496 * be set to AV_CHAN_UNKNOWN.
497 *
498 * This is only a convenience helper function, a custom channel layout can also
499 * be constructed without using this.
500 *
501 * @param channel_layout the layout structure to be initialized
502 * @param nb_channels the number of channels
503 *
504 * @return 0 on success
505 * AVERROR(EINVAL) if the number of channels <= 0
506 * AVERROR(ENOMEM) if the channel map could not be allocated
507 */
508int av_channel_layout_custom_init(AVChannelLayout *channel_layout, int nb_channels);
509
510/**
511 * Initialize a native channel layout from a bitmask indicating which channels
512 * are present.
513 *
514 * @param channel_layout the layout structure to be initialized
515 * @param mask bitmask describing the channel layout
516 *
517 * @return 0 on success
518 * AVERROR(EINVAL) for invalid mask values
519 */
520int av_channel_layout_from_mask(AVChannelLayout *channel_layout, uint64_t mask);
521
522/**
523 * Initialize a channel layout from a given string description.
524 * The input string can be represented by:
525 * - the formal channel layout name (returned by av_channel_layout_describe())
526 * - single or multiple channel names (returned by av_channel_name(), eg. "FL",
527 * or concatenated with "+", each optionally containing a custom name after
528 * a "@", eg. "FL@Left+FR@Right+LFE")
529 * - a decimal or hexadecimal value of a native channel layout (eg. "4" or "0x4")
530 * - the number of channels with default layout (eg. "4c")
531 * - the number of unordered channels (eg. "4C" or "4 channels")
532 * - the ambisonic order followed by optional non-diegetic channels (eg.
533 * "ambisonic 2+stereo")
534 * On error, the channel layout will remain uninitialized, but not necessarily
535 * untouched.
536 *
537 * @param channel_layout uninitialized channel layout for the result
538 * @param str string describing the channel layout
539 * @return 0 on success parsing the channel layout
540 * AVERROR(EINVAL) if an invalid channel layout string was provided
541 * AVERROR(ENOMEM) if there was not enough memory
542 */
543int av_channel_layout_from_string(AVChannelLayout *channel_layout,
544 const char *str);
545
546/**
547 * Get the default channel layout for a given number of channels.
548 *
549 * @param ch_layout the layout structure to be initialized
550 * @param nb_channels number of channels
551 */
552void av_channel_layout_default(AVChannelLayout *ch_layout, int nb_channels);
553
554/**
555 * Iterate over all standard channel layouts.
556 *
557 * @param opaque a pointer where libavutil will store the iteration state. Must
558 * point to NULL to start the iteration.
559 *
560 * @return the standard channel layout or NULL when the iteration is
561 * finished
562 */
563const AVChannelLayout *av_channel_layout_standard(void **opaque);
564
565/**
566 * Free any allocated data in the channel layout and reset the channel
567 * count to 0.
568 *
569 * @param channel_layout the layout structure to be uninitialized
570 */
571void av_channel_layout_uninit(AVChannelLayout *channel_layout);
572
573/**
574 * Make a copy of a channel layout. This differs from just assigning src to dst
575 * in that it allocates and copies the map for AV_CHANNEL_ORDER_CUSTOM.
576 *
577 * @note the destination channel_layout will be always uninitialized before copy.
578 *
579 * @param dst destination channel layout
580 * @param src source channel layout
581 * @return 0 on success, a negative AVERROR on error.
582 */
583int av_channel_layout_copy(AVChannelLayout *dst, const AVChannelLayout *src);
584
585/**
586 * Get a human-readable string describing the channel layout properties.
587 * The string will be in the same format that is accepted by
588 * @ref av_channel_layout_from_string(), allowing to rebuild the same
589 * channel layout, except for opaque pointers.
590 *
591 * @param channel_layout channel layout to be described
592 * @param buf pre-allocated buffer where to put the generated string
593 * @param buf_size size in bytes of the buffer.
594 * @return amount of bytes needed to hold the output string, or a negative AVERROR
595 * on failure. If the returned value is bigger than buf_size, then the
596 * string was truncated.
597 */
598int av_channel_layout_describe(const AVChannelLayout *channel_layout,
599 char *buf, size_t buf_size);
600
601/**
602 * bprint variant of av_channel_layout_describe().
603 *
604 * @note the string will be appended to the bprint buffer.
605 * @return 0 on success, or a negative AVERROR value on failure.
606 */
607int av_channel_layout_describe_bprint(const AVChannelLayout *channel_layout,
608 struct AVBPrint *bp);
609
610/**
611 * Get the channel with the given index in a channel layout.
612 *
613 * @param channel_layout input channel layout
614 * @param idx index of the channel
615 * @return channel with the index idx in channel_layout on success or
616 * AV_CHAN_NONE on failure (if idx is not valid or the channel order is
617 * unspecified)
618 */
619enum AVChannel
620av_channel_layout_channel_from_index(const AVChannelLayout *channel_layout, unsigned int idx);
621
622/**
623 * Get the index of a given channel in a channel layout. In case multiple
624 * channels are found, only the first match will be returned.
625 *
626 * @param channel_layout input channel layout
627 * @param channel the channel whose index to obtain
628 * @return index of channel in channel_layout on success or a negative number if
629 * channel is not present in channel_layout.
630 */
631int av_channel_layout_index_from_channel(const AVChannelLayout *channel_layout,
632 enum AVChannel channel);
633
634/**
635 * Get the index in a channel layout of a channel described by the given string.
636 * In case multiple channels are found, only the first match will be returned.
637 *
638 * This function accepts channel names in the same format as
639 * @ref av_channel_from_string().
640 *
641 * @param channel_layout input channel layout
642 * @param name string describing the channel whose index to obtain
643 * @return a channel index described by the given string, or a negative AVERROR
644 * value.
645 */
646int av_channel_layout_index_from_string(const AVChannelLayout *channel_layout,
647 const char *name);
648
649/**
650 * Get a channel described by the given string.
651 *
652 * This function accepts channel names in the same format as
653 * @ref av_channel_from_string().
654 *
655 * @param channel_layout input channel layout
656 * @param name string describing the channel to obtain
657 * @return a channel described by the given string in channel_layout on success
658 * or AV_CHAN_NONE on failure (if the string is not valid or the channel
659 * order is unspecified)
660 */
661enum AVChannel
662av_channel_layout_channel_from_string(const AVChannelLayout *channel_layout,
663 const char *name);
664
665/**
666 * Find out what channels from a given set are present in a channel layout,
667 * without regard for their positions.
668 *
669 * @param channel_layout input channel layout
670 * @param mask a combination of AV_CH_* representing a set of channels
671 * @return a bitfield representing all the channels from mask that are present
672 * in channel_layout
673 */
674uint64_t av_channel_layout_subset(const AVChannelLayout *channel_layout,
675 uint64_t mask);
676
677/**
678 * Check whether a channel layout is valid, i.e. can possibly describe audio
679 * data.
680 *
681 * @param channel_layout input channel layout
682 * @return 1 if channel_layout is valid, 0 otherwise.
683 */
684int av_channel_layout_check(const AVChannelLayout *channel_layout);
685
686/**
687 * Check whether two channel layouts are semantically the same, i.e. the same
688 * channels are present on the same positions in both.
689 *
690 * If one of the channel layouts is AV_CHANNEL_ORDER_UNSPEC, while the other is
691 * not, they are considered to be unequal. If both are AV_CHANNEL_ORDER_UNSPEC,
692 * they are considered equal iff the channel counts are the same in both.
693 *
694 * @param chl input channel layout
695 * @param chl1 input channel layout
696 * @return 0 if chl and chl1 are equal, 1 if they are not equal. A negative
697 * AVERROR code if one or both are invalid.
698 */
699int av_channel_layout_compare(const AVChannelLayout *chl, const AVChannelLayout *chl1);
700
701/**
702 * Return the order if the layout is n-th order standard-order ambisonic.
703 * The presence of optional extra non-diegetic channels at the end is not taken
704 * into account.
705 *
706 * @param channel_layout input channel layout
707 * @return the order of the layout, a negative error code otherwise.
708 */
709int av_channel_layout_ambisonic_order(const AVChannelLayout *channel_layout);
710
711/**
712 * The conversion must be lossless.
713 */
714#define AV_CHANNEL_LAYOUT_RETYPE_FLAG_LOSSLESS (1 << 0)
715
716/**
717 * The specified retype target order is ignored and the simplest possible
718 * (canonical) order is used for which the input layout can be losslessy
719 * represented.
720 */
721#define AV_CHANNEL_LAYOUT_RETYPE_FLAG_CANONICAL (1 << 1)
722
723/**
724 * Change the AVChannelOrder of a channel layout.
725 *
726 * Change of AVChannelOrder can be either lossless or lossy. In case of a
727 * lossless conversion all the channel designations and the associated channel
728 * names (if any) are kept. On a lossy conversion the channel names and channel
729 * designations might be lost depending on the capabilities of the desired
730 * AVChannelOrder. Note that some conversions are simply not possible in which
731 * case this function returns AVERROR(ENOSYS).
732 *
733 * The following conversions are supported:
734 *
735 * Any -> Custom : Always possible, always lossless.
736 * Any -> Unspecified: Always possible, lossless if channel designations
737 * are all unknown and channel names are not used, lossy otherwise.
738 * Custom -> Ambisonic : Possible if it contains ambisonic channels with
739 * optional non-diegetic channels in the end. Lossy if the channels have
740 * custom names, lossless otherwise.
741 * Custom -> Native : Possible if it contains native channels in native
742 * order. Lossy if the channels have custom names, lossless otherwise.
743 *
744 * On error this function keeps the original channel layout untouched.
745 *
746 * @param channel_layout channel layout which will be changed
747 * @param order the desired channel layout order
748 * @param flags a combination of AV_CHANNEL_LAYOUT_RETYPE_FLAG_* constants
749 * @return 0 if the conversion was successful and lossless or if the channel
750 * layout was already in the desired order
751 * >0 if the conversion was successful but lossy
752 * AVERROR(ENOSYS) if the conversion was not possible (or would be
753 * lossy and AV_CHANNEL_LAYOUT_RETYPE_FLAG_LOSSLESS was specified)
754 * AVERROR(EINVAL), AVERROR(ENOMEM) on error
755 */
756int av_channel_layout_retype(AVChannelLayout *channel_layout, enum AVChannelOrder order, int flags);
757
758/**
759 * @}
760 */
761
762#endif /* AVUTIL_CHANNEL_LAYOUT_H */
763