docs: explain how to write Ultra HDR images

Signed-off-by: Loïc Vital <mugulmotion@gmail.com>

Author: mugulmd

src/doc/builtinplugins.rst

@@ -209,7 +209,7 @@ attributes are supported:
    * - ``oiio:ioproxy``
      - ptr
      - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for
-       example by reading from memory rather than the file system.    
+       example by reading from memory rather than the file system.
 
 Additionally, an integer ``dds:bc5normal`` global attribute is supported
 to control behavior of images compressed in BC5/ATI2 compression format.
@@ -555,7 +555,7 @@ storage.  Currently, OpenImageIO only supports 2D FITS data (images), not 3D
      - int
      - The number of subimages in the file.
    * - *other*
-     - 
+     -
      - all other FITS keywords will be added to the ImageSpec as arbitrary
        named metadata.
 
@@ -885,7 +885,7 @@ attributes are supported:
    * - ``oiio:ioproxy``
      - ptr
      - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for
-       example by reading from memory rather than the file system.    
+       example by reading from memory rather than the file system.
 
 **Configuration settings for ICO output**
 
@@ -1051,7 +1051,7 @@ anywhere near the acceptance of the original JPEG/JFIF format.
      - Describes the chroma subsampling, e.g., ``"4:2:0"`` (the default),
        ``"4:4:4"``, ``"4:2:2"``, ``"4:2:1"``.
    * - ``Exif:*``, ``IPTC:*``, ``XMP:*``, ``GPS:*``
-     - 
+     -
      - Extensive Exif, IPTC, XMP, and GPS data are supported by the
        reader/writer, and you should assume that nearly everything described
        Appendix :ref:`chap-stdmetadata` is properly translated when using
@@ -1111,6 +1111,10 @@ control aspects of the writing itself:
      - int
      - If nonzero, extra attributes will be written into the file as comment
        blocks.
+   * - ``jpeg:ultrahdr``
+     - int
+     - If nonzero, the image will be written as an Ultra HDR image (see the
+       :ref:`Ultra HDR <sec-bundledplugins-jpeg-ultrahdr>` section below).
 
 
 **Custom I/O Overrides**
@@ -1132,9 +1136,11 @@ via the `ImageInput::set_ioproxy()` method and the special
   mode and do not support tiled image input or output.
 
 
+.. _sec-bundledplugins-jpeg-ultrahdr:
+
 **Ultra HDR**
 
-JPEG input also supports Ultra HDR images.
+JPEG input and output support Ultra HDR images.
 Ultra HDR is an image format that encodes a high dynamic range image
 in a JPEG image file by including a gain map in addition to the
 primary image.
@@ -1143,6 +1149,21 @@ a complete reference on the Ultra HDR image format.
 In the specific case of reading an Ultra HDR image, JPEG input will also
 support alpha channels and high dynamic range imagery (`half` pixels).
 
+Ultra HDR *output* is enabled by setting the ``jpeg:ultrahdr`` attribute to a
+nonzero value. This makes it possible, for example, to convert a linear HDR
+OpenEXR image into a widely shareable Ultra HDR JPEG.
+When writing Ultra HDR, the following requirements apply:
+
+* The pixel data type must be ``half`` or ``float`` (an HDR-capable, linear
+  data type).
+* The image must have at least 3 channels. If a 4th channel is present it is preserved;
+  RGB images are written with an opaque alpha.
+* The image's ``oiio:ColorSpace`` must be a linear scene-referred space whose
+  primaries are Rec.709, Display-P3, or Rec.2020 (i.e. ``lin_rec709_scene``,
+  ``lin_p3d65_scene``, or ``lin_rec2020_scene``). The color gamut written to
+  the file is inferred from this.
+* The base image JPEG quality is taken from the ``compression`` attribute
+  (e.g. ``compression="jpeg:90"``), defaulting to 95.
 
 
 |
@@ -1210,8 +1231,8 @@ attributes are supported:
      - ptr
      - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for
        example by reading from memory rather than the file system.
-  
-If OpenJPH is installed, the reader will attempt to read the file first with 
+
+If OpenJPH is installed, the reader will attempt to read the file first with
 the OpenJPH library, and if that fails, it will fall back to the OpenJPEG library.
 
 **Configuration settings for JPEG-2000 output**
@@ -1260,7 +1281,7 @@ writer will attempt to write the file with the OpenJPH library, and the followin
      - (5) number of decompositions.
    * - ``jph:block_size``
      - string
-     - The output block size, defaults to 64,64   
+     - The output block size, defaults to 64,64
    * - ``jph:prog_order``
      - string
      - (RPCL) is the progression order, and can be one of:
@@ -1277,7 +1298,7 @@ writer will attempt to write the file with the OpenJPH library, and the followin
                is repeated for all finer resolutions
    * - ``jph:qstep``
      - float
-     - If supplied, is the quantization step size for lossy compression; 
+     - If supplied, is the quantization step size for lossy compression;
        quantization steps size for all subbands are derived from this value. Valid values can be from 0.00001 to 0.5.
        If not used, the encoder will be lossless.
 
@@ -1317,7 +1338,7 @@ attributes are supported:
      - ptr
      - Pointer to a ``Filesystem::IOProxy`` that will handle the I/O, for
        example by reading from memory rather than the file system.
-       
+
 **Configuration settings for JPEG XL output**
 
 When opening a JPEG XL ImageOutput, the following special metadata tokens
@@ -1354,7 +1375,7 @@ control aspects of the writing itself:
      - float
      - Target visual distance in JND units, lower = higher quality.
        0.0 = mathematically lossless. 1.0 = visually lossless.
-       Recommended range: 0.5 .. 3.0. Allowed range: 0.0 ... 25.0. 
+       Recommended range: 0.5 .. 3.0. Allowed range: 0.0 ... 25.0.
        Mutually exclusive with ``*compression jpegxl:*```.
    * - ``jpegxl:effort``
      - int
@@ -1614,8 +1635,8 @@ The official OpenEXR site is http://www.openexr.com/.
      - the MIPmap rounding mode of the file.
    * - ``openexr:dwaCompressionLevel``
      - float
-     - compression level for dwaa or dwab compression (default: 45.0). 
-       Reflects the level used when reading an existing file. To set 
+     - compression level for dwaa or dwab compression (default: 45.0).
+       Reflects the level used when reading an existing file. To set
        the compression level, use the ``compression`` attribute.
    * - ``openexr::luminancechroma``
      - int
@@ -1636,7 +1657,7 @@ The official OpenEXR site is http://www.openexr.com/.
        This metadata was added in OpenImageIO 3.1, and is only supported when
        OIIO is built against OpenEXR 3.1 or newer.
    * - *other*
-     - 
+     -
      - All other attributes will be added to the ImageSpec by their name and
        apparent type.
 
@@ -1822,7 +1843,7 @@ files use the file extension :file:`.png`.
      - float
      - pixel aspect ratio
    * - ``XResolution``, ``YResolution``, ``ResolutionUnit``
-     - 
+     -
      - resolution and units from the PNG header.
    * - ``oiio:ColorSpace``
      - string
@@ -1968,7 +1989,7 @@ Without loss of generality, we will refer to these all collectively as
 for those who reject the nonsense about naming the files depending on the
 number of channels and bitdepth.
 
-PNM files are widely used in the Unix world as simple ASCII or binary image 
+PNM files are widely used in the Unix world as simple ASCII or binary image
 files that are easy to read and write. They are not compressed, and are
 not particularly efficient for large images. They are not widely used in
 the professional graphics world, but because of their historical
@@ -2029,7 +2050,7 @@ attributes are supported:
        example by reading from memory rather than the file system.
    * - ``pnm:bigendian``
      - int
-     - If nonzero, the PNM file is big-endian (the default is little-endian).  
+     - If nonzero, the PNM file is big-endian (the default is little-endian).
    * - ``pnm:pfmflip``
      - int
      - If this configuration hint is present and is zero, the automatic
@@ -2218,25 +2239,25 @@ options are supported:
    * - ``raw:use_camera_wb``
      - int
      - If 1, use libraw's camera white balance adjustment. Takes precedence
-       over ``raw:use_auto_wb``, ``raw:greybox``, ``raw:user_mul``. 
+       over ``raw:use_auto_wb``, ``raw:greybox``, ``raw:user_mul``.
        (Default: 1)
    * - ``raw:use_auto_wb``
      - int
      - If 1, white balance automatically by averaging over the entire image.
-       Only applies if ``raw:use_camera_wb`` is not equal to 0. Takes 
+       Only applies if ``raw:use_camera_wb`` is not equal to 0. Takes
        precedence over ``raw:greybox``, ``raw:user_mul``.
        (Default: 0)
    * - ``raw:greybox``
      - int[4]
-     - White balance by averaging over the given box. The four values are the 
+     - White balance by averaging over the given box. The four values are the
        X and Y coordinate of the top-left corner, the width and the height.
-       Only applies if the size is non-zero, and ``raw:use_camera_wb`` is not 
-       equal to 0, ``raw:use_auto_wb`` is not equal to 0. Takes 
+       Only applies if the size is non-zero, and ``raw:use_camera_wb`` is not
+       equal to 0, ``raw:use_auto_wb`` is not equal to 0. Takes
        precedence over ``raw:user_mul``.
        (Default: 0, 0, 0, 0; meaning no correction.)
    * - ``raw:cropbox``
      - int[4]
-     - If present, sets the box to crop the image to. The four values are the 
+     - If present, sets the box to crop the image to. The four values are the
        X and Y coordinate of the top-left corner, the width and the height.
        If not present, the image is cropped to match the in-camera JPEG,
        assuming the necessary information is present in the metadata. The
@@ -2270,7 +2291,7 @@ options are supported:
    * - ``raw:user_mul``
      - float[4]
      - Sets user white balance coefficients. Only applies if ``raw:use_camera_wb``
-       is not equal to 0, ``raw:use_auto_wb`` is not equal to 0, and the 
+       is not equal to 0, ``raw:use_auto_wb`` is not equal to 0, and the
        ``raw:greybox`` box is zero size.
    * - ``raw:ColorSpace``
      - string
@@ -2315,7 +2336,7 @@ options are supported:
        (Default: 2.2222222222222223 (1.0/0.45))
    * - ``raw:user_flip``
      - int
-     - Set libraw user flip value : -1 ignored, other values are between [0; 8] with the same 
+     - Set libraw user flip value : -1 ignored, other values are between [0; 8] with the same
        definition than the Exif orientation code.
    * - ``raw:threshold``
      - float
@@ -2352,7 +2373,7 @@ options are supported:
        (Default: -1)
    * - ``raw:thumbnail_sort``
      - int
-     - Controls the sort order of the list the thumbnail gets picked from. 
+     - Controls the sort order of the list the thumbnail gets picked from.
        -1 - sort small-to-large, 0 - don't sort, use the original file order,
        1 - sort large-to-small.
        (Default: 0)
@@ -3271,4 +3292,3 @@ of the z-buffer. Zfile files use the file extension :file:`.zfile`.
    * - ``worldtoscreen``
      - matrix
      - Nl
-