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
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 */
67
68 unsigned refcount;
///< number of 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 */
90
91 unsigned refcount;
///< number of 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 * Construct an AVFilterFormats representing all possible color spaces.
135 *
136 * Note: This list does not include AVCOL_SPC_RESERVED.
137 */
140
141 /**
142 * Construct an AVFilterFormats representing all possible color ranges.
143 */
146
147 /**
148 * Helpers for query_formats() which set all free audio links to the same list
149 * of channel layouts/sample rates. If there are no links hooked to this list,
150 * the list is freed.
151 */
155 /**
156 * Equivalent to ff_set_common_channel_layouts(ctx, ff_make_channel_layout_list(fmts))
157 */
161 /**
162 * Equivalent to ff_set_common_channel_layouts(ctx, ff_all_channel_counts())
163 */
166
170 /**
171 * Equivalent to ff_set_common_samplerates(ctx, ff_make_format_list(samplerates))
172 */
175 const int *samplerates);
176 /**
177 * Equivalent to ff_set_common_samplerates(ctx, ff_all_samplerates())
178 */
181
185 /**
186 * Equivalent to ff_set_common_color_spaces(ctx, ff_make_format_list(color_spaces))
187 */
190 const int *color_spaces);
191
192 /**
193 * Equivalent to ff_set_common_color_spaces(ctx, ff_all_color_spaces())
194 */
197
201 /**
202 * Equivalent to ff_set_common_color_ranges(ctx, ff_make_format_list(color_ranges))
203 */
206 const int *color_ranges);
207
208 /**
209 * Equivalent to ff_set_common_color_ranges(ctx, ff_all_color_ranges())
210 */
213
214 /**
215 * A helper for query_formats() which sets all links to the same list of
216 * formats. If there are no links hooked to this filter, the list of formats is
217 * freed.
218 */
221
222 /**
223 * Equivalent to ff_set_common_formats(ctx, ff_make_format_list(fmts))
224 */
227
228 /**
229 * Helpers for query_formats2() which set all free audio links to the same list
230 * of channel layouts/sample rates. If there are no links hooked to this list,
231 * the list is freed.
232 */
238
248
254
259 const int *samplerates);
260
265
271
276 const int *color_ranges);
277
282
288
293 const int *color_ranges);
294
299
305
310 const int *fmts);
311
315
316 /**
317 * Add *ref as a new reference to f.
318 */
322
323 /**
324 * Remove a reference to a channel layouts list.
325 */
327
330
331 /**
332 * Sets all remaining unset filter lists for all inputs/outputs to their
333 * corresponding `ff_all_*()` lists.
334 */
337
338 /**
339 * Create a list of supported formats. This is intended for use in
340 * AVFilter->query_formats().
341 *
342 * @param fmts list of media formats, terminated by -1
343 * @return the format list, with no existing references
344 */
347
348 /**
349 * Equivalent to ff_make_format_list({const int[]}{ fmt, -1 })
350 */
353
354 /**
355 * Add fmt to the list of media formats contained in *avff.
356 * If *avff is NULL the function allocates the filter formats struct
357 * and puts its pointer in *avff.
358 *
359 * @return a non negative value in case of success, or a negative
360 * value corresponding to an AVERROR code in case of error
361 */
364
365 /**
366 * Return a list of all formats supported by FFmpeg for the given media type.
367 */
370
371 /**
372 * Construct a formats list containing all pixel formats with certain
373 * properties
374 */
377
378 //* format is software, non-planar with sub-sampling
379 #define FF_PIX_FMT_FLAG_SW_FLAT_SUB (1 << 24)
380
381 /**
382 * Construct a formats list containing all planar sample formats.
383 */
386
387 /**
388 * Add *ref as a new reference to formats.
389 * That is the pointers will point like in the ascii art below:
390 * ________
391 * |formats |<--------.
392 * | ____ | ____|___________________
393 * | |refs| | | __|_
394 * | |* * | | | | | | AVFilterLink
395 * | |* *--------->|*ref|
396 * | |____| | | |____|
397 * |________| |________________________
398 */
401
402 /**
403 * If *ref is non-NULL, remove *ref as a reference to the format list
404 * it currently points to, deallocates that list if this was the last
405 * reference, and sets *ref to NULL.
406 *
407 * Before After
408 * ________ ________ NULL
409 * |formats |<--------. |formats | ^
410 * | ____ | ____|________________ | ____ | ____|________________
411 * | |refs| | | __|_ | |refs| | | __|_
412 * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink
413 * | |* *--------->|*ref| | |* | | | |*ref|
414 * | |____| | | |____| | |____| | | |____|
415 * |________| |_____________________ |________| |_____________________
416 */
418
419 /**
420 * Before After
421 * ________ ________
422 * |formats |<---------. |formats |<---------.
423 * | ____ | ___|___ | ____ | ___|___
424 * | |refs| | | | | | |refs| | | | | NULL
425 * | |* *--------->|*oldref| | |* *--------->|*newref| ^
426 * | |* * | | |_______| | |* * | | |_______| ___|___
427 * | |____| | | |____| | | | |
428 * |________| |________| |*oldref|
429 * |_______|
430 */
432
433 /**
434 * Check that fmts is a valid pixel formats list.
435 *
436 * In particular, check for duplicates.
437 */
439
440 /**
441 * Check that fmts is a valid sample formats list.
442 *
443 * In particular, check for duplicates.
444 */
446
447 /**
448 * Check that fmts is a valid sample rates list.
449 *
450 * In particular, check for duplicates.
451 */
453
454 /**
455 * Check that fmts is a valid channel layouts list.
456 *
457 * In particular, check for duplicates.
458 */
460
461 /**
462 * Check that fmts is a valid formats list for YUV colorspace metadata.
463 *
464 * In particular, check for duplicates.
465 */
468
473 } AVFilterFormatsMerger;
474
475 /**
476 * Callbacks and properties to describe the steps of a format negotiation.
477 *
478 * The steps are:
479 *
480 * 1. query_formats(): call the callbacks on all filter to set lists of
481 * supported formats.
482 * When links on a filter must eventually have the same
483 * format, the lists of supported formats are the same
484 * object in memory.
485 * See:
486 * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#12
487 *
488 *
489 * 2. query_formats(): merge lists of supported formats or insert automatic
490 * conversion filters.
491 * Compute the intersection of the lists of supported
492 * formats on the ends of links. If it succeeds, replace
493 * both objects with the intersection everywhere they
494 * are referenced.
495 * If the intersection is empty, insert an automatic
496 * conversion filter.
497 * If several formats are negotiated at once (format,
498 * rate, layout), only merge if all three can be, since
499 * the conversion filter can convert all three at once.
500 * This process goes on as long as progress is made.
501 * See:
502 * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#14
503 * http://www.normalesup.org/~george/articles/format_negotiation_in_libavfilter/#29
504 *
505 * 3. reduce_formats(): try to reduce format conversion within filters.
506 * For each link where there is only one supported
507 * formats on output, for each output of the connected
508 * filter, if the media type is the same and said
509 * format is supported, keep only this one.
510 * This process goes on as long as progress is made.
511 * Rationale: conversion filters will set a large list
512 * of supported formats on outputs but users will
513 * expect the output to be as close as possible as the
514 * input (examples: scale without changing the pixel
515 * format, resample without changint the layout).
516 * FIXME: this can probably be done by merging the
517 * input and output lists instead of re-implementing
518 * the logic.
519 *
520 * 4. swap_sample_fmts():
521 * swap_samplerates():
522 * swap_channel_layouts(): For each filter with an input with only one
523 * supported format, when outputs have several
524 * supported formats, put the best one with
525 * reference to the input at the beginning of the
526 * list, to prepare it for being picked up by
527 * pick_formats().
528 * The best format is the one that is most
529 * similar to the input while not losing too much
530 * information.
531 * This process need to run only once.
532 * FIXME: reduce_formats() operates on all inputs
533 * with a single format, swap_*() operates on the
534 * first one only: check if the difference makes
535 * sense.
536 * TODO: the swapping done for one filter can
537 * override the swapping done for another filter
538 * connected to the same list of formats, maybe
539 * it would be better to compute a total score
540 * for all connected filters and use the score to
541 * pick the format instead of just swapping.
542 * TODO: make the similarity logic available as
543 * public functions in libavutil.
544 *
545 * 5. pick_formats(): Choose one format from the lists of supported formats,
546 * use it for the link and reduce the list to a single
547 * element to force other filters connected to the same
548 * list to use it.
549 * First process all links where there is a single format
550 * and the output links of all filters with an input,
551 * trying to preserve similarity between input and
552 * outputs.
553 * Repeat as long as process is made.
554 * Then do a final run for the remaining filters.
555 * FIXME: the similarity logic (the ref argument to
556 * pick_format()) added in FFmpeg duplicates and
557 * overrides the swapping logic added in libav. Better
558 * merge them into a score system.
559 */
566
568
569 #endif /* AVFILTER_FORMATS_H */