[x265] [PATCH] Add reST script to generate x265 user manual

sagar at multicorewareinc.com sagar at multicorewareinc.com
Tue Mar 25 13:57:16 CET 2014


# HG changeset patch
# User Sagar Kotecha <sagar at multicorewareinc.com>
# Date 1395752215 -19800
#      Tue Mar 25 18:26:55 2014 +0530
# Node ID 3f833c112657f38e8404aab47a2c26fb72814b2d
# Parent  4318d47d934857a5d0a5e2a8dc0eaed48f086197
Add reST script to generate x265 user manual

diff -r 4318d47d9348 -r 3f833c112657 doc/reST/cli.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reST/cli.rst	Tue Mar 25 18:26:55 2014 +0530
@@ -0,0 +1,590 @@
+*********************
+Command line Options
+*********************
+
+Standalone Executable Options
+=============================
+
+.. option:: --help/-h
+
+   Display help text
+
+.. option:: --version/-V
+
+   Display version details
+
+.. option:: --cpuid
+   
+   Limit SIMD capability bitmap
+   
+   **Values:**  0:auto **(Default)**; 1:none
+   
+.. option:: --threads
+   
+   Number of threads for thread pool; 0: detect CPU core count **(Default)**
+   
+.. option:: --preset/-p
+   
+   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.	   
+   
+   **Values:**  ultrafast, superfast, veryfast, faster, fast, medium **(Default)**, slow, slower, veryslow, placebo
+				 
+.. option:: --tune/-t
+
+   Tune the settings for a particular type of source or situation. The changes will
+   be applied after --preset but before all other parameters.
+   
+   **Values:** psnr, ssim **(Default)**, zero-latency.
+
+.. option:: --frame-threads/-F
+    
+   Number of concurrently encoded frames
+  
+   **Range of values:** >=0.  **Default** = auto-determined from a formula based on the number of CPU cores
+
+.. option::--log
+    
+   Logging level
+	
+   **Values:**  0:ERROR; 1:WARNING; 2:INFO **(Default)**; 3:DEBUG; 4:FULL	-1:NONE
+	
+.. option:: --log 3
+
+   produces a log file that records results per frame					
+	
+.. option:: --output/-o
+
+   Bitstream output file name
+	
+.. option:: --no-progress
+
+   Disable per-frame encoding progress reporting
+
+.. option:: --csv <filename>
+
+   Writes encoding results to a comma separated value log file
+   Creates the file if it doesn’t already exist, else adds one line per run
+	
+.. option:: --y4m
+    
+   Parse input stream as YUV4MPEG2 regardless of file extension
+
+------------------------------
+
+Input Options
+=============
+
+.. option:: --input
+
+    Raw YUV or Y4M input file name
+	
+.. option:: --input-depth
+
+    Bit-depth of input file (YUV only).
+	
+    **Values:** any value between 8 and 16. Default is internal depth.
+	
+.. option:: --input-res
+
+    Source picture size [w x h], auto-detected if Y4M
+	
+.. option:: --input-csp
+
+    Source color space parameter, auto detected if Y4M;
+	
+    **Values:** 1:"i420" **(Default)**, or 3:"i444"
+	
+.. option:: --fps
+
+    Source frame rate; auto-detected if Y4M;
+	
+    **Range of values:** positive int or float, or num/denom
+	
+.. option:: --seek
+    
+    Number of frames to skip at start of input file
+	
+    **Range of values:** 0 to the number of frames in the video
+    **Default**: 0
+	
+.. option:: --frames/-f
+
+    Number of frames to be encoded; ‘0’ implies all **(Default)**
+	
+    **Range of values:** 0 to the number of frames in the video
+	
+------------------------------
+
+Reconstructed video options (debugging)
+=======================================
+
+.. option:: --recon/-r
+
+    Re-constructed image YUV or Y4M output file name
+	
+.. option:: --recon-depth
+
+    Bit-depth of output file 
+	
+    **Default:** same as input bit depth
+
+Quad-Tree analysis
+==================
+
+.. option:: --no-wpp
+
+    Disable Wavefront Parallel Processing
+	
+.. option:: --wpp
+
+    Enable Wavefront Parallel Processing **(Default)**
+	
+.. option:: --ctu/-s
+
+    Maximum CU size (width and height)
+   
+    **Values:** 16, 32, 64 **(Default)**
+	
+.. option:: --tu-intra-depth
+
+    Max TU recursive depth for intra CUs
+   
+    **Values:** 1 **(Default)**, 2, 3, 4
+	
+.. option:: --tu-inter-depth
+
+    Max TU recursive depth for inter CUs 
+   
+    **Values:** 1 **(Default)**, 2, 3, 4 	
+
+------------------------------   
+
+Temporal / motion search options
+================================
+
+.. option:: --me
+
+    Motion search method 0: dia; 1: hex **(Default)**; 2: umh; 3: star; 4: full
+	
+.. option:: --subme/-m
+
+    Amount of subpel refinement to perform
+	
+    **Range of values:** an integer from 0 to 7 (0: least…..7: most)
+    **Default: 2**
+	
+.. option:: --merange
+
+    Motion search range
+	
+    **Range of values:** an integer from 0 to 32768
+    **Default: 57**
+	
+.. option:: --no-rect
+
+    Disable rectangular motion partitions Nx2N and 2NxN
+	
+.. option:: --rect
+
+    Enable rectangular motion partitions Nx2N and 2NxN **(Default)**
+	
+.. option:: --no-amp
+
+    Disable asymmetric motion partitions
+	
+.. option:: --amp
+
+    Enable asymmetric motion partitions, requires –rect **(Default)**
+	
+.. option:: --max-merge
+
+   Maximum number of merge candidates
+    
+   **Range of values:** 1 to 5  **Default: 2**
+	
+.. option:: --early-skip
+
+    Enable early SKIP detection
+	
+.. option:: --no-early-skip
+
+    Disable early SKIP detection **(Default)**
+	
+.. option:: --fast-cbf
+
+    Enable Cbf fast mode
+	
+.. option:: --no-fast-cbf
+
+    Disable Cbf fast mode **(Default)**
+ 
+------------------------------
+
+Spatial/intra options
+=====================
+
+.. option:: --rdpenalty
+
+    Penalty for 32x32 intra TU in non-I slices. 
+	
+    **Range of values:** 0:disabled **(Default)**; 1:RD-penalty; 2:maximum
+	
+.. option:: --no-tskip
+
+    Disable intra transform skipping **(Default)**
+	
+.. option:: --tskip
+
+    Enable intra transform skipping 
+	
+.. option:: --no-tskip-fast
+
+    Disable fast intra transform skipping **(Default)**
+	
+.. option:: --tskip-fast
+
+    Enable fast intra transform skipping
+	
+.. option:: --no-strong-intra-smoothing
+
+    Disable strong intra smoothing for 32x32 blocks
+	
+.. option:: --strong-intra-smoothing
+
+   Enable strong intra smoothing for 32x32 blocks **(Default)**
+   
+.. option:: --constrained-intra
+
+    Constrained intra prediction (use only intra coded reference pixels)
+	
+.. option:: --no-constrained-intra
+
+    Disable constrained intra prediction (use only intra coded reference pixels **(Default)**
+
+------------------------------
+
+Slice decision options
+======================
+
+.. option:: --open-gop
+
+    Enable open GOP, allow I-slices to be non-IDR
+	
+.. option:: --no-open-gop
+
+    Disable open GOP. All I-slices are IDR.
+	
+.. option:: --keyint/-I
+
+    Max intra period in frames. A special case of infinite-gop (single keyframe at the beginning of the stream)
+    can be triggered with argument -1.
+	
+    **Range of values:** >= -1 (-1: infinite-gop, 0: auto; 1: intra only) **Default: 250**
+	
+.. option:: --min-keyint/-i
+
+    Minimum GOP size. Scenecuts closer together than this are coded as I, not IDR. 
+	
+    **Range of values:** >=0 (0: auto)
+	
+.. option:: --scenecut
+
+    How aggressively I-frames need to be inserted. The lower the threshold value, the more aggressive the I-frame placement. 
+
+    **Range of values:** >=0  **Default: 40**
+
+.. option:: --no-scenecut
+	
+    Disable adaptive I-frame placement
+
+.. option:: --rc-lookahead
+
+    Number of frames for frame-type lookahead (determines encoder latency) 
+
+    **Range of values:** an integer less than or equal to 250 and greater than maximum consecutive bframe count (--bframes)
+    **Default: 20**
+	
+.. option:: --b-adapt
+
+    Adaptive B frame scheduling
+	
+    **Values:** 0:none; 1:fast; 2:full(trellis) **(Default)**
+	
+.. option:: --bframes/-b
+
+    Maximum number of consecutive b-frames 
+	
+    **Range of values:** 0 to 16  **Default: 4**
+	
+.. option:: --bframe-bias
+	
+    Bias towards B frame decisions
+	
+    **Range of values:** usually >=0 (increase the value for referring more B Frames e.g. 40-50) **Default: 0**
+
+.. option:: --b-pyramid
+
+    Use B-frames as references 0: Disabled, 1: Enabled **(Default)**
+	
+.. option:: --ref
+    
+    Max number of L0 references to be allowed
+
+    **Range of values:** 1 to 16  **Default: 3**
+	
+.. option:: --weightp/-w
+
+    Enable weighted prediction in P slices**(Default)**
+	
+.. option:: --no-weightp
+
+    Disable weighted prediction in P slices 
+
+------------------------------
+
+Quality, rate control and rate distortion options
+=================================================
+.. option:: --bitrate
+
+   Enables ABR rate control.  Specify the target bitrate in kbps.  
+
+   **Range of values:** An integer greater than 0
+	
+.. option:: --crf
+
+   Quality-controlled VBR
+	
+   **Range of values:** an integer from 0 to 51 **Default: 28**
+	
+.. option:: --vbv-bufsize
+
+   Enables VBV in ABR mode. Sets the size of the VBV buffer (kbits)  **Default: 0**
+	
+.. option:: --vbv-maxrate
+	
+   Maximum local bitrate (kbits/sec). Will be used only if vbv-bufsize is also non-zero. Both vbv-bufsize and 
+   vbv-maxrate are required to enable VBV in CRF mode. **Default: 0**
+	
+.. option:: --vbv-init
+
+   Initial VBV buffer occupancy. 
+
+   **Range of values:** 0-1 **Default: 0.9**
+	
+.. option:: --qp/-q
+
+   Base Quantization Parameter for Constant QP mode. Using this option causes x265 to use Constant QP rate control **(Default)**
+
+   **Range of values:** an integer from 0 to 51  **Default: 32**
+	
+.. option:: --aq-mode
+
+   Mode for Adaptive Quantization
+
+   **Range of values:** 0: no Aq; 1: aqVariance 2: aqAutoVariance  **Default: 1**
+	
+.. option:: --aq-strength
+
+   Reduces blocking and blurring in flat and textured areas
+
+   **Range of values:** 0.0  to 3.0 (double)	**Default: 1.0**
+
+.. option:: --cbqpoffs
+	
+   Chroma Cb QP Offset
+
+   **Range of values:**  -12 to 12  **Default: 0**
+	
+.. option:: --crqpoffs
+
+   Chroma Cr QP Offset 
+
+   **Range of values:**  -12 to 12   **Default: 0**
+	
+.. option:: --rd
+
+   Level of RD in mode decision
+
+   **Range of values:** 0: Least - 6: Full RDO Analysis  **Default: 3**
+	
+.. option:: --signhide
+
+   Hide sign bit of one coeff per TU (rdo) **(Default)**
+	
+.. option:: --no-signhide
+
+   Disable hide sign bit of one coeff per TU (rdo)
+
+------------------------------
+ 
+Loop filter
+===========
+
+.. option:: --no-lft
+
+   Disable Loop Filter
+	
+.. option:: --lft
+
+   Enable Loop Filter **(Default)**
+
+------------------------------
+
+Sample Adaptive Offset loop filter
+==================================
+
+.. option:: --no-sao
+
+   Disable Sample Adaptive Offset
+	
+.. option:: --sao
+
+   Enable Sample Adaptive Offset **(Default)**
+	
+.. option:: --sao-lcu-bounds
+
+   0: right/bottom boundary areas skipped **(Default)**; 1: non-deblocked pixels are used
+	
+.. option:: --sao-lcu-opt
+
+   0: SAO picture-based optimization (requires -F1); 1: SAO LCU-based optimization **(Default)**
+
+------------------------------
+
+Quality reporting metrics
+=========================
+
+.. option:: --ssim
+
+   Calculate and report Structural Similarity values
+	
+.. option:: --no-ssim
+
+   Disable SSIM calculation and reporting **(Default)**
+	
+.. option:: --psnr
+
+   Calculate and report Peak Signal to Noise Ratio
+	
+.. option:: --no-psnr
+
+   Disable PSNR calculation and reporting **(Default)**
+
+------------------------------
+
+SEI options
+===========
+
+.. option:: --hash
+
+   Decoded picture hash 0: disabled **(Default)**, 1: MD5, 2: CRC, 3: Checksum
+
+------------------------------
+
+VUI options
+===========
+
+.. option:: --vui
+
+   Enable video usability Information with all fields in the SPS
+
+   **Range of values:** 0: disabled **(Default)**; 1: Enabled
+	
+.. option:: --sar
+
+   Sample Aspect Ratio <int:int|int>, the ratio of width to height of an individual pixel.   
+
+   **values:** 0- undef **(Default)**, 1- 1:1(square), 2- 12:11, 3- 10:11, 4- 16:11, 5- 40:33, 6- 24:11, 7- 20:11, 
+   8- 32:11, 9- 80:33, 10- 18:11, 11- 15:11, 12- 64:33, 13- 160:99, 14- 4:3, 15- 3:2, 16- 2:1 or
+   custom ratio of <int:int> 
+	
+.. option:: --overscan
+
+   Region of image that does not contain information is added to achieve certain resolution or aspect ratio
+
+   **values:** undef **(Default)**, show, crop.
+	
+.. option:: --videoformat
+
+   Specify video format, Explains what type analog video was before digitizing/encoding
+	
+   **values:** 0: undef, 1: component, 2: pal, 3: ntsc, 4: secam, 5: mac **(Default)**
+	
+.. option:: --range
+
+   Specify output range of black level and range of luma and chroma signals
+
+   **values:** full, limited **(Default)**
+	
+.. option:: --colorprim
+
+   Set what color primitives for converting to RGB
+
+   **values:** bt709, bt470m, bt470bg, smpte170m smpte240m, film, bt2020, undef **(Default)**
+	
+.. option:: --transfer
+
+   Specify transfer characteristics
+
+   **values:** bt709bt709, bt470m, bt470bg, smpte170m, smpte240m, linear, log100, log316, iec61966-2-4, bt1361e, iec61966-2-1,
+   bt2020-10, bt2020-12, undef **(Default)**
+
+.. option:: --colormatrix
+
+   Specify color matrix setting i.e set the matrix coefficients used in deriving the luma and chroma
+
+   **values:** bt709, fcc, bt470bg, smpte170m, smpte240m, GBR, YCgCo, bt2020nc, bt2020c, undef **(Default)**
+	
+.. option:: --chromalocs
+
+   Specify chroma sample location
+
+   **Range of values:** 0 **(Default)** – 5 
+	
+.. option:: --no-fieldseq
+
+   Disable pictures are fields and an SEI timing message will be added to every access unit
+	
+.. option:: --fieldseq
+
+   Enable pictures are fields and an SEI timing message will be added to every access unit  [NOT IMPLEMENTED]
+	
+.. option:: --no-framefieldinfo
+
+   A pic-struct will not be added to the SEI timing message **(Default)**
+	
+.. option:: --framefieldinfo
+
+   A pic-struct will be added to the SEI timing message
+	
+.. option:: --crop-rect
+
+   Add bitstream-level cropping rectangle.
+	
+   **values:** left, top, right, bottom
+	
+.. option:: --timinginfo
+
+   Add timing information to the VUI
+
+   **values:** 0 **(Default)** or 1
+	
+.. option:: --nal-hrd
+
+   Add signal HRD information [NOT IMPLEMENTED]
+
+   **values:** 0 **(Default)** or 1
+	
+.. option:: --bitstreamrestriction
+
+   specifies whether that the bitstream restriction parameters for the CVS are present
+
+   **values:** 0 **(Default)** or 1 [NOT IMPLEMENTED]
+	
+.. option:: --subpichrd
+
+   Add sub picture HRD parameters to the HRD
+
+   **values:** 0 **(Default)** or 1 [NOT IMPLEMENTED]
diff -r 4318d47d9348 -r 3f833c112657 doc/reST/conf.py
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reST/conf.py	Tue Mar 25 18:26:55 2014 +0530
@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+#
+# -- General configuration -----------------------------------------------------
+
+source_suffix = '.rst'
+
+#Name of the master file 
+master_doc = 'index'
+
+# General information about the project.
+#This is the title of the project which appears on the top of HTML Document as well as PDF Document
+project = u'x265 Documentation'
+
+
+#This is the Copyright Information that will appear on the bottom of the document
+copyright = u'2014 MulticoreWare Inc'
+
+
+# -- Options for HTML output ---------------------------------------------------
+html_theme = "default"
diff -r 4318d47d9348 -r 3f833c112657 doc/reST/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reST/index.rst	Tue Mar 25 18:26:55 2014 +0530
@@ -0,0 +1,8 @@
+x265 Documentation
+======================
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   cli
+   ...
diff -r 4318d47d9348 -r 3f833c112657 doc/reST/introduction.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/reST/introduction.rst	Tue Mar 25 18:26:55 2014 +0530
@@ -0,0 +1,21 @@
+************
+Introduction
+************
+
+Increase in demand for high resolution video along with increase in the consumption of video can be met only with the supply of a high efficiency codec. The x265 codec from MCW aims at providing the most efficient video encoder with the highest possible quality at even the lowest given bit rate.
+
+About HEVC
+==========
+The High Efficiency Video Coding (HEVC) is the latest generation video compression standard. This standard was developed by the ISO/IEC Moving Picture Experts Group (MPEG) and ITU-T Video Coding Experts Group (VCEG), through their Joint Collaborative Team on Video Coding (JCT-VC). HEVC is also known as ISO/IEC 23008-2 MPEG-H Part 2 and ITU-T H.265. HEVC provides superior video quality and up to twice the data compression as the previous standard (H.264/MPEG-4 AVC). HEVC can support 8K Ultra High Definition video, with a picture size up to 8192x4320 pixels.
+
+About x265
+==========
+The primary objective of x265 is to become the best H.265/HEVC encoder available anywhere, offering the highest compression efficiency and the highest performance on a wide variety of hardware platforms. The x265 encoder is available as an open source library, published under the GPLv2 license. It is also available under a commercial license similar to the x264’s commercial license.
+
+x265 is developed by `MulticoreWare <http://www.multicorewareinc.com>`_, leaders in high performance software solutions, with backing from leading video technology providers including `Telestream <http://www.telestream.com>`_ and `Doremi Labs <http://www.doremilabs.com>`_ (and other companies who want to remain anonymous at this time), and with contributions from open source developers.  x265 leverages many of the outstanding video encoding features and optimizations from the x264 AVC encoder project.
+
+The x265 software is available for free under the GNU GPL 2 license, from https://bitbucket.org/multicoreware/x265.  For commercial companies that wish to distribute x265 without being subject to the open source requirements of the GPL 2 license, commercial licenses are available with competitive terms.  Contact licensing at x265.com to inquire about commercial license terms.  
+
+While x265 is primarily designed as a video encoder software library, a command-line executable is provided to facilitate testing and development.  We expect x265 to be utilized in many leading video hardware and software products and services in the coming months.
+
+


More information about the x265-devel mailing list