[FFmpeg-devel] [PATCH] documentation: add setdar and setsar description to filters.texi

[Mike Scheutzow]

Stefano Sabatini wrote:
> ---
>  doc/filters.texi |   34 ++++++++++++++++++++++++++++++++++
>  1 files changed, 34 insertions(+), 0 deletions(-)
>
> diff --git a/doc/filters.texi b/doc/filters.texi
> index 25be868..bd14067 100644
> --- a/doc/filters.texi
> +++ b/doc/filters.texi
> @@ -901,6 +901,23 @@ ratio of the input image.
>  
>  The default value of @var{width} and @var{height} is 0.
>  
> + at section setdar
> +
> +Set the Display Aspect Ratio for the output video.
>   

The phrase "output video" is ambiguous, because it might mean the output 
of this filter, or
the final output from the entire video filter chain. Changing it to 
"...for the video frame output
from this block" would be better, or explicitly say that later filters 
can modify the value further.

I think you should explicitly mention that this filter does not modify 
the pixel dimensions of the
video frame. (As written, this description implies that internally 
ffmpeg keeps *both* DAR
and SAR values, so changing the number of pixels would be necessary to 
keep *both* values
accurate.)

> +
> +The filter accepts in input a string of the form @var{num}:@var{den},
> +where @var{num} and @var{den} are numerator and denominator of the
> +wanted display aspect ratio, or @var{float}, where @var{float} is a
> +floating number.
> +
> +If a parameter is not specified, it is assumed the value "0:1", and
> +the input display aspect ratio is kept.
> +
> +For example to change the display aspect ratio to 16:9, specify:
> + at example
> +setdar=16:9
> + at end example
> +
>  @section setpts
>  
>  Change the PTS (presentation timestamp) of the input video frames.
> @@ -961,6 +978,23 @@ setpts=N/(25*TB)
>  setpts='1/(25*TB) * (N + 0.05 * sin(N*2*PI/25))'
>  @end example
>  
> + at section setsar
> +
> +Set the Sample (aka Pixel) Aspect Ratio for the output video.
>   

Same comment about "output video" as above.

> +
> +The filter accepts in input a string of the form @var{num}:@var{den},
> +where @var{num} and @var{den} are numerator and denominator of the
> +wanted sample aspect ratio, or @var{float}, where @var{float} is a
> +floating number.
> +
> +If a parameter is not specified, it is assumed the value "0:1", and
> +the input sample aspect ratio is kept.
> +
> +For example to change the sample aspect ratio to 16:9, specify:
> + at example
> +setsar=16:9
>   

Using the example values 16:9 invites confusion between DAR and SAR. 
Better examples would be
"1:1" or "10:11".

> + at end example
> +
>  @section settb
>  
>  Set the timebase to use for the output frames timestamps.
>   


Mike Scheutzow