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 #if LIBAVFILTER_VERSION_MAJOR < 8
162 #endif
163 
164 /**
165  * A helper for query_formats() which sets all links to the same list of channel
166  * layouts/sample rates. If there are no links hooked to this filter, the list
167  * is freed.
168  */
174  AVFilterFormats *samplerates);
175 
176 /**
177  * A helper for query_formats() which sets all links to the same list of
178  * formats. If there are no links hooked to this filter, the list of formats is
179  * freed.
180  */
183 
185 int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout);
186 
187 /**
188  * Add *ref as a new reference to f.
189  */
193 
194 /**
195  * Remove a reference to a channel layouts list.
196  */
198 
200  AVFilterChannelLayouts **newref);
201 
204 
205 /**
206  * Create a list of supported formats. This is intended for use in
207  * AVFilter->query_formats().
208  *
209  * @param fmts list of media formats, terminated by -1
210  * @return the format list, with no existing references
211  */
213 AVFilterFormats *ff_make_format_list(const int *fmts);
214 
215 /**
216  * Add fmt to the list of media formats contained in *avff.
217  * If *avff is NULL the function allocates the filter formats struct
218  * and puts its pointer in *avff.
219  *
220  * @return a non negative value in case of success, or a negative
221  * value corresponding to an AVERROR code in case of error
222  */
224 int ff_add_format(AVFilterFormats **avff, int64_t fmt);
225 
226 /**
227  * Return a list of all formats supported by FFmpeg for the given media type.
228  */
231 
232 /**
233  * Construct a formats list containing all pixel formats with certain
234  * properties
235  */
237 int ff_formats_pixdesc_filter(AVFilterFormats **rfmts, unsigned want, unsigned rej);
238 
239 //* format is software, non-planar with sub-sampling
240 #define FF_PIX_FMT_FLAG_SW_FLAT_SUB (1 << 24)
241 
242 /**
243  * Construct a formats list containing all planar sample formats.
244  */
247 
248 /**
249  * Add *ref as a new reference to formats.
250  * That is the pointers will point like in the ascii art below:
251  * ________
252  * |formats |<--------.
253  * | ____ | ____|___________________
254  * | |refs| | | __|_
255  * | |* * | | | | | | AVFilterLink
256  * | |* *--------->|*ref|
257  * | |____| | | |____|
258  * |________| |________________________
259  */
262 
263 /**
264  * If *ref is non-NULL, remove *ref as a reference to the format list
265  * it currently points to, deallocates that list if this was the last
266  * reference, and sets *ref to NULL.
267  *
268  * Before After
269  * ________ ________ NULL
270  * |formats |<--------. |formats | ^
271  * | ____ | ____|________________ | ____ | ____|________________
272  * | |refs| | | __|_ | |refs| | | __|_
273  * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink
274  * | |* *--------->|*ref| | |* | | | |*ref|
275  * | |____| | | |____| | |____| | | |____|
276  * |________| |_____________________ |________| |_____________________
277  */
279 
280 /**
281  * Before After
282  * ________ ________
283  * |formats |<---------. |formats |<---------.
284  * | ____ | ___|___ | ____ | ___|___
285  * | |refs| | | | | | |refs| | | | | NULL
286  * | |* *--------->|*oldref| | |* *--------->|*newref| ^
287  * | |* * | | |_______| | |* * | | |_______| ___|___
288  * | |____| | | |____| | | | |
289  * |________| |________| |*oldref|
290  * |_______|
291  */
292 void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref);
293 
294 /**
295  * Check that fmts is a valid pixel formats list.
296  *
297  * In particular, check for duplicates.
298  */
299 int ff_formats_check_pixel_formats(void *log, const AVFilterFormats *fmts);
300 
301 /**
302  * Check that fmts is a valid sample formats list.
303  *
304  * In particular, check for duplicates.
305  */
306 int ff_formats_check_sample_formats(void *log, const AVFilterFormats *fmts);
307 
308 /**
309  * Check that fmts is a valid sample rates list.
310  *
311  * In particular, check for duplicates.
312  */
313 int ff_formats_check_sample_rates(void *log, const AVFilterFormats *fmts);
314 
315 /**
316  * Check that fmts is a valid channel layouts list.
317  *
318  * In particular, check for duplicates.
319  */
320 int ff_formats_check_channel_layouts(void *log, const AVFilterChannelLayouts *fmts);
321 
322 #endif /* AVFILTER_FORMATS_H */
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:333
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:135
int ff_formats_check_channel_layouts(void *log, const AVFilterChannelLayouts *fmts)
Check that fmts is a valid channel layouts list.
Definition: formats.c:711
Main libavfilter public API header.
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:437
av_warn_unused_result AVFilterChannelLayouts * ff_all_channel_layouts(void)
Construct an empty AVFilterChannelLayouts/AVFilterFormats struct – representing any channel layout (...
Definition: formats.c:428
Libavfilter version macros.
av_warn_unused_result AVFilterFormats * ff_all_samplerates(void)
Definition: formats.c:422
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:36
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:504
GLint GLenum type
Definition: opengl_enc.c:104
int ff_merge_samplerates(AVFilterFormats *a, AVFilterFormats *b)
Definition: formats.c:163
struct AVFilterChannelLayouts *** refs
references to this list
Definition: formats.h:93
#define f(width, name)
Definition: cbs_vp9.c:255
av_warn_unused_result int ff_default_query_formats(AVFilterContext *ctx)
Definition: formats.c:594
struct AVFilterFormats *** refs
references to this list
Definition: formats.h:70
void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref, AVFilterChannelLayouts **newref)
Definition: formats.c:527
int ff_formats_check_sample_rates(void *log, const AVFilterFormats *fmts)
Check that fmts is a valid sample rates list.
Definition: formats.c:697
unsigned refcount
number of references to this list
Definition: formats.h:69
av_warn_unused_result int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout)
Definition: formats.c:339
uint64_t * channel_layouts
list of channel layouts
Definition: formats.h:87
av_warn_unused_result AVFilterFormats * ff_make_format_list(const int *fmts)
Create a list of supported formats.
Definition: formats.c:287
int ff_formats_check_pixel_formats(void *log, const AVFilterFormats *fmts)
Check that fmts is a valid pixel formats list.
Definition: formats.c:687
char all_counts
accept any channel layout or count
Definition: formats.h:90
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:569
#define b
Definition: input.c:41
av_warn_unused_result AVFilterFormats * ff_planar_sample_fmts(void)
Construct a formats list containing all planar sample formats.
Definition: formats.c:409
av_warn_unused_result int ff_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref)
Add *ref as a new reference to formats.
Definition: formats.c:467
AVFormatContext * ctx
Definition: movenc.c:48
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:169
unsigned nb_formats
number of formats
Definition: formats.h:66
A list of supported channel layouts.
Definition: formats.h:86
int ff_formats_check_sample_formats(void *log, const AVFilterFormats *fmts)
Check that fmts is a valid sample formats list.
Definition: formats.c:692
int ff_can_merge_samplerates(const AVFilterFormats *a, const AVFilterFormats *b)
Definition: formats.c:158
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:588
char all_layouts
accept any known channel layout
Definition: formats.h:89
av_warn_unused_result int ff_channel_layouts_ref(AVFilterChannelLayouts *f, AVFilterChannelLayouts **ref)
Add *ref as a new reference to f.
Definition: formats.c:462
int ff_merge_formats(AVFilterFormats *a, AVFilterFormats *b, enum AVMediaType type)
Definition: formats.c:142
AVMediaType
Definition: avutil.h:199
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:368
enum MovChannelLayoutTag * layouts
Definition: mov_chan.c:434
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:346
#define av_warn_unused_result
Definition: attributes.h:62
static int ref[MAX_W *MAX_W]
Definition: jpeg2000dwt.c:107
int nb_channel_layouts
number of channel layouts
Definition: formats.h:88
AVFilterChannelLayouts * avfilter_make_format64_list(const int64_t *fmts)
Definition: formats.c:308
unsigned refcount
number of references to this list
Definition: formats.h:92
A list of supported formats for one end of a filter link.
Definition: formats.h:65
void ff_channel_layouts_unref(AVFilterChannelLayouts **ref)
Remove a reference to a channel layouts list.
Definition: formats.c:509
An instance of a filter.
Definition: avfilter.h:341
av_warn_unused_result int ff_set_common_samplerates(AVFilterContext *ctx, AVFilterFormats *samplerates)
Definition: formats.c:576
formats
Definition: signature.h:48
av_warn_unused_result AVFilterChannelLayouts * ff_make_format64_list(const int64_t *fmts)
Definition: formats.c:296
void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref)
Before After |formats |<------—.
Definition: formats.c:533
int * formats
list of media formats
Definition: formats.h:67