2 * This file is part of FFmpeg.
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.
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.
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
19 #ifndef AVFILTER_FORMATS_H
20 #define AVFILTER_FORMATS_H
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.
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.
42 * For example, consider the filter chain:
43 * filter (a) --> (b) filter (b) --> (c) filter
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:
51 * First, the first link's lists are merged, yielding:
52 * filter (a) --> (a) filter (a) --> (c) filter
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
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.
65 struct AVFilterFormats {
66 unsigned nb_formats; ///< number of formats
67 int *formats; ///< list of media formats
69 unsigned refcount; ///< number of references to this list
70 struct AVFilterFormats ***refs; ///< references to this list
74 * A list of supported channel layouts.
76 * The list works the same as AVFilterFormats, except for the following
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).
86 struct AVFilterChannelLayouts {
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
92 unsigned refcount; ///< number of references to this list
93 struct AVFilterChannelLayouts ***refs; ///< references to this list
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
103 #define FF_COUNT2LAYOUT(c) (0x8000000000000000ULL | (c))
106 * Decode a channel count encoded as a channel layout.
107 * Return 0 if the channel layout was a real one.
109 #define FF_LAYOUT2COUNT(l) (((l) & 0x8000000000000000ULL) ? \
110 (int)((l) & 0x7FFFFFFF) : 0)
113 * Check the formats/samplerates lists for compatibility for merging
114 * without actually merging.
116 * @return 1 if they are compatible, 0 if not.
118 int ff_can_merge_formats(const AVFilterFormats *a, const AVFilterFormats *b,
119 enum AVMediaType type);
120 int ff_can_merge_samplerates(const AVFilterFormats *a, const AVFilterFormats *b);
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.
128 * Both a and b must have owners (i.e. refcount > 0) for these functions.
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.
134 int ff_merge_channel_layouts(AVFilterChannelLayouts *a,
135 AVFilterChannelLayouts *b);
136 int ff_merge_formats(AVFilterFormats *a, AVFilterFormats *b,
137 enum AVMediaType type);
138 int ff_merge_samplerates(AVFilterFormats *a, AVFilterFormats *b);
141 * Construct an empty AVFilterChannelLayouts/AVFilterFormats struct --
142 * representing any channel layout (with known disposition)/sample rate.
144 av_warn_unused_result
145 AVFilterChannelLayouts *ff_all_channel_layouts(void);
147 av_warn_unused_result
148 AVFilterFormats *ff_all_samplerates(void);
151 * Construct an AVFilterChannelLayouts coding for any channel layout, with
152 * known or unknown disposition.
154 av_warn_unused_result
155 AVFilterChannelLayouts *ff_all_channel_counts(void);
157 av_warn_unused_result
158 AVFilterChannelLayouts *ff_make_format64_list(const int64_t *fmts);
160 #if LIBAVFILTER_VERSION_MAJOR < 8
161 AVFilterChannelLayouts *avfilter_make_format64_list(const int64_t *fmts);
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
169 av_warn_unused_result
170 int ff_set_common_channel_layouts(AVFilterContext *ctx,
171 AVFilterChannelLayouts *layouts);
172 av_warn_unused_result
173 int ff_set_common_samplerates(AVFilterContext *ctx,
174 AVFilterFormats *samplerates);
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
181 av_warn_unused_result
182 int ff_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats);
184 av_warn_unused_result
185 int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout);
188 * Add *ref as a new reference to f.
190 av_warn_unused_result
191 int ff_channel_layouts_ref(AVFilterChannelLayouts *f,
192 AVFilterChannelLayouts **ref);
195 * Remove a reference to a channel layouts list.
197 void ff_channel_layouts_unref(AVFilterChannelLayouts **ref);
199 void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref,
200 AVFilterChannelLayouts **newref);
202 av_warn_unused_result
203 int ff_default_query_formats(AVFilterContext *ctx);
206 * Create a list of supported formats. This is intended for use in
207 * AVFilter->query_formats().
209 * @param fmts list of media formats, terminated by -1
210 * @return the format list, with no existing references
212 av_warn_unused_result
213 AVFilterFormats *ff_make_format_list(const int *fmts);
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.
220 * @return a non negative value in case of success, or a negative
221 * value corresponding to an AVERROR code in case of error
223 av_warn_unused_result
224 int ff_add_format(AVFilterFormats **avff, int64_t fmt);
227 * Return a list of all formats supported by FFmpeg for the given media type.
229 av_warn_unused_result
230 AVFilterFormats *ff_all_formats(enum AVMediaType type);
233 * Construct a formats list containing all pixel formats with certain
236 av_warn_unused_result
237 int ff_formats_pixdesc_filter(AVFilterFormats **rfmts, unsigned want, unsigned rej);
239 //* format is software, non-planar with sub-sampling
240 #define FF_PIX_FMT_FLAG_SW_FLAT_SUB (1 << 24)
243 * Construct a formats list containing all planar sample formats.
245 av_warn_unused_result
246 AVFilterFormats *ff_planar_sample_fmts(void);
249 * Add *ref as a new reference to formats.
250 * That is the pointers will point like in the ascii art below:
252 * |formats |<--------.
253 * | ____ | ____|___________________
255 * | |* * | | | | | | AVFilterLink
256 * | |* *--------->|*ref|
257 * | |____| | | |____|
258 * |________| |________________________
260 av_warn_unused_result
261 int ff_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref);
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.
269 * ________ ________ NULL
270 * |formats |<--------. |formats | ^
271 * | ____ | ____|________________ | ____ | ____|________________
272 * | |refs| | | __|_ | |refs| | | __|_
273 * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink
274 * | |* *--------->|*ref| | |* | | | |*ref|
275 * | |____| | | |____| | |____| | | |____|
276 * |________| |_____________________ |________| |_____________________
278 void ff_formats_unref(AVFilterFormats **ref);
283 * |formats |<---------. |formats |<---------.
284 * | ____ | ___|___ | ____ | ___|___
285 * | |refs| | | | | | |refs| | | | | NULL
286 * | |* *--------->|*oldref| | |* *--------->|*newref| ^
287 * | |* * | | |_______| | |* * | | |_______| ___|___
288 * | |____| | | |____| | | | |
289 * |________| |________| |*oldref|
292 void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref);
295 * Check that fmts is a valid pixel formats list.
297 * In particular, check for duplicates.
299 int ff_formats_check_pixel_formats(void *log, const AVFilterFormats *fmts);
302 * Check that fmts is a valid sample formats list.
304 * In particular, check for duplicates.
306 int ff_formats_check_sample_formats(void *log, const AVFilterFormats *fmts);
309 * Check that fmts is a valid sample rates list.
311 * In particular, check for duplicates.
313 int ff_formats_check_sample_rates(void *log, const AVFilterFormats *fmts);
316 * Check that fmts is a valid channel layouts list.
318 * In particular, check for duplicates.
320 int ff_formats_check_channel_layouts(void *log, const AVFilterChannelLayouts *fmts);
322 #endif /* AVFILTER_FORMATS_H */