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