git.sesse.net Git - ffmpeg/blob - libavcodec/codec_par.h

   1 /*
   2  * Codec parameters public API
   3  *
   4  * This file is part of FFmpeg.
   5  *
   6  * FFmpeg is free software; you can redistribute it and/or
   7  * modify it under the terms of the GNU Lesser General Public
   8  * License as published by the Free Software Foundation; either
   9  * version 2.1 of the License, or (at your option) any later version.
  10  *
  11  * FFmpeg is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14  * Lesser General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU Lesser General Public
  17  * License along with FFmpeg; if not, write to the Free Software
  18  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  19  */
  20
  21 #ifndef AVCODEC_CODEC_PAR_H
  22 #define AVCODEC_CODEC_PAR_H
  23
  24 #include <stdint.h>
  25
  26 #include "libavutil/avutil.h"
  27 #include "libavutil/rational.h"
  28 #include "libavutil/pixfmt.h"
  29
  30 #include "codec_id.h"
  31
  32 /**
  33  * @addtogroup lavc_core
  34  */
  35
  36 enum AVFieldOrder {
  37     AV_FIELD_UNKNOWN,
  38     AV_FIELD_PROGRESSIVE,
  39     AV_FIELD_TT,          //< Top coded_first, top displayed first
  40     AV_FIELD_BB,          //< Bottom coded first, bottom displayed first
  41     AV_FIELD_TB,          //< Top coded first, bottom displayed first
  42     AV_FIELD_BT,          //< Bottom coded first, top displayed first
  43 };
  44
  45 /**
  46  * This struct describes the properties of an encoded stream.
  47  *
  48  * sizeof(AVCodecParameters) is not a part of the public ABI, this struct must
  49  * be allocated with avcodec_parameters_alloc() and freed with
  50  * avcodec_parameters_free().
  51  */
  52 typedef struct AVCodecParameters {
  53     /**
  54      * General type of the encoded data.
  55      */
  56     enum AVMediaType codec_type;
  57     /**
  58      * Specific type of the encoded data (the codec used).
  59      */
  60     enum AVCodecID   codec_id;
  61     /**
  62      * Additional information about the codec (corresponds to the AVI FOURCC).
  63      */
  64     uint32_t         codec_tag;
  65
  66     /**
  67      * Extra binary data needed for initializing the decoder, codec-dependent.
  68      *
  69      * Must be allocated with av_malloc() and will be freed by
  70      * avcodec_parameters_free(). The allocated size of extradata must be at
  71      * least extradata_size + AV_INPUT_BUFFER_PADDING_SIZE, with the padding
  72      * bytes zeroed.
  73      */
  74     uint8_t *extradata;
  75     /**
  76      * Size of the extradata content in bytes.
  77      */
  78     int      extradata_size;
  79
  80     /**
  81      * - video: the pixel format, the value corresponds to enum AVPixelFormat.
  82      * - audio: the sample format, the value corresponds to enum AVSampleFormat.
  83      */
  84     int format;
  85
  86     /**
  87      * The average bitrate of the encoded data (in bits per second).
  88      */
  89     int64_t bit_rate;
  90
  91     /**
  92      * The number of bits per sample in the codedwords.
  93      *
  94      * This is basically the bitrate per sample. It is mandatory for a bunch of
  95      * formats to actually decode them. It's the number of bits for one sample in
  96      * the actual coded bitstream.
  97      *
  98      * This could be for example 4 for ADPCM
  99      * For PCM formats this matches bits_per_raw_sample
 100      * Can be 0
 101      */
 102     int bits_per_coded_sample;
 103
 104     /**
 105      * This is the number of valid bits in each output sample. If the
 106      * sample format has more bits, the least significant bits are additional
 107      * padding bits, which are always 0. Use right shifts to reduce the sample
 108      * to its actual size. For example, audio formats with 24 bit samples will
 109      * have bits_per_raw_sample set to 24, and format set to AV_SAMPLE_FMT_S32.
 110      * To get the original sample use "(int32_t)sample >> 8"."
 111      *
 112      * For ADPCM this might be 12 or 16 or similar
 113      * Can be 0
 114      */
 115     int bits_per_raw_sample;
 116
 117     /**
 118      * Codec-specific bitstream restrictions that the stream conforms to.
 119      */
 120     int profile;
 121     int level;
 122
 123     /**
 124      * Video only. The dimensions of the video frame in pixels.
 125      */
 126     int width;
 127     int height;
 128
 129     /**
 130      * Video only. The aspect ratio (width / height) which a single pixel
 131      * should have when displayed.
 132      *
 133      * When the aspect ratio is unknown / undefined, the numerator should be
 134      * set to 0 (the denominator may have any value).
 135      */
 136     AVRational sample_aspect_ratio;
 137
 138     /**
 139      * Video only. The order of the fields in interlaced video.
 140      */
 141     enum AVFieldOrder                  field_order;
 142
 143     /**
 144      * Video only. Additional colorspace characteristics.
 145      */
 146     enum AVColorRange                  color_range;
 147     enum AVColorPrimaries              color_primaries;
 148     enum AVColorTransferCharacteristic color_trc;
 149     enum AVColorSpace                  color_space;
 150     enum AVChromaLocation              chroma_location;
 151
 152     /**
 153      * Video only. Number of delayed frames.
 154      */
 155     int video_delay;
 156
 157     /**
 158      * Audio only. The channel layout bitmask. May be 0 if the channel layout is
 159      * unknown or unspecified, otherwise the number of bits set must be equal to
 160      * the channels field.
 161      */
 162     uint64_t channel_layout;
 163     /**
 164      * Audio only. The number of audio channels.
 165      */
 166     int      channels;
 167     /**
 168      * Audio only. The number of audio samples per second.
 169      */
 170     int      sample_rate;
 171     /**
 172      * Audio only. The number of bytes per coded audio frame, required by some
 173      * formats.
 174      *
 175      * Corresponds to nBlockAlign in WAVEFORMATEX.
 176      */
 177     int      block_align;
 178     /**
 179      * Audio only. Audio frame size, if known. Required by some formats to be static.
 180      */
 181     int      frame_size;
 182
 183     /**
 184      * Audio only. The amount of padding (in samples) inserted by the encoder at
 185      * the beginning of the audio. I.e. this number of leading decoded samples
 186      * must be discarded by the caller to get the original audio without leading
 187      * padding.
 188      */
 189     int initial_padding;
 190     /**
 191      * Audio only. The amount of padding (in samples) appended by the encoder to
 192      * the end of the audio. I.e. this number of decoded samples must be
 193      * discarded by the caller from the end of the stream to get the original
 194      * audio without any trailing padding.
 195      */
 196     int trailing_padding;
 197     /**
 198      * Audio only. Number of samples to skip after a discontinuity.
 199      */
 200     int seek_preroll;
 201 } AVCodecParameters;
 202
 203 /**
 204  * Allocate a new AVCodecParameters and set its fields to default values
 205  * (unknown/invalid/0). The returned struct must be freed with
 206  * avcodec_parameters_free().
 207  */
 208 AVCodecParameters *avcodec_parameters_alloc(void);
 209
 210 /**
 211  * Free an AVCodecParameters instance and everything associated with it and
 212  * write NULL to the supplied pointer.
 213  */
 214 void avcodec_parameters_free(AVCodecParameters **par);
 215
 216 /**
 217  * Copy the contents of src to dst. Any allocated fields in dst are freed and
 218  * replaced with newly allocated duplicates of the corresponding fields in src.
 219  *
 220  * @return >= 0 on success, a negative AVERROR code on failure.
 221  */
 222 int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
 223
 224
 225 /**
 226  * @}
 227  */
 228
 229 #endif // AVCODEC_CODEC_PAR_H