summaryrefslogtreecommitdiffstats
path: root/devel-docs/xcf.txt
diff options
context:
space:
mode:
Diffstat (limited to 'devel-docs/xcf.txt')
-rw-r--r--devel-docs/xcf.txt1607
1 files changed, 1607 insertions, 0 deletions
diff --git a/devel-docs/xcf.txt b/devel-docs/xcf.txt
new file mode 100644
index 0000000..945c30c
--- /dev/null
+++ b/devel-docs/xcf.txt
@@ -0,0 +1,1607 @@
+====================================
+DOCUMENTATION OF THE XCF FILE FORMAT
+====================================
+
+Introduction
+------------
+
+This document describes the native image file format of GIMP.
+
+Note that the XCF format is a "living" format which follows closely the
+GIMP software and evolves together. The ultimate reference for the
+format is therefore its code, even though we will try to update this
+documentation regularly, to make life simpler to ourselves as well as
+third-party XCF-reader's developers.
+
+The code for reading and writing XCF is found in: app/xcf/
+
+
+License
+-------
+
+Copyright Henning Makholm <henning@makholm.net>, 2006-07-11
+Copyright various GIMP developers (see git log), 2009-2019
+
+This is free documentation; you can modify and/or redistribute
+it according to the terms of the GNU General Public License
+as published by the Free Software Foundation, either version
+2 of the license, or (at your option) any later version.
+
+
+Table of contents
+-----------------
+
+Documentation of the XCF file format
+ License
+ Table of contents
+ Audience
+ Scope
+ Status
+ Version history
+
+1. Basic concepts
+ XCF file
+ Basic data types
+ Canvas
+ Color
+ Pixel data: Tiles
+ Pixel data: Levels of detail hierarchy
+ Channels
+ Layers
+ Layer masks
+ Properties
+ Parasites
+ Selections
+ Floating selection
+ Tattoos
+
+2. General properties
+
+3. The Image structure
+ Header
+ Image properties
+
+4. The Channel structure
+ Channel properties
+
+5. The Layer structure
+ Layer properties
+
+6. The Hierarchy structure
+ Levels
+
+7. Tile data organization
+ Uncompressed tile data
+ RLE compressed tile data
+
+8. Miscellaneous
+ The name XCF
+
+
+Audience
+--------
+
+Audience of this document are developers of GIMP and other software that
+reads and writes XCF files.
+
+
+Scope
+-----
+
+The XCF format is designed to store the whole state of GIMP that is specific to
+one image (i.e., not the cut buffer, tool options, key bindings, etc.) and
+is not undo data. This makes the full collection of data stored in an XCF file
+rather heterogeneous and tied to the internals of GIMP.
+
+Use of the XCF format by third-party software is recommended only as a
+way to get data into and out of GIMP for which it would be impossible or
+inconvenient to use a more standard interchange format. Authors of
+third-party XCF-creating software in particular should take care to
+write files that are as indistinguishable as possible from ones saved by
+GIMP. The GIMP developers take care to make each version of GIMP able to
+read XCF files produced by older GIMP versions, but they make no special
+efforts to allow reading of XCF files created by other software.
+
+Interchanging image data with other applications is not the goal of the
+XCF format. Other formats may be more appropriate. For this use case
+GIMP opens and exports common images formats, like JPEG, PNG and PSD,
+though they may all miss various features of XCF.
+OpenRaster (ORA) in particular is meant to be a generic interchange
+format between software, with as few feature loss as possible, though
+its standardization is still quite slow.
+
+For the stated reasons and clarification GIMP _saves_ XCF files,
+but _exports_ to other image formats.
+
+Beware that CinePaint's native file format is called XCF, too. While it is
+derived from the format described here, both formats differ in many details
+and are _not_ mutually compatible.
+This document does not describe the CinePaint XCF format.
+For more information on that see:
+https://web.archive.org/web/20161024115140/http://www.cinepaint.org/more/docs/xcf.html
+
+
+Status
+------
+
+This specification is an official condensation and extrapolation of
+the XCF-writing and -reading code in version 2.10.14 of GIMP, and
+earlier versions. Yet we remind that the ultimate reference is the
+loading and saving code of the XCF format.
+
+Some of the normative statements made below are enforced by the XCF
+code in GIMP; others are just the authors' informed guess about
+"best practices" that would be likely to maximize interoperability
+with future versions of GIMP.
+
+This document is complete, relatively to GIMP 2.10 features stored in
+the XCF format, though if you discover any errors or missing features,
+we would be thankful if you could report it as a bug:
+https://gitlab.gnome.org/GNOME/gimp/issues
+
+
+Version history
+---------------
+This section lists the changes between file format versions in bigger terms.
+Details are denoted in the text.
+
+Version 0:
+Since GIMP 0.99.16, released on 1997-12-15.
+The initial file format. Everything that is not listed in the following versions
+is part of this.
+
+Version 1:
+Since GIMP 0.99.16, released on 1997-12-15.
+Adds color maps. Chapter 3 "The image structure" describes the PROP_COLOR_MAP
+property.
+
+Version 2:
+Since GIMP 1.3.10, released on 2002-11-07.
+Adds layer modes "Soft light", "Grain extract", "Grain merge" and painting
+mode "Color Erase". In chapter 5 "The layer structure" the description of
+the property PROP_MODE contains the new layer modes.
+Improves path handling in GIMP 1.3.21, released on 5.10.2003.
+Chapter 1 "Basic concepts" describes the path handling in general and
+chapter 2 "General concepts" introduces the PROP_VECTORS property.
+
+Version 3:
+Since GIMP 2.7.1, released on 2010-06-29.
+Adds layer groups. The chapter 5 "The layer structure" describes the new
+properties PROP_GROUP_ITEM, PROP_GROUP_ITEM_FLAGS and PROP_ITEM_PATH.
+
+Version 4 to 13:
+Since GIMP 2.10.0, released on 2018-04-27.
+Adds many layer modes, layer group masks, high-bit depth (precisions
+other than 8-bit gamma), zlib compression and 64-bit offsets for XCF
+files bigger than 4GB.
+
+
+1. BASIC CONCEPTS
+=================
+
+It is recommended that a software developer who wants to take full
+advantage of the XCF format be deeply familiar with GIMP at least
+as a user. The following high-level overview is meant to help those
+non-users who just need to extract pixel data from an XCF file get up
+to speed.
+
+
+XCF file
+--------
+
+An XCF file is a sequence of bytes. In general an XCF file describes a stack of
+layers and channels on a canvas.
+It contains a series of data structures, the order of which is in general not
+significant. The exception to this is that the main image structure must come at
+the very beginning of the file, and that the tile data blocks for each drawable
+must follow each other directly.
+
+References _between_ structures in the XCF file take the form of
+"pointers" that count the number of bytes between the beginning
+of the XCF file and the beginning of the target structure.
+Pointers used to be 32-bit data. Since the maximum address of a layer,
+channel, hierarchy or tile set was 2^32 - 1, i.e. at 4 GB, the maximum
+size for XCF images before GIMP 2.10.0 was quite limited.
+Now pointers can be 64-bit, allowing files big enough for any image
+produced by current technology. See the chapter "Basic data types" for
+description of the POINTER type.
+
+Each structure is designed to be written and read sequentially; many
+contain items of variable length and the concept of an offset _within_
+a data structure is not often relevant.
+
+
+Basic data types
+----------------
+
+A WORD is a 32-bit integer stored as 4 bytes in big-endian order, i.e. with
+the most significant byte first. The word is not necessarily aligned to an
+offset within the XCF file that is a multiple of 4.
+Depending on the context the word can be unsigned or (2's complement) signed.
+UINT32 denotes unsigned words and INT32 denotes signed words in this document.
+
+A FLOAT is stored as a 32-bit IEEE 754 single-precision floating-point number
+in big-endian order.
+
+A STRING is stored as follows:
+
+ uint32 n+1 Number of bytes that follow, including the zero byte
+ byte[n] ... String data in Unicode, encoded using UTF-8
+ byte 0 Zero marks the end of the string.
+
+Exception: the empty string is stored simply as an uint32 with the
+value 0.
+
+A POINTER is stored as a 32-bit integer (4 bytes) in big-endian order
+for XCF up to 10, and 64-bit (8 bytes), still big-endian, for XCF 11
+and over, allowing higher than 4GB XCF files since GIMP 2.10.0.
+
+Canvas
+------
+
+A canvas is an abstract rectangular viewport for the layers and channels.
+The image header stores the canvas' dimensions.
+
+
+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
+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?
+
+Grayscale:
+One intensity value on a scale from 0 (black) to 255 (white).
+Gamma considerations as for RGB.
+
+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.
+
+
+Pixel data: Tiles
+-----------------
+
+Basically pixels are organized in a grid of "tiles", each
+with a width and height of up to 64 pixels. The only tiles that have a
+width less than 64 are those in the rightmost column, and the only
+tiles that have a height less than 64 are those in the bottommost row.
+Thus, a layer measuring 200 x 150 pixels will be divided into 12
+tiles:
+
+ +-----------------+-----------------+------------------+-----------------+
+ | Tile 0: 64 x 64 | Tile 1: 64 x 64 | Tile 2: 64 x 64 | Tile 3: 8 x 64 |
+ +-----------------+-----------------+------------------+-----------------+
+ | Tile 4: 64 x 64 | Tile 5: 64 x 64 | Tile 6: 64 x 64 | Tile 7: 8 x 64 |
+ +-----------------+-----------------+------------------+-----------------+
+ | Tile 8: 64 x 22 | Tile 9: 64 x 22 | Tile 10: 64 x 22 | Tile 11: 8 x 22 |
+ +-----------------+-----------------+------------------+-----------------+
+
+As can be seen from this example, the tiles appear in the XCF file in
+row-major, top-to-bottom, left-to-right order. The dimensions of the
+individual tiles are not stored explicitly in the XCF file, but must
+be computed by the reader.
+
+The tiles that are pointed to by a single level structure must be
+contiguous in the XCF file, because GIMP's XCF reader uses the
+difference between two subsequent tile pointers to judge the amount of
+memory it needs to allocate for internal data structures.
+
+
+Pixel data: Levels of detail hierarchy
+--------------------------------------
+
+The tiles themselves are organized in levels of detail. These levels
+build a hierarchy.
+
+Only the first level structure is used by GIMP's XCF reader,
+except that the reader checks that a terminating zero for the
+level-pointer list can be found. GIMP's XCF writer creates a
+series of dummy level structures (with NULL-pointers to the tiles), each
+declaring a height and width half of the previous one (rounded down),
+until the height and with are both less than 64. Thus, for a layer of
+200 x 150 pixels, this series of levels will be saved:
+
+ A level of 200 x 150 pixels with 12 tiles: the actually used one
+ A level of 100 x 75 pixels with no tiles
+ A level of 50 x 37 pixels with no tiles
+
+Third-party XCF writers should probably mimic this entire structure;
+robust XCF readers should have no reason to even read past the pointer
+to the first level structure.
+
+TODO: The XCF file holds (for unclear historical reasons)
+a level-of-detail hierarchy, but we only use the
+lowest hierarchy level of it and other XCF consumers
+are told to do the same. This looks like a mipmap. Would
+using it to save an image pyramid or the thumbnail
+for the File dialogs get us some benefits?
+
+
+Channel
+-------
+
+A channel is a named object that contains a single byte of information
+for each pixel in the canvas area. Channels have a variety of use as
+intermediate objects during editing; they are not meant to be rendered
+directly when the final image is displayed or exported to layer-less
+formats. A major use of channels is as a store for saved selections.
+
+A channel can be edited as if it was a grayscale layer with the same
+dimensions as the canvas. When it is shown in the GIMP editor UI
+together with other layers, it is used as if it was the _inverse_
+alpha channel of a layer with the same color information in all
+pixels; this color can be stored in the XCF file as a property of the
+channel. This "mask" representation is generally thought of as an UI
+feature rather than an intrinsic semantics of a channel.
+
+Though the channel data structure in the XCF file contains a height
+and width field, these must always be the same as the canvas width and
+height.
+TODO: does this apply to any channel or only to selections?
+
+
+Layer
+-----
+
+A layer is a named rectangular area of pixels which has a definite
+position with respect to the canvas. It may extend beyond the canvas or
+(more commonly) only cover some of it. Each pixel of the layer has a color
+which is specified in one of three ways as described in the "Color" section.
+
+All layers in an image must use the same color model.
+Exception: if the "floating selection" (see below) belongs to a channel or
+layer mask, it will be represented as grayscale pixels with alpha independently
+of the image's overall color model.
+
+Each pixel of a layer also has an alpha component which specifies the
+opacity of the pixel on a linear scale from 0 (denoting an alpha of
+0.0, or completely transparent) to 255 (denoting an alpha of 1.0, or
+completely opaque). The color values do not use "premultiplied alpha"
+storage. The color information for pixels with alpha 0 _may_ be
+meaningful; GIMP preserves it when parts of a layer are erased and
+provides (obscure) ways of recovering it in its user interface.
+
+The bottommost layer _only_ in an image may not contain alpha
+information; in this case all pixels in the layer have an alpha value
+of 255. (Even if the bottommost layer does not cover the entire
+canvas, it is the only layer that can be without an explicit alpha
+channel).
+
+In images that use the indexed color model, GIMP does not support
+partial transparency and interprets alpha values from 0 to 127 as
+fully transparent and values from 128 to 255 as fully opaque. This
+behavior _may_ change in future versions of GIMP.
+TODO: has already changed?
+
+Layers have certain other properties such as a visibility flag,
+a global opacity (which is multiplied with individual pixel alphas)
+a layer group flag and various editing state flags.
+
+
+Layer mask
+----------
+
+The layer mask can be attached to a layer (since GIMP 2.10.0, layer
+group can also have a layer mask).
+Actually it is represented as a channel structure in the XCF file.
+It is referred to from its parent layer and not listed in the master list
+of channels.
+Its dimensions and placement coincide with those of its parent layer.
+
+Unless disabled by the PROP_APPLY_MASK property, the layer mask
+functions as an extra alpha channel for the layer, in that for each
+pixel the layer's alpha byte and the layer mask byte are multiplied to
+find the extent to which the layer blankets the background. Thus a
+layer mask can make parts of the layer more transparent, but never
+more opaque.
+
+
+Properties
+----------
+
+Properties are an extension mechanism to attribute the image, channels
+and layers. Some are attributes for general use, such as PROP_END,
+others are specific to the image, a channel or a layer.
+
+Technically properties are implemented as variable-length series of
+variable-length PROPERTY records which have the following general format
+
+ uint32 type Numerical type identifier
+ uint32 plength Payload length in bytes (but BEWARE! see below)
+ byte[n] ... Payload - interpretation depends on the type
+
+The authoritative source for property type numbers is the file
+app/xcf/xcf-private.h in the GIMP sources. Only GIMP itself should define
+new property types.
+
+The number of properties in a property list is not stored explicitly;
+the last property in the list is identified by having type 0; it must
+have length 0.
+
+XCF readers must skip and ignore property records of unrecognized
+type, and the length word is there to support such skipping. However,
+GIMP's own XCF reader will _ignore_ the length word of most
+properties that it _does_ recognize, and instead reads the amount of
+payload it knows this property to have. This means that a property
+record is not itself extensible: one cannot piggyback extra data onto
+an existing property record by increasing its length. Also, some
+historical versions of GIMP actually stored the wrong length for
+some properties, so there are XCF files with misleading property
+length information in circulation. For maximal compatibility, an XCF
+reader should endeavor to know the native lengths of as many
+properties as possible and fall back to the length word only for truly
+unknown property types.
+
+There is not supposed to be more than one instance of each property in
+a property list, but some versions of GIMP will erroneously emit
+duplicate properties. An XCF reader that meets a duplicated property
+should let the content of the later instance take precedence, except
+for properties that contain lists of subitems, in which the lists
+should generally be concatenated. An XCF writer should never
+deliberately duplicate properties within a single property list.
+
+
+Parasites
+---------
+
+Parasites provide a second level of extensibility.
+A parasite is analogous to a property, but is identified by a string
+rather than a number. This makes a larger namespace available for
+parasites. GIMP plug-ins can access the parasites of an image
+component through the API and can define their own parasite
+names which will be ignored by other plug-ins.
+
+A list of known parasites and their data formats can be found in the
+file devel-doc/parasites.txt of the GIMP source tree.
+
+The PROP_PARASITE property stores the parasites of the image, layers
+and channels and the PROP_VECTORS property those of the paths.
+
+The number of parasites there is not directly encoded; the list ends when
+the total length of the parasite data read equals the property payload length.
+
+GIMP's XCF reader checks that the combined size of all parasites
+in the property precisely equals the length word, so it is safe for
+a reader to use the length word to skip the property without parsing
+the individual parasites.
+
+The parasite content may be binary, but often a textual encoding is
+chosen in order to spare the writing and reading code of having to deal
+with byte ordering.
+
+There can only be one parasite with a given name attached to
+each element of the image. Some versions of GIMP will
+erroneously write some parasites twice in the same property list;
+XCF readers must be prepared to gracefully ignore all but the
+last instance of a parasite name in each property list.
+
+TODO: How shall parasite readers handle lists in duplicate parasites?
+
+Selection
+---------
+
+If the current selection in the editor is nonempty, then GIMP stores it
+as a channel in the XCF file. Pixels with a value of 255 belong to the
+selection; pixels with a value of 0 don't, and pixels with intermediate
+values are partially selected.
+
+
+Floating selection
+------------------
+
+A floating selection is a selection, that is attached to a particular
+layer, channel or layer mask.
+
+Technically it is handled as a layer with alpha.
+
+If a floating selection exists, it must always be the first layer in
+the layer list, but it is not rendered at that position in the layer stack.
+Instead it is logically attached to another layer, or a channel or layer mask,
+and the content of the floating selection is combined with ("anchored to")
+that drawable before it is used to render the visible image.
+
+The floating selection must not have a layer mask of its own, but if
+an ordinary (not floating) selection also exists, it will be used as
+a layer mask for the floating selection.
+
+If a floating selection exists, it must also be the active layer.
+
+Because the floating selection is modal and ephemeral, users rarely
+save XCF files containing a floating selection. It may be acceptable
+for third-party XCF consumers to ignore the floating selection or
+explicitly refuse to process it.
+
+
+Tattoos
+-------
+
+A tattoo is a unique and permanent identifier attached to a drawable or path
+that can be used to uniquely identify it within an image even between sessions.
+
+The tattoo of the image, a layer or channel is stored in the PROP_TATTOO
+property, a tattoo for a path in the PROP_VECTORS property.
+
+The PROP_TATTOO property of the entire image stores a "high-water
+mark" for the entire image; it is greater than OR EQUAL TO any
+tattoo for an element of the image. It allows efficient generation
+of new unused tattoo values and also prevents old tattoo numbers
+from being reused within a single image, lest plug-ins that use
+the tattoos for bookkeeping get confused.
+
+An XCF file must either provide tattoo values for all its elements
+or for none of them. GIMP will invent fresh tattoos when it
+reads in tattoo-less elements, but it does not attempt to keep them
+different from ones specified explicitly in the file.
+TODO: can this cause confusion and hard-to-find errors? If so, fix.
+
+
+Text
+----
+
+GIMP stores text in plain layers with parasites for the text and formatting
+and PROP_TEXT_LAYER_FLAGS for flags.
+
+
+Vector paths
+------------
+
+GIMP stores vector paths as properties of the image.
+If all paths are continuous sequences of Bezier strokes, then GIMP uses
+the PROP_PATHS property, otherwise PROP_VECTORS. PROP_PATHS is for old
+files from GIMP up to version 1.2.
+
+
+2. GENERAL PROPERTIES
+=====================
+
+This chapter describes the formats of the defined property records that
+can appear in more than one context in an XCF file.
+
+PROP_COLOR_TAG (since GIMP 2.10.0, commit 4f9095798d0)
+ uint32 34 Type identification
+ uint32 4 Four bytes of payload
+ uint32 tag Color tag of the layer; one of
+ 0: None
+ 1: Blue
+ 2: Green
+ 3: Yellow
+ 4: Orange
+ 5: Brown
+ 6: Red
+ 7: Violet
+ 8: Gray
+
+ PROP_COLOR_TAG can be assigned to layers, channels and paths. They are
+ only organisational properties and have no consequence on render.
+
+PROP_END
+ uint32 0 Type identification
+ uint32 0 PROP_END has no payload.
+
+ The PROP_END pseudo-property marks the end of any property list.
+
+PROP_FLOAT_OPACITY (essential, since GIMP 2.10.0, commit a2ad257711a)
+ uint32 33 Type identification
+ uint32 4 Four bytes of payload
+ float opacity Opacity on a scale from 0.0 (fully transparent) to
+ 1.0 (fully opaque)
+
+ PROP_FLOAT_OPACITY records the overall opacity setting for the layer
+ or channel. Since GIMP 2.10.0, it always appears in the property list
+ of layers and channels after PROP_OPACITY, which saves the same value,
+ yet with integer precision. This way, new readers can overwrite the
+ 8-bit value with proper precision whereas older readers can simply
+ skip PROP_FLOAT_OPACITY if unknown.
+
+PROP_LINKED (editing state)
+ uint32 9 Type identification
+ uint32 4 Four bytes of payload
+ uint32 linked 1 if the layer is linked; 0 if not
+
+ PROP_LINKED controls the behavior of Transform tools with a layer,
+ channel or path. If a Transform tool is used to transform one of them
+ all other linked elements will be transformed the same way.
+ It appears in the property list for layers, channels and paths.
+
+PROP_LOCK_CONTENT (since version 3, editing state)
+ uint32 28 Type identification
+ uint32 4 Four bytes of payload
+ uint32 locked 1 if the content is locked; 0 if not
+
+ PROP_LOCK_CONTENT specifies whether the layer, channel or path is locked,
+ i.e. cannot be edited.
+
+PROP_LOCK_POSITION (since GIMP 2.10.0, commit d4933b30526, editing state)
+ uint32 32 Type identification
+ uint32 4 Four bytes of payload
+ uint32 locked 1 if the position is locked; 0 if not
+
+ PROP_LOCK_POSITION specifies whether the layer, channel or path's
+ position is locked, i.e. cannot be transformed (translation, etc.).
+
+PROP_OPACITY (essential)
+ uint32 6 Type identification
+ uint32 4 Four bytes of payload
+ uint32 opacity Opacity on a scale from 0 (fully transparent) to
+ 255 (fully opaque)
+
+ PROP_OPACITY records the overall opacity setting for the layer or channel.
+ It appears in the property list of layers and channels.
+
+ Note that though GIMP's user interface displays the opacity as a percentage,
+ it is actually stored on a 0-255 scale. Also note that this opacity value
+ is stored as a 32-bit quantity even though it has been scaled to
+ fit exactly in a single byte.
+
+ When reading old XCF files that lack this property, full opacity
+ should be assumed.
+
+ While this property continues to be stored for compatibility, the new
+ property PROP_FLOAT_OPACITY since GIMP 2.10.0 must override the value
+ of PROP_OPACITY with float precision.
+
+PROP_PARASITES
+ uint32 21 Type identification
+ uint32 plength Total length of the following payload data in bytes
+ ,----------------- Repeat for each parasite:
+ | string name Name of the parasite
+ | uint32 flags Flags of the parasite
+ | uint32 pplength Length of the payload data in bytes
+ | byte[n] ... Parasite-specific payload
+ `--
+
+ PROP_PARASITES stores parasites. It can contain multiple parasite records.
+ See "Basic concepts" and the file parasites.txt for more information about
+ parasites.
+ This property can appear in any property list.
+
+PROP_TATTOO (internal GIMP state)
+ uint32 20 Type identification
+ uint32 4 Four bytes of payload
+ uint32 tattoo Nonzero unsigned integer identifier
+
+ PROP_TATTOO is an unique identifier for the denoted image, channel or layer.
+ It appears in the property list of layers, channels, and the image.
+
+PROP_VISIBLE (essential)
+ uint32 8 Type identification
+ uint32 4 Four bytes of payload
+ uint32 visible 1 if the layer/channel is visible; 0 if not
+
+ PROP_VISIBLE specifies the visibility of a layer or channel.
+ It appears in the property list for layers and channels.
+ For the visibility of a path see the PROP_VECTORS property.
+
+ When reading old XCF files that lack this property, assume that
+ layers are visible and channels are not.
+
+
+3. THE IMAGE STRUCTURE
+======================
+
+Header
+------
+
+The image structure always starts at offset 0 in the XCF file.
+
+ byte[9] "gimp xcf " File type identification
+ byte[4] version XCF version
+ "file": version 0
+ "v001": version 1
+ "v002": version 2
+ "v003": version 3
+ byte 0 Zero marks the end of the version tag.
+ uint32 width Width of canvas
+ uint32 height Height of canvas
+ uint32 base_type Color mode of the image; one of
+ 0: RGB color
+ 1: Grayscale
+ 2: Indexed color
+ (see enum GimpImageBaseType
+ in libgimpbase/gimpbaseenums.h)
+ uint32 precision Image precision; this field is only present for
+ XCF 4 or over (since GIMP 2.10.0). Its value for
+ XCF 7 or over is one of:
+ 100: 8-bit linear integer
+ 150: 8-bit gamma integer
+ 200: 16-bit linear integer
+ 250: 16-bit gamma integer
+ 300: 32-bit linear integer
+ 350: 32-bit gamma integer
+ 500: 16-bit linear floating point
+ 550: 16-bit gamma floating point
+ 600: 32-bit linear floating point
+ 650: 32-bit gamma floating point
+ 700: 64-bit linear floating point
+ 750: 64-bit gamma floating point
+ For XCF 4 (which was a development version, hence
+ this format should not be found often and may be
+ ignored by readers), its value may be one of:
+ 0: 8-bit gamma integer
+ 1: 16-bit gamma integer
+ 2: 32-bit linear integer
+ 3: 16-bit linear floating point
+ 4: 32-bit linear floating point
+ For XCF 5 or 6 (which were development versions,
+ hence these formats may be ignored by readers),
+ its value may be one of:
+ 100: 8-bit linear integer
+ 150: 8-bit gamma integer
+ 200: 16-bit linear integer
+ 250: 16-bit gamma integer
+ 300: 32-bit linear integer
+ 350: 32-bit gamma integer
+ 400: 16-bit linear floating point
+ 450: 16-bit gamma floating point
+ 500: 32-bit linear floating point
+ 550: 32-bit gamma floating point
+ NOTE: XCF 3 or older's precision was always
+ "8-bit gamma integer".
+ property-list Image properties
+ ,----------------- Repeat once for each layer, topmost layer first:
+ | pointer lptr Pointer to the layer structure.
+ `--
+ pointer 0 Zero marks the end of the array of layer pointers.
+ ,------------------ Repeat once for each channel, in no particular order:
+ | pointer cptr Pointer to the channel structure.
+ `--
+ pointer 0 Zero marks the end of the array of channel pointers.
+
+The last 4 characters of the initial 13-character identification string are
+a version indicator. The version will be higher than 3 if the correct
+reconstruction of pixel data from the file requires that the reader
+understands features not described in this specification. On the other
+hand, optional extra information that can be safely ignored will not
+cause the version to increase.
+
+GIMP's XCF writer dynamically selects the lowest version that will
+allow the image to be represented. Third-party XCF writers should do
+likewise.
+
+Version numbers from v100 upwards have been used by CinePaint, which
+originated as a 16-bit fork of GIMP, see "Scope".
+
+
+Image properties
+----------------
+
+The following properties are found only in the property list of the
+image structure. Additionally the list can also contain the properties
+PROP_END, PROP_PARASITES and PROP_TATTOO, defined in chapter 2.
+
+PROP_COLORMAP (essential)
+ uint32 1 Type identification
+ uint32 3*n+4 Payload length in bytes
+ uint32 n Number of colors in the color map (should be <256)
+ ,------------ Repeat n times:
+ | byte r Red component of a color map color
+ | byte g Green component of a color map color
+ | byte b Blue component of a color map color
+ `--
+
+ PROP_COLORMAP stores the color map.
+ It appears in all indexed images.
+
+ The property will be ignored if it is encountered in an RGB or grayscale
+ image. The current GIMP will not write a color map with RGB or
+ grayscale images, but some older ones occasionally did, and readers
+ should be prepared to gracefully ignore it in those cases.
+
+ Note that in contrast to the palette data model of, for example, the
+ PNG format, an XCF color map does not contain alpha components, and
+ there is no color map entry for "transparent"; the alpha channel of
+ layers that have one is always represented separately.
+
+ The structure here is that of since XCF version 1. Comments in the
+ GIMP source code indicate that XCF version 0 could not store indexed
+ images in a sane way; contemporary GIMP versions will complain and
+ reinterpret the pixel data as a grayscale image if they meet a
+ version-0 indexed image.
+
+ Beware that the payload length of the PROP_COLORMAP in particular
+ cannot be trusted: some historic releases of GIMP erroneously
+ wrote n+4 instead of 3*n+4 into the length word (but still actually
+ followed it by 3*n+4 bytes of payload).
+
+PROP_COMPRESSION (essential)
+ uint32 17 Type identification
+ uint32 1 One byte of payload
+ byte comp Compression indicator; one of
+ 0: No compression
+ 1: RLE encoding
+ 2: zlib compression
+ 3: (Never used, but reserved for some fractal compression)
+
+ PROP_COMPRESSION defines the encoding of pixels in tile data blocks in the
+ entire XCF file. See chapter 7 for details.
+
+ Note that unlike most other properties whose payload is always a
+ small integer, PROP_COMPRESSION does _not_ pad the value to a full
+ 32-bit integer.
+
+ Contemporary GIMP versions always write files with comp=1. It is unknown to
+ the author of this document whether versions that wrote completely
+ uncompressed (comp=0) files ever existed.
+
+PROP_GUIDES (editing state)
+ uint32 18 Type identification
+ uint32 5*n Five bytes of payload per guide
+ ,--------------- Repeat n times:
+ | int32 coord Guide coordinate
+ | byte o Guide orientation; one of
+ | 1: The guide is horizontal, and coord is a y coordinate
+ | 2: The guide is vertical, and coord is an x coordinate
+ (see enum XcfOrientationType in /app/xcf/xcf-private.h)
+ `--
+
+ PROP_GUIDES stores the horizontal or vertical positions of guides.
+ It appears if any guides have been defined.
+
+ Some old XCF files define guides with negative coordinates; those
+ should be ignored by readers.
+
+PROP_PATHS
+ uint32 23 Type identification
+ uint32 plength Total length of the following payload in bytes
+ uint32 aindex Index of the active path
+ uint32 n Number of paths that follow
+ path_1
+ path_2
+ ...
+ path_n
+
+ PROP_PATHS stores the paths.
+
+ Each path has one of three formats
+
+ Format 1: Format 2: Format 3:
+ string string string name Name of the path
+ uint32 uint32 uint32 linked 1 if the path is linked;
+ 0 if not
+ byte byte byte state 4 if closed; 2 otherwise
+ (for GIMP 1.2 compatibility)
+ uint32 uint32 uint32 closed 1 if path is closed;
+ 0 otherwise
+ uint32 uint32 uint32 np Number of points
+ uint32=1 uint32=2 uint32=3 version Version indicator
+ uint32 uint32 dummy Ignored; always set to 1
+ uint32 tattoo 0 if none, or see PROP_TATTOO
+ ,---------- ,---------- ,------------------ Repeat for np points:
+ | int32 | int32 | int32 type Type of point; one of
+ | | | 0: Anchor
+ | | | 1: Bezier control point
+ | | | (for GIMP 1.2 compatibility)
+ | int32 | float | float x X coordinate
+ | int32 | float | float y Y coordinate
+ `-- `-- `--
+
+ This format is used to save path data if all paths in the image are
+ continuous sequences of Bezier strokes. Otherwise GIMP stores the paths in
+ PROP_VECTORS.
+
+ Note: the attribute 'linked' was formerly erroneously called 'locked'
+ (but meant 'linked' anyway).
+
+ A closed path is a path which has the last and the first point connected,
+ for instance a triangle.
+
+ GIMP's XCF reader _does not_ check that the total size of all path
+ specifications in the property precisely equals the plength word.
+ Note that this is different to PROP_VECTORS.
+
+ TODO: Clarify: PROP_PATHS cannot represent parasites for paths, but the
+ XCF writer does not check whether all paths are parasite-less when
+ choosing which property to use, so path parasites may be lost upon
+ saving). Is this by design or a bug?
+
+ There may be paths that declare a length of 0 points; these should
+ be ignored.
+
+PROP_RESOLUTION (not editing state, but not _really_ essential either)
+ uint32 19 Type identification
+ uint32 8 Eight bytes of payload
+ float hres Horizontal resolution in pixels per inch (ppi)
+ float vres Vertical resolution in pixels per inch (ppi)
+
+ PROP_RESOLUTION gives the intended physical size of the image's pixels.
+
+ Note that for many images, such as graphics created for the web, the
+ creator does not really have an intended resolution in mind but
+ intends the image to be shown at whatever the natural resolution of
+ the viewer's monitor is. Similarly, photographs commonly do not have
+ a well-defined target size and are intended to be scaled to fit the
+ available space instead. Therefore readers should not interpret the
+ information in this property too rigidly; GIMP writes it to XCF
+ files unconditionally, even if the user has not explicitly chosen a
+ resolution.
+
+PROP_SAMPLE_POINTS
+ uint32 17 Type identification
+ uint32 plength Total length of the following payload in bytes
+ ,---------------- Repeat for each sample point:
+ | uint32 x X coordinate
+ | uint32 y Y coordinate
+ `--
+
+PROP_UNIT (editing state)
+ uint32 22 Type identification
+ uint32 4 Four bytes of payload
+ uint32 uid Unit identifier; one of
+ 1: Inches (25.4 mm)
+ 2: Millimeters (1 mm)
+ 3: Points (127/360 mm)
+ 4: Picas (127/30 mm)
+
+ PROP_UNIT specifies the units used to specify resolution in the Scale Image
+ and Print Size dialogs. Note that this is used only in the user interface;
+ the PROP_RESOLUTION property is always stored in ppi.
+
+ To specify non-standard units use PROP_USER_UNIT.
+
+PROP_USER_UNIT (editing state)
+ uint32 24 Type identification
+ uint32 plength Total length of the following payload in bytes
+ float factor 1 inch divided by the length of the unit
+ uint32 digits Number of decimal digits used with the unit
+ string id An identifier for the unit
+ string symbol Short symbol for the unit
+ string abbrev Abbreviation for the unit
+ string sname Unit name in singular form
+ string pname Unit name in plural form
+
+ PROP_USER_UNIT allows the use of units that are not on the standard list.
+ It is an alternative to PROP_UNIT.
+ TODO: How is this related to the unitrc file?
+
+PROP_VECTORS
+ uint32 25 Type identification
+ uint32 plength Total length of the following payload in bytes
+ uint32 1 Version tag; so far always 1
+ uint32 aindex Index of the active path
+ uint32 n Number of paths that follow
+ ,---------------------- Repeat n times:
+ | string name Name of the path
+ | uint32 tattoo Tattoo of the path (see PROP_TATTOO), or 0
+ | uint32 visible 1 if path is visible, 0 if not
+ | uint32 linked 1 if path is linked, 0 if not
+ | uint32 m Number of parasites for the path
+ | uint32 k Number of strokes in the first path
+ | ,-------------------- Repeat m times:
+ | | parasite ... In same format as in PROP_PARASITES.
+ | `--
+ | ,-------------------- Repeat k times:
+ | | uint32 1 The stroke is a Bezier stroke
+ | | uint32 closed 1 if path is closed; 0 otherwise
+ | | uint32 nf Number of floats given for each point;
+ | | must be >= 2 and <= 6.
+ | | uint32 np Number of control points for this stroke
+ | | ,------------------ Repeat np times:
+ | | | uint32 type Type of the first point; one of
+ | | | 0: Anchor
+ | | | 1: Bezier control point
+ | | | float x X coordinate
+ | | | float y Y coordinate
+ | | | float pressure Only if nf >= 3; otherwise defaults to 1.0
+ | | | float xtilt Only if nf >= 4; otherwise defaults to 0.5
+ | | | float ytilt Only if nf >= 5; otherwise defaults to 0.5
+ | | | float wheel Only if nf == 6; otherwise defaults to 0.5
+ | | `--
+ | `--
+ `--
+
+ PROP_VECTORS stores the paths.
+
+ It appears if all paths are continuous sequences of Bezier strokes;
+ otherwise PROP_PATHS is used.
+
+ GIMP's XCF reader checks that the total size of all path
+ specifications in the property precisely equals the plength word, so
+ it is safe for a reader to use the plength word to skip the property
+ without parsing the individual parasites. (Note that this is _not_
+ the case for PROP_PATHS).
+
+
+4. THE CHANNEL STRUCTURE
+========================
+
+Channel structures are pointed to from layer structures (in case of
+layer masks) or from the master image structure (for all other
+channels).
+
+ uint32 width Width of the channel
+ uint32 height Height of the channel
+ string name Name of the channel
+ property-list Channel properties
+ pointer hptr Pointer to the hierarchy structure with the pixels.
+
+The width and height of the channel must be the same as those of its
+parent structure (the layer in the case of layer masks; the canvas for
+all other channels).
+
+
+Channel properties
+------------------
+
+The following properties are found only in the property list of
+channel structures. Additionally the list can also contain the
+properties: PROP_COLOR_TAG, PROP_END, PROP_FLOAT_OPACITY, PROP_LINKED,
+PROP_LOCK_CONTENT, PROP_LOCK_POSITION, PROP_OPACITY, PROP_PARASITES,
+PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.
+
+PROP_ACTIVE_CHANNEL (editing state)
+ uint32 3 Type identification
+ uint32 0 PROP_ACTIVE_CHANNEL has no payload
+
+ The presence of PROP_ACTIVE_CHANNEL indicates that the channel is the
+ currently active channel.
+ It appears in the property list of the currently active channel.
+ Only zero or one channel must have this property at any time.
+
+PROP_COLOR
+ uint32 16 Type identification
+ uint32 3 Three bytes of payload
+ byte r Red component of color
+ byte g Green component of color
+ byte b Blue component of color
+
+ PROP_COLOR gives the color of the screen that is used to represent the channel
+ when it is visible in the UI.
+ (The alpha of the screen is given as the channel's PROP_OPACITY).
+ TODO: What exactly does "screen" mean here?
+
+ While this property continues to be stored for compatibility, the new
+ property PROP_FLOAT_COLOR since GIMP 2.10.0 must override the value
+ of PROP_COLOR with float precision.
+
+PROP_FLOAT_COLOR (since GIMP 2.10.0, essential, commit 10360c9e130)
+ uint32 38 Type identification
+ uint32 12 Twelve bytes of payload
+ float r Red component of color
+ float g Green component of color
+ float b Blue component of color
+
+ PROP_FLOAT_COLOR gives the color of the screen that is used to
+ represent the channel when it is visible in the UI. Each component is
+ in the range 0.0 to 1.0.
+ PROP_FLOAT_COLOR stores the same property as PROP_COLOR with float
+ precision. Since GIMP 2.10.0, it always appears in the property list
+ of channels after PROP_COLOR. This way, new readers can overwrite the
+ 8-bit value with proper precision whereas older readers can simply
+ skip PROP_FLOAT_COLOR if unknown.
+
+PROP_SELECTION (editing state?)
+ uint32 4 Type identification
+ uint32 0 PROP_SELECTION has no payload
+
+ PROP_SELECTION appears in the property list of the channel structure that
+ represents the selection mask.
+
+PROP_SHOW_MASKED (editing state)
+ uint32 14 Type identification
+ uint32 4 Four bytes of payload
+ uint32 masked 1 if the channel is shown as a mask, 0 if not
+
+ PROP_SHOW_MASKED specifies whether a channel is shown as a mask.
+
+
+5. THE LAYER STRUCTURE
+======================
+
+Layer structures are pointed to from a list of layer pointers in the
+master image structure.
+
+ uint32 width Width of the layer
+ uint32 height Height of the layer
+ uint32 type Color mode of the layer: one of
+ 0: RGB color without alpha
+ 1: RGB color with alpha
+ 2: Grayscale without alpha
+ 3: Grayscale with alpha
+ 4: Indexed without alpha
+ 5: Indexed with alpha
+ (see enum GimpImageType in libgimpbase/gimpbaseenums.h)
+ string name Name of the layer
+ property-list Layer properties
+ pointer hptr Pointer to the hierarchy structure with the pixels
+ pointer mptr Pointer to the layer mask (a channel structure), or 0
+
+The color mode of a layer must match that of the entire image.
+All layers except the bottommost one _must_ have an alpha channel. The bottom
+layer _can_ have an alpha channel.
+TODO: Check whether the redundant color mode storage potentially causes errors.
+Wouldn't a alpha bit/flag be sufficient?
+
+Exception: If the layer is a floating selection and is attached to a channel or
+layer mask, then its color mode must be 3 (grayscale with alpha).
+
+
+Layer properties
+----------------
+
+The following properties are found only in the property list of layer
+structures. Additionally the list can also contain the properties:
+PROP_COLOR_TAG, PROP_END, PROP_FLOAT_OPACITY, PROP_LINKED,
+PROP_LOCK_CONTENT, PROP_LOCK_POSITION, PROP_OPACITY, PROP_PARASITES,
+PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.
+
+PROP_ACTIVE_LAYER (editing state)
+ uint32 2 Type identification
+ uint32 0 PROP_ACTIVE_LAYER has no payload
+
+ The presence of PROP_ACTIVE_LAYER indicates that the channel is the
+ currently active layer.
+ Only zero or one layer must have this property at any time.
+
+PROP_APPLY_MASK (essential)
+ uint32 11 Type identification
+ uint32 4 Four bytes of payload
+ uint32 apply 1 if the layer mask should be applied, 0 if not
+
+ PROP_APPLY_MASK specifies whether the layer mask shall be applied
+ to the layer.
+ If the property does not appear for a layer which has a layer mask,
+ it defaults to true.
+
+ Robust readers should force this to false if the layer has no layer
+ mask. Writers should never save this as true unless the layer has a
+ layer mask.
+
+PROP_COMPOSITE_MODE (since GIMP 2.10.0, essential, commit 8634b5cbc31)
+ uint32 35 Type identification
+ uint32 4 Four bytes of payload
+ int32 mode Composite mode of the layer; one of:
+ 1: Union
+ 2: Clip to backdrop
+ 3: Clip to layer
+ 4: Intersection
+ See below for meaning of negative values.
+
+ PROP_COMPOSITE_MODE records the composite mode, for layers only. A
+ negative value means that the composite mode was left to "Auto",
+ rather than explicitly set, while we still store the mapping of "Auto"
+ at the time of saving the XCF, by inverting it. For instance if "mode"
+ is -2, it means that "Auto" was set, which corresponds to "Clip to
+ backdrop" for this specific layer mode.
+ The reason for this is that we must always keep the expected output,
+ even if we were to change the mapping of "Auto" in the future.
+
+ Note: as you may guess, "Auto" maps to different actual composite
+ modes, depending on PROP_MODE. This system makes so you don't have to
+ know this mapping. A XCF reader may just use the absolute value of
+ PROP_COMPOSITE_MODE.
+
+PROP_COMPOSITE_SPACE (since GIMP 2.10.0, essential, commit 8634b5cbc31)
+ uint32 36 Type identification
+ uint32 4 Four bytes of payload
+ int32 space Composite space of the layer; one of:
+ 1: RGB (linear)
+ 2: RGB (perceptual)
+ 3: LAB
+ See below for meaning of negative values.
+
+ PROP_COMPOSITE_SPACE records the composite mode, for layers only. A
+ negative value means that the composite space was left to "Auto",
+ rather than explicitly set, while we still store the mapping of "Auto"
+ at the time of saving the XCF, by inverting it. For instance if "space"
+ is -3, it means that "Auto" was set, which corresponds to "LAB"
+ composite space for this specific layer mode.
+ The reason for this is that we must always keep the expected output,
+ even if we were to change the mapping of "Auto" in the future.
+
+ Note: as you may guess, "Auto" maps to different actual composite
+ spaces, depending on PROP_MODE. This system makes so you don't have to
+ know this mapping. A XCF reader may just use the absolute value of
+ PROP_COMPOSITE_SPACE.
+
+PROP_BLEND_SPACE (since GIMP 2.10.0, essential, commit 8634b5cbc31)
+ uint32 36 Type identification
+ uint32 4 Four bytes of payload
+ int32 space Composite space of the layer; one of:
+ 1: RGB (linear)
+ 2: RGB (perceptual)
+ 3: LAB
+ See below for meaning of negative values.
+
+ PROP_BLEND_SPACE records the blend mode, for layers only. A negative
+ value means that the composite space was left to "Auto", rather than
+ explicitly set, while we still store the mapping of "Auto" at the time
+ of saving the XCF, by inverting it. For instance if "space" is -3, it
+ means that "Auto" was set, which corresponds to "LAB" composite space
+ for this specific layer mode.
+ The reason for this is that we must always keep the expected output,
+ even if we were to change the mapping of "Auto" in the future.
+
+ Note: as you may guess, "Auto" maps to different actual blend spaces,
+ depending on PROP_MODE. This system makes so you don't have to know
+ this mapping. A XCF reader may just use the absolute value of
+ PROP_BLEND_SPACE.
+
+PROP_EDIT_MASK (editing state)
+ uint32 12 Type identification
+ uint32 4 Four bytes of payload
+ uint32 editing 1 if the layer mask is currently being edited, 0 if not
+
+ PROP_EDIT_MASK specifies whether the layer mask is currently being edited.
+ If the property does not appear for a layer which has a layer mask,
+ it defaults to false.
+
+ Robust readers should force this to false if the layer has no layer
+ mask. Writers should never save this as true unless the layer has a
+ layer mask.
+
+PROP_FLOATING_SELECTION (essential)
+ uint32 5 Type identification
+ uint32 4 Four bytes of payload
+ pointer ptr Pointer to the layer or channel the floating selection is
+ attached to
+
+ PROP_FLOATING_SELECTION indicates that the layer is the floating selection
+ and specifies the pointer to the layer, channel and layer mask it is attached
+ to.
+ It appears in the property list for the layer that is the floating selection.
+ Only zero or one layer must have this property at any time.
+
+PROP_GROUP_ITEM (since version 3)
+ uint32 29 Type identification
+ uint32 0 PROP_GROUP_ITEM has no payload
+
+ PROP_GROUP_ITEM indicates that the layer is a layer group.
+ It appears in the property list if the layer is a layer group.
+
+PROP_ITEM_PATH (since version 3)
+ uint32 30 Type identification
+ uint32 plength Total length of the following payload in bytes
+ item-path List of pointers, represented as uint32 values
+
+TODO: The code reads that it is a list of pointers, represented as uint32
+integers and somehow in the context of layers. What this is for and what
+do the property values mean?
+
+PROP_GROUP_ITEM_FLAGS (since version 3)
+ uint32 31 Type identification
+ uint32 4 Four bytes of payload
+ uint32 flags Flags for the layer, or'ed together from the following set:
+ 0x00000001 Layer group is expanded.
+ (see enum XcfGroupItemFlagsType in app/xcf/xcf-private.h)
+
+ PROP_GROUP_ITEM_FLAGS specifies flags for the layer group.
+ It appears in the property list if the layer is a layer group.
+
+PROP_LOCK_ALPHA (editing state)
+(called PROP_PRESERVE_TRANSPARENCY in GIMP before 2.3)
+ uint32 10 Type identification
+ uint32 4 Four bytes of payload
+ uint32 lock_alpha 1 if alpha is locked; 0 if not
+
+ PROP_LOCK_ALPHA prevents all drawing tools in GIMP from increasing the alpha
+ of any pixel in the layer. Decreasing the alpha is possible.
+
+PROP_MODE (essential)
+ uint32 7 Type identification
+ uint32 4 Four bytes of payload
+ unit32 mode Layer mode; one of
+ * Since "ancient times":
+
+ 0: Normal (legacy)
+ 1: Dissolve (legacy) [random dithering to discrete alpha)
+ 2: Behind (legacy) [not selectable in the GIMP UI]
+ 3: Multiply (legacy)
+ 4: Screen (legacy)
+ 5: Old broken Overlay
+ 6: Difference (legacy)
+ 7: Addition (legacy)
+ 8: Subtract (legacy)
+ 9: Darken only (legacy)
+ 10: Lighten only (legacy)
+ 11: Hue (HSV) (legacy)
+ 12: Saturation (HSV) (legacy)
+ 13: Color (HSL) (legacy)
+ 14: Value (HSV) (legacy)
+ 15: Divide (legacy)
+ 16: Dodge (legacy)
+ 17: Burn (legacy)
+ 18: Hard Light (legacy)
+
+ * Since XCF 2 (GIMP 2.8)
+ 19: Soft light (legacy)
+ 20: Grain extract (legacy)
+ 21: Grain merge (legacy)
+ 22: Color erase (legacy)
+
+ * Since XCF 9 (GIMP 2.10.0)
+ 23: Overlay
+ 24: Hue (LCH)
+ 25: Chroma (LCH)
+ 26: Color (LCH)
+ 27: Lightness (LCH)
+
+ * Since XCF 10 (GIMP 2.10.0)
+ 28: Normal
+ 29: Behind
+ 30: Multiply
+ 31: Screen
+ 32: Difference
+ 33: Addition
+ 34: Subtract
+ 35: Darken only
+ 36: Lighten only
+ 37: Hue (HSV)
+ 38: Saturation (HSV)
+ 39: Color (HSL)
+ 40: Value (HSV)
+ 41: Divide
+ 42: Dodge
+ 43: Burn
+ 44: Hard light
+ 45: Soft light
+ 46: Grain extract
+ 47: Grain merge
+ 48: Vivid light
+ 49: Pin light
+ 50: Linear light
+ 51: Hard mix
+ 52: Exclusion
+ 53: Linear burn
+ 54: Luma/Luminance darken only
+ 55: Luma/Luminance lighten only
+ 56: Luminance
+ 57: Color erase
+ 58: Erase
+ 59: Merge
+ 60: Split
+ 61: Pass through
+
+ PROP_MODE specifies the layer mode.
+
+ When reading old XCF files that lack this property, assume mode==0.
+ The effects of the various layer modes are defined in the document
+ compositing.txt.
+
+ Beware that GIMP ignores all other layer modes than Normal and
+ Dissolve for the bottommost visible layer of the image. If a mode>=3 has
+ been specified for this layer it will interpreted as mode==0 (Normal) for
+ display and flattening purposes. This effect happens for one layer
+ only: even if the bottommost visible layer covers only some (or
+ none) of the canvas, it will be the only layer to have its mode
+ forced to Normal.
+
+ Implementation note: all layer modes are implemented as GEGL
+ operations. The list can be found at:
+ app/operations/layer-modes/gimp-layer-modes.c
+ The "op_name" value in particular gives the operation name allowing
+ reader developers to search for this string. For instance, the
+ "Normal" layer mode is implemented as the "gimp:normal" GEGL operation
+ whose implementation can be found at:
+ app/operations/layer-modes/gimpoperationnormal.c
+
+NOTE: The layer modes 'Old broken Overlay' and 'Soft light (legacy)' are identical.
+
+PROP_OFFSETS (essential)
+ uint32 15 Type identification
+ uint32 8 Eight bytes of payload
+ int32 xoffset Horizontal offset
+ int32 yoffset Vertical offset
+
+ PROP_OFFSETS gives the coordinates of the upper left corner of the layer
+ relative to the upper left corner of the canvas.
+ The coordinates can be negative; this corresponds to a layer that
+ extends to the left of or above the canvas boundary.
+
+ When reading old XCF files that lack this property, assume (0,0).
+
+PROP_SHOW_MASK (editing state)
+ uint32 13 Type identification
+ uint32 4 Four bytes of payload
+ uint32 visible 1 if the layer mask is visible, 0 if not
+
+ PROP_SHOW_MASK specifies whether the layer mask is visible.
+ If the property does not appear for a layer which has a layer mask,
+ it defaults to false.
+
+ Robust readers should force this to false if the layer has no layer
+ mask. Writers should never save this as true unless the layer has a
+ layer mask.
+
+PROP_TEXT_LAYER_FLAGS
+ uint32 26 Type identification
+ uint32 4 Four bytes of payload
+ uint32 flags Flags, or'ed together from the following set:
+ 0x00000001 Do _not_ change the layer name if the text
+ content is changed
+ 0x00000002 The pixel data has been painted to or otherwise
+ modified since the text was rendered.
+ (see the anonymous enum in app/text/gimptextlayer-xcf.c)
+
+ PROP_TEXT_LAYER_FLAGS specifies the text layer behavior by flags.
+ It appears in property lists for text layers.
+ The actual text (and other parameters such as font and color) is a
+ parasite rather than a property.
+
+
+6. THE HIERARCHY STRUCTURE
+==========================
+
+A hierarchy contains data for a rectangular array of pixels.
+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
+
+ pointer lptr Pointer to the "level" structure
+ ,-------- ------ Repeat zero or more times
+ | pointer dlevel Pointer to an unused level structure (dummy level)
+ `--
+ pointer 0 Zero marks the end of the list of level pointers.
+
+The width, height and bpp values are for consistency checking; their
+correct values can always be inferred from the context, and are
+checked when GIMP reads the XCF file.
+
+
+Levels
+------
+
+The level structure for the first level is laid out as follows:
+
+ uint32 width Width of the pixel array
+ uint32 height Height of the pixel array
+ ,----------------- Repeat for each of the ceil(width/64)*ceil(height/64) tiles
+ | pointer tptr Pointer to tile data
+ `--
+ pointer 0 Zero marks the end of the array of tile pointers.
+
+Due to oversight, in the level structures for the aforementioned
+dummy levels, the "pointer" fields are "uint32" instead.
+
+The width and height must be the same as the ones recorded in the
+hierarchy structure (except for the dummy levels).
+
+Ceil(x) is the smallest integer not smaller than x.
+
+
+7. TILE DATA ORGANIZATION
+=========================
+
+The format of the data blocks pointed to by the tile pointers in the
+level structure of hierarchy differs according to the value of the
+PROP_COMPRESSION property of the main image structure. Current
+GIMP versions use RLE compression by default, and zlib compression
+optionally. Readers should nevertheless be prepared to meet the
+older uncompressed format.
+
+Both formats assume the width, height and byte depth of the tile are
+known from the context (namely, they are stored explicitly in the
+hierarchy structure for regular tiles). Both encodings store a linear sequence
+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.
+
+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
+over 8-bit per channel.
+
+Warning: a bug during development was having pixel data saved in the
+host byte order before version 12, which means that any XCF file from
+version 7 to 11 may be broken when saved then loaded on machines with
+different byte orders (and we cannot know for sure which byte order was
+used for storage for these XCF versions, though little-endian may be a
+safe assumption, considering most end-user processors are little-endian
+nowadays). The stable GIMP 2.10.0 always outputs in big-endian and would
+only use XCF version 7 to 11 when precision is 8-bit. Therefore if a XCF
+reader tries to load a XCF 7 to 11 using over 8-bit precision, this XCF
+was created with a development version of GIMP (therefore unsupported)
+and byte-order is unspecified.
+
+Uncompressed tile data
+----------------------
+
+In the uncompressed format the file first contains all the bytes for
+the first pixel, then all the bytes for the second pixel, and so on.
+
+zlib compressed tile data
+------------------------
+
+In the zlib compressed format, each tile is compressed as-is (pixel
+after pixel) with zlib.
+
+RLE compressed tile data
+------------------------
+
+In the Run-Length Encoded format, each tile consists of a run-length
+encoded stream of the first byte of each pixel, then a stream of the
+second byte of each pixel, and so forth. In each of the streams,
+multiple occurrences of the same byte value are represented in
+compressed form. The representation of a stream is a series of
+operations; the first byte of each operation determines the format and
+meaning of the operation (opcode):
+
+ byte n For 0 <= n <= 126: a short run of identical bytes
+ byte v Repeat this value n+1 times
+or
+ byte 127 A long run of identical bytes
+ byte p
+ byte q
+ byte v Repeat this value p*256 + q times
+or
+ byte 128 A long run of different bytes
+ byte p
+ byte q
+ byte[p*256+q] data Copy these verbatim to the output stream
+or
+ byte n For 129 <= n <= 255: a short run of different bytes
+ byte[256-n] data Copy these verbatim to the output stream
+
+The end of the stream for "the first byte of all pixels" (and the
+following similar streams) must occur at the end of one of these
+operations; it is not permitted to have one operation span the
+boundary between streams.
+
+The RLE encoding can cause degenerated encodings in which the original
+data stream may double in size (or grow to arbitrarily large sizes if
+(128,0,0) operations are inserted). Such encodings must be avoided, as
+GIMP's XCF reader expects that the size of an encoded tile is
+never more than 24 KB, which is only 1.5 times the unencoded size of a
+64x64 RGBA tile.
+
+A simple way for an XCF creator to avoid overflow is
+ a) never using opcode 0 (but instead opcode 255)
+ b) using opcodes 127 and 128 only for lengths larger than 127
+ c) never emitting two "different bytes" opcodes next to each other
+ in the encoding of a single stream.
+
+TODO: If each tile has a maximum of 64 pixels (resulting in a maximum of 64
+bytes for each color in this tile), do values>64 and long runs apply at all?
+
+
+8. MISCELLANEOUS
+================
+
+
+The name XCF
+------------
+
+The name XCF honors GIMP's origin at the eXperimental Computing
+Facility of the University of California at Berkeley.
+
+TODO: Integrate this document into the API doc.
+
+TODO: Some properties are denoted with "essential",
+"editing state", "not editing state, but not really
+essential either". What did the original author Henning Makholm mean?
+
+TODO: What will happen with the format after the GEGL
+port? AFAIK the ORA format will play a big role in
+the GEGL context (correct me if I'm wrong).
+Will XCF be dropped then or will ORA then be yet
+another import/export format like PSD etc.?
+
+