[x265-commits] [x265] doc: fix a sphinx build warning
Steve Borho
steve at borho.org
Thu Nov 27 00:05:42 CET 2014
details: http://hg.videolan.org/x265/rev/f488b394693b
branches:
changeset: 8915:f488b394693b
user: Steve Borho <steve at borho.org>
date: Wed Nov 26 16:56:16 2014 -0600
description:
doc: fix a sphinx build warning
Subject: [x265] doc: restructure documentation with better grouping, improve cross-refs
details: http://hg.videolan.org/x265/rev/dfe0803ae6be
branches:
changeset: 8916:dfe0803ae6be
user: Steve Borho <steve at borho.org>
date: Wed Nov 26 16:56:00 2014 -0600
description:
doc: restructure documentation with better grouping, improve cross-refs
diffstat:
doc/reST/cli.rst | 651 +++++++++++++++++++++++----------------------
doc/reST/introduction.rst | 2 +-
doc/reST/presets.rst | 6 +-
3 files changed, 343 insertions(+), 316 deletions(-)
diffs (truncated from 833 to 300 lines):
diff -r 03bd64057e72 -r dfe0803ae6be doc/reST/cli.rst
--- a/doc/reST/cli.rst Wed Nov 26 13:23:17 2014 -0600
+++ b/doc/reST/cli.rst Wed Nov 26 16:56:00 2014 -0600
@@ -30,8 +30,8 @@ Generally, when an option expects a stri
the user may specify the integer ordinal of the value they desire. ie:
:option:`--log-level` 3 is equivalent to :option:`--log-level` debug.
-Standalone Executable Options
-=============================
+Executable Options
+==================
.. option:: --help, -h
@@ -45,6 +45,59 @@ Standalone Executable Options
**CLI ONLY**
+Logging/Statistic Options
+=========================
+
+.. option:: --log-level <integer|string>
+
+ Logging level. Debug level enables per-frame QP, metric, and bitrate
+ logging. If a CSV file is being generated, debug level makes the log
+ be per-frame rather than per-encode. Full level enables hash and
+ weight logging. -1 disables all logging, except certain fatal
+ errors, and can be specified by the string "none".
+
+ 0. error
+ 1. warning
+ 2. info **(default)**
+ 3. debug
+ 4. full
+
+.. option:: --no-progress
+
+ Disable periodic progress reports from the CLI
+
+ **CLI ONLY**
+
+.. option:: --csv <filename>
+
+ Writes encoding results to a comma separated value log file. Creates
+ the file if it doesnt already exist, else adds one line per run. if
+ :option:`--log-level` is debug or above, it writes one line per
+ frame. Default none
+
+.. option:: --cu-stats, --no-cu-stats
+
+ Records statistics on how each CU was coded (split depths and other
+ mode decisions) and reports those statistics at the end of the
+ encode. Default disabled
+
+.. option:: --ssim, --no-ssim
+
+ Calculate and report Structural Similarity values. It is
+ recommended to use :option:`--tune` ssim if you are measuring ssim,
+ else the results should not be used for comparison purposes.
+ Default disabled
+
+.. option:: --psnr, --no-psnr
+
+ Calculate and report Peak Signal to Noise Ratio. It is recommended
+ to use :option:`--tune` psnr if you are measuring PSNR, else the
+ results should not be used for comparison purposes. Default
+ disabled
+
+Performance Options
+===================
+
.. option:: --asm <integer:false:string>, --no-asm
x265 will use all detected CPU SIMD architectures by default. You can
@@ -57,6 +110,17 @@ Standalone Executable Options
One may also directly supply the CPU capability bitmap as an integer.
+.. option:: --frame-threads, -F <integer>
+
+ Number of concurrently encoded frames. Using a single frame thread
+ gives a slight improvement in compression, since the entire reference
+ frames are always available for motion compensation, but it has
+ severe performance implications. Default is an autodetected count
+ based on the number of CPU cores and whether WPP is enabled or not.
+
+ Over-allocation of frame threads will not improve performance, it
+ will generally just increase memory use.
+
.. option:: --threads <integer>
Number of threads to allocate for the worker thread pool This pool
@@ -71,13 +135,24 @@ Standalone Executable Options
Default 0, one thread is allocated per detected hardware thread
(logical CPU cores)
+.. option:: --wpp, --no-wpp
+
+ Enable Wavefront Parallel Processing. The encoder may begin encoding
+ a row as soon as the row above it is at least two CTUs ahead in the
+ encode process. This gives a 3-5x gain in parallelism for about 1%
+ overhead in compression efficiency.
+
+ This feature is implicitly disabled when no thread pool is present.
+
+ Default: Enabled
+
.. option:: --pmode, --no-pmode
Parallel mode decision, or distributed mode analysis. When enabled
the encoder will distribute the analysis work of each CU (merge,
inter, intra) across multiple worker threads. Only recommended if
x265 is not already saturating the CPU cores. In RD levels 3 and 4
- it will be most effective if --rect was enabled. At RD levels 5 and
+ it will be most effective if --rect is enabled. At RD levels 5 and
6 there is generally always enough work to distribute to warrant the
overhead, assuming your CPUs are not already saturated.
@@ -85,7 +160,8 @@ Standalone Executable Options
efficiency. In fact, since the modes are all measured in parallel it
makes certain early-outs impractical and thus you usually get
slightly better compression when it is enabled (at the expense of
- not skipping improbable modes).
+ not skipping improbable modes). This bypassing of early-outs can
+ cause pmode to slow down encodes, especially at faster presets.
This feature is implicitly disabled when no thread pool is present.
@@ -114,7 +190,7 @@ Standalone Executable Options
Sets parameters to preselected values, trading off compression efficiency against
encoding speed. These parameters are applied before all other input parameters are
applied, and so you can override any parameters that these values control. See
- :ref:`presets <preset-tune-ref>` for more detail.
+ :ref:`presets <presets>` for more detail.
0. ultrafast
1. superfast
@@ -130,85 +206,18 @@ Standalone Executable Options
.. option:: --tune, -t <string>
Tune the settings for a particular type of source or situation. The changes will
- be applied after :option:`--preset` but before all other parameters. Default none
- See :ref:`presets <preset-tune-ref>` for more detail.
+ be applied after :option:`--preset` but before all other parameters. Default none.
+ See :ref:`tunings <tunings>` for more detail.
**Values:** psnr, ssim, grain, zero-latency, fast-decode, cbr.
-.. option:: --frame-threads, -F <integer>
-
- Number of concurrently encoded frames. Using a single frame thread
- gives a slight improvement in compression, since the entire reference
- frames are always available for motion compensation, but it has
- severe performance implications. Default is an autodetected count
- based on the number of CPU cores and whether WPP is enabled or not.
-
- Over-allocation of frame threads will not improve performance, it
- will generally just increase memory use.
-
-.. option:: --log-level <integer|string>
-
- Logging level. Debug level enables per-frame QP, metric, and bitrate
- logging. If a CSV file is being generated, debug level makes the log
- be per-frame rather than per-encode. Full level enables hash and
- weight logging. -1 disables all logging, except certain fatal
- errors, and can be specified by the string "none".
-
- 0. error
- 1. warning
- 2. info **(default)**
- 3. debug
- 4. full
-
-.. option:: --csv <filename>
-
- Writes encoding results to a comma separated value log file. Creates
- the file if it doesnt already exist, else adds one line per run. if
- :option:`--log-level` is debug or above, it writes one line per
- frame. Default none
-
-.. option:: --cu-stats, --no-cu-stats
-
- Records statistics on how each CU was coded (split depths and other
- mode decisions) and reports those statistics at the end of the
- encode. Default disabled
-
-.. option:: --output, -o <filename>
-
- Bitstream output file name. If there are two extra CLI options, the
- first is implicitly the input filename and the second is the output
- filename, making the :option:`--output` option optional.
-
- The output file will always contain a raw HEVC bitstream, the CLI
- does not support any container file formats.
-
- **CLI ONLY**
-
-.. option:: --no-progress
-
- Disable CLI periodic progress reports
-
- **CLI ONLY**
-
-Quality reporting metrics
+Input/Output File Options
=========================
-.. option:: --ssim, --no-ssim
-
- Calculate and report Structural Similarity values. It is
- recommended to use :option:`--tune` ssim if you are measuring ssim,
- else the results should not be used for comparison purposes.
- Default disabled
-
-.. option:: --psnr, --no-psnr
-
- Calculate and report Peak Signal to Noise Ratio. It is recommended
- to use :option:`--tune` psnr if you are measuring PSNR, else the
- results should not be used for comparison purposes. Default
- disabled
-
-Input Options
-=============
+These options all describe the input video sequence or, in the case of
+:option:`--dither`, operations that are performed on the sequence prior
+to encode. All options dealing with files (names, formats, offsets or
+frame counts) are only applicable to the CLI application.
.. option:: --input <filename>
@@ -244,21 +253,6 @@ Input Options
**CLI ONLY**
-.. option:: --nr <integer>
-
- Noise reduction - an adaptive deadzone applied after DCT
- (subtracting from DCT coefficients), before quantization, on inter
- blocks. It does no pixel-level filtering, doesn't cross DCT block
- boundaries, has no overlap, doesn't affect intra blocks. The higher
- the strength value parameter, the more aggressively it will reduce
- noise.
-
- Enabling noise reduction will make outputs diverge between different
- numbers of frame threads. Outputs will be deterministic but the
- outputs of -F2 will no longer match the outputs of -F3, etc.
-
- **Values:** any value in range of 100 to 2000. Default disabled.
-
.. option:: --input-res <wxh>
YUV only: Source picture size [w x h]
@@ -287,8 +281,6 @@ Input Options
.. option:: --interlaceMode <false|tff|bff>, --no-interlaceMode
- **EXPERIMENTAL** Specify interlace type of source pictures.
-
0. progressive pictures **(default)**
1. top field first
2. bottom field first
@@ -307,61 +299,20 @@ Input Options
.. option:: --frames, -f <integer>
- Number of frames to be encoded. Default 0 (all)
+ Number of frames of input sequence to be encoded. Default 0 (all)
**CLI ONLY**
-.. option:: --qpfile <filename>
+.. option:: --output, -o <filename>
- Specify a text file which contains frametypes and QPs for some or
- all frames. The format of each line is:
+ Bitstream output file name. If there are two extra CLI options, the
+ first is implicitly the input filename and the second is the output
+ filename, making the :option:`--output` option optional.
- framenumber frametype QP
+ The output file will always contain a raw HEVC bitstream, the CLI
+ does not support any container file formats.
- Frametype can be one of [I,i,P,B,b]. **B** is a referenced B frame,
- **b** is an unreferenced B frame. **I** is a keyframe (random
- access point) while **i** is a I frame that is not a keyframe
- (references are not broken).
-
- Specifying QP (integer) is optional, and if specified they are
- clamped within the encoder to qpmin/qpmax.
-
-.. option:: --scaling-list <filename>
-
- Quantization scaling lists. HEVC supports 6 quantization scaling
- lists to be defined; one each for Y, Cb, Cr for intra prediction and
- one each for inter prediction.
-
- x265 does not use scaling lists by default, but this can also be
- made explicit by :option:`--scaling-list` *off*.
-
More information about the x265-commits
mailing list