Add documentation for new texture CDF options (AcademySoftwareFoundation#3206)

Also, fixed the fact that direct calls to make_texture() were not given
proper defaults for the cdfsigma and cdfbits options.

Related to PR AcademySoftwareFoundation#3159

Author: lgritz

src/doc/maketx.rst

@@ -462,6 +462,33 @@ Command-line arguments are:
 
    (This option was added for OpenImageIO 2.3.)
 
+.. option:: --cdf
+            --cdfsigma <SIGMA>
+            --cdfbits <BITS>
+
+   When `--cdf` is used, the output texture will write a Gaussian CDF and
+   Inverse Gaussian CDF as per-channel metadata in the texture, which can be
+   used by shaders to implement Histogram-Preserving Blending. This is only
+   useful when the texture being created is written to an image format that
+   supports arbitrary metadata (e.g. OpenEXR).
+
+   When `--cdf` has been enabled, the additional options `--cdfsigma` may be
+   used to specify the CDF sigma value (defaulting to 1.0/6.0), and
+   `--cdfbits` specifies the number of bits to use for the size of the CDF
+   table (defaulting to 8, which means 256 bins).
+   
+   References:
+
+   * Histogram-Preserving Blending for Randomized Texture Tiling," JCGT 8(4),
+     2019.
+   
+   * Heitz/Neyret, "High-Performance By-Example Noise using a
+     Histogram-Preserving Blending Operator," ACM SIGGRAPH / Eurographics
+     Symposium on High-Performance Graphics 2018.)
+
+   * Benedikt Bitterli https://benedikt-bitterli.me/histogram-tiling/
+
+   These options were first added in OpenImageIO 2.3.10.
 
 
 .. sec-oiiotooltex:

src/doc/oiiotool.rst

@@ -1289,7 +1289,19 @@ Writing images
       `:bumpformat=` *string*
         For `-obump` only, specifies the interpretation of 3-channel source
         images as one of: `height`, `normal`, `auto` (default).
-
+      `:uvslopes_scale=` *float*
+        For `-obump` only, specifies the amount to scale the bump-map slopes
+        by. (default: 0.0, meaning not to use this feature)
+      `:cdf=` *int*
+        If nonzero, will add to the texture metadata the forward and inverse
+        Gaussian CDF, which can be used by shaders to implement
+        Histogram-Preserving blending. (default: 0)
+      `:cdfsigma=` *float*
+        In conjunction with `cdf=1`, specifies the sigma value to use for the
+        CDF (default: 1.0/6.0).
+      `:cdfbits=` *int*
+        In conjunction with `cdf=1`, specifies the number of bits to use for
+        the size of the CDF table (default: 8, meaning 256 bins).
 
     Examples::
 

src/include/OpenImageIO/imagebufalgo.h

@@ -2092,6 +2092,27 @@ enum MakeTextureMode {
 ///                           factor. The default is 0, disabling the
 ///                           feature. If you use this feature, a suggested
 ///                           value is 256.
+///    - `maketx:cdf` (int) :
+///                           If nonzero, will write a Gaussian CDF and
+///                           Inverse Gaussian CDF as per-channel metadata
+///                           in the texture, which can be used by shaders
+///                           to implement Histogram-Preserving Blending.
+///                           This is only useful when the texture being
+///                           created is written to an image format that
+///                           supports arbitrary metadata (e.g. OpenEXR).
+///                           (See Burley, "On Histogram-Preserving Blending
+///                           for Randomized Texture Tiling," JCGT 8(4), 2019,
+///                           and Heitz/Neyret, "High-Performance By-Example
+///                           Noise using a Histogram-Preserving Blending
+///                           Operator," ACM SIGGRAPH / Eurographics Symposium
+///                           on High-Performance Graphics 2018.) (default: 0)
+///    - `maketx:cdfsigma` (float) :
+///                           When `maketx:cdf` is active, determines the
+///                           CDF sigma (default: 1.0/6).
+///    - `maketx:cdfbits` (int) :
+///                           When `maketx:cdf` is active, determines the
+///                           number of bits to use for the size of the CDF
+///                           table. (default: 8, meaning 256 bins)
 ///
 /// @param  mode
 ///    Describes what type of texture file we are creating and may

src/libOpenImageIO/maketexture.cpp

@@ -1198,16 +1198,16 @@ make_texture_impl(ImageBufAlgo::MakeTextureMode mode, const ImageBuf* input,
         //
         // Eric Heitz and Fabrice Neyret, High-Performance By-Example Noise
         // using a Histogram-Preserving Blending Operator,
-        // https://hal.inria.fr/hal-01824773}, Proceedings of the ACM on
+        // https://hal.inria.fr/hal-01824773, Proceedings of the ACM on
         // Computer Graphics and Interactive Techniques, ACM SIGGRAPH /
-        // Eurographics Symposium on High-Performance Graphics 2018,
+        // Eurographics Symposium on High-Performance Graphics 2018.
         //
         // Benedikt Bitterli
         // https://benedikt-bitterli.me/histogram-tiling/
 
-        const float cdf_sigma = configspec.get_float_attribute(
-            "maketx:cdfsigma");
-        const int cdf_bits  = configspec.get_int_attribute("maketx:cdfbits");
+        const float cdf_sigma
+            = configspec.get_float_attribute("maketx:cdfsigma", 1.0f / 6.0f);
+        const int cdf_bits  = configspec.get_int_attribute("maketx:cdfbits", 8);
         const uint64_t bins = 1 << cdf_bits;
 
         // Normalization coefficient for the truncated normal distribution