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