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 
24 /**
25  * A list of supported formats for one end of a filter link. This is used
26  * during the format negotiation process to try to pick the best format to
27  * use to minimize the number of necessary conversions. Each filter gives a
28  * list of the formats supported by each input and output pad. The list
29  * given for each pad need not be distinct - they may be references to the
30  * same list of formats, as is often the case when a filter supports multiple
31  * formats, but will always output the same format as it is given in input.
32  *
33  * In this way, a list of possible input formats and a list of possible
34  * output formats are associated with each link. When a set of formats is
35  * negotiated over a link, the input and output lists are merged to form a
36  * new list containing only the common elements of each list. In the case
37  * that there were no common elements, a format conversion is necessary.
38  * Otherwise, the lists are merged, and all other links which reference
39  * either of the format lists involved in the merge are also affected.
40  *
41  * For example, consider the filter chain:
42  * filter (a) --> (b) filter (b) --> (c) filter
43  *
44  * where the letters in parenthesis indicate a list of formats supported on
45  * the input or output of the link. Suppose the lists are as follows:
46  * (a) = {A, B}
47  * (b) = {A, B, C}
48  * (c) = {B, C}
49  *
50  * First, the first link's lists are merged, yielding:
51  * filter (a) --> (a) filter (a) --> (c) filter
52  *
53  * Notice that format list (b) now refers to the same list as filter list (a).
54  * Next, the lists for the second link are merged, yielding:
55  * filter (a) --> (a) filter (a) --> (a) filter
56  *
57  * where (a) = {B}.
58  *
59  * Unfortunately, when the format lists at the two ends of a link are merged,
60  * we must ensure that all links which reference either pre-merge format list
61  * get updated as well. Therefore, we have the format list structure store a
62  * pointer to each of the pointers to itself.
63  */
65  unsigned nb_formats; ///< number of formats
66  int *formats; ///< list of media formats
67 
68  unsigned refcount; ///< number of references to this list
69  struct AVFilterFormats ***refs; ///< references to this list
70 };
71 
72 /**
73  * A list of supported channel layouts.
74  *
75  * The list works the same as AVFilterFormats, except for the following
76  * differences:
77  * - A list with all_layouts = 1 means all channel layouts with a known
78  * disposition; nb_channel_layouts must then be 0.
79  * - A list with all_counts = 1 means all channel counts, with a known or
80  * unknown disposition; nb_channel_layouts must then be 0 and all_layouts 1.
81  * - The list must not contain a layout with a known disposition and a
82  * channel count with unknown disposition with the same number of channels
83  * (e.g. AV_CH_LAYOUT_STEREO and FF_COUNT2LAYOUT(2).
84  */
86  AVChannelLayout *channel_layouts; ///< list of channel layouts
87  int nb_channel_layouts; ///< number of channel layouts
88  char all_layouts; ///< accept any known channel layout
89  char all_counts; ///< accept any channel layout or count
90 
91  unsigned refcount; ///< number of references to this list
92  struct AVFilterChannelLayouts ***refs; ///< references to this list
93 };
94 
95 /**
96  * Encode a channel count as a channel layout.
97  * FF_COUNT2LAYOUT(c) means any channel layout with c channels, with a known
98  * or unknown disposition.
99  * The result is only valid inside AVFilterChannelLayouts and immediately
100  * related functions.
101  */
102 #define FF_COUNT2LAYOUT(c) ((AVChannelLayout) { .order = AV_CHANNEL_ORDER_UNSPEC, .nb_channels = c })
103 
104 /**
105  * Decode a channel count encoded as a channel layout.
106  * Return 0 if the channel layout was a real one.
107  */
108 #define FF_LAYOUT2COUNT(l) (((l)->order == AV_CHANNEL_ORDER_UNSPEC) ? \
109  (l)->nb_channels : 0)
110 
111 #define KNOWN(l) (!FF_LAYOUT2COUNT(l)) /* for readability */
112 
113 /**
114  * Construct an empty AVFilterChannelLayouts/AVFilterFormats struct --
115  * representing any channel layout (with known disposition)/sample rate.
116  */
119 
122 
123 /**
124  * Construct an AVFilterChannelLayouts coding for any channel layout, with
125  * known or unknown disposition.
126  */
129 
132 
133 /**
134  * Helpers for query_formats() which set all free audio links to the same list
135  * of channel layouts/sample rates. If there are no links hooked to this list,
136  * the list is freed.
137  */
141 /**
142  * Equivalent to ff_set_common_channel_layouts(ctx, ff_make_channel_layout_list(fmts))
143  */
146  const AVChannelLayout *fmts);
147 /**
148  * Equivalent to ff_set_common_channel_layouts(ctx, ff_all_channel_counts())
149  */
152 
155  AVFilterFormats *samplerates);
156 /**
157  * Equivalent to ff_set_common_samplerates(ctx, ff_make_format_list(samplerates))
158  */
161  const int *samplerates);
162 /**
163  * Equivalent to ff_set_common_samplerates(ctx, ff_all_samplerates())
164  */
167 
168 /**
169  * A helper for query_formats() which sets all links to the same list of
170  * formats. If there are no links hooked to this filter, the list of formats is
171  * freed.
172  */
175 
176 /**
177  * Equivalent to ff_set_common_formats(ctx, ff_make_format_list(fmts))
178  */
181 
184  const AVChannelLayout *channel_layout);
185 
186 /**
187  * Add *ref as a new reference to f.
188  */
192 
193 /**
194  * Remove a reference to a channel layouts list.
195  */
197 
199  AVFilterChannelLayouts **newref);
200 
203 
204 /**
205  * Create a list of supported formats. This is intended for use in
206  * AVFilter->query_formats().
207  *
208  * @param fmts list of media formats, terminated by -1
209  * @return the format list, with no existing references
210  */
212 AVFilterFormats *ff_make_format_list(const int *fmts);
213 
214 /**
215  * Equivalent to ff_make_format_list({const int[]}{ fmt, -1 })
216  */
219 
220 /**
221  * Add fmt to the list of media formats contained in *avff.
222  * If *avff is NULL the function allocates the filter formats struct
223  * and puts its pointer in *avff.
224  *
225  * @return a non negative value in case of success, or a negative
226  * value corresponding to an AVERROR code in case of error
227  */
229 int ff_add_format(AVFilterFormats **avff, int64_t fmt);
230 
231 /**
232  * Return a list of all formats supported by FFmpeg for the given media type.
233  */
236 
237 /**
238  * Construct a formats list containing all pixel formats with certain
239  * properties
240  */
242 AVFilterFormats *ff_formats_pixdesc_filter(unsigned want, unsigned rej);
243 
244 //* format is software, non-planar with sub-sampling
245 #define FF_PIX_FMT_FLAG_SW_FLAT_SUB (1 << 24)
246 
247 /**
248  * Construct a formats list containing all planar sample formats.
249  */
252 
253 /**
254  * Add *ref as a new reference to formats.
255  * That is the pointers will point like in the ascii art below:
256  * ________
257  * |formats |<--------.
258  * | ____ | ____|___________________
259  * | |refs| | | __|_
260  * | |* * | | | | | | AVFilterLink
261  * | |* *--------->|*ref|
262  * | |____| | | |____|
263  * |________| |________________________
264  */
267 
268 /**
269  * If *ref is non-NULL, remove *ref as a reference to the format list
270  * it currently points to, deallocates that list if this was the last
271  * reference, and sets *ref to NULL.
272  *
273  * Before After
274  * ________ ________ NULL
275  * |formats |<--------. |formats | ^
276  * | ____ | ____|________________ | ____ | ____|________________
277  * | |refs| | | __|_ | |refs| | | __|_
278  * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink
279  * | |* *--------->|*ref| | |* | | | |*ref|
280  * | |____| | | |____| | |____| | | |____|
281  * |________| |_____________________ |________| |_____________________
282  */
284 
285 /**
286  * Before After
287  * ________ ________
288  * |formats |<---------. |formats |<---------.
289  * | ____ | ___|___ | ____ | ___|___
290  * | |refs| | | | | | |refs| | | | | NULL
291  * | |* *--------->|*oldref| | |* *--------->|*newref| ^
292  * | |* * | | |_______| | |* * | | |_______| ___|___
293  * | |____| | | |____| | | | |
294  * |________| |________| |*oldref|
295  * |_______|
296  */
297 void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref);
298 
299 /**
300  * Check that fmts is a valid pixel formats list.
301  *
302  * In particular, check for duplicates.
303  */
304 int ff_formats_check_pixel_formats(void *log, const AVFilterFormats *fmts);
305 
306 /**
307  * Check that fmts is a valid sample formats list.
308  *
309  * In particular, check for duplicates.
310  */
311 int ff_formats_check_sample_formats(void *log, const AVFilterFormats *fmts);
312 
313 /**
314  * Check that fmts is a valid sample rates list.
315  *
316  * In particular, check for duplicates.
317  */
318 int ff_formats_check_sample_rates(void *log, const AVFilterFormats *fmts);
319 
320 /**
321  * Check that fmts is a valid channel layouts list.
322  *
323  * In particular, check for duplicates.
324  */
325 int ff_formats_check_channel_layouts(void *log, const AVFilterChannelLayouts *fmts);
326 
327 typedef struct AVFilterFormatMerger {
328  unsigned offset;
329  int (*merge)(void *a, void *b);
330  int (*can_merge)(const void *a, const void *b);
331 } AVFilterFormatsMerger;
332 
333 /**
334  * Callbacks and properties to describe the steps of a format negotiation.
335  *
336  * The steps are:
337  *
338  * 1. query_formats(): call the callbacks on all filter to set lists of
339  * supported formats.
340  * When links on a filter must eventually have the same
341  * format, the lists of supported formats are the same
342  * object in memory.
343  * See:
344  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#12
345  *
346  *
347  * 2. query_formats(): merge lists of supported formats or insert automatic
348  * conversion filters.
349  * Compute the intersection of the lists of supported
350  * formats on the ends of links. If it succeeds, replace
351  * both objects with the intersection everywhere they
352  * are referenced.
353  * If the intersection is empty, insert an automatic
354  * conversion filter.
355  * If several formats are negotiated at once (format,
356  * rate, layout), only merge if all three can be, since
357  * the conversion filter can convert all three at once.
358  * This process goes on as long as progress is made.
359  * See:
360  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#14
361  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#29
362  *
363  * 3. reduce_formats(): try to reduce format conversion within filters.
364  * For each link where there is only one supported
365  * formats on output, for each output of the connected
366  * filter, if the media type is the same and said
367  * format is supported, keep only this one.
368  * This process goes on as long as progress is made.
369  * Rationale: conversion filters will set a large list
370  * of supported formats on outputs but users will
371  * expect the output to be as close as possible as the
372  * input (examples: scale without changing the pixel
373  * format, resample without changint the layout).
374  * FIXME: this can probably be done by merging the
375  * input and output lists instead of re-implementing
376  * the logic.
377  *
378  * 4. swap_sample_fmts():
379  * swap_samplerates():
380  * swap_channel_layouts(): For each filter with an input with only one
381  * supported format, when outputs have several
382  * supported formats, put the best one with
383  * reference to the input at the beginning of the
384  * list, to prepare it for being picked up by
385  * pick_formats().
386  * The best format is the one that is most
387  * similar to the input while not losing too much
388  * information.
389  * This process need to run only once.
390  * FIXME: reduce_formats() operates on all inputs
391  * with a single format, swap_*() operates on the
392  * first one only: check if the difference makes
393  * sense.
394  * TODO: the swapping done for one filter can
395  * override the swapping done for another filter
396  * connected to the same list of formats, maybe
397  * it would be better to compute a total score
398  * for all connected filters and use the score to
399  * pick the format instead of just swapping.
400  * TODO: make the similarity logic available as
401  * public functions in libavutil.
402  *
403  * 5. pick_formats(): Choose one format from the lists of supported formats,
404  * use it for the link and reduce the list to a single
405  * element to force other filters connected to the same
406  * list to use it.
407  * First process all links where there is a single format
408  * and the output links of all filters with an input,
409  * trying to preserve similarity between input and
410  * outputs.
411  * Repeat as long as process is made.
412  * Then do a final run for the remaining filters.
413  * FIXME: the similarity logic (the ref argument to
414  * pick_format()) added in FFmpeg duplicates and
415  * overrides the swapping logic added in libav. Better
416  * merge them into a score system.
417  */
418 typedef struct AVFilterNegotiation {
419  unsigned nb_mergers;
420  const AVFilterFormatsMerger *mergers;
421  const char *conversion_filter;
424 
426 
427 #endif /* AVFILTER_FORMATS_H */
formats
formats
Definition: signature.h:48
ff_formats_changeref
void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref)
Definition: formats.c:671
AVFilterChannelLayouts
A list of supported channel layouts.
Definition: formats.h:85
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:923
ff_filter_get_negotiation
const AVFilterNegotiation * ff_filter_get_negotiation(AVFilterLink *link)
Definition: formats.c:342
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:557
layouts
enum MovChannelLayoutTag * layouts
Definition: mov_chan.c:326
ff_all_samplerates
av_warn_unused_result AVFilterFormats * ff_all_samplerates(void)
Definition: formats.c:551
ff_make_formats_list_singleton
av_warn_unused_result AVFilterFormats * ff_make_formats_list_singleton(int fmt)
Equivalent to ff_make_format_list({const int[]}{ fmt, -1 })
Definition: formats.c:474
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:635
AVFilterNegotiation::conversion_filter
const char * conversion_filter
Definition: formats.h:421
b
#define b
Definition: input.c:41
ff_channel_layouts_changeref
void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref, AVFilterChannelLayouts **newref)
Definition: formats.c:665
AVFilterFormats::formats
int * formats
list of media formats
Definition: formats.h:66
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:449
ff_add_channel_layout
av_warn_unused_result int ff_add_channel_layout(AVFilterChannelLayouts **l, const AVChannelLayout *channel_layout)
Definition: formats.c:466
AVFilterFormats
A list of supported formats for one end of a filter link.
Definition: formats.h:64
ff_default_query_formats
av_warn_unused_result int ff_default_query_formats(AVFilterContext *ctx)
Definition: formats.c:760
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:909
AVFilterNegotiation
Callbacks and properties to describe the steps of a format negotiation.
Definition: formats.h:418
AVFilterNegotiation::nb_mergers
unsigned nb_mergers
Definition: formats.h:419
AVFilterChannelLayouts::refs
struct AVFilterChannelLayouts *** refs
references to this list
Definition: formats.h:92
AVFilterFormats::refs
struct AVFilterFormats *** refs
references to this list
Definition: formats.h:69
ff_set_common_formats_from_list
av_warn_unused_result int ff_set_common_formats_from_list(AVFilterContext *ctx, const int *fmts)
Equivalent to ff_set_common_formats(ctx, ff_make_format_list(fmts))
Definition: formats.c:755
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:538
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:380
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:596
ctx
AVFormatContext * ctx
Definition: movenc.c:48
AVFilterNegotiation::mergers
const AVFilterFormatsMerger * mergers
Definition: formats.h:420
link
Filter the word “frame” indicates either a video frame or a group of audio as stored in an AVFrame structure Format for each input and each output the list of supported formats For video that means pixel format For audio that means channel sample they are references to shared objects When the negotiation mechanism computes the intersection of the formats supported at each end of a link
Definition: filter_design.txt:23
AVFilterFormatMerger::offset
unsigned offset
Definition: formats.h:328
AVFilterFormatMerger::can_merge
int(* can_merge)(const void *a, const void *b)
Definition: formats.h:330
AVFilterFormats::nb_formats
unsigned nb_formats
number of formats
Definition: formats.h:65
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:899
AVFilterFormats::refcount
unsigned refcount
number of references to this list
Definition: formats.h:68
ff_set_common_channel_layouts
av_warn_unused_result int ff_set_common_channel_layouts(AVFilterContext *ctx, AVFilterChannelLayouts *layouts)
Helpers for query_formats() which set all free audio links to the same list of channel layouts/sample...
Definition: formats.c:708
f
f
Definition: af_crystalizer.c:122
AVMediaType
AVMediaType
Definition: avutil.h:199
AVChannelLayout
An AVChannelLayout holds information about the channel layout of audio data.
Definition: channel_layout.h:301
ff_set_common_channel_layouts_from_list
av_warn_unused_result int ff_set_common_channel_layouts_from_list(AVFilterContext *ctx, const AVChannelLayout *fmts)
Equivalent to ff_set_common_channel_layouts(ctx, ff_make_channel_layout_list(fmts))
Definition: formats.c:715
AVFilterChannelLayouts::channel_layouts
AVChannelLayout * channel_layouts
list of channel layouts
Definition: formats.h:86
ff_set_common_samplerates_from_list
av_warn_unused_result int ff_set_common_samplerates_from_list(AVFilterContext *ctx, const int *samplerates)
Equivalent to ff_set_common_samplerates(ctx, ff_make_format_list(samplerates))
Definition: formats.c:733
AVFilterFormatMerger::merge
int(* merge)(void *a, void *b)
Definition: formats.h:329
AVFilterChannelLayouts::all_layouts
char all_layouts
accept any known channel layout
Definition: formats.h:88
AVFilterChannelLayouts::all_counts
char all_counts
accept any channel layout or count
Definition: formats.h:89
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:480
ff_make_channel_layout_list
av_warn_unused_result AVFilterChannelLayouts * ff_make_channel_layout_list(const AVChannelLayout *fmts)
Definition: formats.c:389
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_set_common_all_samplerates
av_warn_unused_result int ff_set_common_all_samplerates(AVFilterContext *ctx)
Equivalent to ff_set_common_samplerates(ctx, ff_all_samplerates())
Definition: formats.c:739
ff_set_common_all_channel_counts
av_warn_unused_result int ff_set_common_all_channel_counts(AVFilterContext *ctx)
Equivalent to ff_set_common_channel_layouts(ctx, ff_all_channel_counts())
Definition: formats.c:721
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:749
ff_channel_layouts_unref
void ff_channel_layouts_unref(AVFilterChannelLayouts **ref)
Remove a reference to a channel layouts list.
Definition: formats.c:647
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:904
AVFilterNegotiation::conversion_opts_offset
unsigned conversion_opts_offset
Definition: formats.h:422
avfilter.h
ref
static int ref[MAX_W *MAX_W]
Definition: jpeg2000dwt.c:112
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:591
AVFilterContext
An instance of a filter.
Definition: avfilter.h:392
AVFilterChannelLayouts::nb_channel_layouts
int nb_channel_layouts
number of channel layouts
Definition: formats.h:87
ff_set_common_samplerates
av_warn_unused_result int ff_set_common_samplerates(AVFilterContext *ctx, AVFilterFormats *samplerates)
Definition: formats.c:726
AVFilterFormatMerger
Definition: formats.h:327
AVFilterChannelLayouts::refcount
unsigned refcount
number of references to this list
Definition: formats.h:91
int
int
Definition: ffmpeg_filter.c:156
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:566
ff_formats_pixdesc_filter
av_warn_unused_result AVFilterFormats * ff_formats_pixdesc_filter(unsigned want, unsigned rej)
Construct a formats list containing all pixel formats with certain properties.
Definition: formats.c:498