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  uint64_t *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) (0x8000000000000000ULL | (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) & 0x8000000000000000ULL) ? \
109  (int)((l) & 0x7FFFFFFF) : 0)
110 
111 /**
112  * Construct an empty AVFilterChannelLayouts/AVFilterFormats struct --
113  * representing any channel layout (with known disposition)/sample rate.
114  */
117 
120 
121 /**
122  * Construct an AVFilterChannelLayouts coding for any channel layout, with
123  * known or unknown disposition.
124  */
127 
129 AVFilterChannelLayouts *ff_make_format64_list(const int64_t *fmts);
130 
131 /**
132  * Helpers for query_formats() which set all free audio links to the same list
133  * of channel layouts/sample rates. If there are no links hooked to this list,
134  * the list is freed.
135  */
139 /**
140  * Equivalent to ff_set_common_channel_layouts(ctx, ff_make_format64_list(fmts))
141  */
144  const int64_t *fmts);
145 /**
146  * Equivalent to ff_set_common_channel_layouts(ctx, ff_all_channel_counts())
147  */
150 
153  AVFilterFormats *samplerates);
154 /**
155  * Equivalent to ff_set_common_samplerates(ctx, ff_make_format_list(samplerates))
156  */
159  const int *samplerates);
160 /**
161  * Equivalent to ff_set_common_samplerates(ctx, ff_all_samplerates())
162  */
165 
166 /**
167  * A helper for query_formats() which sets all links to the same list of
168  * formats. If there are no links hooked to this filter, the list of formats is
169  * freed.
170  */
173 
174 /**
175  * Equivalent to ff_set_common_formats(ctx, ff_make_format_list(fmts))
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  * Equivalent to ff_make_format_list({const int[]}{ fmt, -1 })
213  */
216 
217 /**
218  * Add fmt to the list of media formats contained in *avff.
219  * If *avff is NULL the function allocates the filter formats struct
220  * and puts its pointer in *avff.
221  *
222  * @return a non negative value in case of success, or a negative
223  * value corresponding to an AVERROR code in case of error
224  */
226 int ff_add_format(AVFilterFormats **avff, int64_t fmt);
227 
228 /**
229  * Return a list of all formats supported by FFmpeg for the given media type.
230  */
233 
234 /**
235  * Construct a formats list containing all pixel formats with certain
236  * properties
237  */
239 AVFilterFormats *ff_formats_pixdesc_filter(unsigned want, unsigned rej);
240 
241 //* format is software, non-planar with sub-sampling
242 #define FF_PIX_FMT_FLAG_SW_FLAT_SUB (1 << 24)
243 
244 /**
245  * Construct a formats list containing all planar sample formats.
246  */
249 
250 /**
251  * Add *ref as a new reference to formats.
252  * That is the pointers will point like in the ascii art below:
253  * ________
254  * |formats |<--------.
255  * | ____ | ____|___________________
256  * | |refs| | | __|_
257  * | |* * | | | | | | AVFilterLink
258  * | |* *--------->|*ref|
259  * | |____| | | |____|
260  * |________| |________________________
261  */
264 
265 /**
266  * If *ref is non-NULL, remove *ref as a reference to the format list
267  * it currently points to, deallocates that list if this was the last
268  * reference, and sets *ref to NULL.
269  *
270  * Before After
271  * ________ ________ NULL
272  * |formats |<--------. |formats | ^
273  * | ____ | ____|________________ | ____ | ____|________________
274  * | |refs| | | __|_ | |refs| | | __|_
275  * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink
276  * | |* *--------->|*ref| | |* | | | |*ref|
277  * | |____| | | |____| | |____| | | |____|
278  * |________| |_____________________ |________| |_____________________
279  */
281 
282 /**
283  * Before After
284  * ________ ________
285  * |formats |<---------. |formats |<---------.
286  * | ____ | ___|___ | ____ | ___|___
287  * | |refs| | | | | | |refs| | | | | NULL
288  * | |* *--------->|*oldref| | |* *--------->|*newref| ^
289  * | |* * | | |_______| | |* * | | |_______| ___|___
290  * | |____| | | |____| | | | |
291  * |________| |________| |*oldref|
292  * |_______|
293  */
294 void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref);
295 
296 /**
297  * Check that fmts is a valid pixel formats list.
298  *
299  * In particular, check for duplicates.
300  */
301 int ff_formats_check_pixel_formats(void *log, const AVFilterFormats *fmts);
302 
303 /**
304  * Check that fmts is a valid sample formats list.
305  *
306  * In particular, check for duplicates.
307  */
308 int ff_formats_check_sample_formats(void *log, const AVFilterFormats *fmts);
309 
310 /**
311  * Check that fmts is a valid sample rates list.
312  *
313  * In particular, check for duplicates.
314  */
315 int ff_formats_check_sample_rates(void *log, const AVFilterFormats *fmts);
316 
317 /**
318  * Check that fmts is a valid channel layouts list.
319  *
320  * In particular, check for duplicates.
321  */
322 int ff_formats_check_channel_layouts(void *log, const AVFilterChannelLayouts *fmts);
323 
324 typedef struct AVFilterFormatMerger {
325  unsigned offset;
326  int (*merge)(void *a, void *b);
327  int (*can_merge)(const void *a, const void *b);
328 } AVFilterFormatsMerger;
329 
330 /**
331  * Callbacks and properties to describe the steps of a format negotiation.
332  *
333  * The steps are:
334  *
335  * 1. query_formats(): call the callbacks on all filter to set lists of
336  * supported formats.
337  * When links on a filter must eventually have the same
338  * format, the lists of supported formats are the same
339  * object in memory.
340  * See:
341  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#12
342  *
343  *
344  * 2. query_formats(): merge lists of supported formats or insert automatic
345  * conversion filters.
346  * Compute the intersection of the lists of supported
347  * formats on the ends of links. If it succeeds, replace
348  * both objects with the intersection everywhere they
349  * are referenced.
350  * If the intersection is empty, insert an automatic
351  * conversion filter.
352  * If several formats are negotiated at once (format,
353  * rate, layout), only merge if all three can be, since
354  * the conversion filter can convert all three at once.
355  * This process goes on as long as progress is made.
356  * See:
357  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#14
358  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#29
359  *
360  * 3. reduce_formats(): try to reduce format conversion within filters.
361  * For each link where there is only one supported
362  * formats on output, for each output of the connected
363  * filter, if the media type is the same and said
364  * format is supported, keep only this one.
365  * This process goes on as long as progress is made.
366  * Rationale: conversion filters will set a large list
367  * of supported formats on outputs but users will
368  * expect the output to be as close as possible as the
369  * input (examples: scale without changing the pixel
370  * format, resample without changint the layout).
371  * FIXME: this can probably be done by merging the
372  * input and output lists instead of re-implementing
373  * the logic.
374  *
375  * 4. swap_sample_fmts():
376  * swap_samplerates():
377  * swap_channel_layouts(): For each filter with an input with only one
378  * supported format, when outputs have several
379  * supported formats, put the best one with
380  * reference to the input at the beginning of the
381  * list, to prepare it for being picked up by
382  * pick_formats().
383  * The best format is the one that is most
384  * similar to the input while not losing too much
385  * information.
386  * This process need to run only once.
387  * FIXME: reduce_formats() operates on all inputs
388  * with a single format, swap_*() operates on the
389  * first one only: check if the difference makes
390  * sense.
391  * TODO: the swapping done for one filter can
392  * override the swapping done for another filter
393  * connected to the same list of formats, maybe
394  * it would be better to compute a total score
395  * for all connected filters and use the score to
396  * pick the format instead of just swapping.
397  * TODO: make the similarity logic available as
398  * public functions in libavutil.
399  *
400  * 5. pick_formats(): Choose one format from the lists of supported formats,
401  * use it for the link and reduce the list to a single
402  * element to force other filters connected to the same
403  * list to use it.
404  * First process all links where there is a single format
405  * and the output links of all filters with an input,
406  * trying to preserve similarity between input and
407  * outputs.
408  * Repeat as long as process is made.
409  * Then do a final run for the remaining filters.
410  * FIXME: the similarity logic (the ref argument to
411  * pick_format()) added in FFmpeg duplicates and
412  * overrides the swapping logic added in libav. Better
413  * merge them into a score system.
414  */
415 typedef struct AVFilterNegotiation {
416  unsigned nb_mergers;
417  const AVFilterFormatsMerger *mergers;
418  const char *conversion_filter;
421 
423 
424 #endif /* AVFILTER_FORMATS_H */
formats
formats
Definition: signature.h:48
ff_formats_changeref
void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref)
Definition: formats.c:621
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:855
ff_filter_get_negotiation
const AVFilterNegotiation * ff_filter_get_negotiation(AVFilterLink *link)
Definition: formats.c:343
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:516
layouts
enum MovChannelLayoutTag * layouts
Definition: mov_chan.c:434
ff_all_samplerates
av_warn_unused_result AVFilterFormats * ff_all_samplerates(void)
Definition: formats.c:510
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:433
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:592
AVFilterNegotiation::conversion_filter
const char * conversion_filter
Definition: formats.h:418
b
#define b
Definition: input.c:40
ff_channel_layouts_changeref
void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref, AVFilterChannelLayouts **newref)
Definition: formats.c:615
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:420
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:710
ff_add_channel_layout
av_warn_unused_result int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout)
Definition: formats.c:426
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:841
AVFilterNegotiation
Callbacks and properties to describe the steps of a format negotiation.
Definition: formats.h:415
AVFilterNegotiation::nb_mergers
unsigned nb_mergers
Definition: formats.h:416
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:705
AVFilterChannelLayouts::channel_layouts
uint64_t * channel_layouts
list of channel layouts
Definition: formats.h:86
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:497
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:381
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:555
ctx
AVFormatContext * ctx
Definition: movenc.c:48
f
#define f(width, name)
Definition: cbs_vp9.c:255
AVFilterNegotiation::mergers
const AVFilterFormatsMerger * mergers
Definition: formats.h:417
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:325
AVFilterFormatMerger::can_merge
int(* can_merge)(const void *a, const void *b)
Definition: formats.h:327
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:831
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:658
AVMediaType
AVMediaType
Definition: avutil.h:199
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:683
AVFilterFormatMerger::merge
int(* merge)(void *a, void *b)
Definition: formats.h:326
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:439
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:689
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:671
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:699
ff_set_common_channel_layouts_from_list
av_warn_unused_result int ff_set_common_channel_layouts_from_list(AVFilterContext *ctx, const int64_t *fmts)
Equivalent to ff_set_common_channel_layouts(ctx, ff_make_format64_list(fmts))
Definition: formats.c:665
ff_channel_layouts_unref
void ff_channel_layouts_unref(AVFilterChannelLayouts **ref)
Remove a reference to a channel layouts list.
Definition: formats.c:597
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:836
AVFilterNegotiation::conversion_opts_offset
unsigned conversion_opts_offset
Definition: formats.h:419
ff_make_format64_list
av_warn_unused_result AVFilterChannelLayouts * ff_make_format64_list(const int64_t *fmts)
Definition: formats.c:390
avfilter.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:550
AVFilterContext
An instance of a filter.
Definition: avfilter.h:386
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:676
AVFilterFormatMerger
Definition: formats.h:324
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:525
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:457