[FFmpeg-devel] [PATCH] doc: add libswscale.texi

[Stefano Sabatini]

On date Thursday 2012-11-15 11:23:23 +0100, Stefano Sabatini encoded:
> On date Wednesday 2012-11-14 00:05:14 +0100, Clément Bœsch encoded:
> > On Tue, Nov 13, 2012 at 11:50:02PM +0100, Stefano Sabatini wrote:
> > > ---
> > >  doc/Makefile        |    1 +
> > >  doc/libswscale.texi |  155 +++++++++++++++++++++++++++++++++++++++++++++++++++
> > >  2 files changed, 156 insertions(+)
> > >  create mode 100644 doc/libswscale.texi
> > > 
> > > diff --git a/doc/Makefile b/doc/Makefile
> > > index 8709b0a..0d91824 100644
> > > --- a/doc/Makefile
> > > +++ b/doc/Makefile
> > > @@ -1,4 +1,5 @@
> > >  DOCLIBS-$(CONFIG_AVUTIL)  += libavutil
> > > +DOCLIBS-$(CONFIG_SWSCALE) += libswscale
> > >  DOCLIBS-$(CONFIG_SWRESAMPLE) += libswresample
> > >  DOCLIBS-$(CONFIG_AVCODEC) += libavcodec
> > >  DOCLIBS-$(CONFIG_AVFILTER) += libavfilter
> > > diff --git a/doc/libswscale.texi b/doc/libswscale.texi
> > > new file mode 100644
> > > index 0000000..150e1ef
> > > --- /dev/null
> > > +++ b/doc/libswscale.texi
> > > @@ -0,0 +1,155 @@
> > > +\input texinfo @c -*- texinfo -*-
> > > +
> > > + at settitle Libswscale Documentation
> > > + at titlepage
> > > + at center @titlefont{Libswscale Documentation}
> > > + at end titlepage
> > > +
> > > + at top
> > > +
> > > + at contents
> > > +
> > > + at chapter Description
> > > + at c man begin DESCRIPTION
> > > +
> > > +The libswscale library performs highly optimized image scaling and
> > > +colorspace / pixel format conversion operations.
> > > +
> > > +The libswscale library performs the following conversions:
> > > +
> > > + at itemize
> > > + at item
> > > + at emph{Rescaling}: is the process of changing the video size. Several
> > > +rescaling options and algorithms are available. This is usually a
> > > +lossy process.
> > > +
> > > + at item
> > > + at emph{Format conversion}: is the process of converting the image
> > > +format and colorspace of the image, for example from planar YUV420P to
> > > +RGB24 packed. It also handles packing conversion, when passing from
> > > +packed layout (all pixels belonging to distinct planes interleaved in
> > > +the same buffer), to planar layout (all samples belonging to the same
> > > +plane stored in a dedicated buffer or "plane").
> > > +
> > > +This is usually a lossy process in case the colorspace of source and
> > > +destination formats differ.
> > > + at end itemize
> > > +
> > > + at c man end DESCRIPTION
> > > +
> > > + at chapter Video Conversion Options
> > > + at c man begin VIDEO CONVERSION OPTIONS
> > > +
> > > +The video converter supports the following named options.
> > > +
> > > +Options may be set by specifying - at var{option} @var{value} in the
> > 
> > nit: @code{-option value}?
> 
> Uhm no, I still prefer @var, since @code implies literal content.
> 
> > > +FFmpeg tools, or by setting the value explicitly in the
> > > + at code{SwsContext} options or using the @file{libavutil/opt.h} API for
> > > +programmatic use.
> > > +
> > 
> > The multiple "or" are kind of uneasy to parse.
> 
> Yes, reworded.
>  
> > > + at table @option
> > > +
> > > + at item sws_flags
> > > +Set the scaler flags. This is also used to set the scaling
> > > +algorithm. Only a single algorithm should be selected.
> > > +
> > > +It accepts the following values:
> > > + at table @samp
> > > + at item fast_bilinear
> > > +select fast bilinear scaling algorithm
> > > +
> > > + at item bilinear
> > > +select bilinear scaling algorithm
> > > +
> > > + at item bicubic
> > > +select bicubic scaling algorithm
> > > +
> > > + at item experimental
> > > +select experimental scaling algorithm
> > > +
> > > + at item nighbor
> > > +select nearest neighbor rescaling algorithm
> > > +
> > > + at item area
> > > +select averaging area rescaling algorithm
> > > +
> > > + at item bicubiclin
> > > +select bicub scaling algorithm for the luma component, bilinear for
> > > +chroma components
> > > +
> > > + at item gauss
> > > +select Gaussian rescaling algorithm
> > > +
> > > + at item sinc
> > > +select sinc rescaling algorithm
> > > +
> > > + at item lanczos
> > > +select lanczos rescaling algorithm
> > > +
> > > + at item spline
> > > +select natural bicubic spline rescaling algorithm
> > > +
> > > + at item print_info
> > > +enable printing/debug logging
> > > +
> > > + at item accurate_rnd
> > > +enable accurante rounding
> > > +
> > 
> > accurate
> 
> Fixed.
> 
> > > + at item full_chroma_int
> > > +enable full chroma interpolation
> > > +
> > > + at item full_chroma_inp
> > > +select full chroma input
> > > +
> > > + at item bitexact
> > > +enable bitexact output
> > > + at end table
> > > +
> > 
> > Above: no caps, no dot
> > Below:    caps,    dots
> 
> Fixed.
> 
> > > + at item srcw
> > > +Set source width.
> > > +
> > > + at item srch
> > > +Set source height.
> > > +
> > > + at item dstw
> > > +Set destination width.
> > > +
> > > + at item dsth
> > > +Set destination height.
> > > +
> > > + at item src_format
> > > +Set source pixel format (must be expressed as an integer).
> > > +
> > > + at item dst_format
> > > +Set destination pixel format (must be expressed as an integer).
> > > +
> > > + at item src_range
> > > +Select source range.
> > > +
> > > + at item dst_range
> > > +Select destination range.
> > > +
> > 
> > > + at item param0, param1
> > > +Set scaler parameters 0 and 1, used by some algorithm. It is a
> > > +floating point value.
> > > +
> > 
> 
> > Is it really necessary to document this?
> 
> Again, bad/incomplete documentation is better than no documentation
> at all. Slightly reworded to make it more clear (we completely miss
> which algorithms need them, and what they mean).
> 
> > 
> > > + at end table
> > > +
> > > + at c man end VIDEO CONVERSION OPTIONS
> > > +
> > > + at ignore
> > > +
> > > + at setfilename libswscale
> > > + at settitle video conversion library
> > > +
> > 
> > "conversion" sounds inappropriate, or could be completed with "scaling".
> 
> Changed to:
> @settitle video scaling and pixel format conversion library
> 
> 
> > What's the meaning of the "sw" btw?
> 
> SowftWare?
> 
> > > + at c man begin SEEALSO
> 
> > > +ffmpeg(1), ffplay(1), ffprobe(1), ffserver(1), libavutil(3)
> > 
> > So, what's the logic behind the lib*(3) ties? It seems relatively
> > inconsistent between the different lib*.texi files, but I guess that can
> > be fixed when we have all of them upstream.
> 
> libx should only mention libraries on which it depends, currently
> inconsistent because libavcodec and libavfilter were added when no
> other documents were still available. I'll fix it globally when we
> have all the pieces in places.
> 
> > 
> > > + at c man end
> > > +
> > > + at c man begin AUTHORS
> > > +See Git history (git://source.ffmpeg.org/ffmpeg)
> > > + at c man end
> > > +
> > > + at end ignore
> > > +
> > > + at bye
> > 
> > No more comment from me, looks fine overall; and thanks for doing this,
> > it's gonna get pretty neat.
> 
> Thanks for the review, I'll push in a few days if I read no more
> comments.
> -- 
> FFmpeg = Funny Formidable Meaningful Philosophical Everlasting Governor

> From 1d1f10cad83d60bab370f6f56d250fa34f72deff Mon Sep 17 00:00:00 2001
> From: Stefano Sabatini <stefasab at gmail.com>
> Date: Tue, 13 Nov 2012 23:49:09 +0100
> Subject: [PATCH] doc: add libswscale.texi
> 
> ---
>  doc/Makefile        |    1 +
>  doc/libswscale.texi |  154 +++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 155 insertions(+)
>  create mode 100644 doc/libswscale.texi

Updated. Will push today or later, please comment.
-- 
FFmpeg = Frightening Fostering Multimedia Philosophical Elastic Game
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0004-doc-add-libswscale.texi-and-ffmpeg-scaler.texi-files.patch
Type: text/x-diff
Size: 5821 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121125/349e3b9e/attachment.bin>