[x265] [PATCH] level: clarify level/tier behavior a bit more

[Steve Borho]

# HG changeset patch
# User Steve Borho <steve at borho.org>
# Date 1432313099 18000
#      Fri May 22 11:44:59 2015 -0500
# Node ID ad0f5c336d66350a99a8c69b75661b2928e7a347
# Parent  a7bf7a150a705489cb63d0454c59ec599bad8c93
level: clarify level/tier behavior a bit more

There should be no-need to check level at the same time we check if high tier
is requested. High tier cannot be configured independent of a level, so the
bitrate and buffer size will have been clamped to the user's level/tier by
enforceLevel().

diff -r a7bf7a150a70 -r ad0f5c336d66 doc/reST/cli.rst
--- a/doc/reST/cli.rst	Fri May 22 14:29:35 2015 +0530
+++ b/doc/reST/cli.rst	Fri May 22 11:44:59 2015 -0500
@@ -479,6 +479,9 @@
 	specified level, main tier first, turning on high tier only if 
 	necessary and available at that level.
 
+	If :option:`--level-idc` has not been specified, this argument is
+	ignored.
+
 .. option:: --ref <1..16>
 
 	Max number of L0 references to be allowed. This number has a linear
@@ -511,6 +514,7 @@
 	Default: disabled
 
 .. note::
+
 	:option:`--profile`, :option:`--level-idc`, and
 	:option:`--high-tier` are only intended for use when you are
 	targeting a particular decoder (or decoders) with fixed resource
@@ -519,6 +523,19 @@
 	parameters to meet those requirements but it will never raise
 	them. It may enable VBV constraints on a CRF encode.
 
+	Also note that x265 determines the decoder requirement level in
+	three steps.  First, the user configures an x265_param structure
+	with their suggested encoder options and then optionally calls
+	x265_param_apply_profile() to enforce a specific profile (main,
+	main10, etc). Second, an encoder is created from this x265_param
+	instance and the :option:`--level-idc` and :option:`--high-tier`
+	parameters are used to reduce bitrate or other features in order to
+	enforce the target level. Finally, the encoder re-examines the final
+	set of parameters and detects the actual minimum decoder requirement
+	level and this is what is signaled in the bitstream headers. The
+	detected decoder level will only use High tier if the user specified
+	a High tier level.
+
 Mode decision / Analysis
 ========================
 
diff -r a7bf7a150a70 -r ad0f5c336d66 source/encoder/level.cpp
--- a/source/encoder/level.cpp	Fri May 22 14:29:35 2015 +0530
+++ b/source/encoder/level.cpp	Fri May 22 11:44:59 2015 -0500
@@ -167,11 +167,14 @@
         if (CHECK_RANGE(bitrate, levels[i].maxBitrateMain, levels[i].maxBitrateHigh) ||
             CHECK_RANGE((uint32_t)param.rc.vbvBufferSize, levels[i].maxCpbSizeMain, levels[i].maxCpbSizeHigh))
         {
-            /* If the user has not enabled high tier, continue looking to see if we can encode at a higher level, main tier */
-            if (!param.bHighTier && (levels[i].levelIdc < param.levelIdc))
+            /* The bitrate or buffer size are out of range for Main tier, but in
+             * range for High tier. If the user requested High tier then give
+             * them High tier at this level.  Otherwise allow the loop to
+             * progress to the Main tier of the next level */
+            if (param.bHighTier)
+                vps.ptl.tierFlag = Level::HIGH;
+            else
                 continue;
-            else
-                vps.ptl.tierFlag = Level::HIGH;
         }
         else
             vps.ptl.tierFlag = Level::MAIN;