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
36enum 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 */
52typedef 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 */
208AVCodecParameters *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 */
214void 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 */
222int avcodec_parameters_copy(AVCodecParameters *dst, const AVCodecParameters *src);
223
224
225/**
226 * @}
227 */
228
229#endif // AVCODEC_CODEC_PAR_H
230

source code of include/x86_64-linux-gnu/libavcodec/codec_par.h