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

[Stefano Sabatini]

On date Sunday 2011-03-27 11:22:32 -0400, Mike Scheutzow encoded:
> 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'm specifying:
Set the Display Aspect Ratio for the *filter* output video.

this should put emphasis on the fact that the value is set for the
*filter* output video, rather than for the *filterchain* or tool
output video. I don't think it is necessary to extend this more, as
this is a filter documentation, so it should be already quite clear in
the mind of the reader.
 
> 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.)

I tried to extend and clarify in the description all the possible
confusion point that you pointed out.

> >+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".

Yes.

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

Thanks for the excellent suggestions.

Patch updated (I'll apply in few days if I see no more comments).
-- 
FFmpeg = Foolish & Fantastic Merciless Pacific Erroneous Gangster
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-documentation-add-setdar-and-setsar-description-to-f.patch
Type: text/x-diff
Size: 3008 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20110329/58c481fe/attachment.bin>