lavfi: clarify the behaviour of avfilter_graph_create_filter()

Mention explicitly that no options can be set manually when using this function.

Anton Khirnov committed 2 years ago

Commit ca860d81 parent d3f76db1 file · +9 −3Browse files

Showing the changes to libavfilter (1 of 1 file). Show all

Unified · Split

 AVFilterContext *avfilter_graph_get_filter(AVFilterGraph *graph, const char *name);
 /**
- * Create and add a filter instance into an existing graph.
+ * A convenience wrapper that allocates and initializes a filter in a single
- * The filter instance is created from the filter filt and inited
+ * step. The filter instance is created from the filter filt and inited with the
- * with the parameter args. opaque is currently ignored.
+ * parameter args. opaque is currently ignored.
  *
  * In case of success put in *filt_ctx the pointer to the created
  * filter instance, otherwise set *filt_ctx to NULL.
  * @param graph_ctx the filter graph
  * @return a negative AVERROR error code in case of failure, a non
  * negative value otherwise
+ *
+ * @warning Since the filter is initialized after this function successfully
+ *          returns, you MUST NOT set any further options on it. If you need to
+ *          do that, call ::avfilter_graph_alloc_filter(), followed by setting
+ *          the options, followed by ::avfilter_init_dict() instead of this
+ *          function.
  */
 int avfilter_graph_create_filter(AVFilterContext **filt_ctx, const AVFilter *filt,
                                  const char *name, const char *args, void *opaque,

Keyboard shortcuts