[FFmpeg-devel] [PATCH] doc: update filter_design.txt to API changes.

[Stefano Sabatini]

On date Thursday 2012-11-29 17:42:15 +0100, Nicolas George encoded:
> 
> Signed-off-by: Nicolas George <nicolas.george at normalesup.org>
> ---
>  doc/filter_design.txt |   69 +++++++++++++++++++++++++++++--------------------
>  1 file changed, 41 insertions(+), 28 deletions(-)
> 
> 
> I performed the corresponding reindents. A word-diff would probably be more
> readable.
> 
> 
> diff --git a/doc/filter_design.txt b/doc/filter_design.txt
> index 362fce4..4da281b 100644
> --- a/doc/filter_design.txt
> +++ b/doc/filter_design.txt
> @@ -15,13 +15,13 @@ Format negotiation
>    the list of supported formats.
>  
>    For video links, that means pixel format. For audio links, that means
> -  channel layout, and sample format (the sample packing is implied by the
> -  sample format).
> +  channel layout, sample format (the sample packing is implied by the sample
> +  format) and sample rate.
>  
>    The lists are not just lists, they are references to shared objects. When
>    the negotiation mechanism computes the intersection of the formats
> -  supported at each ends of a link, all references to both lists are
> -  replaced with a reference to the intersection. And when a single format is
> +  supported at each end of a link, all references to both lists are replaced
> +  with a reference to the intersection. And when a single format is
>    eventually chosen for a link amongst the remaining list, again, all
>    references to the list are updated.
>  
> @@ -68,15 +68,15 @@ Buffer references ownership and permissions
>  
>      Here are the (fairly obvious) rules for reference ownership:
>  
> -    * A reference received by the start_frame or filter_frame method
> -      belong to the corresponding filter.
> +    * A reference received by the filter_frame method (or its start_frame
> +      obsolete version) belong to the corresponding filter.

belongS

>  
>        Special exception: for video references: the reference may be used
>        internally for automatic copying and must not be destroyed before
>        end_frame; it can be given away to ff_start_frame.
>  
> -    * A reference passed to ff_start_frame or ff_filter_frame is given
> -      away and must no longer be used.

> +    * A reference passed ff_filter_frame (or the obsolete ff_start_frame) is
> +      given away and must no longer be used.

A reference passed _to_ ... (or _to_ the ...

>  
>      * A reference created with avfilter_ref_buffer belongs to the code that
>        created it.
> @@ -93,21 +93,22 @@ Buffer references ownership and permissions
>      The AVFilterLink structure has a few AVFilterBufferRef fields. Here are
>      the rules to handle them:
>  
> -    * cur_buf is set before the start_frame and filter_frame methods to
> -      the same reference given as argument to the methods and belongs to the
> +    * cur_buf is set before filter_frame (or start_frame) method to
> +      the same reference given as argument to the method and belongs to the
>        destination filter of the link. If it has not been cleared after
> -      end_frame or filter_frame, libavfilter will automatically destroy
> -      the reference; therefore, any filter that needs to keep the reference
> -      for longer must set cur_buf to NULL.

> +      filter_frame returns (or end_frame), libavfilter will automatically

To me it sounds more natural:
 If it has not been cleared after filter_frame (or end_frame) returns, ...

> +      destroy the reference; therefore, any filter that needs to keep the
> +      reference for longer must set cur_buf to NULL.
>  
>      * out_buf belongs to the source filter of the link and can be used to
>        store a reference to the buffer that has been sent to the destination.
> -      If it is not NULL after end_frame or filter_frame, libavfilter will
> +      If it is not NULL after filter_frame (or end_frame), libavfilter will
>        automatically destroy the reference.
>  
> -      If a video input pad does not have a start_frame method, the default
> -      method will request a buffer on the first output of the filter, store
> -      the reference in out_buf and push a second reference to the output.
> +      If a video input pad have neither filter_frame nor start_frame
> +      methods, the default method will request a buffer on the first output
> +      of the filter, store the reference in out_buf and push a second
> +      reference to the output.
>  
>      * src_buf, cur_buf_copy and partial_buf are used by libavfilter
>        internally and must not be accessed by filters.
> @@ -119,8 +120,10 @@ Buffer references ownership and permissions
>      the code that owns the reference is allowed to do to the buffer data.
>      Different references for the same buffer can have different permissions.
>  
> -    For video filters, the permissions only apply to the parts of the buffer
> -    that have already been covered by the draw_slice method.

> +    For video filters that implement the obsolete

I think "obsolete" is not the right term, "deprecated" seems more
correct.

> +    start_frame/draw_slice/end_frame API, the permissions only apply to the
> +    parts of the buffer that have already been covered by the draw_slice
> +    method.
>  
>      The value is a binary OR of the following constants:
>  
> @@ -179,7 +182,7 @@ Buffer references ownership and permissions
>        with the WRITE permission.
>  
>      * Filters that intend to keep a reference after the filtering process
> -      is finished (after end_frame or filter_frame returns) must have the
> +      is finished (after filter_frame (or end_frame) returns) must have the

Nit: possibly skip evil annidated ((..))

>        PRESERVE permission on it and remove the WRITE permission if they
>        create a new reference to give it away.
>  
> @@ -198,11 +201,11 @@ Frame scheduling
>    Simple filters that output one frame for each input frame should not have
>    to worry about it.
>  

> -  start_frame / filter_frame
> -  ----------------------------
> +  filter_frame (or start_frame)
> +  -----------------------------

Well that's weird, you already predicted how the name was going to
change.

>  
> -    These methods are called when a frame is pushed to the filter's input.
> -    They can be called at any time except in a reentrant way.
> +    This method is called when a frame is pushed to the filter's input. It
> +    can be called at any time except in a reentrant way.
>  
>      If the input frame is enough to produce output, then the filter should
>      push the output frames on the output link immediately.
> @@ -213,7 +216,7 @@ Frame scheduling
>      filter; these buffered frames must be flushed immediately if a new input
>      produces new output.
>  
> -    (Example: framerate-doubling filter: start_frame must (1) flush the
> +    (Example: framerate-doubling filter: filter_frame must (1) flush the
>      second copy of the previous frame, if it is still there, (2) push the
>      first copy of the incoming frame, (3) keep the second copy for later.)
>  
> @@ -233,8 +236,8 @@ Frame scheduling
>  
>      This method is called when a frame is wanted on an output.
>  
> -    For an input, it should directly call start_frame or filter_frame on
> -    the corresponding output.
> +    For an input, it should directly call filter_frame on the corresponding
> +    output.
>  
>      For a filter, if there are queued frames already ready, one of these
>      frames should be pushed. If not, the filter should request a frame on
> @@ -266,4 +269,14 @@ Frame scheduling
>  
>      Note that, except for filters that can have queued frames, request_frame
>      does not push frames: it requests them to its input, and as a reaction,
> -    the start_frame / filter_frame method will be called and do the work.
> +    the filter_frame method will be called and do the work.
> +
> +Legacy API
> +==========
> +
> +  Until libavfilter 3.23, the filter_frame method was split:
> +
> +  - for video filters, it was made of start_frame, draw_slice (that could be
> +    called several times on distinct parts of the frame) and end_frame;
> +
> +  - for audio filters, it was called filter_samples.

LGTM otherwise, thanks.

BTW, as noted by Clement there are some "avfilter_" in the docs which
should be replaced by "ff_".
-- 
FFmpeg = Faithful Fast Majestic Problematic Exuberant Guide