libavutil/channel_layout.h

   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
  83     /** Channel is empty can be safely skipped. */
  84     AV_CHAN_UNUSED = 0x200,
  85
  86     /** Channel contains data, but its position is unknown. */
  87     AV_CHAN_UNKNOWN = 0x300,
  88
  89     /**
  90      * Range of channels between AV_CHAN_AMBISONIC_BASE and
  91      * AV_CHAN_AMBISONIC_END represent Ambisonic components using the ACN system.
  92      *
  93      * Given a channel id `<i>` between AV_CHAN_AMBISONIC_BASE and
  94      * AV_CHAN_AMBISONIC_END (inclusive), the ACN index of the channel `<n>` is
  95      * `<n> = <i> - AV_CHAN_AMBISONIC_BASE`.
  96      *
  97      * @note these values are only used for AV_CHANNEL_ORDER_CUSTOM channel
  98      * orderings, the AV_CHANNEL_ORDER_AMBISONIC ordering orders the channels
  99      * implicitly by their position in the stream.
 100      */
 101     AV_CHAN_AMBISONIC_BASE = 0x400,
 102     // leave space for 1024 ids, which correspond to maximum order-32 harmonics,
 103     // which should be enough for the foreseeable use cases
 104     AV_CHAN_AMBISONIC_END  = 0x7ff,
 105 };
 106
 107 enum AVChannelOrder {
 108     /**
 109      * Only the channel count is specified, without any further information
 110      * about the channel order.
 111      */
 112     AV_CHANNEL_ORDER_UNSPEC,
 113     /**
 114      * The native channel order, i.e. the channels are in the same order in
 115      * which they are defined in the AVChannel enum. This supports up to 63
 116      * different channels.
 117      */
 118     AV_CHANNEL_ORDER_NATIVE,
 119     /**
 120      * The channel order does not correspond to any other predefined order and
 121      * is stored as an explicit map. For example, this could be used to support
 122      * layouts with 64 or more channels, or with empty/skipped (AV_CHAN_SILENCE)
 123      * channels at arbitrary positions.
 124      */
 125     AV_CHANNEL_ORDER_CUSTOM,
 126     /**
 127      * The audio is represented as the decomposition of the sound field into
 128      * spherical harmonics. Each channel corresponds to a single expansion
 129      * component. Channels are ordered according to ACN (Ambisonic Channel
 130      * Number).
 131      *
 132      * The channel with the index n in the stream contains the spherical
 133      * harmonic of degree l and order m given by
 134      * @code{.unparsed}
 135      *   l   = floor(sqrt(n)),
 136      *   m   = n - l * (l + 1).
 137      * @endcode
 138      *
 139      * Conversely given a spherical harmonic of degree l and order m, the
 140      * corresponding channel index n is given by
 141      * @code{.unparsed}
 142      *   n = l * (l + 1) + m.
 143      * @endcode
 144      *
 145      * Normalization is assumed to be SN3D (Schmidt Semi-Normalization)
 146      * as defined in AmbiX format $ 2.1.
 147      */
 148     AV_CHANNEL_ORDER_AMBISONIC,
 149 };
 150
 151
 152 /**
 153  * @defgroup channel_masks Audio channel masks
 154  *
 155  * A channel layout is a 64-bits integer with a bit set for every channel.
 156  * The number of bits set must be equal to the number of channels.
 157  * The value 0 means that the channel layout is not known.
 158  * @note this data structure is not powerful enough to handle channels
 159  * combinations that have the same channel multiple times, such as
 160  * dual-mono.
 161  *
 162  * @{
 163  */
 164 #define AV_CH_FRONT_LEFT             (1ULL << AV_CHAN_FRONT_LEFT           )
 165 #define AV_CH_FRONT_RIGHT            (1ULL << AV_CHAN_FRONT_RIGHT          )
 166 #define AV_CH_FRONT_CENTER           (1ULL << AV_CHAN_FRONT_CENTER         )
 167 #define AV_CH_LOW_FREQUENCY          (1ULL << AV_CHAN_LOW_FREQUENCY        )
 168 #define AV_CH_BACK_LEFT              (1ULL << AV_CHAN_BACK_LEFT            )
 169 #define AV_CH_BACK_RIGHT             (1ULL << AV_CHAN_BACK_RIGHT           )
 170 #define AV_CH_FRONT_LEFT_OF_CENTER   (1ULL << AV_CHAN_FRONT_LEFT_OF_CENTER )
 171 #define AV_CH_FRONT_RIGHT_OF_CENTER  (1ULL << AV_CHAN_FRONT_RIGHT_OF_CENTER)
 172 #define AV_CH_BACK_CENTER            (1ULL << AV_CHAN_BACK_CENTER          )
 173 #define AV_CH_SIDE_LEFT              (1ULL << AV_CHAN_SIDE_LEFT            )
 174 #define AV_CH_SIDE_RIGHT             (1ULL << AV_CHAN_SIDE_RIGHT           )
 175 #define AV_CH_TOP_CENTER             (1ULL << AV_CHAN_TOP_CENTER           )
 176 #define AV_CH_TOP_FRONT_LEFT         (1ULL << AV_CHAN_TOP_FRONT_LEFT       )
 177 #define AV_CH_TOP_FRONT_CENTER       (1ULL << AV_CHAN_TOP_FRONT_CENTER     )
 178 #define AV_CH_TOP_FRONT_RIGHT        (1ULL << AV_CHAN_TOP_FRONT_RIGHT      )
 179 #define AV_CH_TOP_BACK_LEFT          (1ULL << AV_CHAN_TOP_BACK_LEFT        )
 180 #define AV_CH_TOP_BACK_CENTER        (1ULL << AV_CHAN_TOP_BACK_CENTER      )
 181 #define AV_CH_TOP_BACK_RIGHT         (1ULL << AV_CHAN_TOP_BACK_RIGHT       )
 182 #define AV_CH_STEREO_LEFT            (1ULL << AV_CHAN_STEREO_LEFT          )
 183 #define AV_CH_STEREO_RIGHT           (1ULL << AV_CHAN_STEREO_RIGHT         )
 184 #define AV_CH_WIDE_LEFT              (1ULL << AV_CHAN_WIDE_LEFT            )
 185 #define AV_CH_WIDE_RIGHT             (1ULL << AV_CHAN_WIDE_RIGHT           )
 186 #define AV_CH_SURROUND_DIRECT_LEFT   (1ULL << AV_CHAN_SURROUND_DIRECT_LEFT )
 187 #define AV_CH_SURROUND_DIRECT_RIGHT  (1ULL << AV_CHAN_SURROUND_DIRECT_RIGHT)
 188 #define AV_CH_LOW_FREQUENCY_2        (1ULL << AV_CHAN_LOW_FREQUENCY_2      )
 189 #define AV_CH_TOP_SIDE_LEFT          (1ULL << AV_CHAN_TOP_SIDE_LEFT        )
 190 #define AV_CH_TOP_SIDE_RIGHT         (1ULL << AV_CHAN_TOP_SIDE_RIGHT       )
 191 #define AV_CH_BOTTOM_FRONT_CENTER    (1ULL << AV_CHAN_BOTTOM_FRONT_CENTER  )
 192 #define AV_CH_BOTTOM_FRONT_LEFT      (1ULL << AV_CHAN_BOTTOM_FRONT_LEFT    )
 193 #define AV_CH_BOTTOM_FRONT_RIGHT     (1ULL << AV_CHAN_BOTTOM_FRONT_RIGHT   )
 194
 195 #if FF_API_OLD_CHANNEL_LAYOUT
 196 /** Channel mask value used for AVCodecContext.request_channel_layout
 197     to indicate that the user requests the channel order of the decoder output
 198     to be the native codec channel order.
 199     @deprecated channel order is now indicated in a special field in
 200                 AVChannelLayout
 201     */
 202 #define AV_CH_LAYOUT_NATIVE          0x8000000000000000ULL
 203 #endif
 204
 205 /**
 206  * @}
 207  * @defgroup channel_mask_c Audio channel layouts
 208  * @{
 209  * */
 210 #define AV_CH_LAYOUT_MONO              (AV_CH_FRONT_CENTER)
 211 #define AV_CH_LAYOUT_STEREO            (AV_CH_FRONT_LEFT|AV_CH_FRONT_RIGHT)
 212 #define AV_CH_LAYOUT_2POINT1           (AV_CH_LAYOUT_STEREO|AV_CH_LOW_FREQUENCY)
 213 #define AV_CH_LAYOUT_2_1               (AV_CH_LAYOUT_STEREO|AV_CH_BACK_CENTER)
 214 #define AV_CH_LAYOUT_SURROUND          (AV_CH_LAYOUT_STEREO|AV_CH_FRONT_CENTER)
 215 #define AV_CH_LAYOUT_3POINT1           (AV_CH_LAYOUT_SURROUND|AV_CH_LOW_FREQUENCY)
 216 #define AV_CH_LAYOUT_4POINT0           (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_CENTER)
 217 #define AV_CH_LAYOUT_4POINT1           (AV_CH_LAYOUT_4POINT0|AV_CH_LOW_FREQUENCY)
 218 #define AV_CH_LAYOUT_2_2               (AV_CH_LAYOUT_STEREO|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
 219 #define AV_CH_LAYOUT_QUAD              (AV_CH_LAYOUT_STEREO|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
 220 #define AV_CH_LAYOUT_5POINT0           (AV_CH_LAYOUT_SURROUND|AV_CH_SIDE_LEFT|AV_CH_SIDE_RIGHT)
 221 #define AV_CH_LAYOUT_5POINT1           (AV_CH_LAYOUT_5POINT0|AV_CH_LOW_FREQUENCY)
 222 #define AV_CH_LAYOUT_5POINT0_BACK      (AV_CH_LAYOUT_SURROUND|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
 223 #define AV_CH_LAYOUT_5POINT1_BACK      (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_LOW_FREQUENCY)
 224 #define AV_CH_LAYOUT_6POINT0           (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_CENTER)
 225 #define AV_CH_LAYOUT_6POINT0_FRONT     (AV_CH_LAYOUT_2_2|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
 226 #define AV_CH_LAYOUT_HEXAGONAL         (AV_CH_LAYOUT_5POINT0_BACK|AV_CH_BACK_CENTER)
 227 #define AV_CH_LAYOUT_3POINT1POINT2     (AV_CH_LAYOUT_3POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
 228 #define AV_CH_LAYOUT_6POINT1           (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_CENTER)
 229 #define AV_CH_LAYOUT_6POINT1_BACK      (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_BACK_CENTER)
 230 #define AV_CH_LAYOUT_6POINT1_FRONT     (AV_CH_LAYOUT_6POINT0_FRONT|AV_CH_LOW_FREQUENCY)
 231 #define AV_CH_LAYOUT_7POINT0           (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
 232 #define AV_CH_LAYOUT_7POINT0_FRONT     (AV_CH_LAYOUT_5POINT0|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
 233 #define AV_CH_LAYOUT_7POINT1           (AV_CH_LAYOUT_5POINT1|AV_CH_BACK_LEFT|AV_CH_BACK_RIGHT)
 234 #define AV_CH_LAYOUT_7POINT1_WIDE      (AV_CH_LAYOUT_5POINT1|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
 235 #define AV_CH_LAYOUT_7POINT1_WIDE_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER)
 236 #define AV_CH_LAYOUT_5POINT1POINT2_BACK (AV_CH_LAYOUT_5POINT1_BACK|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
 237 #define AV_CH_LAYOUT_OCTAGONAL         (AV_CH_LAYOUT_5POINT0|AV_CH_BACK_LEFT|AV_CH_BACK_CENTER|AV_CH_BACK_RIGHT)
 238 #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)
 239 #define AV_CH_LAYOUT_5POINT1POINT4_BACK (AV_CH_LAYOUT_5POINT1POINT2_BACK|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT)
 240 #define AV_CH_LAYOUT_7POINT1POINT2     (AV_CH_LAYOUT_7POINT1|AV_CH_TOP_FRONT_LEFT|AV_CH_TOP_FRONT_RIGHT)
 241 #define AV_CH_LAYOUT_7POINT1POINT4_BACK (AV_CH_LAYOUT_7POINT1POINT2|AV_CH_TOP_BACK_LEFT|AV_CH_TOP_BACK_RIGHT)
 242 #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)
 243 #define AV_CH_LAYOUT_STEREO_DOWNMIX    (AV_CH_STEREO_LEFT|AV_CH_STEREO_RIGHT)
 244 #define AV_CH_LAYOUT_22POINT2          (AV_CH_LAYOUT_7POINT1POINT4_BACK|AV_CH_FRONT_LEFT_OF_CENTER|AV_CH_FRONT_RIGHT_OF_CENTER|AV_CH_BACK_CENTER|AV_CH_LOW_FREQUENCY_2|AV_CH_TOP_FRONT_CENTER|AV_CH_TOP_CENTER|AV_CH_TOP_SIDE_LEFT|AV_CH_TOP_SIDE_RIGHT|AV_CH_TOP_BACK_CENTER|AV_CH_BOTTOM_FRONT_CENTER|AV_CH_BOTTOM_FRONT_LEFT|AV_CH_BOTTOM_FRONT_RIGHT)
 245
 246 #define AV_CH_LAYOUT_7POINT1_TOP_BACK AV_CH_LAYOUT_5POINT1POINT2_BACK
 247
 248 enum AVMatrixEncoding {
 249     AV_MATRIX_ENCODING_NONE,
 250     AV_MATRIX_ENCODING_DOLBY,
 251     AV_MATRIX_ENCODING_DPLII,
 252     AV_MATRIX_ENCODING_DPLIIX,
 253     AV_MATRIX_ENCODING_DPLIIZ,
 254     AV_MATRIX_ENCODING_DOLBYEX,
 255     AV_MATRIX_ENCODING_DOLBYHEADPHONE,
 256     AV_MATRIX_ENCODING_NB
 257 };
 258
 259 /**
 260  * @}
 261  */
 262
 263 /**
 264  * An AVChannelCustom defines a single channel within a custom order layout
 265  *
 266  * Unlike most structures in FFmpeg, sizeof(AVChannelCustom) is a part of the
 267  * public ABI.
 268  *
 269  * No new fields may be added to it without a major version bump.
 270  */
 271 typedef struct AVChannelCustom {
 272     enum AVChannel id;
 273     char name[16];
 274     void *opaque;
 275 } AVChannelCustom;
 276
 277 /**
 278  * An AVChannelLayout holds information about the channel layout of audio data.
 279  *
 280  * A channel layout here is defined as a set of channels ordered in a specific
 281  * way (unless the channel order is AV_CHANNEL_ORDER_UNSPEC, in which case an
 282  * AVChannelLayout carries only the channel count).
 283  * All orders may be treated as if they were AV_CHANNEL_ORDER_UNSPEC by
 284  * ignoring everything but the channel count, as long as av_channel_layout_check()
 285  * considers they are valid.
 286  *
 287  * Unlike most structures in FFmpeg, sizeof(AVChannelLayout) is a part of the
 288  * public ABI and may be used by the caller. E.g. it may be allocated on stack
 289  * or embedded in caller-defined structs.
 290  *
 291  * AVChannelLayout can be initialized as follows:
 292  * - default initialization with {0}, followed by setting all used fields
 293  *   correctly;
 294  * - by assigning one of the predefined AV_CHANNEL_LAYOUT_* initializers;
 295  * - with a constructor function, such as av_channel_layout_default(),
 296  *   av_channel_layout_from_mask() or av_channel_layout_from_string().
 297  *
 298  * The channel layout must be unitialized with av_channel_layout_uninit()
 299  *
 300  * Copying an AVChannelLayout via assigning is forbidden,
 301  * av_channel_layout_copy() must be used instead (and its return value should
 302  * be checked)
 303  *
 304  * No new fields may be added to it without a major version bump, except for
 305  * new elements of the union fitting in sizeof(uint64_t).
 306  */
 307 typedef struct AVChannelLayout {
 308     /**
 309      * Channel order used in this layout.
 310      * This is a mandatory field.
 311      */
 312     enum AVChannelOrder order;
 313
 314     /**
 315      * Number of channels in this layout. Mandatory field.
 316      */
 317     int nb_channels;
 318
 319     /**
 320      * Details about which channels are present in this layout.
 321      * For AV_CHANNEL_ORDER_UNSPEC, this field is undefined and must not be
 322      * used.
 323      */
 324     union {
 325         /**
 326          * This member must be used for AV_CHANNEL_ORDER_NATIVE, and may be used
 327          * for AV_CHANNEL_ORDER_AMBISONIC to signal non-diegetic channels.
 328          * It is a bitmask, where the position of each set bit means that the
 329          * AVChannel with the corresponding value is present.
 330          *
 331          * I.e. when (mask & (1 << AV_CHAN_FOO)) is non-zero, then AV_CHAN_FOO
 332          * is present in the layout. Otherwise it is not present.
 333          *
 334          * @note when a channel layout using a bitmask is constructed or
 335          * modified manually (i.e.  not using any of the av_channel_layout_*
 336          * functions), the code doing it must ensure that the number of set bits
 337          * is equal to nb_channels.
 338          */
 339         uint64_t mask;
 340         /**
 341          * This member must be used when the channel order is
 342          * AV_CHANNEL_ORDER_CUSTOM. It is a nb_channels-sized array, with each
 343          * element signalling the presence of the AVChannel with the
 344          * corresponding value in map[i].id.
 345          *
 346          * I.e. when map[i].id is equal to AV_CHAN_FOO, then AV_CH_FOO is the
 347          * i-th channel in the audio data.
 348          *
 349          * When map[i].id is in the range between AV_CHAN_AMBISONIC_BASE and
 350          * AV_CHAN_AMBISONIC_END (inclusive), the channel contains an ambisonic
 351          * component with ACN index (as defined above)
 352          * n = map[i].id - AV_CHAN_AMBISONIC_BASE.
 353          *
 354          * map[i].name may be filled with a 0-terminated string, in which case
 355          * it will be used for the purpose of identifying the channel with the
 356          * convenience functions below. Otherise it must be zeroed.
 357          */
 358         AVChannelCustom *map;
 359     } u;
 360
 361     /**
 362      * For some private data of the user.
 363      */
 364     void *opaque;
 365 } AVChannelLayout;
 366
 367 /**
 368  * Macro to define native channel layouts
 369  *
 370  * @note This doesn't use designated initializers for compatibility with C++ 17 and older.
 371  */
 372 #define AV_CHANNEL_LAYOUT_MASK(nb, m) \
 373     { /* .order */ AV_CHANNEL_ORDER_NATIVE, \
 374       /* .nb_channels */  (nb), \
 375       /* .u.mask */ { m }, \
 376       /* .opaque */ NULL }
 377
 378 /**
 379  * @name Common pre-defined channel layouts
 380  * @{
 381  */
 382 #define AV_CHANNEL_LAYOUT_MONO              AV_CHANNEL_LAYOUT_MASK(1,  AV_CH_LAYOUT_MONO)
 383 #define AV_CHANNEL_LAYOUT_STEREO            AV_CHANNEL_LAYOUT_MASK(2,  AV_CH_LAYOUT_STEREO)
 384 #define AV_CHANNEL_LAYOUT_2POINT1           AV_CHANNEL_LAYOUT_MASK(3,  AV_CH_LAYOUT_2POINT1)
 385 #define AV_CHANNEL_LAYOUT_2_1               AV_CHANNEL_LAYOUT_MASK(3,  AV_CH_LAYOUT_2_1)
 386 #define AV_CHANNEL_LAYOUT_SURROUND          AV_CHANNEL_LAYOUT_MASK(3,  AV_CH_LAYOUT_SURROUND)
 387 #define AV_CHANNEL_LAYOUT_3POINT1           AV_CHANNEL_LAYOUT_MASK(4,  AV_CH_LAYOUT_3POINT1)
 388 #define AV_CHANNEL_LAYOUT_4POINT0           AV_CHANNEL_LAYOUT_MASK(4,  AV_CH_LAYOUT_4POINT0)
 389 #define AV_CHANNEL_LAYOUT_4POINT1           AV_CHANNEL_LAYOUT_MASK(5,  AV_CH_LAYOUT_4POINT1)
 390 #define AV_CHANNEL_LAYOUT_2_2               AV_CHANNEL_LAYOUT_MASK(4,  AV_CH_LAYOUT_2_2)
 391 #define AV_CHANNEL_LAYOUT_QUAD              AV_CHANNEL_LAYOUT_MASK(4,  AV_CH_LAYOUT_QUAD)
 392 #define AV_CHANNEL_LAYOUT_5POINT0           AV_CHANNEL_LAYOUT_MASK(5,  AV_CH_LAYOUT_5POINT0)
 393 #define AV_CHANNEL_LAYOUT_5POINT1           AV_CHANNEL_LAYOUT_MASK(6,  AV_CH_LAYOUT_5POINT1)
 394 #define AV_CHANNEL_LAYOUT_5POINT0_BACK      AV_CHANNEL_LAYOUT_MASK(5,  AV_CH_LAYOUT_5POINT0_BACK)
 395 #define AV_CHANNEL_LAYOUT_5POINT1_BACK      AV_CHANNEL_LAYOUT_MASK(6,  AV_CH_LAYOUT_5POINT1_BACK)
 396 #define AV_CHANNEL_LAYOUT_6POINT0           AV_CHANNEL_LAYOUT_MASK(6,  AV_CH_LAYOUT_6POINT0)
 397 #define AV_CHANNEL_LAYOUT_6POINT0_FRONT     AV_CHANNEL_LAYOUT_MASK(6,  AV_CH_LAYOUT_6POINT0_FRONT)
 398 #define AV_CHANNEL_LAYOUT_3POINT1POINT2     AV_CHANNEL_LAYOUT_MASK(6,  AV_CH_LAYOUT_3POINT1POINT2)
 399 #define AV_CHANNEL_LAYOUT_HEXAGONAL         AV_CHANNEL_LAYOUT_MASK(6,  AV_CH_LAYOUT_HEXAGONAL)
 400 #define AV_CHANNEL_LAYOUT_6POINT1           AV_CHANNEL_LAYOUT_MASK(7,  AV_CH_LAYOUT_6POINT1)
 401 #define AV_CHANNEL_LAYOUT_6POINT1_BACK      AV_CHANNEL_LAYOUT_MASK(7,  AV_CH_LAYOUT_6POINT1_BACK)
 402 #define AV_CHANNEL_LAYOUT_6POINT1_FRONT     AV_CHANNEL_LAYOUT_MASK(7,  AV_CH_LAYOUT_6POINT1_FRONT)
 403 #define AV_CHANNEL_LAYOUT_7POINT0           AV_CHANNEL_LAYOUT_MASK(7,  AV_CH_LAYOUT_7POINT0)
 404 #define AV_CHANNEL_LAYOUT_7POINT0_FRONT     AV_CHANNEL_LAYOUT_MASK(7,  AV_CH_LAYOUT_7POINT0_FRONT)
 405 #define AV_CHANNEL_LAYOUT_7POINT1           AV_CHANNEL_LAYOUT_MASK(8,  AV_CH_LAYOUT_7POINT1)
 406 #define AV_CHANNEL_LAYOUT_7POINT1_WIDE      AV_CHANNEL_LAYOUT_MASK(8,  AV_CH_LAYOUT_7POINT1_WIDE)
 407 #define AV_CHANNEL_LAYOUT_7POINT1_WIDE_BACK AV_CHANNEL_LAYOUT_MASK(8,  AV_CH_LAYOUT_7POINT1_WIDE_BACK)
 408 #define AV_CHANNEL_LAYOUT_5POINT1POINT2_BACK AV_CHANNEL_LAYOUT_MASK(8, AV_CH_LAYOUT_5POINT1POINT2_BACK)
 409 #define AV_CHANNEL_LAYOUT_OCTAGONAL         AV_CHANNEL_LAYOUT_MASK(8,  AV_CH_LAYOUT_OCTAGONAL)
 410 #define AV_CHANNEL_LAYOUT_CUBE              AV_CHANNEL_LAYOUT_MASK(8,  AV_CH_LAYOUT_CUBE)
 411 #define AV_CHANNEL_LAYOUT_5POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(10, AV_CH_LAYOUT_5POINT1POINT4_BACK)
 412 #define AV_CHANNEL_LAYOUT_7POINT1POINT2     AV_CHANNEL_LAYOUT_MASK(10, AV_CH_LAYOUT_7POINT1POINT2)
 413 #define AV_CHANNEL_LAYOUT_7POINT1POINT4_BACK AV_CHANNEL_LAYOUT_MASK(12, AV_CH_LAYOUT_7POINT1POINT4_BACK)
 414 #define AV_CHANNEL_LAYOUT_HEXADECAGONAL     AV_CHANNEL_LAYOUT_MASK(16, AV_CH_LAYOUT_HEXADECAGONAL)
 415 #define AV_CHANNEL_LAYOUT_STEREO_DOWNMIX    AV_CHANNEL_LAYOUT_MASK(2,  AV_CH_LAYOUT_STEREO_DOWNMIX)
 416 #define AV_CHANNEL_LAYOUT_22POINT2          AV_CHANNEL_LAYOUT_MASK(24, AV_CH_LAYOUT_22POINT2)
 417
 418 #define AV_CHANNEL_LAYOUT_7POINT1_TOP_BACK  AV_CHANNEL_LAYOUT_5POINT1POINT2_BACK
 419
 420 #define AV_CHANNEL_LAYOUT_AMBISONIC_FIRST_ORDER \
 421     { /* .order */ AV_CHANNEL_ORDER_AMBISONIC, \
 422       /* .nb_channels */ 4, \
 423       /* .u.mask */ { 0 }, \
 424       /* .opaque */ NULL }
 425 /** @} */
 426
 427 struct AVBPrint;
 428
 429 #if FF_API_OLD_CHANNEL_LAYOUT
 430 /**
 431  * @name Deprecated Functions
 432  * @{
 433  */
 434
 435 /**
 436  * Return a channel layout id that matches name, or 0 if no match is found.
 437  *
 438  * name can be one or several of the following notations,
 439  * separated by '+' or '|':
 440  * - the name of an usual channel layout (mono, stereo, 4.0, quad, 5.0,
 441  *   5.0(side), 5.1, 5.1(side), 7.1, 7.1(wide), downmix);
 442  * - the name of a single channel (FL, FR, FC, LFE, BL, BR, FLC, FRC, BC,
 443  *   SL, SR, TC, TFL, TFC, TFR, TBL, TBC, TBR, DL, DR);
 444  * - a number of channels, in decimal, followed by 'c', yielding
 445  *   the default channel layout for that number of channels (@see
 446  *   av_get_default_channel_layout);
 447  * - a channel layout mask, in hexadecimal starting with "0x" (see the
 448  *   AV_CH_* macros).
 449  *
 450  * Example: "stereo+FC" = "2c+FC" = "2c+1c" = "0x7"
 451  *
 452  * @deprecated use av_channel_layout_from_string()
 453  */
 454 attribute_deprecated
 455 uint64_t av_get_channel_layout(const char *name);
 456
 457 /**
 458  * Return a channel layout and the number of channels based on the specified name.
 459  *
 460  * This function is similar to (@see av_get_channel_layout), but can also parse
 461  * unknown channel layout specifications.
 462  *
 463  * @param[in]  name             channel layout specification string
 464  * @param[out] channel_layout   parsed channel layout (0 if unknown)
 465  * @param[out] nb_channels      number of channels
 466  *
 467  * @return 0 on success, AVERROR(EINVAL) if the parsing fails.
 468  * @deprecated use av_channel_layout_from_string()
 469  */
 470 attribute_deprecated
 471 int av_get_extended_channel_layout(const char *name, uint64_t* channel_layout, int* nb_channels);
 472
 473 /**
 474  * Return a description of a channel layout.
 475  * If nb_channels is <= 0, it is guessed from the channel_layout.
 476  *
 477  * @param buf put here the string containing the channel layout
 478  * @param buf_size size in bytes of the buffer
 479  * @param nb_channels number of channels
 480  * @param channel_layout channel layout bitset
 481  * @deprecated use av_channel_layout_describe()
 482  */
 483 attribute_deprecated
 484 void av_get_channel_layout_string(char *buf, int buf_size, int nb_channels, uint64_t channel_layout);
 485
 486 /**
 487  * Append a description of a channel layout to a bprint buffer.
 488  * @deprecated use av_channel_layout_describe()
 489  */
 490 attribute_deprecated
 491 void av_bprint_channel_layout(struct AVBPrint *bp, int nb_channels, uint64_t channel_layout);
 492
 493 /**
 494  * Return the number of channels in the channel layout.
 495  * @deprecated use AVChannelLayout.nb_channels
 496  */
 497 attribute_deprecated
 498 int av_get_channel_layout_nb_channels(uint64_t channel_layout);
 499
 500 /**
 501  * Return default channel layout for a given number of channels.
 502  *
 503  * @deprecated use av_channel_layout_default()
 504  */
 505 attribute_deprecated
 506 int64_t av_get_default_channel_layout(int nb_channels);
 507
 508 /**
 509  * Get the index of a channel in channel_layout.
 510  *
 511  * @param channel_layout channel layout bitset
 512  * @param channel a channel layout describing exactly one channel which must be
 513  *                present in channel_layout.
 514  *
 515  * @return index of channel in channel_layout on success, a negative AVERROR
 516  *         on error.
 517  *
 518  * @deprecated use av_channel_layout_index_from_channel()
 519  */
 520 attribute_deprecated
 521 int av_get_channel_layout_channel_index(uint64_t channel_layout,
 522                                         uint64_t channel);
 523
 524 /**
 525  * Get the channel with the given index in channel_layout.
 526  * @deprecated use av_channel_layout_channel_from_index()
 527  */
 528 attribute_deprecated
 529 uint64_t av_channel_layout_extract_channel(uint64_t channel_layout, int index);
 530
 531 /**
 532  * Get the name of a given channel.
 533  *
 534  * @return channel name on success, NULL on error.
 535  *
 536  * @deprecated use av_channel_name()
 537  */
 538 attribute_deprecated
 539 const char *av_get_channel_name(uint64_t channel);
 540
 541 /**
 542  * Get the description of a given channel.
 543  *
 544  * @param channel  a channel layout with a single channel
 545  * @return  channel description on success, NULL on error
 546  * @deprecated use av_channel_description()
 547  */
 548 attribute_deprecated
 549 const char *av_get_channel_description(uint64_t channel);
 550
 551 /**
 552  * Get the value and name of a standard channel layout.
 553  *
 554  * @param[in]  index   index in an internal list, starting at 0
 555  * @param[out] layout  channel layout mask
 556  * @param[out] name    name of the layout
 557  * @return  0  if the layout exists,
 558  *          <0 if index is beyond the limits
 559  * @deprecated use av_channel_layout_standard()
 560  */
 561 attribute_deprecated
 562 int av_get_standard_channel_layout(unsigned index, uint64_t *layout,
 563                                    const char **name);
 564 /**
 565  * @}
 566  */
 567 #endif
 568
 569 /**
 570  * Get a human readable string in an abbreviated form describing a given channel.
 571  * This is the inverse function of @ref av_channel_from_string().
 572  *
 573  * @param buf pre-allocated buffer where to put the generated string
 574  * @param buf_size size in bytes of the buffer.
 575  * @param channel the AVChannel whose name to get
 576  * @return amount of bytes needed to hold the output string, or a negative AVERROR
 577  *         on failure. If the returned value is bigger than buf_size, then the
 578  *         string was truncated.
 579  */
 580 int av_channel_name(char *buf, size_t buf_size, enum AVChannel channel);
 581
 582 /**
 583  * bprint variant of av_channel_name().
 584  *
 585  * @note the string will be appended to the bprint buffer.
 586  */
 587 void av_channel_name_bprint(struct AVBPrint *bp, enum AVChannel channel_id);
 588
 589 /**
 590  * Get a human readable string describing a given channel.
 591  *
 592  * @param buf pre-allocated buffer where to put the generated string
 593  * @param buf_size size in bytes of the buffer.
 594  * @param channel the AVChannel whose description to get
 595  * @return amount of bytes needed to hold the output string, or a negative AVERROR
 596  *         on failure. If the returned value is bigger than buf_size, then the
 597  *         string was truncated.
 598  */
 599 int av_channel_description(char *buf, size_t buf_size, enum AVChannel channel);
 600
 601 /**
 602  * bprint variant of av_channel_description().
 603  *
 604  * @note the string will be appended to the bprint buffer.
 605  */
 606 void av_channel_description_bprint(struct AVBPrint *bp, enum AVChannel channel_id);
 607
 608 /**
 609  * This is the inverse function of @ref av_channel_name().
 610  *
 611  * @return the channel with the given name
 612  *         AV_CHAN_NONE when name does not identify a known channel
 613  */
 614 enum AVChannel av_channel_from_string(const char *name);
 615
 616 /**
 617  * Initialize a native channel layout from a bitmask indicating which channels
 618  * are present.
 619  *
 620  * @param channel_layout the layout structure to be initialized
 621  * @param mask bitmask describing the channel layout
 622  *
 623  * @return 0 on success
 624  *         AVERROR(EINVAL) for invalid mask values
 625  */
 626 int av_channel_layout_from_mask(AVChannelLayout *channel_layout, uint64_t mask);
 627
 628 /**
 629  * Initialize a channel layout from a given string description.
 630  * The input string can be represented by:
 631  *  - the formal channel layout name (returned by av_channel_layout_describe())
 632  *  - single or multiple channel names (returned by av_channel_name(), eg. "FL",
 633  *    or concatenated with "+", each optionally containing a custom name after
 634  *    a "@", eg. "FL@Left+FR@Right+LFE")
 635  *  - a decimal or hexadecimal value of a native channel layout (eg. "4" or "0x4")
 636  *  - the number of channels with default layout (eg. "4c")
 637  *  - the number of unordered channels (eg. "4C" or "4 channels")
 638  *  - the ambisonic order followed by optional non-diegetic channels (eg.
 639  *    "ambisonic 2+stereo")
 640  *
 641  * @param channel_layout input channel layout
 642  * @param str string describing the channel layout
 643  * @return 0 channel layout was detected, AVERROR_INVALIDATATA otherwise
 644  */
 645 int av_channel_layout_from_string(AVChannelLayout *channel_layout,
 646                                   const char *str);
 647
 648 /**
 649  * Get the default channel layout for a given number of channels.
 650  *
 651  * @param ch_layout the layout structure to be initialized
 652  * @param nb_channels number of channels
 653  */
 654 void av_channel_layout_default(AVChannelLayout *ch_layout, int nb_channels);
 655
 656 /**
 657  * Iterate over all standard channel layouts.
 658  *
 659  * @param opaque a pointer where libavutil will store the iteration state. Must
 660  *               point to NULL to start the iteration.
 661  *
 662  * @return the standard channel layout or NULL when the iteration is
 663  *         finished
 664  */
 665 const AVChannelLayout *av_channel_layout_standard(void **opaque);
 666
 667 /**
 668  * Free any allocated data in the channel layout and reset the channel
 669  * count to 0.
 670  *
 671  * @param channel_layout the layout structure to be uninitialized
 672  */
 673 void av_channel_layout_uninit(AVChannelLayout *channel_layout);
 674
 675 /**
 676  * Make a copy of a channel layout. This differs from just assigning src to dst
 677  * in that it allocates and copies the map for AV_CHANNEL_ORDER_CUSTOM.
 678  *
 679  * @note the destination channel_layout will be always uninitialized before copy.
 680  *
 681  * @param dst destination channel layout
 682  * @param src source channel layout
 683  * @return 0 on success, a negative AVERROR on error.
 684  */
 685 int av_channel_layout_copy(AVChannelLayout *dst, const AVChannelLayout *src);
 686
 687 /**
 688  * Get a human-readable string describing the channel layout properties.
 689  * The string will be in the same format that is accepted by
 690  * @ref av_channel_layout_from_string(), allowing to rebuild the same
 691  * channel layout, except for opaque pointers.
 692  *
 693  * @param channel_layout channel layout to be described
 694  * @param buf pre-allocated buffer where to put the generated string
 695  * @param buf_size size in bytes of the buffer.
 696  * @return amount of bytes needed to hold the output string, or a negative AVERROR
 697  *         on failure. If the returned value is bigger than buf_size, then the
 698  *         string was truncated.
 699  */
 700 int av_channel_layout_describe(const AVChannelLayout *channel_layout,
 701                                char *buf, size_t buf_size);
 702
 703 /**
 704  * bprint variant of av_channel_layout_describe().
 705  *
 706  * @note the string will be appended to the bprint buffer.
 707  * @return 0 on success, or a negative AVERROR value on failure.
 708  */
 709 int av_channel_layout_describe_bprint(const AVChannelLayout *channel_layout,
 710                                       struct AVBPrint *bp);
 711
 712 /**
 713  * Get the channel with the given index in a channel layout.
 714  *
 715  * @param channel_layout input channel layout
 716  * @param idx index of the channel
 717  * @return channel with the index idx in channel_layout on success or
 718  *         AV_CHAN_NONE on failure (if idx is not valid or the channel order is
 719  *         unspecified)
 720  */
 721 enum AVChannel
 722 av_channel_layout_channel_from_index(const AVChannelLayout *channel_layout, unsigned int idx);
 723
 724 /**
 725  * Get the index of a given channel in a channel layout. In case multiple
 726  * channels are found, only the first match will be returned.
 727  *
 728  * @param channel_layout input channel layout
 729  * @param channel the channel whose index to obtain
 730  * @return index of channel in channel_layout on success or a negative number if
 731  *         channel is not present in channel_layout.
 732  */
 733 int av_channel_layout_index_from_channel(const AVChannelLayout *channel_layout,
 734                                          enum AVChannel channel);
 735
 736 /**
 737  * Get the index in a channel layout of a channel described by the given string.
 738  * In case multiple channels are found, only the first match will be returned.
 739  *
 740  * This function accepts channel names in the same format as
 741  * @ref av_channel_from_string().
 742  *
 743  * @param channel_layout input channel layout
 744  * @param name string describing the channel whose index to obtain
 745  * @return a channel index described by the given string, or a negative AVERROR
 746  *         value.
 747  */
 748 int av_channel_layout_index_from_string(const AVChannelLayout *channel_layout,
 749                                         const char *name);
 750
 751 /**
 752  * Get a channel described by the given string.
 753  *
 754  * This function accepts channel names in the same format as
 755  * @ref av_channel_from_string().
 756  *
 757  * @param channel_layout input channel layout
 758  * @param name string describing the channel to obtain
 759  * @return a channel described by the given string in channel_layout on success
 760  *         or AV_CHAN_NONE on failure (if the string is not valid or the channel
 761  *         order is unspecified)
 762  */
 763 enum AVChannel
 764 av_channel_layout_channel_from_string(const AVChannelLayout *channel_layout,
 765                                       const char *name);
 766
 767 /**
 768  * Find out what channels from a given set are present in a channel layout,
 769  * without regard for their positions.
 770  *
 771  * @param channel_layout input channel layout
 772  * @param mask a combination of AV_CH_* representing a set of channels
 773  * @return a bitfield representing all the channels from mask that are present
 774  *         in channel_layout
 775  */
 776 uint64_t av_channel_layout_subset(const AVChannelLayout *channel_layout,
 777                                   uint64_t mask);
 778
 779 /**
 780  * Check whether a channel layout is valid, i.e. can possibly describe audio
 781  * data.
 782  *
 783  * @param channel_layout input channel layout
 784  * @return 1 if channel_layout is valid, 0 otherwise.
 785  */
 786 int av_channel_layout_check(const AVChannelLayout *channel_layout);
 787
 788 /**
 789  * Check whether two channel layouts are semantically the same, i.e. the same
 790  * channels are present on the same positions in both.
 791  *
 792  * If one of the channel layouts is AV_CHANNEL_ORDER_UNSPEC, while the other is
 793  * not, they are considered to be unequal. If both are AV_CHANNEL_ORDER_UNSPEC,
 794  * they are considered equal iff the channel counts are the same in both.
 795  *
 796  * @param chl input channel layout
 797  * @param chl1 input channel layout
 798  * @return 0 if chl and chl1 are equal, 1 if they are not equal. A negative
 799  *         AVERROR code if one or both are invalid.
 800  */
 801 int av_channel_layout_compare(const AVChannelLayout *chl, const AVChannelLayout *chl1);
 802
 803 /**
 804  * @}
 805  */
 806
 807 #endif /* AVUTIL_CHANNEL_LAYOUT_H */