[FFmpeg-devel] [PATCH v7 2/2] doc: Add libsvt_hevc encoder docs

[Gyan]

On 11-03-2019 12:32 PM, Jing SUN wrote:
> Add docs for libsvt_hevc encoder in encoders.texi and general.texi
>
> Signed-off-by: Jun Zhao <jun.zhao at intel.com>
> Signed-off-by: Huang, Zhengxu <zhengxu.huang at intel.com>
> Signed-off-by: hassene <hassene.tmar at intel.com>
> Signed-off-by: Jing SUN <jing.a.sun at intel.com>
> ---
>   doc/encoders.texi | 145 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
>   doc/general.texi  |   8 +++
>   2 files changed, 153 insertions(+)
>
> diff --git a/doc/encoders.texi b/doc/encoders.texi
> index 29625ba..0b30776 100644
> --- a/doc/encoders.texi
> +++ b/doc/encoders.texi
> @@ -1569,6 +1569,151 @@ Set maximum NAL size in bytes.
>   Allow skipping frames to hit the target bitrate if set to 1.
>   @end table
>   
> + at section libsvt_hevc
> +
> +Scalable Video Technology for HEVC encoder (SVT-HEVC encoder) wrapper.

Remove 'encoder' inside the brackets.
> +This encoder requires the presence of the headers and
> +library during configuration. You need to explicitly configure the
> +build with @code{--enable-libsvthevc}. The library is detected using
> + at command{pkg-config}.
> +
> +For more information about the library see
> + at url{https://github.com/intel/SVT-HEVC.git}.
> +
> + at subsection Options
> +
> +The following FFmpeg global options affect the configurations of the
> +libsvt_hevc encoder.
s/configurations/configuration
> + at table @option
> + at item b  (@emph{bitrate})
> +Set the bitrate (as a number of bits per second). Default is 7M.
> +
> + at item g  / @option{gop_size}
> +Set the GOP size. Default is -2 (unspecified).
> +
> + at item flags +cgop
> +Enable closed GOP.
> +
> + at item qmin (@emph{min-q})
> +Defaults 10
"Default is 10."
> + at item qmax (@emph{max-q})
> +Defaults 48

"Default is 48."
> +Set minimum/maximum quantisation values.  Valid range is from 0 to 51
s/quantisation/quantization

> +Has to be qmax > = qmin).
"It is required that qmax >= qmin". Ideally, this should be fully 
verbal, but will do.

> + at item profile (@emph{profile})
> +Set profile restrictions. Can assume one of the following possible values:
> +
> +Default is 2 (main10).
> +
> + at table @samp
> + at item main
> +main profile
> + at item main10
> +main10 profile
> + at end table
Move the default to after the table.

> +
> + at item level
What are the permissible values? Is the default dynamic or fixed?
> + at option{profile} sets the value of @emph{profile}.
> + at option{level} sets the value of @emph{level}.

If this refers to the bitstream flags, make that clearer, and use the 
exact labels e.g. profile_idc. Place each sentence after its option entry.

> + at item hielevel
> +Set hierarchical levels. Can assume one of the following possible values:
> +
> +Default is 3 (4level).
> +
> + at table @samp
> + at item flat
> +none hierarchy level
> + at item 2level
> +2-level hierarchy
> + at item 3level
> +3-level hierarchy
> + at item 4level
> +4-level hierarchy
> + at end table

Move the default to after the table.
> + at item la_depth
> +Set look-ahead depth, depending on bit rate control mode @option{rc}, when
> +bit rate control mode is set to vbr it's best to set this parameter to be
> +equal to the intra period value (such is the default set by the encoder),
> +when cqp is chosen, then a look ahead is recommended. The range is from @var{0-256}.

"
Set lookahead depth (in frames). Range is @var{-1 - 256} where -1 
indicates the value is unset. Default is -1.
In rate-control mode @var{vbr}, if unset, the encoder will set this to 
the intra period value. In rate-control mode @var{cqp},
it is recommended that look-ahead depth be set.
"

What does the encoder do in cqp mode if value is unset? Are there 
specific guidelines for optimum la-depth value, in each rc mode?
If there are significant tradeoffs, in terms of latency or resource 
usage, mention those.
> + at item preset
> +A preset defining the quality vs density tradeoff point that the
> +encoding is to be performed at.(e.g. 0 is the highest quality mode,
> +12 is the highest density mode). The range is from @var{0-12}. Default is 9.

"
A preset setting the quality vs. density tradeoff that the encoder 
should make.
Range is @var{0-12}. Lower values favour quality over density. Default is 9.
"
> + at item tier
> +Set @emph{general_tier_flag}.  This may affect the level chosen for the stream
> +if it is not explicitly specified. Can assume one of the following possible values:
> +
> +Default is 1 (main).
> +
> + at table @samp
> + at item main
> +main tier
> + at item high
> +high tier
> + at end table

Move default to after the table.

> + at item rc
> +Set bit rate control mode. Can assume one of the following possible values:
> +
> +Default is 0 (cqp).
> +
> + at table @samp
> + at item cqp
> +Constant QP (CQP) mode
> + at item vbr
> +Variable Bit Rate (VBR) mode
> + at end table

Move default to after the table.
> + at item tune
> +Set quality tuning mode. Can assume one of the following possible values:
> +
> +Default is 1 (oq).
> +
> + at table @samp
> + at item sq
> +Visually optimized mode
> + at item oq
> +PSNR / SSIM optimized mode
> + at item vmaf
> +VMAF optimized mode
> + at end table

Move default to after the table.
> + at item bl_mode
> +Enables or disables Random Access Prediction. Default is 0 (disable).
> + at end table
Double-check, but I think this end directive is meant to close the table 
for the private options and is not correctly placed. The one after hdr 
is the correct one.
> + at item hdr
> +High dynamic range input. Default is 0 (disable).
"Flags input as having high dynamic range. Default is 0 (disabled)."

Thanks,
Gyan