diff --git a/src/doc/maketx.rst b/src/doc/maketx.rst index c1e9b2c1d2..debe76e266 100644 --- a/src/doc/maketx.rst +++ b/src/doc/maketx.rst @@ -462,6 +462,33 @@ Command-line arguments are: (This option was added for OpenImageIO 2.3.) +.. option:: --cdf + --cdfsigma + --cdfbits + + 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: diff --git a/src/doc/oiiotool.rst b/src/doc/oiiotool.rst index f20bf86a10..a79b7473f7 100644 --- a/src/doc/oiiotool.rst +++ b/src/doc/oiiotool.rst @@ -1306,7 +1306,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:: diff --git a/src/include/OpenImageIO/imagebufalgo.h b/src/include/OpenImageIO/imagebufalgo.h index 0372b98f69..183f1c574a 100644 --- a/src/include/OpenImageIO/imagebufalgo.h +++ b/src/include/OpenImageIO/imagebufalgo.h @@ -2123,6 +2123,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 diff --git a/src/libOpenImageIO/maketexture.cpp b/src/libOpenImageIO/maketexture.cpp index 986b18df34..ec6730928e 100644 --- a/src/libOpenImageIO/maketexture.cpp +++ b/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