diff options
Diffstat (limited to 'devel-docs/xcf.txt')
| -rw-r--r-- | devel-docs/xcf.txt | 1607 |
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.? + + |