FFmpeg
formats.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 #ifndef AVFILTER_FORMATS_H
20 #define AVFILTER_FORMATS_H
21 
22 #include "avfilter.h"
23 #include "version.h"
24 
25 /**
26  * A list of supported formats for one end of a filter link. This is used
27  * during the format negotiation process to try to pick the best format to
28  * use to minimize the number of necessary conversions. Each filter gives a
29  * list of the formats supported by each input and output pad. The list
30  * given for each pad need not be distinct - they may be references to the
31  * same list of formats, as is often the case when a filter supports multiple
32  * formats, but will always output the same format as it is given in input.
33  *
34  * In this way, a list of possible input formats and a list of possible
35  * output formats are associated with each link. When a set of formats is
36  * negotiated over a link, the input and output lists are merged to form a
37  * new list containing only the common elements of each list. In the case
38  * that there were no common elements, a format conversion is necessary.
39  * Otherwise, the lists are merged, and all other links which reference
40  * either of the format lists involved in the merge are also affected.
41  *
42  * For example, consider the filter chain:
43  * filter (a) --> (b) filter (b) --> (c) filter
44  *
45  * where the letters in parenthesis indicate a list of formats supported on
46  * the input or output of the link. Suppose the lists are as follows:
47  * (a) = {A, B}
48  * (b) = {A, B, C}
49  * (c) = {B, C}
50  *
51  * First, the first link's lists are merged, yielding:
52  * filter (a) --> (a) filter (a) --> (c) filter
53  *
54  * Notice that format list (b) now refers to the same list as filter list (a).
55  * Next, the lists for the second link are merged, yielding:
56  * filter (a) --> (a) filter (a) --> (a) filter
57  *
58  * where (a) = {B}.
59  *
60  * Unfortunately, when the format lists at the two ends of a link are merged,
61  * we must ensure that all links which reference either pre-merge format list
62  * get updated as well. Therefore, we have the format list structure store a
63  * pointer to each of the pointers to itself.
64  */
66  unsigned nb_formats; ///< number of formats
67  int *formats; ///< list of media formats
68 
69  unsigned refcount; ///< number of references to this list
70  struct AVFilterFormats ***refs; ///< references to this list
71 };
72 
73 /**
74  * A list of supported channel layouts.
75  *
76  * The list works the same as AVFilterFormats, except for the following
77  * differences:
78  * - A list with all_layouts = 1 means all channel layouts with a known
79  * disposition; nb_channel_layouts must then be 0.
80  * - A list with all_counts = 1 means all channel counts, with a known or
81  * unknown disposition; nb_channel_layouts must then be 0 and all_layouts 1.
82  * - The list must not contain a layout with a known disposition and a
83  * channel count with unknown disposition with the same number of channels
84  * (e.g. AV_CH_LAYOUT_STEREO and FF_COUNT2LAYOUT(2).
85  */
87  uint64_t *channel_layouts; ///< list of channel layouts
88  int nb_channel_layouts; ///< number of channel layouts
89  char all_layouts; ///< accept any known channel layout
90  char all_counts; ///< accept any channel layout or count
91 
92  unsigned refcount; ///< number of references to this list
93  struct AVFilterChannelLayouts ***refs; ///< references to this list
94 };
95 
96 /**
97  * Encode a channel count as a channel layout.
98  * FF_COUNT2LAYOUT(c) means any channel layout with c channels, with a known
99  * or unknown disposition.
100  * The result is only valid inside AVFilterChannelLayouts and immediately
101  * related functions.
102  */
103 #define FF_COUNT2LAYOUT(c) (0x8000000000000000ULL | (c))
104 
105 /**
106  * Decode a channel count encoded as a channel layout.
107  * Return 0 if the channel layout was a real one.
108  */
109 #define FF_LAYOUT2COUNT(l) (((l) & 0x8000000000000000ULL) ? \
110  (int)((l) & 0x7FFFFFFF) : 0)
111 
112 /**
113  * Check the formats/samplerates lists for compatibility for merging
114  * without actually merging.
115  *
116  * @return 1 if they are compatible, 0 if not.
117  */
119  enum AVMediaType type);
121 
122 /**
123  * Merge the formats/channel layouts/samplerates lists if they are compatible
124  * and update all the references of a and b to point to the combined list and
125  * free the old lists as needed. The combined list usually contains the
126  * intersection of the lists of a and b.
127  *
128  * Both a and b must have owners (i.e. refcount > 0) for these functions.
129  *
130  * @return 1 if merging succeeded, 0 if a and b are incompatible
131  * and negative AVERROR code on failure.
132  * a and b are unmodified if 0 is returned.
133  */
137  enum AVMediaType type);
139 
140 /**
141  * Construct an empty AVFilterChannelLayouts/AVFilterFormats struct --
142  * representing any channel layout (with known disposition)/sample rate.
143  */
146 
149 
150 /**
151  * Construct an AVFilterChannelLayouts coding for any channel layout, with
152  * known or unknown disposition.
153  */
156 
158 AVFilterChannelLayouts *ff_make_format64_list(const int64_t *fmts);
159 
160 /**
161  * A helper for query_formats() which sets all links to the same list of channel
162  * layouts/sample rates. If there are no links hooked to this filter, the list
163  * is freed.
164  */
170  AVFilterFormats *samplerates);
171 
172 /**
173  * A helper for query_formats() which sets all links to the same list of
174  * formats. If there are no links hooked to this filter, the list of formats is
175  * freed.
176  */
179 
181 int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout);
182 
183 /**
184  * Add *ref as a new reference to f.
185  */
189 
190 /**
191  * Remove a reference to a channel layouts list.
192  */
194 
196  AVFilterChannelLayouts **newref);
197 
200 
201 /**
202  * Create a list of supported formats. This is intended for use in
203  * AVFilter->query_formats().
204  *
205  * @param fmts list of media formats, terminated by -1
206  * @return the format list, with no existing references
207  */
209 AVFilterFormats *ff_make_format_list(const int *fmts);
210 
211 /**
212  * Add fmt to the list of media formats contained in *avff.
213  * If *avff is NULL the function allocates the filter formats struct
214  * and puts its pointer in *avff.
215  *
216  * @return a non negative value in case of success, or a negative
217  * value corresponding to an AVERROR code in case of error
218  */
220 int ff_add_format(AVFilterFormats **avff, int64_t fmt);
221 
222 /**
223  * Return a list of all formats supported by FFmpeg for the given media type.
224  */
227 
228 /**
229  * Construct a formats list containing all pixel formats with certain
230  * properties
231  */
233 int ff_formats_pixdesc_filter(AVFilterFormats **rfmts, unsigned want, unsigned rej);
234 
235 //* format is software, non-planar with sub-sampling
236 #define FF_PIX_FMT_FLAG_SW_FLAT_SUB (1 << 24)
237 
238 /**
239  * Construct a formats list containing all planar sample formats.
240  */
243 
244 /**
245  * Add *ref as a new reference to formats.
246  * That is the pointers will point like in the ascii art below:
247  * ________
248  * |formats |<--------.
249  * | ____ | ____|___________________
250  * | |refs| | | __|_
251  * | |* * | | | | | | AVFilterLink
252  * | |* *--------->|*ref|
253  * | |____| | | |____|
254  * |________| |________________________
255  */
258 
259 /**
260  * If *ref is non-NULL, remove *ref as a reference to the format list
261  * it currently points to, deallocates that list if this was the last
262  * reference, and sets *ref to NULL.
263  *
264  * Before After
265  * ________ ________ NULL
266  * |formats |<--------. |formats | ^
267  * | ____ | ____|________________ | ____ | ____|________________
268  * | |refs| | | __|_ | |refs| | | __|_
269  * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink
270  * | |* *--------->|*ref| | |* | | | |*ref|
271  * | |____| | | |____| | |____| | | |____|
272  * |________| |_____________________ |________| |_____________________
273  */
275 
276 /**
277  * Before After
278  * ________ ________
279  * |formats |<---------. |formats |<---------.
280  * | ____ | ___|___ | ____ | ___|___
281  * | |refs| | | | | | |refs| | | | | NULL
282  * | |* *--------->|*oldref| | |* *--------->|*newref| ^
283  * | |* * | | |_______| | |* * | | |_______| ___|___
284  * | |____| | | |____| | | | |
285  * |________| |________| |*oldref|
286  * |_______|
287  */
288 void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref);
289 
290 /**
291  * Check that fmts is a valid pixel formats list.
292  *
293  * In particular, check for duplicates.
294  */
295 int ff_formats_check_pixel_formats(void *log, const AVFilterFormats *fmts);
296 
297 /**
298  * Check that fmts is a valid sample formats list.
299  *
300  * In particular, check for duplicates.
301  */
302 int ff_formats_check_sample_formats(void *log, const AVFilterFormats *fmts);
303 
304 /**
305  * Check that fmts is a valid sample rates list.
306  *
307  * In particular, check for duplicates.
308  */
309 int ff_formats_check_sample_rates(void *log, const AVFilterFormats *fmts);
310 
311 /**
312  * Check that fmts is a valid channel layouts list.
313  *
314  * In particular, check for duplicates.
315  */
316 int ff_formats_check_channel_layouts(void *log, const AVFilterChannelLayouts *fmts);
317 
318 #endif /* AVFILTER_FORMATS_H */
formats
formats
Definition: signature.h:48
ff_formats_changeref
void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref)
Definition: formats.c:525
AVFilterChannelLayouts
A list of supported channel layouts.
Definition: formats.h:86
ff_formats_check_channel_layouts
int ff_formats_check_channel_layouts(void *log, const AVFilterChannelLayouts *fmts)
Check that fmts is a valid channel layouts list.
Definition: formats.c:703
ff_all_channel_layouts
av_warn_unused_result AVFilterChannelLayouts * ff_all_channel_layouts(void)
Construct an empty AVFilterChannelLayouts/AVFilterFormats struct – representing any channel layout (w...
Definition: formats.c:420
layouts
enum MovChannelLayoutTag * layouts
Definition: mov_chan.c:434
ff_all_samplerates
av_warn_unused_result AVFilterFormats * ff_all_samplerates(void)
Definition: formats.c:414
ff_formats_unref
void ff_formats_unref(AVFilterFormats **ref)
If *ref is non-NULL, remove *ref as a reference to the format list it currently points to,...
Definition: formats.c:496
b
#define b
Definition: input.c:41
ff_channel_layouts_changeref
void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref, AVFilterChannelLayouts **newref)
Definition: formats.c:519
AVFilterFormats::formats
int * formats
list of media formats
Definition: formats.h:67
ff_add_format
av_warn_unused_result int ff_add_format(AVFilterFormats **avff, int64_t fmt)
Add fmt to the list of media formats contained in *avff.
Definition: formats.c:325
ff_can_merge_formats
int ff_can_merge_formats(const AVFilterFormats *a, const AVFilterFormats *b, enum AVMediaType type)
Check the formats/samplerates lists for compatibility for merging without actually merging.
Definition: formats.c:134
AVFilterFormats
A list of supported formats for one end of a filter link.
Definition: formats.h:65
ff_default_query_formats
av_warn_unused_result int ff_default_query_formats(AVFilterContext *ctx)
Definition: formats.c:586
ff_merge_samplerates
int ff_merge_samplerates(AVFilterFormats *a, AVFilterFormats *b)
Definition: formats.c:162
ff_add_channel_layout
av_warn_unused_result int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout)
Definition: formats.c:331
type
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf type
Definition: writing_filters.txt:86
ff_formats_check_sample_rates
int ff_formats_check_sample_rates(void *log, const AVFilterFormats *fmts)
Check that fmts is a valid sample rates list.
Definition: formats.c:689
AVFilterChannelLayouts::refs
struct AVFilterChannelLayouts *** refs
references to this list
Definition: formats.h:93
AVFilterFormats::refs
struct AVFilterFormats *** refs
references to this list
Definition: formats.h:70
AVFilterChannelLayouts::channel_layouts
uint64_t * channel_layouts
list of channel layouts
Definition: formats.h:87
ff_planar_sample_fmts
av_warn_unused_result AVFilterFormats * ff_planar_sample_fmts(void)
Construct a formats list containing all planar sample formats.
Definition: formats.c:401
ff_make_format_list
av_warn_unused_result AVFilterFormats * ff_make_format_list(const int *fmts)
Create a list of supported formats.
Definition: formats.c:286
ff_formats_ref
av_warn_unused_result int ff_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref)
Add *ref as a new reference to formats.
Definition: formats.c:459
ctx
AVFormatContext * ctx
Definition: movenc.c:48
f
#define f(width, name)
Definition: cbs_vp9.c:255
AVFilterFormats::nb_formats
unsigned nb_formats
number of formats
Definition: formats.h:66
ff_formats_check_pixel_formats
int ff_formats_check_pixel_formats(void *log, const AVFilterFormats *fmts)
Check that fmts is a valid pixel formats list.
Definition: formats.c:679
ff_merge_channel_layouts
int ff_merge_channel_layouts(AVFilterChannelLayouts *a, AVFilterChannelLayouts *b)
Merge the formats/channel layouts/samplerates lists if they are compatible and update all the referen...
Definition: formats.c:168
AVFilterFormats::refcount
unsigned refcount
number of references to this list
Definition: formats.h:69
ff_set_common_channel_layouts
av_warn_unused_result int ff_set_common_channel_layouts(AVFilterContext *ctx, AVFilterChannelLayouts *layouts)
A helper for query_formats() which sets all links to the same list of channel layouts/sample rates.
Definition: formats.c:561
ff_merge_formats
int ff_merge_formats(AVFilterFormats *a, AVFilterFormats *b, enum AVMediaType type)
Definition: formats.c:141
AVMediaType
AVMediaType
Definition: avutil.h:199
AVFilterChannelLayouts::all_layouts
char all_layouts
accept any known channel layout
Definition: formats.h:89
AVFilterChannelLayouts::all_counts
char all_counts
accept any channel layout or count
Definition: formats.h:90
ff_all_formats
av_warn_unused_result AVFilterFormats * ff_all_formats(enum AVMediaType type)
Return a list of all formats supported by FFmpeg for the given media type.
Definition: formats.c:338
a
The reader does not expect b to be semantically here and if the code is changed by maybe adding a a division or other the signedness will almost certainly be mistaken To avoid this confusion a new type was SUINT is the C unsigned type but it holds a signed int to use the same example SUINT a
Definition: undefined.txt:41
av_warn_unused_result
#define av_warn_unused_result
Definition: attributes.h:64
ff_can_merge_samplerates
int ff_can_merge_samplerates(const AVFilterFormats *a, const AVFilterFormats *b)
Definition: formats.c:157
ff_set_common_formats
av_warn_unused_result int ff_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats)
A helper for query_formats() which sets all links to the same list of formats.
Definition: formats.c:580
ff_channel_layouts_unref
void ff_channel_layouts_unref(AVFilterChannelLayouts **ref)
Remove a reference to a channel layouts list.
Definition: formats.c:501
ff_formats_check_sample_formats
int ff_formats_check_sample_formats(void *log, const AVFilterFormats *fmts)
Check that fmts is a valid sample formats list.
Definition: formats.c:684
ff_formats_pixdesc_filter
av_warn_unused_result int ff_formats_pixdesc_filter(AVFilterFormats **rfmts, unsigned want, unsigned rej)
Construct a formats list containing all pixel formats with certain properties.
Definition: formats.c:360
ff_make_format64_list
av_warn_unused_result AVFilterChannelLayouts * ff_make_format64_list(const int64_t *fmts)
Definition: formats.c:295
avfilter.h
version.h
ref
static int ref[MAX_W *MAX_W]
Definition: jpeg2000dwt.c:107
ff_channel_layouts_ref
av_warn_unused_result int ff_channel_layouts_ref(AVFilterChannelLayouts *f, AVFilterChannelLayouts **ref)
Add *ref as a new reference to f.
Definition: formats.c:454
AVFilterContext
An instance of a filter.
Definition: avfilter.h:333
AVFilterChannelLayouts::nb_channel_layouts
int nb_channel_layouts
number of channel layouts
Definition: formats.h:88
ff_set_common_samplerates
av_warn_unused_result int ff_set_common_samplerates(AVFilterContext *ctx, AVFilterFormats *samplerates)
Definition: formats.c:568
AVFilterChannelLayouts::refcount
unsigned refcount
number of references to this list
Definition: formats.h:92
ff_all_channel_counts
av_warn_unused_result AVFilterChannelLayouts * ff_all_channel_counts(void)
Construct an AVFilterChannelLayouts coding for any channel layout, with known or unknown disposition.
Definition: formats.c:429