---
libavfilter/avfilter.h | 102 +++++++++++++++++++++++++++++++++++++++---------
1 file changed, 84 insertions(+), 18 deletions(-)
diff --git a/libavfilter/avfilter.h b/libavfilter/avfilter.h
index 51d0fb5..2826392 100644
--- a/libavfilter/avfilter.h
+++ b/libavfilter/avfilter.h
@@ -396,20 +396,41 @@ enum AVMediaType avfilter_pad_get_type(const AVFilterPad
*pads, int pad_idx);
* callback functions used to interact with the filter.
*/
typedef struct AVFilter {
- const char *name; ///< filter name
+ /**
+ * Filter name. Must be non-NULL and unique among filters.
+ */
+ const char *name;
/**
- * A description for the filter. You should use the
- * NULL_IF_CONFIG_SMALL() macro to define it.
+ * A description for the filter. May be NULL.
+ *
+ * You should use the NULL_IF_CONFIG_SMALL() macro to define it.
*/
const char *description;
- const AVFilterPad *inputs; ///< NULL terminated list of inputs. NULL if
none
- const AVFilterPad *outputs; ///< NULL terminated list of outputs. NULL if
none
+ /**
+ * List of inputs, terminated by a zeroed element.
+ *
+ * NULL if there are no (static) inputs. Instances of filters with
+ * AVFILTER_FLAG_DYNAMIC_INPUTS set may have more inputs than present in
this list.
+ */
+ const AVFilterPad *inputs;
+ /**
+ * List of outputs, terminated by a zeroed element.
+ *
+ * NULL if there are no (static) outputs. Instances of filters with
+ * AVFILTER_FLAG_DYNAMIC_OUTPUTS set may have more outputs than present in
+ * this list.
+ */
+ const AVFilterPad *outputs;
/**
- * A class for the private data, used to access filter private
- * AVOptions.
+ * A class for the private data, used to declare filter private AVOptions.
+ * This field is NULL for the filters that do not declare any options.
+ *
+ * If this field is non-NULL, the first member of the filter private data
+ * must be a pointer to AVClass, which will be set by libavfilter generic
+ * code to this class.
*/
const AVClass *priv_class;
@@ -427,29 +448,71 @@ typedef struct AVFilter {
*/
/**
- * Filter initialization function. Called when all the options have been
- * set.
+ * Filter initialization function.
+ *
+ * This callback will be called only once during the filter lifetime, after
+ * all the options have been set, but before links between filters are
+ * established and format negotiation is done.
+ *
+ * Basic filter initialization should be done here. Filters with dynamic
+ * inputs and/or outputs should create those inputs/outputs here based on
+ * provided options. No more changes to this filter's inputs/outputs can be
+ * done after this callback.
+ *
+ * This callback must not assume that the filter links exist or frame
+ * parameters are known.
+ *
+ * @ref AVFilter.uninit "uninit" is guaranteed to be called even if
+ * initialization fails, so this callback does not have to clean up on
+ * failure.
+ *
+ * @return 0 on success, a negative AVERROR on failure
*/
int (*init)(AVFilterContext *ctx);
/**
- * Should be set instead of init by the filters that want to pass a
- * dictionary of AVOptions to nested contexts that are allocated in
- * init.
+ * Should be set instead of @ref AVFilter.init "init" by the filters that
+ * want to pass a dictionary of AVOptions to nested contexts that are
+ * allocated in init.
+ *
+ * On return, the options dict should be freed and replaced with one that
+ * contains all the options which could not be processed by this filter (or
+ * with NULL if all the options are processed).
+ *
+ * Otherwise the semantics is the same as for @ref AVFilter.init "init".
*/
int (*init_dict)(AVFilterContext *ctx, AVDictionary **options);
/**
- * Filter uninitialization function. Should deallocate any memory held
- * by the filter, release any buffer references, etc. This does not need
- * to deallocate the AVFilterContext->priv memory itself.
+ * Filter uninitialization function.
+ *
+ * Called only once right before the filter is freed. Should deallocate any
+ * memory held by the filter, release any buffer references, etc. This does
+ * not need to deallocate the AVFilterContext.priv memory itself.
+ *
+ * This callback may be called even if @ref AVFilter.init "init" was not
+ * called or failed, so it must be prepared to handle such a situation.
*/
void (*uninit)(AVFilterContext *ctx);
/**
- * Queries formats supported by the filter and its pads, and sets the
- * in_formats for links connected to its output pads, and out_formats
- * for links connected to its input pads.
+ * Query formats supported by the filter on its inputs and outputs.
+ *
+ * This callback is called after the filter is initialized (so the inputs
+ * and outputs are fixed), shortly before the format negotiation. This
+ * callback may be called more than once.
+ *
+ * This callback must set AVFilterLink.out_formats on every input link and
+ * AVFilterLink.in_formats on every output link to a list of supported
+ * pixel/sample formats on that link. For audio links, this filter must
also
+ * set @ref AVFilterLink.in_samplerates "in_samplerates" /
+ * @ref AVFilterLink.out_samplerates "out_samplerates" and
+ * @ref AVFilterLink.in_channel_layouts "in_channel_layouts" /
+ * @ref AVFilterLink.out_channel_layouts "out_channel_layouts" analogously.
+ *
+ * This callback may be NULL for filters with one input, in which case
+ * libavfilter assumes that it supports all formats on input and preserves
+ * them on output.
*
* @return zero on success, a negative value corresponding to an
* AVERROR code otherwise
@@ -458,6 +521,9 @@ typedef struct AVFilter {
int priv_size; ///< size of private data to allocate for the filter
+ /**
+ * Used by the filter registration system.
+ */
struct AVFilter *next;
} AVFilter;
--
1.7.10.4
_______________________________________________
libav-devel mailing list
[email protected]
https://lists.libav.org/mailman/listinfo/libav-devel
