doc: add a tutorial for writing filters.

doc/writing_filters.txt

@@ -0,0 +1,424 @@
+This document is a tutorial/initiation for writing simple filters in
+libavfilter.
+
+Foreword: just like everything else in FFmpeg, libavfilter is monolithic, which
+means that it is highly recommended that you submit your filters to the FFmpeg
+development mailing-list and make sure it is applied. Otherwise, your filter is
+likely to have a very short lifetime due to more a less regular internal API
+changes, and a limited distribution, review, and testing.
+
+Bootstrap
+=========
+
+Let's say you want to write a new simple video filter called "foobar" which
+takes one frame in input, changes the pixels in whatever fashion you fancy, and
+outputs the modified frame. The most simple way of doing this is to take a
+similar filter.  We'll pick edgedetect, but any other should do. You can look
+for others using the `./ffmpeg -v 0 -filters|grep ' V->V '` command.
+
+ - cp libavfilter/vf_{edgedetect,foobar}.c
+ - sed -i s/edgedetect/foobar/g -i libavfilter/vf_foobar.c
+ - sed -i s/EdgeDetect/Foobar/g -i libavfilter/vf_foobar.c
+ - edit libavfilter/Makefile, and add an entry for "foobar" following the
+   pattern of the other filters.
+ - edit libavfilter/allfilters.c, and add an entry for "foobar" following the
+   pattern of the other filters.
+ - ./configure ...
+ - make -j<whatever> ffmpeg
+ - ./ffmpeg -i tests/lena.pnm -vf foobar foobar.png
+
+If everything went right, you should get a foobar.png with Lena edge-detected.
+
+That's it, your new playground is ready.
+
+Some little details about what's going on:
+libavfilter/allfilters.c:avfilter_register_all() is called at runtime to create
+a list of the available filters, but it's important to know that this file is
+also parsed by the configure script, which in turn will define variables for
+the build system and the C:
+
+    --- after running configure ---
+
+    $ grep FOOBAR config.mak
+    CONFIG_FOOBAR_FILTER=yes
+    $ grep FOOBAR config.h
+    #define CONFIG_FOOBAR_FILTER 1
+
+CONFIG_FOOBAR_FILTER=yes from the config.mak is later used to enable the filter in
+libavfilter/Makefile and CONFIG_FOOBAR_FILTER=1 from the config.h will be used
+for registering the filter in libavfilter/allfilters.c.
+
+Filter code layout
+==================
+
+You now need some theory about the general code layout of a filter. Open your
+libavfilter/vf_foobar.c. This section will detail the important parts of the
+code you need to understand before messing with it.
+
+Copyright
+---------
+
+First chunk is the copyright. Most filters are LGPL, and we are assuming
+vf_foobar is as well. We are also assuming vf_foobar is not an edge detector
+filter, so you can update the boilerplate with your credits.
+
+Doxy
+----
+
+Next chunk is the Doxygen about the file. See http://ffmpeg.org/doxygen/trunk/.
+Detail here what the filter is, does, and add some references if you feel like
+it.
+
+Context
+-------
+
+Skip the headers and scroll down to the definition of FoobarContext. This is
+your local state context. It is already filled with 0 when you get it so do not
+worry about uninitialized read into this context. This is where you put every
+"global" information you need, typically the variable storing the user options.
+You'll notice the first field "const AVClass *class"; it's the only field you
+need to keep assuming you have a context. There are some magic you don't care
+about around this field, just let it be (in first position) for now.
+
+Options
+-------
+
+Then comes the options array. This is what will define the user accessible
+options. For example, -vf foobar=mode=colormix:high=0.4:low=0.1. Most options
+have the following pattern:
+  name, description, offset, type, default value, minimum value, maximum value, flags
+
+ - name is the option name, keep it simple, lowercase
+ - description are short, in lowercase, without period, and describe what they
+   do, for example "set the foo of the bar"
+ - offset is the offset of the field in your local context, see the OFFSET()
+   macro; the option parser will use that information to fill the fields
+   according to the user input
+ - type is any of AV_OPT_TYPE_* defined in libavutil/opt.h
+ - default value is an union where you pick the appropriate type; "{.dbl=0.3}",
+   "{.i64=0x234}", "{.str=NULL}", ...
+ - min and max values define the range of available values, inclusive
+ - flags are AVOption generic flags. See AV_OPT_FLAG_* definitions
+
+In doubt, just look at the other AVOption definitions all around the codebase,
+there are tons of examples.
+
+Class
+-----
+
+AVFILTER_DEFINE_CLASS(foobar) will define a unique foobar_class with some kind
+of signature referencing the options, etc. which will be referenced in the
+definition of the AVFilter.
+
+Filter definition
+-----------------
+
+At the end of the file, you will find foobar_inputs, foobar_outputs and
+the AVFilter ff_vf_foobar. Don't forget to update the AVFilter.description with
+a description of what the filter does, starting with a capitalized letter and
+ending with a period. You'd better drop the AVFilter.flags entry for now, and
+re-add them later depending on the capabilities of your filter.
+
+Callbacks
+---------
+
+Let's now study the common callbacks. Before going into details, note that all
+these callbacks are explained in details in libavfilter/avfilter.h, so in
+doubt, refer to the doxy in that file.
+
+init()
+~~~~~~
+
+First one to be called is init(). It's flagged as cold because not called
+often. Look for "cold" on
+http://gcc.gnu.org/onlinedocs/gcc/Function-Attributes.html for more
+information.
+
+As the name suggests, init() is where you eventually initialize and allocate
+your buffers, pre-compute your data, etc. Note that at this point, your local
+context already has the user options initialized, but you still haven't any
+clue about the kind of data input you will get, so this function is often
+mainly used to sanitize the user options.
+
+Some init()s will also define the number of inputs or outputs dynamically
+according to the user options. A good example of this is the split filter, but
+we won't cover this here since vf_foobar is just a simple 1:1 filter.
+
+uninit()
+~~~~~~~~
+
+Similarly, there is the uninit() callback, doing what the name suggest. Free
+everything you allocated here.
+
+query_formats()
+~~~~~~~~~~~~~~~
+
+This is following the init() and is used for the format negotiation, basically
+where you say what pixel format(s) (gray, rgb 32, yuv 4:2:0, ...) you accept
+for your inputs, and what you can output. All pixel formats are defined in
+libavutil/pixfmt.h. If you don't change the pixel format between the input and
+the output, you just have to define a pixel formats array and call
+ff_set_common_formats(). For more complex negotiation, you can refer to other
+filters such as vf_scale.
+
+config_props()
+~~~~~~~~~~~~~~
+
+This callback is not necessary, but you will probably have one or more
+config_props() anyway. It's not a callback for the filter itself but for its
+inputs or outputs (they're called "pads" - AVFilterPad - in libavfilter's
+lexicon).
+
+Inside the input config_props(), you are at a point where you know which pixel
+format has been picked after query_formats(), and more information such as the
+video width and height (inlink->{w,h}). So if you need to update your internal
+context state depending on your input you can do it here. In edgedetect you can
+see that this callback is used to allocate buffers depending on these
+information. They will be destroyed in uninit().
+
+Inside the output config_props(), you can define what you want to change in the
+output. Typically, if your filter is going to double the size of the video, you
+will update outlink->w and outlink->h.
+
+filter_frame()
+~~~~~~~~~~~~~~
+
+This is the callback you are waiting from the beginning: it is where you
+process the received frames. Along with the frame, you get the input link from
+where the frame comes from.
+
+    static int filter_frame(AVFilterLink *inlink, AVFrame *in) { ... }
+
+You can get the filter context through that input link:
+
+    AVFilterContext *ctx = inlink->dst;
+
+Then access your internal state context:
+
+    FoobarContext *foobar = ctx->priv;
+
+And also the output link where you will send your frame when you are done:
+
+    AVFilterLink *outlink = ctx->outputs[0];
+
+Here, we are picking the first output. You can have several, but in our case we
+only have one since we are in a 1:1 input-output situation.
+
+If you want to define a simple pass-through filter, you can just do:
+
+    return ff_filter_frame(outlink, in);
+
+But of course, you probably want to change the data of that frame.
+
+This can be done by accessing frame->data[] and frame->linesize[].  Important
+note here: the width does NOT match the linesize. The linesize is always
+greater or equal to the width. The padding created should not be changed or
+even read. Typically, keep in mind that a previous filter in your chain might
+have altered the frame dimension but not the linesize. Imagine a crop filter
+that halves the video size: the linesizes won't be changed, just the width.
+
+    <-------------- linesize ------------------------>
+    +-------------------------------+----------------+ ^
+    |                               |                | |
+    |                               |                | |
+    |           picture             |    padding     | | height
+    |                               |                | |
+    |                               |                | |
+    +-------------------------------+----------------+ v
+    <----------- width ------------->
+
+Before modifying the "in" frame, you have to make sure it is writable, or get a
+new one. Multiple scenarios are possible here depending on the kind of
+processing you are doing.
+
+Let's say you want to change one pixel depending on multiple pixels (typically
+the surrounding ones) of the input. In that case, you can't do an in-place
+processing of the input so you will need to allocate a new frame, with the same
+properties as the input one, and send that new frame to the next filter:
+
+    AVFrame *out = ff_get_video_buffer(outlink, outlink->w, outlink->h);
+    if (!out) {
+        av_frame_free(&in);
+        return AVERROR(ENOMEM);
+    }
+    av_frame_copy_props(out, in);
+
+    // out->data[...] = foobar(in->data[...])
+
+    av_frame_free(&in);
+    return ff_filter_frame(outlink, out);
+
+In-place processing
+~~~~~~~~~~~~~~~~~~~
+
+If you can just alter the input frame, you probably just want to do that
+instead:
+
+    av_frame_make_writable(in);
+    // in->data[...] = foobar(in->data[...])
+    return ff_filter_frame(outlink, in);
+
+You may wonder why a frame might not be writable. The answer is that for
+example a previous filter might still own the frame data: imagine a filter
+prior to yours in the filtergraph that needs to cache the frame. You must not
+alter that frame, otherwise it will make that previous filter buggy. This is
+where av_frame_make_writable() helps (it won't have any effect if the frame
+already is writable).
+
+The problem with using av_frame_make_writable() is that in the worst case it
+will copy the whole input frame before you change it all over again with your
+filter: if the frame is not writable, av_frame_make_writable() will allocate
+new buffers, and copy the input frame data. You don't want that, and you can
+avoid it by just allocating a new buffer if necessary, and process from in to
+out in your filter, saving the memcpy. Generally, this is done following this
+scheme:
+
+    int direct = 0;
+    AVFrame *out;
+
+    if (av_frame_is_writable(in)) {
+        direct = 1;
+        out = in;
+    } else {
+        out = ff_get_video_buffer(outlink, outlink->w, outlink->h);
+        if (!out) {
+            av_frame_free(&in);
+            return AVERROR(ENOMEM);
+        }
+        av_frame_copy_props(out, in);
+    }
+
+    // out->data[...] = foobar(in->data[...])
+
+    if (!direct)
+        av_frame_free(&in);
+    return ff_filter_frame(outlink, out);
+
+Of course, this will only work if you can do in-place processing. To test if
+your filter handles well the permissions, you can use the perms filter. For
+example with:
+
+    -vf perms=random,foobar
+
+Make sure no automatic pixel conversion is inserted between perms and foobar,
+otherwise the frames permissions might change again and the test will be
+meaningless: add av_log(0,0,"direct=%d\n",direct) in your code to check that.
+You can avoid the issue with something like:
+
+    -vf format=rgb24,perms=random,foobar
+
+...assuming your filter accepts rgb24 of course. This will make sure the
+necessary conversion is inserted before the perms filter.
+
+Timeline
+~~~~~~~~
+
+Adding timeline support
+(http://ffmpeg.org/ffmpeg-filters.html#Timeline-editing) is often an easy
+feature to add. In the most simple case, you just have to add
+AVFILTER_FLAG_SUPPORT_TIMELINE_GENERIC to the AVFilter.flags. You can typically
+do this when your filter does not need to save the previous context frames, or
+basically if your filter just alter whatever goes in and doesn't need
+previous/future information. See for instance commit 86cb986ce that adds
+timeline support to the fieldorder filter.
+
+In some cases, you might need to reset your context somehow. This is handled by
+the AVFILTER_FLAG_SUPPORT_TIMELINE_INTERNAL flag which is used if the filter
+must not process the frames but still wants to keep track of the frames going
+through (to keep them in cache for when it's enabled again). See for example
+commit 69d72140a that adds timeline support to the phase filter.
+
+Threading
+~~~~~~~~~
+
+libavfilter does not yet support frame threading, but you can add slice
+threading to your filters.
+
+Let's say the foobar filter has the following frame processing function:
+
+    dst = out->data[0];
+    src = in ->data[0];
+
+    for (y = 0; y < inlink->h; y++) {
+        for (x = 0; x < inlink->w; x++)
+            dst[x] = foobar(src[x]);
+        dst += out->linesize[0];
+        src += in ->linesize[0];
+    }
+
+The first thing is to make this function work into slices. The new code will
+look like this:
+
+    for (y = slice_start; y < slice_end; y++) {
+        for (x = 0; x < inlink->w; x++)
+            dst[x] = foobar(src[x]);
+        dst += out->linesize[0];
+        src += in ->linesize[0];
+    }
+
+The source and destination pointers, and slice_start/slice_end will be defined
+according to the number of jobs. Generally, it looks like this:
+
+    const int slice_start = (in->height *  jobnr   ) / nb_jobs;
+    const int slice_end   = (in->height * (jobnr+1)) / nb_jobs;
+    uint8_t       *dst = out->data[0] + slice_start * out->linesize[0];
+    const uint8_t *src =  in->data[0] + slice_start *  in->linesize[0];
+
+This new code will be isolated in a new filter_slice():
+
+    static int filter_slice(AVFilterContext *ctx, void *arg, int jobnr, int nb_jobs) { ... }
+
+Note that we need our input and output frame to define slice_{start,end} and
+dst/src, which are not available in that callback. They will be transmitted
+through the opaque void *arg. You have to define a structure which contains
+everything you need:
+
+    typedef struct ThreadData {
+        AVFrame *in, *out;
+    } ThreadData;
+
+If you need some more information from your local context, put them here.
+
+In you filter_slice function, you access it like that:
+
+    const ThreadData *td = arg;
+
+Then in your filter_frame() callback, you need to call the threading
+distributor with something like this:
+
+    ThreadData td;
+
+    // ...
+
+    td.in  = in;
+    td.out = out;
+    ctx->internal->execute(ctx, filter_slice, &td, NULL, FFMIN(outlink->h, ctx->graph->nb_threads));
+
+    // ...
+
+    return ff_filter_frame(outlink, out);
+
+Last step is to add AVFILTER_FLAG_SLICE_THREADS flag to AVFilter.flags.
+
+For more example of slice threading additions, you can try to run git log -p
+--grep 'slice threading' libavfilter/
+
+Finalization
+~~~~~~~~~~~~
+
+When your awesome filter is finished, you have a few more steps before you're
+done:
+
+ - write its documentation in doc/filters.texi, and test the output with make
+   doc/ffmpeg-filters.html.
+ - add a FATE test, generally by adding an entry in
+   tests/fate/filter-video.mak, add running make fate-filter-foobar GEN=1 to
+   generate the data.
+ - add an entry in the Changelog
+ - edit libavfilter/version.h and increase LIBAVFILTER_VERSION_MINOR by one
+   (and reset LIBAVFILTER_VERSION_MICRO to 100)
+ - git add ... && git commit -m "avfilter: add foobar filter." && git format-patch -1
+
+When all of this is done, you can submit your patch to the ffmpeg-devel
+mailing-list for review.  If you need any help, feel free to come on our IRC
+channel, #ffmpeg-devel on irc.freenode.net.