software-manual.tex 112 KB
Newer Older
1
\documentclass[a4paper,11pt]{jvetdoc}
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

\usepackage{geometry}[2010/02/12]

\usepackage{hyperref}
\hypersetup{colorlinks=true,
            linkcolor=black,      % color of internal links (change box color with linkbordercolor)
            citecolor=black,      % color of links to bibliography
            filecolor=black,      % color of file links
            urlcolor=blue}
\usepackage{color,soul}

\usepackage[position=bottom]{subfig}
\captionsetup[subfloat]{position=top}
\usepackage{multirow}
\usepackage{dcolumn}
\newcolumntype{.}{D{.}{.}{-1}}
\usepackage{colortbl}
\usepackage{makecell}
\usepackage{longtable}
\usepackage{array}
\usepackage{algorithm2e}
\usepackage{amsmath}

25
26
27
28
29
30
31
32
33
34
35
36
\urlstyle{same}

% code highlighting
\usepackage{minted,xcolor}
\definecolor{bggray}{gray}{0.95}
\setminted{
bgcolor=bggray,
xleftmargin=3ex,
breaklines=true,
fontsize=\footnotesize}


37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
\usepackage[strings]{underscore}
\usepackage{csquotes}
\MakeOuterQuote{"}
\EnableQuotes

\newcommand\None{}
\newcommand\NotSet{}
\makeatletter
\newcommand{\Option}[1]{\ifx\optOption\@empty\gdef\optOption{#1}\else\g@addto@macro\optOption{ \\ #1}\fi}
\newcommand{\ShortOption}[1]{\ifx\optShortOption\@empty\gdef\optShortOption{#1}\else\g@addto@macro\optShortOption{ \\ #1}\fi}
\newcommand{\Default}[1]{\ifx\optDefault\@empty\gdef\optDefault{#1}\else\g@addto@macro\optDefault{ \\ #1}\fi}
\newcommand{\clearOptions}{\gdef\optOption{}\gdef\optShortOption{}\gdef\optDefault{}}
\makeatother
\newenvironment{OptionTable}[1]{%
	\footnotesize
	\def\arraystretch{1.8}
	\clearOptions
	\begin{longtable}{l<{\makecell[tl]{\optOption}}%
	                  >{\texttt\bgroup}l<{\makecell[tl]{\optShortOption}\egroup}%
	                  c<{\makecell[tc]{\optDefault}}%
	                  >{\def\arraystretch{1.0}}p{0.5\textwidth}<{\clearOptions}}
	\caption{#1} \\
	\hspace*{12em}&&\hspace*{8em}&\kill
	\hline
	 \thead{Option} &
	 \egroup\thead{Shorthand}\bgroup &
	 \thead{Default} &
	 \thead{Description} \\
	\hline
	\endfirsthead
	\caption[]{#1 (Continued)} \\
	\hspace*{12em}&&\hspace*{8em}&\kill
	\hline
	 \thead{Option} &
	 \egroup\thead{Shorthand}\bgroup &
	 \thead{Default} &
	 \thead{Description} \\
	\hline
	\endhead
	 \multicolumn{4}{r}{Continued...}\\
	 \hline
	\endfoot
	 \hline
	\endlastfoot
}{%
	\hline
	\end{longtable}
}

\newenvironment{OptionTableNoShorthand}[2]{%
87
	\scriptsize
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
	\def\arraystretch{1.8}
	\clearOptions
	\begin{longtable}{l<{\makecell[tl]{\optOption}}%
	                  c<{\makecell[tc]{\optDefault}}%
	                  >{\def\arraystretch{1.0}}p{0.5\textwidth}<{\clearOptions}}
	\caption{#1} \label{#2} \\
	\hspace*{12em}&\hspace*{8em}&\kill
	\hline
	 \thead{Option} &
	 \thead{Default} &
	 \thead{Description} \\
	\hline
	\endfirsthead
	\caption[]{#1 (Continued)} \\
	\hspace*{12em}&\hspace*{8em}&\kill
	\hline
	 \thead{Option} &
	 \thead{Default} &
	 \thead{Description} \\
	\hline
	\endhead
	 \multicolumn{3}{r}{Continued...}\\
	 \hline
	\endfoot
	 \hline
	\endlastfoot
}{%
	\hline
	\end{longtable}
}

\newenvironment{SEIListTable}[1]{%
120
	\scriptsize
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
	\def\arraystretch{1.8}
	\clearOptions
	\begin{longtable}{c<{\makecell[tl]{\optOption}}%
	                  l<{\makecell[tc]{\optDefault}}%
	                  >{\def\arraystretch{1.0}}p{0.3\textwidth}<{\clearOptions}}
	\caption{#1} \\
	\hspace*{12em}&\hspace*{8em}&\kill
	\hline
	 \thead{SEI Number} &
	 \thead{SEI Name} &
	 \thead{Table number of encoder controls, if available} \\
	\hline
	\endfirsthead
	\caption[]{#1 (Continued)} \\
	\hspace*{12em}&\hspace*{8em}&\kill
	\hline
	 \thead{SEI Number} &
	 \thead{SEI Name} &
	 \thead{Table number of encoder controls, if available} \\
	\hline
	\endhead
	 \multicolumn{3}{r}{Continued...}\\
	 \hline
	\endfoot
	 \hline
	\endlastfoot
}{%
	\hline
	\end{longtable}
}

\newenvironment{MacroTable}[1]{%
153
	\scriptsize
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
	\def\arraystretch{1.3}
	\clearOptions
	\begin{longtable}{lcp{0.5\textwidth}}
	 \caption{#1} \\
	%\hspace*{12em}&&\hspace*{8em}&\kill
	 \hline
	  \thead{Option} &
	  \thead{Default} &
	  \thead{Description} \\
	 \hline
	\endfirsthead
	 \caption[]{#1 (Continued)} \\
	 \hline
	  \thead{Option} &
	  \thead{Default} &
	  \thead{Description} \\
	 \hline
	\endhead
	 \multicolumn{3}{r}{Continued...}\\
	 \hline
	\endfoot
	 \hline
	\endlastfoot
}{%
	\end{longtable}
}

181
\title{VTM Software Manual}
182
183
184
185
186
187
188
\author{%
	Frank Bossen
	\email{frank@bossentech.com}
	\and
	David Flynn
	\email{dflynn@blackberry.com}
	\and
189
190
191
192
	Xiang Li
	\email{xlxiangli@tencent.com}
	\and
	Karl Sharman
193
194
195
196
197
198
	\email{karl.sharman@eu.sony.com}
	\and
	Karsten S\"uhring
	\email{karsten.suehring@hhi.fraunhofer.de}
}

199
200
201
202
203
\jvetmeeting{}
\jvetdocnum{Software Manual}
\jvetdocstatus{Software AHG working document}
\jvetdocpurpose{Information}
\jvetdocsource{AHG chairs}
204
205
206
207

\begin{document}
\maketitle
\begin{abstract}
208
This document is a user manual describing usage of the VTM reference software
209
for the VVC project. It applies to version 5.2 of the software.
210
211
212
213
214
215
216
217
\end{abstract}

\tableofcontents
\listoftables


\section{General Information}
Reference software is being made available to provide a reference
218
219
implementation of the HEVC standard being developed by the Joint 
Video Experts Team (JVET) regrouping experts from
220
221
222
223
224
225
226
ITU-T SG 16 and ISO/IEC SC29 WG11. One of the main goals of the
reference software is to provide a basis upon which to conduct
experiments in order to determine which coding tools provide desired
coding performance. It is not meant to be a particularly efficient
implementation of anything, and one may notice its apparent
unsuitability for a particular use. It should not be construed to be a
reflection of how complex a production-quality implementation of a
227
future VVC standard would be.
228
229
230
231

This document aims to provide guidance on the usage of the reference
software. It is widely suspected to be incomplete and suggestions for
improvements are welcome. Such suggestions and general inquiries may be
232
233
234
sent to the general JVET email reflector on
\url{https://lists.rwth-aachen.de/postorius/lists/jvet.lists.rwth-aachen.de/} 
(registration required).
235
236

\subsection*{Bug reporting}
237
238
239
Bugs should be reported on the issue tracker set up at:

\url{https://jvet.hhi.fraunhofer.de/trac/vvc/}
240
241

\section{Installation and compilation}
242
The software may be retrieved from the GitLab server located at:
243

244
245
246
247
248
249
250
\url{https://vcgit.hhi.fraunhofer.de/jvet/VVCSoftware_VTM}

Table~\ref{tab:project-files} lists the compiler environments and versions 
for which building the software is tested.

Note that the software makes use of C++11 language features, which may not
be available in older compilers.
251
252

\begin{table}[ht]
253
\caption{Supported compilers}
254
255
256
257
\label{tab:project-files}
\centering
\begin{tabular}{ll}
\hline
258
259
 \thead{Compiler environment} &
 \thead{Versions} \\
260
\hline
261
262
263
MS Visual Studio  & 2015 and 2017 \\
GCC               & 5.4 and 7.3 \\
Xcode/clang       & latest \\
264
265
266
267
\hline
\end{tabular}
\end{table}

268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
By default the software is built as 64-bit binaries to be used on a 64-bit OS. 
This allows the software to use more than 2GB of RAM.

The software uses CMake to create platform-specific build files. 

\subsection {Build instructions for plain CMake (suggested)}

\textbf{Note:} A working CMake installation is required for building the software.

CMake generates configuration files for the compiler environment/development
environment on each platform. The following is a list of examples for Windows
(MS Visual Studio), macOS (Xcode) and Linux (make).

Open a command prompt on your system and change into the root directory
of this project.

Create a build directory in the root directory:
\begin{minted}{bash}
mkdir build 
\end{minted}
Use one of the following CMake commands, based on your platform. Feel free to change the 
commands to satisfy your needs.

\textbf{Windows Visual Studio 2015 64 Bit:}
\begin{minted}{bash}
cd build
cmake .. -G "Visual Studio 14 2015 Win64"
\end{minted}
Then open the generated solution file in MS Visual Studio.

\textbf{macOS Xcode:}
\begin{minted}{bash}
cd build
cmake .. -G "Xcode"
\end{minted}
Then open the generated work space in Xcode.

\textbf{Linux}

For generating Linux Release Makefile:
\begin{minted}{bash}
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
\end{minted}
For generating Linux Debug Makefile:
\begin{minted}{bash}
cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
\end{minted}
Then type
\begin{minted}{bash}
make -j
\end{minted}
to build the software.

For more details, refer to the CMake documentation: \url{https://cmake.org/cmake/help/latest/}

\subsection {Build instructions for make}

\textbf{Note:}
The build instructions in this section require the make tool and Python
to be installed, which are part of usual Linux and macOS environments. 
See section \ref{windowsinstall} for installation instruction for Python 
and GnuWin32 on Windows.

Open a command prompt on your system and change into the root directory
of this project.

To use the default system compiler simply call:
\begin{minted}{bash}
make all
\end{minted}
For MSYS2 and MinGW:
Open an MSYS MinGW 64-Bit terminal and change into the root directory
of this project.

Call:
\begin{minted}{bash}
make all toolset=gcc
\end{minted}

\subsection{Tool Installation on Windows}
\label{windowsinstall}

Download CMake: \url{http://www.cmake.org/} and install it.

Python and GnuWin32 are not mandatory, but they simplify the build process for the user.

\begin{table}[ht]
\footnotesize
\centering
\begin{tabular}{ll}
\hline
Python     &    \url{https://www.python.org/downloads/release/python-371/} \\
GnuWin32   &    \url{https://sourceforge.net/projects/getgnuwin32/files/getgnuwin32/0.6.30/GetGnuWin32-0.6.3.exe/download} \\
\hline
\end{tabular}
\end{table}

To use MinGW, install MSYS2:
\url{http://repo.msys2.org/distrib/msys2-x86_64-latest.exe}

Installation instructions:
\url{https://www.msys2.org/}

Install the needed toolchains:
\begin{minted}{bash}
pacman -S --needed base-devel mingw-w64-i686-toolchain mingw-w64-x86_64-toolchain git subversion mingw-w64-i686-cmake mingw-w64-x86_64-cmake
\end{minted}
377
378
379
380
381

%%%%
%%%%
%%%%
\section{Using the encoder}
382
383

\begin{minted}{bash}
384
TAppEncoder 	[--help] [-c config.cfg] [--parameter=value]
385
\end{minted}
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469

\begin{table}[ht]
\footnotesize
\centering
\begin{tabular}{lp{0.5\textwidth}}
\hline
 \thead{Option} &
 \thead{Description} \\
\hline
\texttt{--help} & Prints parameter usage. \\
\texttt{-c} & Defines configuration file to use.  Multiple configuration files
     may be used with repeated --c options. \\
\texttt{--}\emph{parameter}\texttt{=}\emph{value}
    & Assigns value to a given parameter as further described below.
      Some parameters are also supported by shorthand
      "--\em{opt}~\emph{value}". These are shown in brackets after the parameter
      name in the tables of this document\\
\hline
\end{tabular}
\end{table}

Sample configuration files are provided in the cfg/ folder.
Parameters are defined by the last value encountered on the command line.
Therefore if a setting is set via a configuration file, and then a subsequent
command line parameter changes that same setting, the command line parameter
value will be used.

\subsection{GOP structure table}
\label{sec:gop-structure}
Defines the cyclic GOP structure that will be used repeatedly
throughout the sequence. The table should contain GOPSize lines,
named Frame1, Frame2, etc. The frames are listed in decoding
order, so Frame1 is the first frame in decoding order, Frame2 is
the second and so on. Among other things, the table specifies all
reference pictures kept by the decoder for each frame. This
includes pictures that are used for reference for the current
picture as well as pictures that will be used for reference in
the future. The encoder will not automatically calculate which
pictures have to be kept for future references, they must
be specified. Note that some specified reference frames for
pictures encoded in the very first GOP after an IDR frame might
not be available. This is handled automatically by the encoder,
so the reference pictures can be given in the GOP structure table
as if there were infinitely many identical GOPs before the
current one. Each line in the table contains the parameters used
for the corresponding frame, separated by whitespace:

\begin{itemize}
\item[]\textbf{Type}: Slice type, can be either I, P or B.

\item[]\textbf{POC}: Display order of the frame within a GOP, ranging
from 1 to GOPSize.

\item[]\textbf{QPOffset}: QP offset is added to the QP parameter to set
the final QP value to use for this frame.

\item[]\textbf{QPOffsetModelOff}: Offset parameter to a linear model to adjust final QP based on QP + QPoffset.

\item[]\textbf{QPOffsetModelScale}: Scale parameter to a linear model to adjust final QP based on QP + QPoffset.

\item[]\textbf{SliceCbQPOffset}: The slice-level Cb QP offset.

\item[]\textbf{SliceCrQPOffset}: The slice-level Cr QP offset.

\item[]\textbf{QPFactor}: Weight used during rate distortion
optimization. Higher values mean lower quality and less bits. Typical
range is between
0.3 and 1.

\item[]\textbf{tcOffsetDiv2}: In-loop deblocking filter parameter tcOffsetDiv2 
is added to the base parameter LoopFilterTcOffset_div2 to set the final tc_offset_div2 
parameter for this picture signalled in the slice segment header. The final 
value of tc_offset_div2 shall be an integer number in the range $-6..6$.

\item[]\textbf{betaOffsetDiv2}: In-loop deblocking filter parameter betaOffsetDiv2 
is added to the base parameter LoopFilterBetaOffset_div2 to set the final beta_offset_div2 
parameter for this picture signalled in the slice segment header. The final 
value of beta_offset_div2 shall be an integer number in the range $-6..6$.

\item[]\textbf{temporal_id}: Temporal layer of the frame. A frame cannot
predict from a frame with a higher temporal id. If a frame with higher
temporal IDs is listed among a frame's reference pictures, it is
not used, but is kept for possible use in future frames.

Hendry's avatar
Hendry committed
470
471
\item[]\textbf{num_ref_pics_active_L0}: Number of reference pictures in lists L0
that are used during coding.
472

Hendry's avatar
Hendry committed
473
474
\item[]\textbf{num_ref_pics_L0}: Size of reference picture list L0.
This includes pictures that are used for reference for the
475
476
477
current picture as well as pictures that will be used for reference in
the future.

Hendry's avatar
Hendry committed
478
\item[]\textbf{reference_pictures_L0}: A space-separated list of
479
480
num_ref_pics integers, specifying the POC of the reference pictures
kept, relative the POC of the current frame. The picture list shall be
Hendry's avatar
Hendry committed
481
482
ordered as their intendend order in the L0.
Note that any pictures not supplied in this list and in the list of L1 will be discarded and
483
484
therefore not available as reference pictures later.

Hendry's avatar
Hendry committed
485
486
487
488
489
490
491
492
493
494
495
496
497
498
\item[]\textbf{num_ref_pics_active_L1}: Number of reference pictures in lists L1
that are used during coding.

\item[]\textbf{num_ref_pics_L1}: Size of reference picture list L1.
This includes pictures that are used for reference for the
current picture as well as pictures that will be used for reference in
the future.

\item[]\textbf{reference_pictures_L1}: A space-separated list of
num_ref_pics integers, specifying the POC of the reference pictures
kept, relative the POC of the current frame. The picture list shall be
ordered as their intendend order in the L1.
Note that any pictures not supplied in this list and in the list of L0 will be discarded and
therefore not available as reference pictures later.
499
500
501
502

For example, consider the coding structure of Figure~\ref{fig:gop-example}.
This coding structure is of size 4. The pictures are listed in decoding
order. Frame1 shall therefore describe picture with $\textrm{POC}=4$. It
Hendry's avatar
Hendry committed
503
references picture 0, and therefore has 4 as a reference picture.
504
Similarly, Frame2 has a POC of 2, and since it references pictures 0 and
Hendry's avatar
Hendry committed
505
4, its reference pictures are listed as \verb|2 -2|. Frame3 is a special
506
507
case: even though it only references pictures with POC 0 and 2, it also
needs to include the picture with POC 4, which must be kept in order to
Hendry's avatar
Hendry committed
508
509
510
be used as a reference picture in the future. Note that picture with POC 4 can be
included in the L0 or L1. The reference picture list for Frame3 therefore becomes \verb|1 -1 -3|. 
Frame4 has a POC of 3 and its list of reference pictures is \verb|1 -1|.
511
\end{itemize}
512
513
514
515
516

\begin{figure}[h]
\caption{A GOP structure}
\label{fig:gop-example}
\centering
517
\includegraphics[width=0.7\textwidth]{figures/gop-structure-example}
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
\end{figure}

In order to specify this to the encoder, the parameters in
Table~\ref{tab:gop-example} could be used.

\begin{table}[ht]
\footnotesize
\caption{GOP structure example}
\label{tab:gop-example}
\centering
\begin{tabular}{lrrrr}
\hline
 \thead{} &
 \thead{Frame1} &
 \thead{Frame2} &
 \thead{Frame3} &
 \thead{Frame4} \\
\hline
Hendry's avatar
Hendry committed
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
Type                   &   P  &    B   &         B   &       B \\
POC                    &   4  &    2   &         1   &       3 \\
QPOffset               &   1  &    2   &         3   &       3 \\
QPOffsetModelOff       & 0.0  &  0.0   &       0.0   &     0.0 \\
QPOffsetModelScale     & 0.0  &  0.0   &       0.0   &     0.0 \\
SliceCbQPOffset        &   0  &    0   &         0   &       0 \\
SliceCrQPOffset        &   0  &    0   &         0   &       0 \\
QPfactor               & 0.5  &  0.5   &       0.5   &     0.5 \\
tcOffsetDiv2           &   0  &    1   &         2   &       2 \\  
betaOffsetDiv2         &   0  &    0   &         0   &       0 \\
temporal_id            &   0  &    1   &         2   &       2 \\
num_ref_pics_active_L0 &   1  &    1   &         1   &       1 \\
num_ref_pics_L0        &   1  &    1   &         1   &       1 \\
reference_pictures_L0  &   4  &    2   &         1   &       1 \\
num_ref_pics_active_L1 &   0  &    1   &         1   &       1 \\
num_ref_pics_L1        &   0  &    1   &         2   &       1 \\
reference_pictures_L1  &      & $-$2   & $-$1 $-$3   &    $-$1 \\
553
554
555
556
557
558
559
560
561
562
563
564
\hline
\end{tabular}
\end{table}

Here, the frames used for prediction have been given higher
quality by assigning a lower QP offset. Also, the non-reference
frames have been marked as belonging to a higher temporal layer,
to make it possible to decode only every other frame. Note: each
line should contain information for one frame, so this
configuration would be specified as:

\begin{verbatim}
Hendry's avatar
Hendry committed
565
566
567
568
Frame1: P 4 1 0 0 0.5 0 0 0 1 1  4 1 1  4
Frame2: B 2 2 0 0 0.5 1 0 1 1 1  2 1 1 -2
Frame3: B 1 3 0 0 0.5 2 0 2 1 1  1 1 2 -1 -3
Frame4: B 3 3 0 0 0.5 2 0 2 1 1  1 1 1 -1
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
\end{verbatim}




%%%%
%%%%
%%%%
\newgeometry{tmargin=1.6cm,lmargin=1cm,rmargin=1cm,bmargin=1in,nohead}
\subsection{Encoder parameters}

%%
%% File, I/O and source parameters
%%
Shorthand alternatives for the parameter that can be used on the command line are shown in brackets after the parameter name.

\begin{OptionTableNoShorthand}{File, I/O and source parameters.}{tab:fileIO}
\Option{InputFile (-i)} &
%\ShortOption{-i} &
\Default{\NotSet} &
Specifies the input video file.

Video data must be in a raw 4:2:0, or 4:2:2 planar format, 4:4:4 planar format (Y$'$CbCr, RGB or GBR), or in a raw 4:0:0 format. 

Note: When the bit depth of samples is larger than 8, each sample is encoded in
2 bytes (little endian, LSB-justified).
\\

\Option{BitstreamFile (-b)} &
%\ShortOption{-b} &
\Default{\NotSet} &
Specifies the output coded bit stream file.
\\

\Option{ReconFile (-o)} &
%\ShortOption{-o} &
\Default{\NotSet} &
Specifies the output locally reconstructed video file.
\\

\Option{SourceWidth (-wdt)}%
\Option{SourceHeight (-hgt)} &
%\ShortOption{-wdt}%
%\ShortOption{-hgt} &
\Default{0}%
\Default{0} &
Specifies the width and height of the input video in luma samples.
\\

\Option{InputBitDepth}
 &
%\ShortOption{\None} &
\Default{8} &
Specifies the bit depth of the input video.
\\

\Option{MSBExtendedBitDepth} &
%\ShortOption{\None} &
\Default{0} &
Extends the input video by adding MSBs of value 0. When 0, no extension is applied and the InputBitDepth is used.

The MSBExtendedBitDepth becomes the effective file InputBitDepth for subsequent processing.
\\

\Option{InternalBitDepth} &
%\ShortOption{\None} &
\Default{0} &
Specifies the bit depth used for coding. When 0, the setting defaults to the
value of the MSBExtendedBitDepth.

If the input video is a different bit depth to InternalBitDepth, it is
automatically converted by:
\begin{displaymath}
\left\lfloor
 \frac{\mathrm{Pel} * 2^{\mathrm{InternalBitDepth}}}{
     2^{\mathrm{MSBExtendedBitDepth}}}
\right\rfloor
\end{displaymath}

Note: The effect of this option is as if the input video is externally
converted to the MSBExtendedBitDepth and then to the InternalBitDepth
and then coded with this value as InputBitDepth. The codec has no
notion of different bit depths.
\\

\Option{OutputBitDepth} &
%\ShortOption{\None} &
\Default{0} &
Specifies the bit depth of the output locally reconstructed video file.
When 0, the setting defaults to the value of InternalBitDepth.
Note: This option has no effect on the decoding process.
\\

\Option{InputBitDepthC}%
\Option{MSBExtendedBitDepthC}%
\Option{InternalBitDepthC}%
\Option{OutputBitDepthC} &
%\ShortOption{\None} &
\Default{0}%
\Default{0}%
\Default{0}%
\Default{0} &
Specifies the various bit-depths for chroma components.  These only need
to be specified if non-equal luma and chroma bit-depth processing is
required. When 0, the setting defaults to the corresponding non-Chroma value.
\\

\Option{InputColourSpaceConvert} &
%\ShortOption{\None} &
\Default{\NotSet} &
The colour space conversion to apply to input video. Permitted values are:
\par
\begin{tabular}{lp{0.3\textwidth}}
  UNCHANGED & No colour space conversion is applied \\
  YCbCrToYCrCb & Swap the second and third components \\
  YCbCrtoYYY & Set the second and third components to the values in the first \\
  RGBtoGBR & Reorder the three components \\
\end{tabular}
\par
If no value is specified, no colour space conversion is applied. The list may eventually also include RGB to YCbCr or YCgCo conversions.
\\

\Option{SNRInternalColourSpace} &
%\ShortOption{\None} &
\Default{false} &
When this is set true, then no colour space conversion is applied prior to PSNR calculation, otherwise the inverse of InputColourSpaceConvert is applied.
\\

\Option{OutputInternalColourSpace} &
%\ShortOption{\None} &
\Default{false} &
When this is set true, then no colour space conversion is applied to the reconstructed video, otherwise the inverse of InputColourSpaceConvert is applied.
\\

\Option{InputChromaFormat} &
%\ShortOption{\None} &
\Default{420} &
Specifies the chroma format used in the input file. Permitted values (depending on the profile) are 400, 420, 422 or 444.
\\

\Option{ChromaFormatIDC (-cf)} &
%\ShortOption{-cf} &
\Default{0} &
Specifies the chroma format to use for processing. Permitted values (depending on the profile) are 400, 420, 422 or 444; the value of 0 indicates that the value of InputChromaFormat should be used instead.
\\

\Option{MSEBasedSequencePSNR} &
%\ShortOption{\None} &
\Default{false} &
When 0, the PSNR output is a linear average of the frame PSNRs; when 1, additional PSNRs are output which are formed from the average MSE of all the frames. The latter is useful when coding near-losslessly, where occasional frames become lossless.
\\

\Option{PrintFrameMSE} &
%\ShortOption{\None} &
\Default{false} &
When 1, the Mean Square Error (MSE) values of each frame will also be output alongside the default PSNR values.
\\

\Option{PrintSequenceMSE} &
%\ShortOption{\None} &
\Default{false} &
When 1, the Mean Square Error (MSE) values of the entire sequence will also be output alongside the default PSNR values.
\\

\Option{SummaryOutFilename} &
%\ShortOption{\None} &
\Default{false} &
Filename to use for producing summary output file. If empty, do not produce a file.
\\

\Option{SummaryPicFilenameBase} &
%\ShortOption{\None} &
\Default{false} &
Base filename to use for producing summary picture output files. The actual filenames used will have I.txt, P.txt and B.txt appended. If empty, do not produce a file.
\\

\Option{SummaryVerboseness} &
%\ShortOption{\None} &
\Default{false} &
Specifies the level of the verboseness of the text output.
\\

\Option{CabacZeroWordPaddingEnabled} &
%\ShortOption{\None} &
\Default{false} &
When 1, CABAC zero word padding will be enabled. This is currently not the default value for the setting.
\\

\Option{ConformanceWindowMode} &
%\ShortOption{\None} &
\Default{0} &
Specifies how the parameters related to the conformance window are interpreted (cropping/padding).
The following modes are available:
\par
\begin{tabular}{cp{0.43\textwidth}}
0 & No cropping / padding \\
1 & Automatic padding to the next minimum CU size \\
2 & Padding according to parameters HorizontalPadding and VerticalPadding \\
3 & Cropping according to parameters ConfWinLeft, ConfWinRight, ConfWinTop and ConfWinBottom \\
\end{tabular}
\\

\Option{HorizontalPadding (-pdx)}%
\Option{VerticalPadding (-pdy)} &
%\ShortOption{-pdx}%
%\ShortOption{-pdy} &
\Default{0} &
Specifies the horizontal and vertical padding to be applied to the input
video in luma samples when ConformanceWindowMode is 2.  Must be a multiple of
the chroma resolution (e.g. a multiple of two for 4:2:0).
\\

\Option{ConfWinLeft}%
\Option{ConfWinRight}%
\Option{ConfWinTop}%
\Option{ConfWinBottom} &
%\ShortOption{\None} &
\Default{0} &
Specifies the horizontal and vertical cropping to be applied to the
input video in luma samples when ConformanceWindowMode is 3. 
Must be a multiple of the chroma resolution (e.g. a multiple of
two for 4:2:0).
\\

\Option{FrameRate (-fr)} &
%\ShortOption{-fr} &
\Default{0} &
Specifies the frame rate of the input video.

Note: This option only affects the reported bit rates.
\\

\Option{FrameSkip (-fs)} &
%\ShortOption{-fs} &
\Default{0} &
Specifies a number of frames to skip at beginning of input video file.
\\

\Option{FramesToBeEncoded (-f)} &
%\ShortOption{-f} &
\Default{0} &
Specifies the number of frames to be encoded (see note regarding TemporalSubsampleRatio). When 0, all frames are coded.
\\

\Option{TemporalSubsampleRatio (-ts)} &
%\ShortOption{-fs} &
\Default{1} &
Temporally subsamples the input video sequence. A value of $N$ will skip $(N-1)$ frames of input video after each coded input video frame. Note the FramesToBeEncoded does not account for the temporal skipping of frames, which will reduce the number of frames encoded accordingly. The reported bit rates will be reduced and VUI information is scaled so as to present the video at the correct speed. The minimum and default value is 1.
\\

\Option{FieldCoding} &
%\ShortOption{\None} &
\Default{false} &
When 1, indicates that field-based coding is to be applied.
\\

\Option{TopFieldFirst (-Tff)} &
%\ShortOption{\None} &
\Default{0} &
Indicates the order of the fields packed into the input frame. When 1, the top field is temporally first.
\\

\Option{ClipInputVideoToRec709Range} &
%\ShortOption{\None} &
\Default{0} &
If 1 then clip input video to the Rec. 709 Range on loading when InternalBitDepth is less than MSBExtendedBitDepth.
\\

\Option{ClipOutputVideoToRec709Range} &
%\ShortOption{\None} &
\Default{0} &
If 1 then clip output video to the Rec. 709 Range on saving when OutputBitDepth is less than InternalBitDepth.
\\

\Option{EfficientFieldIRAPEnabled} &
%\ShortOption{\None} &
\Default{1} &
Enable to code fields in a specific, potentially more efficient, order.
\\

\Option{HarmonizeGopFirstFieldCoupleEnabled} &
%\ShortOption{\None} &
\Default{1} &
Enables harmonization of Gop first field couple.
\\

\Option{AccessUnitDelimiter} &
%\ShortOption{\None} &
\Default{0} &
Add Access Unit Delimiter NAL units between all Access Units.
\\

\end{OptionTableNoShorthand}

%%
%% profile, level and conformance options
%%
\begin{OptionTableNoShorthand}{Profile and level parameters}{tab:profile}
\Option{Profile} &
%\ShortOption{\None} &
\Default{none} &
Specifies the profile to which the encoded bitstream complies.

Valid HEVC Ver. 1 values are: none, main, main10, main-still-picture

Valid HEVC Ver. 2 (RExt) values are: main-RExt, high-throughput-RExt,
monochrome, monochrome12, monochrome16, main12, main_422_10,
main_422_12, main_444, main_444_10, main_444_12, main_444_16,
main_intra, main_10_intra, main_12_intra, main_422_10_intra, main_422_12_intra,
main_444_intra, main_444_10_intra, main_444_12_intra, main_444_16_intra.

When main-RExt is specified, the constraint flags are either manually specified, or calculated via the other supplied settings.

Compatibility flags are automatically determined according to the profile.
NB: There is currently only limited validation that the encoder configuration complies with the profile, level and tier constraints.
\\

\Option{Level} &
%\ShortOption{\None} &
\Default{none} &
Specifies the level to which the encoded bitstream complies.
Valid values are: none, 1, 2, 2.1, 3, 3.1, 4, 4.1, 5, 5.1, 5.2, 6, 6.1, 6.2, 8.5

NB: There is currently only limited validation that the encoder configuration complies with the profile, level and tier constraints.
\\

\Option{Tier} &
%\ShortOption{\None} &
\Default{main} &
Specifies the level tier to which the encoded bitsream complies.
Valid values are: main, high.

NB: There is currently only limited validation that the encoder configuration complies with the profile, level and tier constraints.
\\

Lidong Xu's avatar
Lidong Xu committed
904
905
906
907
908
909
\Option{SubProfile} &
%\ShortOption{\None} &
\Default{0} &
Indicates interoperability metadata registered as specified by X Recommendation ITU-T T.35.
\\

910
911
912
913
914
915
\Option{EnableDecodingParameterSet} &
%\ShortOption{\None} &
\Default{false} &
Enables writing of a decoding parameter set. If disabled, no parameter set will be written and the specical reserved ID zero will be used in the SPS indicating no constraint.
\\

916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\Option{MaxBitDepthConstraint} &
%\ShortOption{\None} &
\Default{0} &
For --profile=main-RExt, specifies the value to use to derive the general_max_bit_depth constraint flags for RExt profiles; when 0, use $\max(InternalBitDepth, InternalBitDepthC)$
\\

\Option{MaxChromaFormatConstraint} &
%\ShortOption{\None} &
\Default{0} &
For --profile=main-RExt, specifies the chroma-format to use for the general profile constraints for RExt profiles; when 0, use the value of ChromaFormatIDC.
\\

\Option{IntraConstraintFlag} &
%\ShortOption{\None} &
\Default{false} &
For --profile=main-RExt, specifies the value of general_intra_constraint_flag to use for RExt profiles.
\\

\Option{OnePictureOnlyConstraintFlag} &
%\ShortOption{\None} &
\Default{false} &
For --profile=main-RExt, specifies the value of general_one_picture_only_constraint_flag to use for RExt profiles.
\\

\Option{LowerBitRateConstraintFlag} &
%\ShortOption{\None} &
\Default{true} &
Specifies the value of general_lower_bit_constraint_flag to use for RExt profiles.
\\

\Option{ProgressiveSource} &
%\ShortOption{\None} &
\Default{false} &
Specifies the value of general_progressive_source_flag
\\

\Option{InterlacedSource} &
%\ShortOption{\None} &
\Default{false} &
Specifies the value of general_interlaced_source_flag 
\\

\Option{NonPackedSource} &
%\ShortOption{\None} &
\Default{false} &
Specifies the value of general_non_packed_constraint_flag
\\

\Option{FrameOnly} &
%\ShortOption{\None} &
\Default{false} &
Specifies the value of general_frame_only_constraint_flag
\\

\end{OptionTableNoShorthand}


%%
%% Unit definition parameters
%%

\begin{OptionTableNoShorthand}{Unit definition parameters}{tab:unit}
\Option{MaxCUWidth} &
%\ShortOption{\None} &
\Default{64} &
Defines the maximum CU width.
\\

\Option{MaxCUHeight} &
%\ShortOption{\None} &
\Default{64} &
Defines the maximum CU height.
\\

\Option{MaxCUSize (-s)} &
%\ShortOption{\None} &
\Default{64} &
Defines the maximum CU size.
\\

\Option{MaxPartitionDepth (-h)} &
%\ShortOption{-h} &
\Default{4} &
Defines the depth of the CU tree.
\\