lavu/opt: add AV_OPT_FLAG_DEPRECATED
[ffmpeg.git] / doc / writing_filters.txt
index 7051f5e..98b9c6f 100644 (file)
@@ -3,8 +3,8 @@ 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
+development mailing-list and make sure that they are applied. Otherwise, your filters
+are likely to have a very short lifetime due to more or less regular internal API
 changes, and a limited distribution, review, and testing.
 
 Bootstrap
@@ -23,7 +23,7 @@ for others using the `./ffmpeg -v 0 -filters|grep ' V->V '` command.
    pattern of the other filters.
  - ./configure ...
  - make -j<whatever> ffmpeg
- - ./ffmpeg -i http://upload.wikimedia.org/wikipedia/en/2/24/Lenna.png -vf foobar foobar.png
+ - ./ffmpeg -i http://samples.ffmpeg.org/image-samples/lena.pnm -vf foobar foobar.png
    Note here: you can obviously use a random local image instead of a remote URL.
 
 If everything went right, you should get a foobar.png with Lena edge-detected.
@@ -31,21 +31,19 @@ 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:
+libavfilter/allfilters.c:this file is 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
+    $ grep FOOBAR ffbuild/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.
+CONFIG_FOOBAR_FILTER=yes from the ffbuild/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
 ==================
@@ -64,7 +62,7 @@ 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/.
+Next chunk is the Doxygen about the file. See https://ffmpeg.org/doxygen/trunk/.
 Detail here what the filter is, does, and add some references if you feel like
 it.
 
@@ -73,11 +71,11 @@ 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.
+worry about uninitialized reads into this context. This is where you put all
+"global" information that you need; typically the variables 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.
+need to keep assuming you have a context. There is some magic you don't need to
+care about around this field, just let it be (in the first position) for now.
 
 Options
 -------
@@ -87,7 +85,7 @@ 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
+ - name is the option name, keep it simple and 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()
@@ -99,7 +97,7 @@ have the following pattern:
  - 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,
+When in doubt, just look at the other AVOption definitions all around the codebase,
 there are tons of examples.
 
 Class
@@ -146,14 +144,14 @@ 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
+Similarly, there is the uninit() callback, doing what the name suggests. 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
+This follows the init() and is used for the format negotiation. Basically
+you specify here 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
@@ -182,7 +180,7 @@ will update outlink->w and outlink->h.
 filter_frame()
 ~~~~~~~~~~~~~~
 
-This is the callback you are waiting from the beginning: it is where you
+This is the callback you are waiting for 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.
 
@@ -317,7 +315,7 @@ Adding timeline support
 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
+basically if your filter just alters whatever goes in and doesn't need
 previous/future information. See for instance commit 86cb986ce that adds
 timeline support to the fieldorder filter.