channel_layout.h (34091B)
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 47 enum 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 114 enum 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 260 enum 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 */ 283 typedef 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 */ 319 typedef 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 444 struct 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 */ 457 int 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 */ 464 void 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 */ 476 int 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 */ 483 void 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 */ 491 enum 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 */ 508 int 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 */ 520 int 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 */ 543 int 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 */ 552 void 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 */ 563 const 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 */ 571 void 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 */ 583 int 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 */ 598 int 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 */ 607 int 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 */ 619 enum AVChannel 620 av_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 */ 631 int 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 */ 646 int 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 */ 661 enum AVChannel 662 av_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 */ 674 uint64_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 */ 684 int 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 */ 699 int 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 */ 709 int 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 */ 756 int av_channel_layout_retype(AVChannelLayout *channel_layout, enum AVChannelOrder order, int flags); 757 758 /** 759 * @} 760 */ 761 762 #endif /* AVUTIL_CHANNEL_LAYOUT_H */