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

[Clément Bœsch]

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}?

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

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

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

> + 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?

> + 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".
What's the meaning of the "sw" btw?

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

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

-- 
Clément B.
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 490 bytes
Desc: not available
URL: <http://ffmpeg.org/pipermail/ffmpeg-devel/attachments/20121114/96c6d5d4/attachment.asc>