[x265] [PATCH] api: change --crop-rect to --display-window to avoid confusion

[Steve Borho]

# HG changeset patch
# User Steve Borho <steve at borho.org>
# Date 1436547151 18000
#      Fri Jul 10 11:52:31 2015 -0500
# Node ID d336396371d61df766eed3fd76b3545e89b4a769
# Parent  977dc8564cc4b9800f221bc65e446b729d0f30af
api: change --crop-rect to --display-window to avoid confusion

It seems that in x264 --crop-rect defined their conformance window, so it can
be confusing to users that our --crop-rect defined a display window instead.

This commit changes the documentaion to use --display-window but still allows
--crop-rect to be used in the CLI and param_parse() so existing work-flows are
not affected.

diff -r 977dc8564cc4 -r d336396371d6 doc/reST/cli.rst
--- a/doc/reST/cli.rst	Thu Jul 09 17:47:46 2015 -0700
+++ b/doc/reST/cli.rst	Fri Jul 10 11:52:31 2015 -0500
@@ -1512,13 +1512,19 @@
 	15. 3:2
 	16. 2:1
 
-.. option:: --crop-rect <left,top,right,bottom>
+.. option:: --display-window <left,top,right,bottom>
 
 	Define the (overscan) region of the image that does not contain
 	information because it was added to achieve certain resolution or
-	aspect ratio. The decoder may be directed to crop away this region
-	before displaying the images via the :option:`--overscan` option.
-	Default undefined (not signaled)
+	aspect ratio (the areas are typically black bars). The decoder may
+	be directed to crop away this region before displaying the images
+	via the :option:`--overscan` option.  Default undefined (not
+	signaled).
+
+	Note that this has nothing to do with padding added internally by
+	the encoder to ensure the pictures size is a multiple of the minimum
+	coding unit (4x4). This is padding is signaled in a separate
+	"conformance window" and is not user-configurable.
 
 .. option:: --overscan <show|crop>
 
diff -r 977dc8564cc4 -r d336396371d6 source/common/param.cpp
--- a/source/common/param.cpp	Thu Jul 09 17:47:46 2015 -0700
+++ b/source/common/param.cpp	Fri Jul 10 11:52:31 2015 -0500
@@ -830,7 +830,7 @@
         p->vui.chromaSampleLocTypeTopField = atoi(value);
         p->vui.chromaSampleLocTypeBottomField = p->vui.chromaSampleLocTypeTopField;
     }
-    OPT("crop-rect")
+    OPT2("display-window", "crop-rect")
     {
         p->vui.bEnableDefaultDisplayWindowFlag = 1;
         bError |= sscanf(value, "%d,%d,%d,%d",
diff -r 977dc8564cc4 -r d336396371d6 source/x265cli.h
--- a/source/x265cli.h	Thu Jul 09 17:47:46 2015 -0700
+++ b/source/x265cli.h	Fri Jul 10 11:52:31 2015 -0500
@@ -185,7 +185,8 @@
     { "transfer",       required_argument, NULL, 0 },
     { "colormatrix",    required_argument, NULL, 0 },
     { "chromaloc",      required_argument, NULL, 0 },
-    { "crop-rect",      required_argument, NULL, 0 },
+    { "display-window", required_argument, NULL, 0 },
+    { "crop-rect",      required_argument, NULL, 0 }, /* DEPRECATED */
     { "master-display", required_argument, NULL, 0 },
     { "max-cll",        required_argument, NULL, 0 },
     { "no-dither",            no_argument, NULL, 0 },
@@ -384,7 +385,7 @@
     H0("                                 Choose from 0=undef, 1=1:1(\"square\"), 2=12:11, 3=10:11, 4=16:11,\n");
     H0("                                 5=40:33, 6=24:11, 7=20:11, 8=32:11, 9=80:33, 10=18:11, 11=15:11,\n");
     H0("                                 12=64:33, 13=160:99, 14=4:3, 15=3:2, 16=2:1 or custom ratio of <int:int>. Default %d\n", param->vui.aspectRatioIdc);
-    H1("   --crop-rect <string>          Add 'left,top,right,bottom' to the bitstream-level cropping rectangle\n");
+    H1("   --display-window <string>     Describe overscan cropping region as 'left,top,right,bottom' in pixels\n");
     H1("   --overscan <string>           Specify whether it is appropriate for decoder to show cropped region: undef, show or crop. Default undef\n");
     H0("   --videoformat <string>        Specify video format from undef, component, pal, ntsc, secam, mac. Default undef\n");
     H0("   --range <string>              Specify black level and range of luma and chroma signals as full or limited Default limited\n");