encoders.texi: update libvpx documentation

modeled after the libx264 section.

Reviewed-by: Lou Logan <lou@lrcd.com>
Reviewed-by: Stefano Sabatini <stefasab@gmail.com>
Signed-off-by: James Zern <jzern@google.com>

1 files changed, 103 insertions, 75 deletions

diff --git a/doc/encoders.texi b/doc/encoders.texi
index 753e683..8b0ecb7 100644
--- a/doc/encoders.texi
+++ b/doc/encoders.texi
@@ -1416,113 +1416,141 @@ You need to explicitly configure the build with @code{--enable-libvpx}.
 
 @subsection Options
 
-Mapping from FFmpeg to libvpx options with conversion notes in parentheses.
+The following options are supported by the libvpx wrapper. The
+@command{vpxenc}-equivalent options or values are listed in parentheses
+for easy migration.
 
-@table @option
+To reduce the duplication of documentation, only the private options
+and some others requiring special attention are documented here. For
+the documentation of the undocumented generic options, see
+@ref{codec-options,,the Codec Options chapter}.
 
-@item threads
-g_threads
+To get more documentation of the libvpx options, invoke the command
+@command{ffmpeg -h encoder=libvpx}, @command{ffmpeg -h encoder=libvpx-vp9} or
+@command{vpxenc --help}. Further information is available in the libvpx API
+documentation.
 
-@item profile
-g_profile
+@table @option
 
-@item vb
-rc_target_bitrate
+@item b (@emph{target-bitrate})
+Set bitrate in bits/s. Note that FFmpeg's @option{b} option is
+expressed in bits/s, while @command{vpxenc}'s @option{target-bitrate} is in
+kilobits/s.
 
-@item g
-kf_max_dist
+@item g (@emph{kf-max-dist})
 
-@item keyint_min
-kf_min_dist
+@item keyint_min (@emph{kf-min-dist})
 
-@item qmin
-rc_min_quantizer
+@item qmin (@emph{min-q})
 
-@item qmax
-rc_max_quantizer
+@item qmax (@emph{max-q})
 
-@item bufsize, vb
-rc_buf_sz
-@code{(bufsize * 1000 / vb)}
+@item bufsize (@emph{buf-sz}, @emph{buf-optimal-sz})
+Set ratecontrol buffer size (in bits). Note @command{vpxenc}'s options are
+specified in milliseconds, the libvpx wrapper converts this value as follows:
+@code{buf-sz = bufsize * 1000 / bitrate},
+@code{buf-optimal-sz = bufsize * 1000 / bitrate * 5 / 6}.
 
-rc_buf_optimal_sz
-@code{(bufsize * 1000 / vb * 5 / 6)}
+@item rc_init_occupancy (@emph{buf-initial-sz})
+Set number of bits which should be loaded into the rc buffer before decoding
+starts. Note @command{vpxenc}'s option is specified in milliseconds, the libvpx
+wrapper converts this value as follows:
+@code{rc_init_occupancy * 1000 / bitrate}.
 
-@item rc_init_occupancy, vb
-rc_buf_initial_sz
-@code{(rc_init_occupancy * 1000 / vb)}
+@item undershoot-pct
+Set datarate undershoot (min) percentage of the target bitrate.
 
-@item rc_buffer_aggressivity
-rc_undershoot_pct
+@item overshoot-pct
+Set datarate overshoot (max) percentage of the target bitrate.
 
-@item skip_threshold
-rc_dropframe_thresh
+@item skip_threshold (@emph{drop-frame})
 
-@item qcomp
-rc_2pass_vbr_bias_pct
+@item qcomp (@emph{bias-pct})
 
-@item maxrate, vb
-rc_2pass_vbr_maxsection_pct
-@code{(maxrate * 100 / vb)}
+@item maxrate (@emph{maxsection-pct})
+Set GOP max bitrate in bits/s. Note @command{vpxenc}'s option is specified as a
+percentage of the target bitrate, the libvpx wrapper converts this value as
+follows: @code{(maxrate * 100 / bitrate)}.
 
-@item minrate, vb
-rc_2pass_vbr_minsection_pct
-@code{(minrate * 100 / vb)}
+@item minrate (@emph{minsection-pct})
+Set GOP min bitrate in bits/s. Note @command{vpxenc}'s option is specified as a
+percentage of the target bitrate, the libvpx wrapper converts this value as
+follows: @code{(minrate * 100 / bitrate)}.
 
-@item minrate, maxrate, vb
-@code{VPX_CBR}
-@code{(minrate == maxrate == vb)}
+@item minrate, maxrate, b @emph{end-usage=cbr}
+@code{(minrate == maxrate == bitrate)}.
 
-@item crf
-@code{VPX_CQ}, @code{VP8E_SET_CQ_LEVEL}
+@item crf (@emph{end-usage=cq}, @emph{cq-level})
 
-@item quality
-@table @option
-@item @var{best}
-@code{VPX_DL_BEST_QUALITY}
-@item @var{good}
-@code{VPX_DL_GOOD_QUALITY}
-@item @var{realtime}
-@code{VPX_DL_REALTIME}
+@item quality, deadline (@emph{deadline})
+@table @samp
+@item best
+Use best quality deadline. Poorly named and quite slow, this option should be
+avoided as it may give worse quality output than good.
+@item good
+Use good quality deadline. This is a good trade-off between speed and quality
+when used with the @option{cpu-used} option.
+@item realtime
+Use realtime quality deadline.
 @end table
 
-@item speed
-@code{VP8E_SET_CPUUSED}
+@item speed, cpu-used (@emph{cpu-used})
+Set quality/speed ratio modifier. Higher values speed up the encode at the cost
+of quality.
 
-@item nr
-@code{VP8E_SET_NOISE_SENSITIVITY}
+@item nr (@emph{noise-sensitivity})
 
-@item mb_threshold
-@code{VP8E_SET_STATIC_THRESHOLD}
+@item static-thresh
+Set a change threshold on blocks below which they will be skipped by the
+encoder.
 
-@item slices
-@code{VP8E_SET_TOKEN_PARTITIONS}
+@item slices (@emph{token-parts})
+Note that FFmpeg's @option{slices} option gives the total number of partitions,
+while @command{vpxenc}'s @option{token-parts} is given as
+@code{log2(partitions)}.
 
 @item max-intra-rate
-@code{VP8E_SET_MAX_INTRA_BITRATE_PCT}
+Set maximum I-frame bitrate as a percentage of the target bitrate. A value of 0
+means unlimited.
 
 @item force_key_frames
 @code{VPX_EFLAG_FORCE_KF}
 
 @item Alternate reference frame related
 @table @option
-@item vp8flags altref
-@code{VP8E_SET_ENABLEAUTOALTREF}
-@item @var{arnr_max_frames}
-@code{VP8E_SET_ARNR_MAXFRAMES}
-@item @var{arnr_type}
-@code{VP8E_SET_ARNR_TYPE}
-@item @var{arnr_strength}
-@code{VP8E_SET_ARNR_STRENGTH}
-@item @var{rc_lookahead}
-g_lag_in_frames
-@end table
-
-@item vp8flags error_resilient
-g_error_resilient
-
-@item aq_mode
-@code{VP9E_SET_AQ_MODE}
+@item auto-alt-ref
+Enable use of alternate reference frames (2-pass only).
+@item arnr-max-frames
+Set altref noise reduction max frame count.
+@item arnr-type
+Set altref noise reduction filter type: backward, forward, centered.
+@item arnr-strength
+Set altref noise reduction filter strength.
+@item rc-lookahead, lag-in-frames (@emph{lag-in-frames})
+Set number of frames to look ahead for frametype and ratecontrol.
+@end table
+
+@item error-resilient
+Enable error resiliency features.
+
+@item VP9-specific options
+@table @option
+@item lossless
+Enable lossless mode.
+@item tile-columns
+Set number of tile columns to use. Note this is given as
+@code{log2(tile_columns)}. For example, 8 tile columns would be requested by
+setting the @option{tile-columns} option to 3.
+@item tile-rows
+Set number of tile rows to use. Note this is given as @code{log2(tile_rows)}.
+For example, 4 tile rows would be requested by setting the @option{tile-rows}
+option to 2.
+@item frame-parallel
+Enable frame parallel decodability features.
+@item aq-mode
+Set adaptive quantization mode (0: off (default), 1: variance 2: complexity, 3:
+cyclic refresh).
+@end table
 
 @end table