Revision 35f3fdf4

View differences:

libavfilter/avfilter.h
102 102
void avfilter_unref_pic(AVFilterPicRef *ref);
103 103

  
104 104
/**
105
 * A list of supported formats for one end of a filter link. This is used
106
 * during the format negotiation process to try to pick the best format to
107
 * use to minimize the number of necessary conversions. Each filter gives a
108
 * list of the formats supported by each input and output pad. The list
109
 * given for each pad need not be distinct - they may be references to the
110
 * same list of formats, as is often the case when a filter supports multiple
111
 * formats, but will always outut the same format as it is given in input.
112
 *
113
 * In this way, a list of possible input formats and a list of possible
114
 * output formats are associated with each link. When a set of formats is
115
 * negotiated over a link, the input and output lists are merged to form a
116
 * new list containing only the common elements of each list. In the case
117
 * that there were no common elements, a format conversion is necessary.
118
 * Otherwise, the lists are merged, and all other links which reference
119
 * either of the format lists involved in the merge are also affected.
120
 *
121
 * For example, consider the filter chain:
122
 * filter (a) --> (b) filter (b) --> (c) filter
123
 *
124
 * where the letters in parenthesis indicate a list of formats supported on
125
 * the input or output of the link. Suppose the lists are as follows:
126
 * (a) = {A, B}
127
 * (b) = {A, B, C}
128
 * (c) = {B, C}
129
 *
130
 * First, the first link's lists are merged, yielding:
131
 * filter (a) --> (a) filter (a) --> (c) filter
132
 *
133
 * Notice that format list (b) now refers to the same list as filter list (a).
134
 * Next, the lists for the second link are merged, yielding:
135
 * filter (a) --> (a) filter (a) --> (a) filter
136
 *
137
 * where (a) = {B}.
138
 *
139
 * Unfortunately, when the format lists at the two ends of a link are merged,
140
 * we must ensure that all links which reference either pre-merge format list
141
 * get updated as well. Therefore, we have the format list structure store a
142
 * pointer to each of the pointers to itself.
143
 */
144
typedef struct AVFilterFormats AVFilterFormats;
145
struct AVFilterFormats
146
{
147
    unsigned format_count;      ///< number of formats
148
    int *formats;               ///< list of formats
149

  
150
    unsigned refcount;          ///< number of references to this list
151
    AVFilterFormats ***refs;    ///< references to this list
152
};
153

  
154
/**
155
 * Helper function to create a list of supported formats.  This is intended
156
 * for use in AVFilter->query_formats().
157
 * @param len The number of formats supported
158
 * @param ... A list of the supported formats
159
 * @return    The format list, with no existing references
160
 */
161
AVFilterFormats *avfilter_make_format_list(int len, ...);
162

  
163
/**
164
 * Returns a fairly comprehensive list of colorspaces which are supported by
165
 * many of the included filters. This is not truly "all" the colorspaces, but
166
 * it is most of them, and it is the most commonly supported large subset.
167
 */
168
AVFilterFormats *avfilter_all_colorspaces(void);
169

  
170
/**
171
 * If a and b share at least one common format, they are merged into a new
172
 * format list which is returned.  All the references to a and b are updated
173
 * to point to this new list, and a and b are deallocated.
174
 *
175
 * If a and b do not share any common formats, neither is modified, and NULL
176
 * is returned.
177
 */
178
AVFilterFormats *avfilter_merge_formats(AVFilterFormats *a, AVFilterFormats *b);
179

  
180
/** Adds *ref as a new reference to f */
181
void avfilter_formats_ref(AVFilterFormats *f, AVFilterFormats **ref);
182

  
183
/**
184
 * Remove *ref as a reference to the format list it currently points to,
185
 * deallocate that list if this was the last reference, and set *ref to NULL
186
 */
187
void avfilter_formats_unref(AVFilterFormats **ref);
188

  
189
/**
105 190
 * A filter pad used for either input or output
106 191
 */
107 192
struct AVFilterPad
......
140 225
    int rej_perms;
141 226

  
142 227
    /**
143
     * Callback to get a list of supported formats.  The returned list should
144
     * be terminated by -1 (see avfilter_make_format_list for an easy way to
145
     * create such a list).
146
     *
147
     * This is used for both input and output pads.  If ommitted from an output
148
     * pad, it is assumed that the only format supported is the same format
149
     * that is being used for the filter's first input.  If the filter has no
150
     * inputs, then this may not be ommitted for its output pads.
151
     */
152
    int *(*query_formats)(AVFilterLink *link);
153

  
154
    /**
155 228
     * Callback called before passing the first slice of a new frame.  If
156 229
     * NULL, the filter layer will default to storing a reference to the
157 230
     * picture inside the link structure.
......
219 292
int avfilter_default_config_output_link(AVFilterLink *link);
220 293
/** Default handler for config_props() for video inputs */
221 294
int avfilter_default_config_input_link (AVFilterLink *link);
222
/** Default handler for query_formats() for video outputs */
223
int *avfilter_default_query_output_formats(AVFilterLink *link);
224 295
/** Default handler for get_video_buffer() for video inputs */
225 296
AVFilterPicRef *avfilter_default_get_video_buffer(AVFilterLink *link,
226 297
                                                  int perms);
298
/**
299
 * A helper for query_formats() which sets all links to the same list of
300
 * formats. If there are no links hooked to this filter, the list of formats is
301
 * freed.
302
 */
303
void avfilter_set_common_formats(AVFilterContext *ctx, AVFilterFormats *formats);
304
/** Default handler for query_formats() */
305
int avfilter_default_query_formats(AVFilterContext *ctx);
227 306

  
228 307
/**
229 308
 * Filter definition.  This defines the pads a filter contains, and all the
......
251 330
     */
252 331
    void (*uninit)(AVFilterContext *ctx);
253 332

  
333
    /**
334
     * Query formats supported by the filter and its pads. Should set the
335
     * in_formats for links connected to its output pads, and out_formats
336
     * for links connected to its input pads.
337
     *
338
     * Should return zero on success.
339
     */
340
    int (*query_formats)(AVFilterContext *);
341

  
254 342
    const AVFilterPad *inputs;  ///< NULL terminated list of inputs. NULL if none
255 343
    const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if none
256 344
} AVFilter;
......
295 383
    enum PixelFormat format;    ///< agreed upon image colorspace
296 384

  
297 385
    /**
386
     * Lists of formats supported by the input and output filters respectively.
387
     * These lists are used for negotiating the format to actually be used,
388
     * which will be loaded into the format member, above, when chosen.
389
     */
390
    AVFilterFormats *in_formats;
391
    AVFilterFormats *out_formats;
392

  
393
    /**
298 394
     * The picture reference currently being sent across the link by the source
299 395
     * filter.  This is used internally by the filter system to allow
300 396
     * automatic copying of pictures which d not have sufficient permissions
......
415 511
void avfilter_destroy(AVFilterContext *filter);
416 512

  
417 513
/**
418
 * Helper function to create a list of supported formats.  This is intended
419
 * for use in AVFilterPad->query_formats().
420
 * @param len The number of formats supported
421
 * @param ... A list of the supported formats
422
 * @return    The format list in a form suitable for returning from
423
 *            AVFilterPad->query_formats()
514
 * Insert a filter in the middle of an existing link.
515
 * @param link The link into which the filter should be inserted
516
 * @param filt The filter to be inserted
517
 * @param in   The input pad on the filter to connect
518
 * @param out  The output pad on the filter to connect
519
 * @return     Zero on success
424 520
 */
425
int *avfilter_make_format_list(int len, ...);
521
int avfilter_insert_filter(AVFilterLink *link, AVFilterContext *filt,
522
                           unsigned in, unsigned out);
426 523

  
427 524
/**
428 525
 * Insert a new pad

Also available in: Unified diff