software-manual.tex

\end{tabular}
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Structure of pictures information SEI message encoder parameters}{tab:sei-sop-info}
\Option{SEISOPDescription} &
\Default{0} &
Enables or disables the insertion of the Structure of pictures information SEI messages.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Active parameter sets SEI message encoder parameters}{tab:sei-active-parameter-sets}
\Option{SEIActiveParameterSets} &
\Default{0} &
Enables or disables the insertion of the Active parameter sets
SEI messages.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Decoding unit information SEI message encoder parameters}{tab:sei-decoding-unit-info}
\Option{SEIDecodingUnitInfo} &
\Default{0} &
Enables or disables the insertion of the Decoding unit information
SEI messages. This option has no effect if VuiParametersPresent is disabled.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Temporal sub-layer zero index SEI message encoder parameters}{tab:sei-temporal-level-0}
\Option{SEITemporalLevel0Index} &
\Default{0} &
Enables or disables the insertion of the Temporal level zero index
SEI messages.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Decoded picture hash SEI message encoder parameters}{tab:sei-decoded-picture-hash}
\Option{SEIDecodedPictureHash} &
\Default{0} &
Enables or disables the calculation and insertion of the Decoded picture hash
SEI messages.
\par
\begin{tabular}{cp{0.35\textwidth}}
  0 & Disabled \\
  1 & Transmits MD5 in SEI message and writes the value to the encoder
      log \\
  2 & Transmits CRC in SEI message and writes the value to the encoder
      log \\
  3 & Transmits checksum in SEI message and writes the value to the encoder
      log \\
\end{tabular}
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Scalable nesting SEI message encoder parameters}{tab:sei-scalable-nesting}
\Option{SEIScalableNesting} &
\Default{0} &
Enables or disables the use of the scalable nesting SEI messages.
\\
\end{OptionTableNoShorthand}


        
\begin{OptionTableNoShorthand}{Region refresh information SEI message encoder parameters}{tab:sei-region-refresh-info}
\Option{SEIGradualDecodingRefreshInfo} &
\Default{0} &
Enables or disables the insertion of the Gradual decoding refresh information
SEI messages.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{No display SEI message encoder parameters}{tab:sei-no-display}
\Option{SEINoDisplay} &
\Default{0} &
When non-zero, generate no-display SEI message for temporal layer N or higher.
\\
\end{OptionTableNoShorthand}


        
\begin{OptionTableNoShorthand}{Time code SEI message encoder parameters}{tab:sei-time-code}
\Option{SEITimeCodeEnabled} &
\Default{false} &
When true (non-zero), generate Time code SEI messages.
\\
\Option{SEITimeCodeNumClockTs} &
\Default{0} &
Number of clock time sets, in the range of 0 to 3 (inclusive).
\\
\Option{SEITimeCodeTimeStampFlag} &
\Default{\None} &
Time stamp flag associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeFieldBasedFlag} &
\Default{\None} &
Field based flag associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeCountingType} &
\Default{\None} &
Counting type associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeFullTsFlag} &
\Default{\None} &
Full time stamp flag associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeDiscontinuityFlag} &
\Default{\None} &
Discontinuity flag associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeCntDroppedFlag} &
\Default{\None} &
Counter dropped flag associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeNumFrames} &
\Default{\None} &
Number of frames associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeSecondsFlag} &
\Default{\None} &
Flag to signal seconds value presence in each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeMinutesFlag} &
\Default{\None} &
Flag to signal minutes value presence in each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeHoursFlag} &
\Default{\None} &
Flag to signal hours value presence in each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeSecondsValue} &
\Default{\None} &
Seconds value for each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeMinutesValue} &
\Default{\None} &
Minutes value for each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeHoursValue} &
\Default{\None} &
Hours value for each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeOffsetLength} &
\Default{\None} &
Time offset length associated to each time set (comma or space separated list of entries).
\\
\Option{SEITimeCodeTimeOffset} &
\Default{\None} &
Time offset associated to each time set (comma or space separated list of entries).
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Mastering display colour volume SEI message encoder parameters}{tab:sei-mastering-display-colour-volume}
\Option{SEIMasteringDisplayColourVolume} &
\Default{false} &
When true (non-zero), generate Mastering display colour volume SEI message.
\\
\Option{SEIMasteringDisplayMaxLuminance} &
\Default{10000} &
Specifies the mastering display maximum luminance value in units of 1/10000 candela per square metre.
\\
\Option{SEIMasteringDisplayMinLuminance} &
\Default{0} &
Specifies the mastering display minimum luminance value in units of 1/10000 candela per square metre.
\\
\Option{SEIMasteringDisplayPrimaries} &
\Default{0,50000, 0,0, 50000,0} &
Mastering display primaries for all three colour planes in CIE xy coordinates in increments of 1/50000 (results in the ranges 0 to 50000 inclusive).
\\
\Option{SEIMasteringDisplayWhitePoint} &
\Default{16667, 16667} &
Mastering display white point CIE xy coordinates in normalized increments of 1/50000 (e.g. 0.333 = 16667).
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Segmented rectangular frame packing arrangement SEI message encoder parameters}{tab:sei-seg-rect-fpa}
\Option{SEISegmentedRectFramePacking} &
\Default{0} &
Controls generation of segmented rectangular frame packing SEI messages.
\\
\Option{SEISegmentedRectFramePackingCancel} &
\Default{false} &
If true, cancels the persistence of any previous SRFPA SEI message.
\\
\Option{SEISegmentedRectFramePackingType} &
\Default{0} &
Specifies the arrangement of the frames in the reconstructed picture.
\\
\Option{SEISegmentedRectFramePackingPersistence} &
\Default{false} &
If false the SEI applies to the current frame only.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Temporal motion-constrained tile sets SEI message encoder parameters}{tab:sei-tmcts}
\Option{SEITempMotionConstrainedTileSets} &
\Default{false} &
When true (non-zero), generates example temporal motion constrained tile sets SEI messages.
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Chroma resampling filter hint SEI message encoder parameters}{tab:chroma-resampling-filter-hint}
\Option{SEIChromaResamplingFilterHint} &
\Default{false} &
When true (non-zero), generates example chroma sampling filter hint SEI messages.
\\
\Option{SEIChromaResamplingHorizontalFilterType} &
\Default{2} &
Defines the index of the chroma sampling horizontal filter:
\par
\begin{tabular}{cp{0.35\textwidth}}
  0 & Unspecified \\
  1 & Filters signalled within the SEI message \\
  2 & Filters as described by SMPTE RP 2050-1:2012\\
\end{tabular}
\\
\Option{SEIChromaResamplingVerticalFilterType} &
\Default{2} &
Defines the index of the chroma sampling vertical filter:
\par
\begin{tabular}{cp{0.35\textwidth}}
  0 & Unspecified \\
  1 & Filters signalled within the SEI message \\
  2 & Filters as described in the 5/3 filter description of ITU-T Rec. T.800 | ISO/IEC 15444-1\\
\end{tabular}
\\
\end{OptionTableNoShorthand}



\begin{OptionTableNoShorthand}{Knee function SEI message encoder parameters}{tab:sei-knee-function}
\Option{SEIKneeFunctionInfo} &
\Default{false} &
Enables (true) or disables (false) the insertion of the Knee function SEI messages.
\\
\Option{SEIKneeFunctionId} &
\Default{0} &
Specifies Id of Knee function SEI message for a given session.
\\
\Option{SEIKneeFunctionCancelFlag} &
\Default{false} &
Indicates that Knee function SEI message cancels the persistance (true) or follows (false).
\\
\Option{SEIKneeFunctionPersistenceFlag} &
\Default{true} &
Specifies the persistence of the Knee function SEI message.
\\
\Option{SEIKneeFunctionInputDrange} &
\Default{1000} &
Specifies the peak luminance level for the input picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionInputDispLuminance} &
\Default{100} &
Specifies the expected display brightness for the input picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionOutputDrange} &
\Default{4000} &
Specifies the peak luminance level for the output picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionOutputDispLuminance} &
\Default{800} &
Specifies the expected display brightness for the output picture of Knee function SEI messages.
\\
\Option{SEIKneeFunctionNumKneePointsMinus1} &
\Default{2} &
Specifies the number of knee points - 1.
\\
\Option{SEIKneeFunctionInputKneePointValue} &
\Default{} &
Array of input knee point. Default table can be set to the following:
\par
\begin{tabular}{cp{0.45\textwidth}}
600 800 900
\end{tabular}
\\
\Option{SEIKneeFunctionOutputKneePointValue} &
\Default{} &
Array of output knee point. Default table can be set to the following:
\par
\begin{tabular}{cp{0.45\textwidth}}
100 250 450
\end{tabular}
\\
\end{OptionTableNoShorthand}


\begin{OptionTableNoShorthand}{Colour remapping SEI message encoder parameters}{tab:sei-colour-remapping}
\Option{SEIColourRemappingInfoFileRoot (-cri)} &
\Default{\NotSet} &
Specifies the prefix of input Colour Remapping Information file. Prefix is completed by ``_x.txt'' where x is the  POC number.
The contents of the file are a list of the SEI message's syntax element names (in decoding order) immediately followed by a `:' and then the associated value.
An example file can be found in cfg/misc/example_colour_remapping_sei_encoder_0.txt.
\\
\end{OptionTableNoShorthand}



%\Option{SEITimeCode} &
%\Default{false} &
%When true, generate time code SEI messages.
%\\

%%
%%
%%
\subsection{Hardcoded encoder parameters}
\begin{MacroTable}{CommonDef.h constants}
ADAPT_SR_SCALE &
1 &
Defines a scaling factor used to derive the motion search range is
adaptive (see ASR configuration parameter). Default value is 1.
\\

MAX_GOP &
64 &
maximum size of value of hierarchical GOP.
\\

MAX_NUM_REF &
4 &
maximum number of multiple reference frames
\\

MAX_NUM_REF_LC &
8 &
maximum number of combined reference frames
\\

AMVP_MAX_NUM_CANDS &
2 &
maximum number of final candidates
\\

AMVP_MAX_NUM_CANDS_MEM &
3 &
\\

MRG_MAX_NUM_CANDS &
5 &
\\

DYN_REF_FREE &
off &
dynamic free of reference memories
\\

MAX_TLAYER &
8 &
maximum number of temporal layers
\\

ADAPT_SR_SCALE &
on &
division factor for adaptive search range
\\

EARLY_SKIP_THRES &
1.5 &
early skip if RD < EARLY_SKIP_THRES*avg[BestSkipRD]
\\

MAX_NUM_REF_PICS &
16 &
\\

MAX_CHROMA_FORMAT_IDC &
3 &
\\
\end{MacroTable}

\subsubsection*{TypeDef.h}
Numerous constants that guard individual adoptions are defined within
\url{source/Lib/TLibCommon/TypeDef.h}.


%%
%%
%%
\clearpage
\section{Using the decoder}
\subsection{General}
\begin{minted}{bash}
TAppDecoder -b str.bin -o dec.yuv [options]
\end{minted}

\begin{OptionTableNoShorthand}{Decoder options}{tab:decoder-options}
\Option{(--help)} &
%\ShortOption{\None} &
\Default{\None} &
Prints usage information.
\\

\Option{BitStreamFile (-b)} &
%\ShortOption{-b} &
\Default{\NotSet} &
Defines the input bit stream file name.
\\

\Option{ReconFile (-o)} &
%\ShortOption{-o} &
\Default{\NotSet} &
Defines reconstructed YUV file name. If empty, no file is generated.
\\

\Option{SkipFrames (-s)} &
%\ShortOption{-s} &
\Default{0} &
Defines the number of pictures in decoding order to skip.
\\

\Option{MaxTemporalLayer (-t)} &
%\ShortOption{-t} &
\Default{-1} &
Defines the maximum temporal layer to be decoded. If -1, then all layers are decoded.
\\

\Option{TarDecLayerIdSetFile (-l)} &
%\ShortOption{-t} &
\Default{\NotSet} &
Specifies the targetDecLayerIdSet file name. The file would contain white-space separated LayerId values of the layers that are to be decoded.
Omitting the parameter, or using a value of -1 in the file decodes all layers.
\\

\Option{OutputBitDepth (-d)} &
%\ShortOption{-d} &
\Default{0 \\ (Native)} &
Specifies the luma bit-depth of the reconstructed YUV file (the value 0 indicates
that the native bit-depth is used)
\\

\Option{OutputBitDepthC} &
%\ShortOption{\None} &
\Default{0 \\ (Native)} &
Defines the chroma bit-depth of the reconstructed YUV file (the value 0 indicates
that the native bit-depth is used)
\\

\Option{TargetLayer (-p)} &
%\ShortOption{-p} &
\Default{-1 \\ (Native)} &
Specifies the target bitstream Layer to be decoded. (the value -1 indicates
that decoding the whole bitstream )
\\

\Option{SEIDecodedPictureHash} &
%\ShortOption{\None} &
\Default{1} &
Enable or disable verification of any Picture hash SEI messages. When
this parameter is set to 0, the feature is disabled and all messages are
ignored. When set to 1 (default), the feature is enabled and the decoder
has the following behaviour:
\begin{itemize}
\item
  If Picture hash SEI messages are included in the bit stream, the same type
  of hash is calculated for each decoded picture and written to the
  log together with an indication whether the calculted value matches
  the value in the SEI message. 
  Decoding will continue even if there is a mismatch.

\item
  After decoding is complete, if any MD5sum comparison failed, a warning
  is printed and the decoder exits with the status EXIT_FAILURE

\item
  The per-picture MD5 log message has the following formats:
  [MD5:d41d8cd98f00b204e9800998ecf8427e,(OK)],
  [MD5:d41d8cd98f00b204e9800998ecf8427e,(unk)],
  [MD5:d41d8cd98f00b204e9800998ecf8427e,(***ERROR***)] [rxMD5:b9e1...]
  where, "(unk)" implies that no MD5 was signalled for this picture,
  "(OK)" implies that the decoder agrees with the signalled MD5,
  "(***ERROR***)" implies that the decoder disagrees with the signalled
  MD5. "[rxMD5:...]" is the signalled MD5 if different.
\end{itemize}
\\

\Option{OutputDecodedSEIMessagesFilename} &
%\ShortOption{\None} &
\Default{\NotSet} &
When a non-empty file name is specified, information regarding any decoded SEI messages will be output to the indicated file. If the file name is '-', then stdout is used instead.
\\

\Option{SEIColourRemappingInfoFilename} &
%\ShortOption{\None} &
\Default{\NotSet} &
Specifies that the colour remapping SEI message should be applied to the output video, with the output written to this file.
If no value is specified, the SEI message is ignored and no mapping is applied.
\\

\Option{RespectDefDispWindow (-w)} &
%\ShortOption{-w} &
\Default{0} &
Video region to be output by the decoder.
\par
\begin{tabular}{cp{0.45\textwidth}}
  0 & Output content inside the conformance window. \\
  1 & Output content inside the default window. \\
\end{tabular}
\\

\Option{OutputColourSpaceConvert} &
\Default{\NotSet} &
Specifies the colour space conversion to apply to 444 video. Permitted values are:
\par
\begin{tabular}{lp{0.45\textwidth}}
  UNCHANGED   & No colour space conversion is applied \\
  YCrCbToYCbCr & Swap the second and third components \\
  GBRtoRGB     & Reorder the three components \\
\end{tabular}
If no value is specified, no colour space conversion is applied. The list may eventually also include RGB to YCbCr or YCgCo conversions.\\
\\

\Option{PYUV} &
\Default{false} &
When true, output 10-bit and 12-bit YUV data as 5-byte and 3-byte (respectively) packed YUV data. See doc/pyuv_format.pdf for details. Ignored for interlaced output.
\\

\Option{SEINoDisplay} &
\Default{false} &
When true, do not output frames for which there is an SEI NoDisplay message.
\\

\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.
\\

\end{OptionTableNoShorthand}


\subsection{Using the decoder analyser}
If the decoder is compiled with the macro RExt__DECODER_DEBUG_BIT_STATISTICS defined as 1 (either externally, or by editing TypeDef.h), the decoder will gather fractional bit counts associated with the different syntax elements, producing a table of the number of bits per syntax element, and where appropriate, according to block size and colour component/channel.
The Linux makefile will compile both the analyser and standard version when the `all' or `everything' target is used (where the latter will also build  high-bit-depth executables).



\section{Block statistics extension}
\label{sec:block-stat-extens}

The block statistics extension enables straightforward visualization and statistical analysis of coding tool
usage in encoded bitstreams. The extension enables the reference
software encoder and decoder to write out statistics files in a configurable
way, which in turn can be loaded into a suitable YUV player for overlay of the
reconstructed YUV sequence, or can be used for statistical analysis at a
selectable scope (e.g. block/picture/sequence level). An example implementation
for such visualization is available with the open-source YUView player
(\url{https://github.com/IENT/YUView}). 


\subsection{Usage}
\label{sec:usage}

The software has to be compiled with the macros ENABLE_TRACING and
K0149_BLOCK_STATISTICS  defined as 1. The statistics can be written by either
encoder or decoder.

The extension adds additional trace channels to the ``dtrace'' functionality of
the software. The following trace channels were added:
\begin{description}
\item[D_BLOCK_STATISTICS_ALL] All syntax elements are written, no matter whether
  they are actually encoded or derived.
\item[D_BLOCK_STATISTICS_CODED] Tries to write only syntax elements, which have
  also been encoded.
\end{description}

The following additional encoder options are available (part of ``dtrace''). See
the file dtrace_next.h for more details.

\begin{OptionTableNoShorthand}{Decoder options}{tab:decoder-block-statistics}
\Option{TraceFile} &
%\ShortOption{\None} &
\Default{\None} &
File name of the produced trace file.
\\

\Option{TraceRule} &
%\ShortOption{-b} &
\Default{\NotSet} &
Specifies which traces should be saved, and for which POCs.
\\

\end{OptionTableNoShorthand}

Concrete examples of calls for  generating a block statistics file are:
\begin{minted}{bash}
bin/DecoderAppStatic -b str/BasketballDrive_1920x1080_QP37.vvc \
    --TraceFile="stats/BasketballDrive_1920x1080_QP37_coded.vtmbmsstats" \
    --TraceRule="D_BLOCK_STATISTICS_CODED:poc>=0"

bin/DecoderAppStatic -b str/BasketballDrive_1920x1080_QP37.vvc \
    --TraceFile="stats/BasketballDrive_1920x1080_QP37_all.vtmbmsstats" \
    --TraceRule="D_BLOCK_STATISTICS_ALL:poc>=0"   
\end{minted}


\subsection{Block statistics file formats}
\label{sec:block-stat-file}
The trace file will contain a header listing information of all available block
statistics. For each statistic it lists a type and a scale for vectors or range
for integers if applicable: 
\begin{verbatim}
# VTMBMS Block Statistics
# Sequence size: [832x 480]
# Block Statistic Type: PredMode; Flag; 
# Block Statistic Type: MergeFlag; Flag; 
# Block Statistic Type: MVL0; Vector; Scale: 4
# Block Statistic Type: MVL1; Vector; Scale: 4
# Block Statistic Type: IPCM; Flag; 
# Block Statistic Type: Y_IntraMode; Integer; [0, 73]
# Block Statistic Type: Cb_IntraMode; Integer; [0, 73]
\end{verbatim}

Two formats are available for the statistics for each block, a human readable
format and a CSV based format. The header remains the same for both cases. 

For both formats each row contains the information for one block statistic. The
order of the data is: picture order count (POC), location of top left corner of
the block, size of the block, name of the statistic, and value of the
statistic. 
The macro BLOCK_STATS_AS_CSV is available in order to choose the required format.
The human readable format can also be easily processed with other software, for
example YUView, using regular expressions. The CSV based formats provides the
universal interface required by spreadsheet applications.

The human readable format is based on the format used for the other dtrace
statistics. Some examples for this format are:
\begin{verbatim}
BlockStat: POC 16 @( 112,   0) [ 8x 8] SkipFlag=1
BlockStat: POC 16 @( 112,   0) [ 8x 8] InterDir=1
BlockStat: POC 16 @( 112,   0) [ 8x 8] MergeFlag=1
BlockStat: POC 16 @( 112,   0) [ 8x 8] MergeIdx=0
BlockStat: POC 16 @( 112,   0) [ 8x 8] MergeType=0
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVPIdxL0=255
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVPNumL0=255
BlockStat: POC 16 @( 112,   0) [ 8x 8] RefIdxL0=0
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVDL0={   0,   0}
BlockStat: POC 16 @( 112,   0) [ 8x 8] MVL0={ -70,  18}
BlockStat: POC 16 @( 112,   8) [ 8x 8] PredMode=0
BlockStat: POC 16 @( 112,   8) [ 8x 8] PartSize=0
\end{verbatim}

Some examples of the CSV based format are:
\begin{verbatim}
BlockStat;16; 112;   0; 8; 8;SkipFlag;1
BlockStat;16; 112;   0; 8; 8;InterDir;1
BlockStat;16; 112;   0; 8; 8;MergeFlag;1
BlockStat;16; 112;   0; 8; 8;MergeIdx;0
BlockStat;16; 112;   0; 8; 8;MergeType;0
BlockStat;16; 112;   0; 8; 8;MVPIdxL0;255
BlockStat;16; 112;   0; 8; 8;MVPNumL0;255
BlockStat;16; 112;   0; 8; 8;RefIdxL0;0
BlockStat;16; 112;   0; 8; 8;MVDL0;   0;   0
BlockStat;16; 112;   0; 8; 8;MVL0; -70;  18
BlockStat;16; 112;   8; 8; 8;PredMode;0
BlockStat;16; 112;   8; 8; 8;PartSize;0
\end{verbatim}

\subsection{Visualization}
\label{sec:visualization}

The block statistics can be viewed with YUView, which is freely available under
GPLv3: \url{https://github.com/IENT/YUView}. The latest releases and the master
branch have the functionality required for  viewing the block statistics. YUView
assumes that the file extension of block statistics file is
“.vtmbmsstats”. However, if a file is not recognized you can choose from a list
of supported file formats.


Statistics can be overlaid with YUV sequences. Some example snapshots are:

\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.8\linewidth]{figures/YUView}
  \caption{YUView}
  \label{fig:yuview}
\end{figure}

\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.5\linewidth]{figures/raceHorsesShot2MotionVectors}
  \caption{Motion vectors}
  \label{fig:motion-vectors}
\end{figure}


\begin{figure}[htpb]
  \centering
  \includegraphics[width=0.5\linewidth]{figures/raceHorsesShot3SkipFlag}
  \caption{Skip flag}
  \label{fig:skip-flag}
\end{figure}

\subsection{Adding statistics}
\label{sec:adding-statistics}

In order to add further block statistics, do the following:


\begin{description}
\item[source/Lib/CommonLib/dtrace_blockstatistics.h]
  Add your statistic to the BlockStatistic enum:	
\begin{minted}{c++}
enum class BlockStatistic {
  // general
  PredMode,
  PartSize,
  Depth,
\end{minted}
  
Further, add your statistic to the map blockstatistic2description:
\begin{minted}{c++}
static const std::map<BlockStatistic, 
  std::tuple<std::string, BlockStatisticType, std::string>> 
  blockstatistic2description =
{
  { BlockStatistic::PredMode, 
    std::tuple<std::string, BlockStatisticType, std::string>
    {"PredMode", BlockStatisticType::Flag, ""}},
  { BlockStatistic::MergeFlag,
    std::tuple<std::string, BlockStatisticType, std::string>
    {"MergeFlag", BlockStatisticType::Flag, ""}},
  { BlockStatistic::MVL0,
    std::tuple<std::string, BlockStatisticType, std::string>
    {"MVL0", BlockStatisticType::Vector, "Scale: 4"}},
  YOURS
\end{minted}


\item[source/Lib/CommonLib/dtrace_blockstatistics.cpp] All code for
  writing syntax elements is kept in this file in
  getAndStoreBlockStatistics. This function is called once for each
  CTU, after it has been en/decoded. The following macros have been
  defined to facilitate writing of block statistics:
\begin{minted}{c++}
DTRACE_BLOCK_SCALAR(ctx,channel,cs_cu_pu,stat_type,val)   
DTRACE_BLOCK_SCALAR_CHROMA(ctx,channel,cs_cu_pu,stat_type,val)
DTRACE_BLOCK_VECTOR(ctx,channel,cu_pu,stat_type,v_x,v_y)    
DTRACE_BLOCK_AFFINETF(ctx,channel,pu,stat_type,v_x0,v_y0,v_x1,v_y1,v_x2,v_y2) 
\end{minted}

An example:
\begin{minted}{c++}
DTRACE_BLOCK_SCALAR(g_trace_ctx, D_BLOCK_STATISTICS_ALL, 
  cu, GetBlockStatisticName(BlockStatistic::PredMode), cu.predMode);
\end{minted}


\item[Block statistics for debugging] The statistics can also be used
  to write out other data, not just syntax elements. Add your
  statistics to dtrace_blockstatistics.h. Where it should be used the
  following headers have to be included:
\begin{minted}{c++}
#include "dtrace_next.h"
#include "dtrace_blockstatistics.h"
\end{minted}
\end{description}





\section{Using the stream merge tool}
\label{sec:stream-merge-tool}

The StreamMergeApp tool takes multiple single-layer (singe nuh_layer_id) bistreams 
as inputs and merge them into a multi-layer bistream by interleaving the NALUs 
from the input single layer bistreams. During the merge, the tool assigns a new unique
nuh_layer_id for each input bitstream. Then the decoder could specify which layer 
bitstream to be decoded through the command line option "-p nuh_layer_id". 

\subsection{Usage}
\label{sec:stream-merge-usage}

\begin{minted}{bash}
StreamMergeApp 	<bitstream1> <bitstream2> [<bitstream3> ...] <outfile>
\end{minted}

The command line options bistreamX specify the file names of the input single-layer 
bistreams. At least two input bitstreams need to be specified. The merged multi-layer 
bistream will be stored into the outfile.

\end{document}