[FFmpeg-devel] [PATCH V2] doc/encoders.texi: Add doc for qsv

[Xiang, Haihao]

On Thu, 2022-01-06 at 11:00 +0800, Wenbin Chen wrote:
> Add doc for qsv decoder.
> Add more option's introduction to qsv encoder.
> 
> Signed-off-by: Wenbin Chen <wenbin.chen at intel.com>
> ---
>  doc/decoders.texi |  42 ++++++++
>  doc/encoders.texi | 253 +++++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 292 insertions(+), 3 deletions(-)
> 
> diff --git a/doc/decoders.texi b/doc/decoders.texi
> index 49ab735dce..de2429abba 100644
> --- a/doc/decoders.texi
> +++ b/doc/decoders.texi
> @@ -126,6 +126,48 @@ Set amount of frame threads to use during decoding. The
> default value is 0 (auto
>  
>  @end table
>  
> + at section QSV Decoders
> +
> +The family of Intel QuickSync Video decoders (VC1, MPEG-2, H.264, HEVC,
> +JPEG/MJPEG, VP8, VP9, AV1).
> +
> + at subsection Common Options
> +
> +The following options are supported by all qsv decoders.
> +
> + at table @option
> +
> + at item @var{async_depth}
> +Internal parallelization depth, the higher the value the higher the latency.
> +
> + at item @var{gpu_copy}
> +A GPU-accelerated copy between video and system memory
> + at table @samp
> + at item default
> + at item on
> + at item off
> + at end table
> +
> + at end table
> +
> + at subsection HEVC Options
> +Extra options for hevc_qsv.
> +
> + at table @option
> +
> + at item @var{load_plugin}
> +A user plugin to load in an internal session
> + at table @samp
> + at item none
> + at item hevc_sw
> + at item hevc_hw
> + at end table
> +
> + at item @var{load_plugins}
> +A :-separate list of hexadecimal plugin UIDs to load in an internal session
> +
> + at end table
> +
>  @c man end VIDEO DECODERS
>  
>  @chapter Audio Decoders
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index e3b61de5a1..7cc8be1209 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -3123,12 +3123,13 @@ Setting a higher @option{bits_per_mb} limit will
> improve the speed.
>  For the fastest encoding speed set the @option{qscale} parameter (4 is the
>  recommended value) and do not set a size constraint.
>  
> - at section QSV encoders
> + at section QSV Encoders
>  
> -The family of Intel QuickSync Video encoders (MPEG-2, H.264, HEVC, JPEG/MJPEG
> and VP9)
> +The family of Intel QuickSync Video encoders (MPEG-2, H.264, HEVC, JPEG/MJPEG
> +and VP9)
>  
> + at subsection Ratecontrol Method
>  The ratecontrol method is selected as follows:
> -
>  @itemize @bullet
>  @item
>  When @option{global_quality} is specified, a quality-based mode is used.
> @@ -3176,6 +3177,7 @@ Note that depending on your system, a different mode
> than the one you specified
>  may be selected by the encoder. Set the verbosity level to @var{verbose} or
>  higher to see the actual settings used by the QSV runtime.
>  
> + at subsection Global Options -> MSDK Options
>  Additional libavcodec global options are mapped to MSDK options as follows:
>  
>  @itemize
> @@ -3212,6 +3214,251 @@ encoder use CAVLC instead of CABAC.
>  
>  @end itemize
>  
> + at subsection Common Options
> +Following options are used by all qsv encoders.
> +
> + at table @option
> + at item @var{async_depth}
> +Specifies how many asynchronous operations an application performs
> +before the application explicitly synchronizes the result. If zero,
> +the value is not specified.
> +
> + at item @var{avbr_accuracy}
> +Accuracy of the AVBR ratecontrol (unit of tenth of percent).
> +
> + at item @var{avbr_convergence}
> +Convergence of the AVBR ratecontrol (unit of 100 frames)
> +
> +The parameters @var{avbr_accuracy} and @var{avbr_convergence} are for the
> +average variable bitrate control (AVBR) algorithm.
> +The algorithm focuses on overall encoding quality while meeting the specified
> +bitrate, @var{target_bitrate}, within the accuracy range @var{avbr_accuracy},
> +after a @var{avbr_Convergence} period. This method does not follow HRD and
> the
> +instant bitrate is not capped or padded.
> +
> + at item @var{preset}
> +This option itemizes a range of choices from veryfast (best speed) to
> veryslow
> +(best quality).
> + at table @samp
> + at item veryfast
> + at item faster
> + at item fast
> + at item medium
> + at item slow
> + at item slower
> + at item veryslow
> + at end table
> +
> + at item @var{forced_idr}
> +Forcing I frames as IDR frames.
> +
> + at item @var{low_power}
> +For encoders set this flag to ON to reduce power consumption and GPU usage.
> + at end table
> +
> + at subsection H264 options
> +These options are used by h264_qsv
> +
> + at table @option
> + at item @var{extbrc}
> +Extended bitrate control.
> +
> + at item @var{recovery_point_sei}
> +Set this flag to insert the recovery point SEI message at the beginning of
> every
> +intra refresh cycle.
> +
> + at item @var{rdo}
> +Enable rate distortion optimization.
> +
> + at item @var{max_frame_size}
> +Maximum encoded frame size in bytes.
> +
> + at item @var{max_slice_size}
> +Maximum encoded slice size in bytes.
> +
> + at item @var{bitrate_limit}
> +Toggle bitrate limitations.
> +Modifies bitrate to be in the range imposed by the QSV encoder. Setting this
> +flag off may lead to violation of HRD conformance. Mind that specifying
> bitrate
> +below the QSV encoder range might significantly affect quality. If on this
> +option takes effect in non CQP modes: if bitrate is not in the range imposed
> +by the QSV encoder, it will be changed to be in the range.
> +
> + at item @var{mbbrc}
> +Setting this flag enables macroblock level bitrate control that generally
> +improves subjective visual quality. Enabling this flag may have negative
> impact
> +on performance and objective visual quality metric.
> +
> + at item @var{adaptive_i}
> +This flag controls insertion of I frames by the QSV encoder. Turn ON this
> flag
> +to allow changing of frame type from P and B to I.
> +
> + at item @var{adaptive_b}
> +This flag controls changing of frame type from B to P.
> +
> + at item @var{b_strategy}
> +This option controls usage of B frames as reference.
> +
> + at item @var{cavlc}
> +If set, CAVLC is used; if unset, CABAC is used for encoding.
> +
> + at item @var{vcm}
> +Video conferencing mode, please see ratecontrol method.
> +
> + at item @var{idr_interval}
> +Distance (in I-frames) between IDR frames.
> +
> + at item @var{pic_timing_sei}
> +Insert picture timing SEI with pic_struct_syntax element.
> +
> + at item @var{single_sei_nal_unit}
> +Put all the SEI messages into one NALU.
> +
> + at item @var{max_dec_frame_buffering}
> +Maximum number of frames buffered in the DPB.
> +
> + at item @var{look_ahead}
> +Use VBR algorithm with look ahead.
> +
> + at item @var{look_ahead_depth}
> +Depth of look ahead in number frames.
> +
> + at item @var{look_ahead_downsampling}
> +Downscaling factor for the frames saved for the lookahead analysis.
> + at table @samp
> + at item unknown
> + at item auto
> + at item off
> + at item 2x
> + at item 4x
> + at end table
> +
> + at item @var{int_ref_type}
> +Specifies intra refresh type. The major goal of intra refresh is improvement
> of
> +error resilience without significant impact on encoded bitstream size caused
> by
> +I frames. The SDK encoder achieves this by encoding part of each frame in
> +refresh cycle using intra MBs. @var{none} means no refresh. @var{vertical}
> means
> +vertical refresh, by column of MBs.
> +
> + at item @var{int_ref_cycle_size}
> +Specifies number of pictures within refresh cycle starting from 2. 0 and 1
> are
> +invalid values.
> +
> + at item @var{int_ref_qp_delta}
> +Specifies QP difference for inserted intra MBs. This is signed value in
> +[-51, 51] range if target encoding bit-depth for luma samples is 8 and this
> +range is [-63, 63] for 10 bit-depth or [-75, 75] for 12 bit-depth
> respectively.
> +
> + at item @var{profile}
> + at table @samp
> + at item unknown
> + at item baseline
> + at item main
> + at item high
> + at end table
> +
> + at item @var{a53cc}
> +Use A53 Closed Captions (if available).
> +
> + at item @var{aud}
> +Insert the Access Unit Delimiter NAL.
> +
> + at item @var{mfmode}
> +Multi-Frame Mode.
> + at table @samp
> + at item off
> + at item auto
> + at end table
> +
> + at item @var{repeat_pps}
> +Repeat pps for every frame.
> + at end table
> +
> + at subsection HEVC Options
> +These options are used by hevc_qsv
> +
> + at table @option
> + at item @var{extbrc}
> +Extended bitrate control.
> +
> + at item @var{recovery_point_sei}
> +Set this flag to insert the recovery point SEI message at the beginning of
> every
> +intra refresh cycle.
> +
> + at item @var{rdo}
> +Enable rate distortion optimization.
> +
> + at item @var{idr_interval}
> +Distance (in I-frames) between IDR frames.
> + at table @samp
> + at item begin_only
> +Output an IDR-frame only at the beginning of the stream.
> + at end table
> +
> + at item @var{load_plugin}
> +A user plugin to load in an internal session.
> + at table @samp
> + at item none
> + at item hevc_sw
> + at item hevc_hw
> + at end table
> +
> + at item @var{load_plugins}
> +A :-separate list of hexadecimal plugin UIDs to load in
> +an internal session.
> +
> + at item @var{look_ahead_depth}
> +Depth of look ahead in number frames, available when extbrc option is
> enabled.
> +
> + at item @var{profile}
> + at table @samp
> + at item unknown
> + at item main
> + at item main10
> + at item mainsp
> + at item rext
> + at end table
> +
> + at item @var{gpb}
> +1: GPB (generalized P/B frame)
> +
> +0: regular P frame.
> +
> + at item @var{tile_cols}
> +Number of columns for tiled encoding.
> +
> + at item @var{tile_rows}
> +Number of rows for tiled encoding.
> +
> + at item @var{aud}
> +Insert the Access Unit Delimiter NAL.
> + at end table
> +
> + at subsection MPEG2 Options
> +These options are used by mpeg2_qsv
> + at table @option
> + at item @var{profile}
> + at table @samp
> + at item unknown
> + at item simple
> + at item main
> + at item high
> + at end table
> + at end table
> +
> + at subsection VP9 Options
> +These options are used by vp9_qsv
> + at table @option
> + at item @var{profile}
> + at table @samp
> + at item unknown
> + at item profile0
> + at item profile1
> + at item profile2
> + at item profile3
> + at end table
> + at end table
> +
>  @section snow
>  
>  @subsection Options

Applied, thx!