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

[Stefano Sabatini]

On date Tuesday 2011-03-29 00:00:28 +0200, Stefano Sabatini encoded:
> 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).

Updated with a few changes (changed W/H ->
HORIZONTAL_RESOLUTION/VERTICAL_RESOLUTION in the DAR/SAR equation,
also updated the paragraph about the default value, I see that the
default value logic needs some revisitation).
-- 
FFmpeg = Fabulous & Frightening Mournful Peaceful Exciting Gem
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-documentation-add-setdar-and-setsar-description-to-f.patch
Type: text/x-diff
Size: 2963 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20110330/13269705/attachment.bin>