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  * 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 typedef struct AVFilterFormatMerger {
319  unsigned offset;
320  int (*merge)(void *a, void *b);
321  int (*can_merge)(const void *a, const void *b);
322 } AVFilterFormatsMerger;
323 
324 /**
325  * Callbacks and properties to describe the steps of a format negotiation.
326  *
327  * The steps are:
328  *
329  * 1. query_formats(): call the callbacks on all filter to set lists of
330  * supported formats.
331  * When links on a filter must eventually have the same
332  * format, the lists of supported formats are the same
333  * object in memory.
334  * See:
335  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#12
336  *
337  *
338  * 2. query_formats(): merge lists of supported formats or insert automatic
339  * conversion filters.
340  * Compute the intersection of the lists of supported
341  * formats on the ends of links. If it succeeds, replace
342  * both objects with the intersection everywhere they
343  * are referenced.
344  * If the intersection is empty, insert an automatic
345  * conversion filter.
346  * If several formats are negotiated at once (format,
347  * rate, layout), only merge if all three can be, since
348  * the conversion filter can convert all three at once.
349  * This process goes on as long as progress is made.
350  * See:
351  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#14
352  * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#29
353  *
354  * 3. reduce_formats(): try to reduce format conversion within filters.
355  * For each link where there is only one supported
356  * formats on output, for each output of the connected
357  * filter, if the media type is the same and said
358  * format is supported, keep only this one.
359  * This process goes on as long as progress is made.
360  * Rationale: conversion filters will set a large list
361  * of supported formats on outputs but users will
362  * expect the output to be as close as possible as the
363  * input (examples: scale without changing the pixel
364  * format, resample without changint the layout).
365  * FIXME: this can probably be done by merging the
366  * input and output lists instead of re-implementing
367  * the logic.
368  *
369  * 4. swap_sample_fmts():
370  * swap_samplerates():
371  * swap_channel_layouts(): For each filter with an input with only one
372  * supported format, when outputs have several
373  * supported formats, put the best one with
374  * reference to the input at the beginning of the
375  * list, to prepare it for being picked up by
376  * pick_formats().
377  * The best format is the one that is most
378  * similar to the input while not losing too much
379  * information.
380  * This process need to run only once.
381  * FIXME: reduce_formats() operates on all inputs
382  * with a single format, swap_*() operates on the
383  * first one only: check if the difference makes
384  * sense.
385  * TODO: the swapping done for one filter can
386  * override the swapping done for another filter
387  * connected to the same list of formats, maybe
388  * it would be better to compute a total score
389  * for all connected filters and use the score to
390  * pick the format instead of just swapping.
391  * TODO: make the similarity logic available as
392  * public functions in libavutil.
393  *
394  * 5. pick_formats(): Choose one format from the lists of supported formats,
395  * use it for the link and reduce the list to a single
396  * element to force other filters connected to the same
397  * list to use it.
398  * First process all links where there is a single format
399  * and the output links of all filters with an input,
400  * trying to preserve similarity between input and
401  * outputs.
402  * Repeat as long as process is made.
403  * Then do a final run for the remaining filters.
404  * FIXME: the similarity logic (the ref argument to
405  * pick_format()) added in FFmpeg duplicates and
406  * overrides the swapping logic added in libav. Better
407  * merge them into a score system.
408  */
409 typedef struct AVFilterNegotiation {
410  unsigned nb_mergers;
411  const AVFilterFormatsMerger *mergers;
412  const char *conversion_filter;
415 
417 
418 #endif /* AVFILTER_FORMATS_H */
formats
formats
Definition: signature.h:48
ff_formats_changeref
void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref)
Definition: formats.c:619
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:825
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:514
layouts
enum MovChannelLayoutTag * layouts
Definition: mov_chan.c:434
ff_all_samplerates
av_warn_unused_result AVFilterFormats * ff_all_samplerates(void)
Definition: formats.c:508
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:590
AVFilterNegotiation::conversion_filter
const char * conversion_filter
Definition: formats.h:412
b
#define b
Definition: input.c:40
ff_channel_layouts_changeref
void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref, AVFilterChannelLayouts **newref)
Definition: formats.c:613
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:419
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:708
ff_add_channel_layout
av_warn_unused_result int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout)
Definition: formats.c:425
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:811
AVFilterNegotiation
Callbacks and properties to describe the steps of a format negotiation.
Definition: formats.h:409
AVFilterNegotiation::nb_mergers
unsigned nb_mergers
Definition: formats.h:410
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:703
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:495
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:553
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:411
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:319
AVFilterFormatMerger::can_merge
int(* can_merge)(const void *a, const void *b)
Definition: formats.h:321
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:801
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:656
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:681
AVFilterFormatMerger::merge
int(* merge)(void *a, void *b)
Definition: formats.h:320
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:432
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:687
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:669
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:697
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:663
ff_channel_layouts_unref
void ff_channel_layouts_unref(AVFilterChannelLayouts **ref)
Remove a reference to a channel layouts list.
Definition: formats.c:595
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:806
AVFilterNegotiation::conversion_opts_offset
unsigned conversion_opts_offset
Definition: formats.h:413
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:454
ff_make_format64_list
av_warn_unused_result AVFilterChannelLayouts * ff_make_format64_list(const int64_t *fmts)
Definition: formats.c:389
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:548
AVFilterContext
An instance of a filter.
Definition: avfilter.h:346
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:674
AVFilterFormatMerger
Definition: formats.h:318
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:523