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

[Stefano Sabatini]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0002-doc-add-libswscale.texi.patch
Type: text/x-diff
Size: 4442 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121115/7b9d3075/attachment.bin>