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 typedef struct AVFilterChannelLayouts { 86 uint64_t *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 } AVFilterChannelLayouts; 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) (0x8000000000000000ULL | (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) & 0x8000000000000000ULL) ? \ 109 (int)((l) & 0x7FFFFFFF) : 0) 110 111 /** 112 * Return a channel layouts/samplerates list which contains the intersection of 113 * the layouts/samplerates of a and b. Also, all the references of a, all the 114 * references of b, and a and b themselves will be deallocated. 115 * 116 * If a and b do not share any common elements, neither is modified, and NULL 117 * is returned. 118 */ 119 AVFilterChannelLayouts *ff_merge_channel_layouts(AVFilterChannelLayouts *a, 120 AVFilterChannelLayouts *b); 121 AVFilterFormats *ff_merge_samplerates(AVFilterFormats *a, 122 AVFilterFormats *b); 123 124 /** 125 * Construct an empty AVFilterChannelLayouts/AVFilterFormats struct -- 126 * representing any channel layout (with known disposition)/sample rate. 127 */ 128 av_warn_unused_result 129 AVFilterChannelLayouts *ff_all_channel_layouts(void); 130 131 av_warn_unused_result 132 AVFilterFormats *ff_all_samplerates(void); 133 134 /** 135 * Construct an AVFilterChannelLayouts coding for any channel layout, with 136 * known or unknown disposition. 137 */ 138 av_warn_unused_result 139 AVFilterChannelLayouts *ff_all_channel_counts(void); 140 141 av_warn_unused_result 142 AVFilterChannelLayouts *avfilter_make_format64_list(const int64_t *fmts); 143 144 av_warn_unused_result 145 AVFilterChannelLayouts *ff_make_formatu64_list(const uint64_t *fmts); 146 147 148 /** 149 * A helper for query_formats() which sets all links to the same list of channel 150 * layouts/sample rates. If there are no links hooked to this filter, the list 151 * is freed. 152 */ 153 av_warn_unused_result 154 int ff_set_common_channel_layouts(AVFilterContext *ctx, 155 AVFilterChannelLayouts *layouts); 156 av_warn_unused_result 157 int ff_set_common_samplerates(AVFilterContext *ctx, 158 AVFilterFormats *samplerates); 159 160 /** 161 * A helper for query_formats() which sets all links to the same list of 162 * formats. If there are no links hooked to this filter, the list of formats is 163 * freed. 164 */ 165 av_warn_unused_result 166 int ff_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats); 167 168 av_warn_unused_result 169 int ff_add_channel_layout(AVFilterChannelLayouts **l, uint64_t channel_layout); 170 171 /** 172 * Add *ref as a new reference to f. 173 */ 174 av_warn_unused_result 175 int ff_channel_layouts_ref(AVFilterChannelLayouts *f, 176 AVFilterChannelLayouts **ref); 177 178 /** 179 * Remove a reference to a channel layouts list. 180 */ 181 void ff_channel_layouts_unref(AVFilterChannelLayouts **ref); 182 183 void ff_channel_layouts_changeref(AVFilterChannelLayouts **oldref, 184 AVFilterChannelLayouts **newref); 185 186 av_warn_unused_result 187 int ff_default_query_formats(AVFilterContext *ctx); 188 189 /** 190 * Set the formats list to all known channel layouts. This function behaves 191 * like ff_default_query_formats(), except it only accepts known channel 192 * layouts. It should only be used with audio filters. 193 */ 194 av_warn_unused_result 195 int ff_query_formats_all_layouts(AVFilterContext *ctx); 196 197 /** 198 * Create a list of supported formats. This is intended for use in 199 * AVFilter->query_formats(). 200 * 201 * @param fmts list of media formats, terminated by -1 202 * @return the format list, with no existing references 203 */ 204 av_warn_unused_result 205 AVFilterFormats *ff_make_format_list(const int *fmts); 206 207 /** 208 * Add fmt to the list of media formats contained in *avff. 209 * If *avff is NULL the function allocates the filter formats struct 210 * and puts its pointer in *avff. 211 * 212 * @return a non negative value in case of success, or a negative 213 * value corresponding to an AVERROR code in case of error 214 */ 215 av_warn_unused_result 216 int ff_add_format(AVFilterFormats **avff, int64_t fmt); 217 218 /** 219 * Return a list of all formats supported by FFmpeg for the given media type. 220 */ 221 av_warn_unused_result 222 AVFilterFormats *ff_all_formats(enum AVMediaType type); 223 224 /** 225 * Construct a formats list containing all pixel formats with certain 226 * properties 227 */ 228 av_warn_unused_result 229 int ff_formats_pixdesc_filter(AVFilterFormats **rfmts, unsigned want, unsigned rej); 230 231 //* format is software, non-planar with sub-sampling 232 #define FF_PIX_FMT_FLAG_SW_FLAT_SUB (1 << 24) 233 234 /** 235 * Construct a formats list containing all planar sample formats. 236 */ 237 av_warn_unused_result 238 AVFilterFormats *ff_planar_sample_fmts(void); 239 240 /** 241 * Return a format list which contains the intersection of the formats of 242 * a and b. Also, all the references of a, all the references of b, and 243 * a and b themselves will be deallocated. 244 * 245 * If a and b do not share any common formats, neither is modified, and NULL 246 * is returned. 247 */ 248 AVFilterFormats *ff_merge_formats(AVFilterFormats *a, AVFilterFormats *b, 249 enum AVMediaType type); 250 251 /** 252 * Add *ref as a new reference to formats. 253 * That is the pointers will point like in the ascii art below: 254 * ________ 255 * |formats |<--------. 256 * | ____ | ____|___________________ 257 * | |refs| | | __|_ 258 * | |* * | | | | | | AVFilterLink 259 * | |* *--------->|*ref| 260 * | |____| | | |____| 261 * |________| |________________________ 262 */ 263 av_warn_unused_result 264 int ff_formats_ref(AVFilterFormats *formats, AVFilterFormats **ref); 265 266 /** 267 * If *ref is non-NULL, remove *ref as a reference to the format list 268 * it currently points to, deallocates that list if this was the last 269 * reference, and sets *ref to NULL. 270 * 271 * Before After 272 * ________ ________ NULL 273 * |formats |<--------. |formats | ^ 274 * | ____ | ____|________________ | ____ | ____|________________ 275 * | |refs| | | __|_ | |refs| | | __|_ 276 * | |* * | | | | | | AVFilterLink | |* * | | | | | | AVFilterLink 277 * | |* *--------->|*ref| | |* | | | |*ref| 278 * | |____| | | |____| | |____| | | |____| 279 * |________| |_____________________ |________| |_____________________ 280 */ 281 void ff_formats_unref(AVFilterFormats **ref); 282 283 /** 284 * Before After 285 * ________ ________ 286 * |formats |<---------. |formats |<---------. 287 * | ____ | ___|___ | ____ | ___|___ 288 * | |refs| | | | | | |refs| | | | | NULL 289 * | |* *--------->|*oldref| | |* *--------->|*newref| ^ 290 * | |* * | | |_______| | |* * | | |_______| ___|___ 291 * | |____| | | |____| | | | | 292 * |________| |________| |*oldref| 293 * |_______| 294 */ 295 void ff_formats_changeref(AVFilterFormats **oldref, AVFilterFormats **newref); 296 297 #endif /* AVFILTER_FORMATS_H */ 298