[gimp] devel-docs: update the XCF docs.

[Jehan <jehanp src gnome org>]

commit 672b77dedb17415496d6181d1cd18488a9dd9af7
Author: Jehan <jehan girinstud io>
Date:   Thu Oct 31 16:49:53 2019 +0100

    devel-docs: update the XCF docs.
    
    Various texts were still assuming 8-bit per component.

 devel-docs/xcf.txt | 71 +++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 46 insertions(+), 25 deletions(-)
---
diff --git a/devel-docs/xcf.txt b/devel-docs/xcf.txt
index 623d5d3854..6877019683 100644
--- a/devel-docs/xcf.txt
+++ b/devel-docs/xcf.txt
@@ -248,32 +248,44 @@ Color
 
 RGB:
 Three intensity values for red, green, and blue additive color
-components, each on a scale from 0 to 255. The exact color space
-is not specified. GIMP displays image data directly on PC
-display hardware without any software correction, so in most
-cases the intensity values should be considered nonlinear samples
-that map to physical light intensities using a power function
-with an exponent ("gamma") of about 2.5. (This is how PC hardware
+components. The exact format depends on the field 'precision' of the
+image header. If this field is absent (i.e. for XCF version 3 or
+before), "8-bit gamma integer" is assumed, which means each component is
+on a scale from 0 to 255, with the intensity values considered nonlinear
+samples that map to physical light intensities using a power function
+with an exponent ("gamma") of about 2.5 (this is how PC hardware
 commonly treat bit values in the video buffer, which incidentally
 also has the property of making each 1/255th step about equally
 perceptible to the human eye when the monitor is correctly
 adjusted).
-Beware, however, that GIMP's compositing algorithms (as described
-in the document compositing.txt) implicitly treat the intensities
-as _linear_ samples. The XCF file format currently has no support
-for storing the intended gamma of the samples.
-
-TODO: Are the statements about color space, gamma and layer modes still valid?
+When the precision field is present though, it defines the storage
+format and the exact color space depends on the color profile attached
+to the image. The color profile is saved as a parasite named
+"icc-profile" on the image. If no profile is set, sRGB is assumed.
+
+Beware, however, that **before GIMP 2.10**, GIMP's compositing
+algorithms (as described in the document compositing.txt) implicitly
+treated the intensities as _linear_ samples. The XCF file format had no
+support for storing the intended gamma of the samples.
+Since GIMP 2.10.0 and over, you must rely on PROP_COMPOSITE_MODE,
+PROP_COMPOSITE_SPACE and PROP_BLEND_SPACE for compositing and blending.
 
 Grayscale:
-One intensity value on a scale from 0 (black) to 255 (white).
-Gamma considerations as for RGB.
+One intensity value. Grayscale has the same precision considerations as
+for RGB and it can also have a profile since GIMP 2.10.0, as well as
+compositing and blending rules.
+
+On older XCF without precision field, the value was simply on a scale
+from 0 (black) to 255 (white).
 
 Indexed:
 An 8-bit index into a color map that is shared between all
 layers. The color map maps each index to an RGB triple which is
 interpreted as in the RGB model.
 
+It is to be noted that Indexed image in GIMP is limited to 8-bit integer
+RGB, even in GIMP 2.10.
+
 
 Pixel data: Tiles
 -----------------
@@ -1444,13 +1456,19 @@ It appears in a context: each layer and channel has a pointer to its hierarchy.
 
   uint32      width   Width of the pixel array
   uint32      height  Height of the pixel array
-  uint32      bpp     Number of bytes per pixel given
-                        3: RGB color without alpha
-                        4: RGB color with alpha
-                        1: Grayscale without alpha
-                        2: Grayscale with alpha
-                        1: Indexed without alpha
-                        2: Indexed with alpha
+  uint32      bpp     Number of bytes per pixel; this depends on the
+                      color mode and image precision (fields 'base_type'
+                      and 'precision' of the image header). For
+                      instance, some combination values:
+                        3: RGB color without alpha in 8-bit precision
+                        4: RGB color with alpha in 8-bit precision
+                        6: RGB color without alpha in 16-bit precision
+                        16: RGB color with alpha in 32-bit precision
+                        1: Grayscale without alpha in 8-bit precision
+                        4: Grayscale with alpha in 16-bit precision
+                        1: Indexed without alpha (always 8-bit)
+                        2: Indexed with alpha (always 8-bit)
+                      And so on.
 
   pointer     lptr    Pointer to the "level" structure
   ,--------   ------  Repeat zero or more times
@@ -1501,10 +1519,13 @@ of width*height pixels, extracted from the tile in row-major,
 top-to-bottom, left-to-right order (the same as the reading direction
 of multi-line English text).
 
-In color modes with alpha information, the alpha value is the last of
-the 2 or 4 bytes for each pixel. In RGB color modes, the 3 (first)
-bytes for each pixel is the red intensity, the green intensity, and
-the blue intensity, in that order.
+In color modes with alpha information, the alpha value is the last bytes
+for each pixels, after the color information.
+In RGB color modes, the color information (first bytes for each pixel)
+is the red intensity, the green intensity, and the blue intensity, in
+that order.
+The exact size of each component depends on the 'precision' field, for
+instance 1 byte in 8-bit modes, 2 bytes in 16-bit, and so on.
 
 Tile data, as other data in XCF format, is big-endian. In particular it
 means that pixel values are stored as big-endian when the precision is