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 */ 65 struct AVFilterFormats { 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 */ 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 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 */ 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); 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 */ 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); 139 140 /** 141 * Construct an empty AVFilterChannelLayouts/AVFilterFormats struct -- 142 * representing any channel layout (with known disposition)/sample rate. 143 */ 144 av_warn_unused_result 145 AVFilterChannelLayouts *ff_all_channel_layouts(void); 146 147 av_warn_unused_result 148 AVFilterFormats *ff_all_samplerates(void); 149 150 /** 151 * Construct an AVFilterChannelLayouts coding for any channel layout, with 152 * known or unknown disposition. 153 */ 154 av_warn_unused_result 155 AVFilterChannelLayouts *ff_all_channel_counts(void); 156 157 av_warn_unused_result 158 AVFilterChannelLayouts *ff_make_format64_list(const int64_t *fmts); 159 160 #if LIBAVFILTER_VERSION_MAJOR < 8 161 AVFilterChannelLayouts *avfilter_make_format64_list(const int64_t *fmts); 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 */ 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); 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 */ 181 av_warn_unused_result 182 int ff_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats); 183 184 av_warn_unused_result 185 int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout); 186 187 /** 188 * Add *ref as a new reference to f. 189 */ 190 av_warn_unused_result 191 int ff_channel_layouts_ref(AVFilterChannelLayouts *f, 192 AVFilterChannelLayouts **ref); 193 194 /** 195 * Remove a reference to a channel layouts list. 196 */ 197 void ff_channel_layouts_unref(AVFilterChannelLayouts **ref); 198 199 void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref, 200 AVFilterChannelLayouts **newref); 201 202 av_warn_unused_result 203 int ff_default_query_formats(AVFilterContext *ctx); 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 */ 212 av_warn_unused_result 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 */ 223 av_warn_unused_result 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 */ 229 av_warn_unused_result 230 AVFilterFormats *ff_all_formats(enum AVMediaType type); 231 232 /** 233 * Construct a formats list containing all pixel formats with certain 234 * properties 235 */ 236 av_warn_unused_result 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 */ 245 av_warn_unused_result 246 AVFilterFormats *ff_planar_sample_fmts(void); 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 */ 260 av_warn_unused_result 261 int ff_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref); 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 */ 278 void ff_formats_unref(AVFilterFormats **ref); 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 */ 323