[FFmpeg-devel,v3] doc/v4l2_m2m: Add documentation

From: Andriy Gelman <andriy.gelman@gmail.com>

Signed-off-by: Andriy Gelman <andriy.gelman@gmail.com>
---

Gyan, I added an extra paragraph about the buffer parameters. It doesn't seem
right to add the same content into each bullet point. Let me know your thoughts. 

Thanks,
Andriy

 doc/decoders.texi | 32 +++++++++++++++++++++++++++++
 doc/encoders.texi | 51 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+)

On 17/01/2020 03:42, Andriy Gelman wrote:
> From: Andriy Gelman <andriy.gelman@gmail.com>
> 
> Signed-off-by: Andriy Gelman <andriy.gelman@gmail.com>
> ---
> 
> Gyan, I added an extra paragraph about the buffer parameters. It doesn't seem
> right to add the same content into each bullet point. Let me know your thoughts. 

The discussion of them could go in general.texi instead?

It might be worth mentioning at the same time that you need recentish linux kernel headers installed to build.

>  doc/decoders.texi | 32 +++++++++++++++++++++++++++++
>  doc/encoders.texi | 51 +++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 83 insertions(+)
> 
> diff --git a/doc/decoders.texi b/doc/decoders.texi
> index f18226b3504..22a587ffdb9 100644
> --- a/doc/decoders.texi
> +++ b/doc/decoders.texi
> @@ -86,6 +86,38 @@ AVS2-P2/IEEE1857.4 video decoder wrapper.
>  
>  This decoder allows libavcodec to decode AVS2 streams with davs2 library.
>  
> +@section v4l2m2m
> +
> +libavcodec supports a set of v4l2m2m wrappers for interfacing with
> +hardware decoders. Depending on the hardware's capabilities the following decoders may be selected:
> +h264, hevc, mpeg1, mpeg2, mpeg4, h263, vc1, vp8, and vp9.
> +
> +To use a specific decoder append a  _v4l2m2m suffix. For example to select h264
> +decoder use:
> +@example
> +ffmpeg -codec:v h264_v4l2m2m -i INPUT OUTPUT
> +@end example
> +
> +libavcodec also supports changing the number of output and capture buffers on
> +the v4l2m2m device. If the API is used as per the recommendation, there should
> +be no reason to change the parameters from the default values. The description
> +of the parameters is as follows:
> +
> +@table @option
> +@item num_output_buffers
> +Number of memory mapped buffers to store the input packets. This value is only a
> +suggestion to the hardware device. The device will attempt to allocate the
> +number of buffers, but the actual value may be smaller/larger and ultimately
> +depends on the device. The default for the option is 16, minimum is 6, and any
> +large value (representable by an int) is accepted for the max.> +
> +@item num_capture_buffers
> +Number of memory mapped buffers to store the decompressed frames. The device
> +will attempt to allocate the number of buffers, but the actual value may be
> +smaller/larger and ultimately depends on the device. Default is 20, minimum is
> +20, and any large value (representable by an int) is accepted for the max.
> +@end table

I wonder whether it would be more helpful to explain /why/ these values are exposed.

There are four factors competing here:
1) Reordering in the stream, if the decoder is returning reference frame buffers directly without any extra copies.  (This was what drove the choice of the default value.)
2) Allowing extra buffers that the user can hold on to outside the decoder without blocking forward progress.
3) Possible parallelism in the decoder, which may be able to increase single-stream throughput by using more buffers.
4) Minimising the amount of memory being used.

So: it's possible that a larger value may be required for some weird streams (not necessarily detectable in advance), while in many (most, even) cases quite a bit of memory can be saved by decreasing the numbers.

> +
>  @c man end VIDEO DECODERS
>  
>  @chapter Audio Decoders
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index 61e674cf968..f82500ca34c 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -3117,6 +3117,57 @@ required to produce a stream usable with all decoders.
>  
>  @end table
>  
> +@section v4l2m2m
> +
> +libavcodec supports a set of v4l2m2m wrappers for interfacing with hardware encoders.
> +Depending on the hardware's capabilities the following encoders may be selected:
> +mpeg4, h263, h264, hevc, and vp8.
> +
> +To use a specific encoder append _v4l2m2m suffix. For example to select h264 use:
> +@example
> +ffmpeg -i INPUT [-pix_fmt pixfmt] -codec:v h264_v4l2m2m OUTPUT
> +@end example
> +In some cases, it may be necessary to insert a pixel format conversion with
> +@code{-pix_fmt}. This is required if the pixel format of the input does not
> +match the format of the encoder. If there is a mismatch, libavcodec will
> +exit and specify the required pixfmt to use.
> +
> +Standard libavcodec options (encoder and device dependent) that can be set are:
> +@itemize
> +@item
> +@option{b} / @option{bit_rate}
> +@item
> +@option{g} / @option{gop_size}
> +@item
> +@option{bf} / @option{max_b_frames}
> +@item
> +@option{qpel}
> +@item
> +@option{qmin}
> +@item
> +@option{qmax}
> +@end itemize

Also profile.

> +
> +libavcodec also supports changing the number of output and capture buffers
> +on the v4l2m2m device. If the API is used as per the recommendation, there
> +should be no reason to change the parameters from the default values. The
> +description of the parameters is as follows:
> +
> +@table @option
> +@item num_output_buffers
> +Number of memory mapped buffers to store the input frames. This value is only a
> +suggestion to the hardware device. The device will attempt to allocate the
> +number of buffers, but the actual value may be smaller/larger and ultimately
> +depends on the device. The default for the option is 16, minimum is 6, and any
> +large value (representable by an int) is accepted for the max.
> +
> +@item num_capture_buffers
> +Number of memory mapped buffers to store the compressed packets. The device will
> +attempt to allocate the number of buffers, but the actual value may be
> +smaller/larger and ultimately depends on the device. Default is 4, minimum is 4,
> +and any large value (representable by an int) is accepted for the max.
> +@end table
> +
>  @section vc2
>  
>  SMPTE VC-2 (previously BBC Dirac Pro). This codec was primarily aimed at
> 

Thanks,

- Mark