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 make our possible to update this documentation regularly, to make life simpler to ourselves as well as third-party XCF-reader’s developers.

This document used to be in the source repository. The older documentation for the XCF format dates from 1997-11-24, which was replaced in 2006-08-31 by a more extensive version by Henning Makholm. Finally this file was moved from the source code to the developer website on 2022-11-14.

The code for reading and writing XCF is found in: app/xcf/

License

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.

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/Infrastructure/gimp-web-devel/-/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.
Version 14
Since GIMP 3.0.0, released on TODO. Allows multiple layers to have the property PROP_ACTIVE_LAYER, hence multiple layers selected at once.
Version 15
Since GIMP 3.0.0, released on TODO. PROP_GUIDES now allows off-canvas guide positions, i.e. negative positions and over canvas-dimensions positions.
Version 16
Since GIMP 3.0.0, released on TODO.
  • Allows multiple channels to have the property PROP_ACTIVE_CHANNEL, hence multiple channels selected at once.
  • PROP_LINKED is deprecated. Old XCF files loaded by newer GIMP will transform linked items into stored item sets PROP_ITEM_SET.
  • New PROP_ITEM_SET and PROP_ITEM_SET_ITEM to store sets of layers, channels or paths.
Version 17
Since GIMP 3.0.0, released on TODO.
  • New PROP_LOCK_VISIBILITY on layers and channels.
  • PROP_LOCK_POSITION and PROP_LOCK_ALPHA can now be set on layer groups.
Vection 18
Since GIMP 3.0.0, released on TODO.
  • New Vectors Structure for storing paths with properties.
Vection 19
Since GIMP 3.0.0, released on TODO.
  • New format of font information in text layer
Vection 20
Since GIMP 3.0.0, released on TODO.
  • Layer effects

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.

A GeglColor is an object from the GEGL library that represents a color value along with its encoding and color space information. It is serialized in an XCF file as follows:

  STRING  varies  The babl encoding, such as "R'G'B'A double"
  uint32  1       The size in bytes of the color data
  uint8   n       The color data
  uint32  1       The size of the ICC profile (may be 0 if none)
  uint8   n       (Optional) The ICC profile data

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. The exact format depends on the field ‘precision’ of the image header. If this field is absent (i.e. for XCF version 3 or before), “8-bit gamma integer” is assumed, which means each component is on a scale from 0 to 255, with the intensity values considered nonlinear samples that map to physical light intensities using a power function with an exponent (“gamma”) of about 2.5 (this is how PC hardware commonly treat bit values in the video buffer, which incidentally also has the property of making each 1/255th step about equally perceptible to the human eye when the monitor is correctly adjusted). When the precision field is present though, it defines the storage format and the exact color space depends on the color profile attached to the image. The color profile is saved as a parasite named “icc-profile” on the image. If no profile is set, sRGB is assumed.

Beware, however, that before GIMP 2.10, GIMP’s compositing algorithms (as described in the document compositing.txt) implicitly treated the intensities as linear samples. The XCF file format had no support for storing the intended gamma of the samples. Since GIMP 2.10.0 and over, you must rely on PROP_COMPOSITE_MODE, PROP_COMPOSITE_SPACE and PROP_BLEND_SPACE for compositing and blending.

Grayscale: One intensity value. Grayscale has the same precision considerations as for RGB and it can also have a profile since GIMP 2.10.0, as well as compositing and blending rules.

On older XCF without precision field, the value was simply on a scale from 0 (black) to 255 (white).

Indexed: An 8-bit index into a color map that is shared between all layers. The color map maps each index to an RGB triple which is interpreted as in the RGB model.

It is to be noted that Indexed image in GIMP is limited to 8-bit integer RGB, even in GIMP 2.10.

Pixel data: Tiles

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, channels and vectors structures. The PROP_VECTORS stores those of paths when using this image property instead of proper vectors structure.

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 only selected 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.

If more than 2 paths are selected or if a path have a color tag, a content lock or a position lock, GIMP will use vectors structures, which bumps the XCF to at least version 18. If the XCF is already 18 or later, GIMP will always use vectors structure.

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_LINKED property is deprecated and must not be used since XCF version 16. XCF readers and writers are expected to convert linked items into item sets instead (see PROP_ITEM_SET).

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.).

Up to XCF 16, this could not be set on layer groups. It is possible since XCF 17.

PROP_LOCK_VISIBILITY (since version 3, editing state)

  uint32  42         Type identification
  uint32  4          Four bytes of payload
  uint32  locked     1 if visibility is locked; 0 if not

PROP_LOCK_VISIBILITY prevents the visibility to be switched (either explicitly for the item or when using features changing visibility to a range of items).

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, layer or path. It appears in the property list of layers, channels, vectors 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, channels and paths.

For the visibility of a path stored with the older PROP_VECTORS property, see this property’s description.

When reading old XCF files that lack this property, assume that layers are visible and channels are not.

PROP_ITEM_SET_ITEM (since GIMP 3.0)

  uint32  41         Type identification
  uint32  4          Four bytes of payload
  uint32  set        The `PROP_ITEM_SET` this item is listed in.

PROP_ITEM_SET_ITEM can be assigned to layers, channels and paths. They are only organisational properties and have no consequence on render.

The ‘set’ attribute corresponds to the numbered PROP_ITEM_SET this item belongs to, considering that the appearance order of PROP_ITEM_SET properties matter. It can only belong to a named item set and all items in a set must be of the proper type.

The image structure

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.
  ,------------------  Repeat once for each path, in no particular order:
  | pointer cptr       Pointer to the vectors structure.
  `--
  pointer   0           Zero marks the end of the array of vectors 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 3n+4 into the length word (but still actually followed it by 3n+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 for XCF < 15. Since XCF 15, off-canvas guides are possible, such as negative coordinates or bigger than the canvas width/height.

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 or in Vectors Structure.

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   39       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).

PROP_ITEM_SET (since GIMP 3.0)

  uint32  40         Type identification
  uint32  plength    Total length of the following payload in bytes
  uint32  item_type  The type of item in this set:
                     0: layers
                     1: channels
                     2: paths
  uint32  method     Selection method:
                     0: basic text search
                     1: regular expression search
                     2: glob pattern search
                     0xffffffff (max uint32): named item set
  string  label      Pattern to use for selection or name of the item
                     set if method is 0xffffffff.

They are only organisational properties and have no consequence on render. The order matters for display and also for PROP_ITEM_SET_ITEM.

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_LOCK_VISIBILITY, 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.

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
  ,--------   ------  Repeat for each layer effect (zero or more times)
  | pointer  eptr   Pointer to an effect structure
  `--
  pointer     0       Zero marks the end of the list of effect pointers.

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_LOCK_VISIBILITY, 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 layer is currently selected. Up to XCF 13 and below, only zero or one layer could have this property at any time. Since XCF 14 and over, there can be any number of layers selected together.

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  37         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

PROP_ITEM_PATH indicates the path of the layer if inside a group, i.e. its position within the group (last element of the list), but also the position of the group itself within its own level, up to the top-level position (first element).

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.

Up to XCF 16, this could not be set on layer groups. It is possible since XCF 17.

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.

The vectors structure

Vectors structures are pointed to from the master image structure.

  string    name       Name of the path
  uint32    plength    Total length of the following payload in bytes
  property-list        Vectors properties
  uint32    1          Version tag; so far always 1
  uint32    k          Number of strokes in the path
  ,-------------------- 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
  | `--
  `--

Vectors properties

The following properties are found only in the property list of vectors structures. Additionally the list can also contain the properties: PROP_COLOR_TAG, PROP_END, PROP_LOCK_CONTENT, PROP_LOCK_POSITION, PROP_PARASITES, PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.

PROP_SELECTED_PATH (editing state)

  uint32  43     Type identification
  uint32  0      `PROP_SELECTED_PATH` has no payload

The presence of PROP_SELECTED_PATH indicates that the path is currently selected. It appears in the property list of any currently selected path. Any number of paths (or none) can have this property at any time.

The effect structure

Effect structures are pointed to from a list of effect pointers in the layer structures.

  string     name   Effect name
  string     icon   Effect icon name
  string     op     GEGL Operation name
  property-list     Effect properties
  pointer    mptr   Pointer to the effect mask (a channel structure), or 0

Effect properties

The following properties are found only in the property list of layer structures. Additionally the list can also contain the properties PROP_END, PROP_VISIBLE, PROP_FLOAT_OPACITY, PROP_MODE, PROP_BLEND_SPACE, PROP_COMPOSITE_SPACE and PROP_COMPOSITE_MODE defined previously.

PROP_FILTER_REGION (since GIMP 3.0.0)

  uint32  44       Type identification
  uint32  4        Four bytes of payload
  uint32  region   Region used as input:
                     0: selection
                     1: entire drawable

PROP_FILTER_ARGUMENT (since GIMP 3.0.0)

  uint32  45       Type identification
  uint32  plength  Total length of the following payload data in bytes
  string  name     Argument name
  uint32  type     Argument type:
                     0: unknown
                     1: integer
                     2: boolean
                     3: float
                     4: string
                     5: enum
                     6: GimpConfig
                     7: unsigned integer
                     8: GeglColor
  byte[n] data     Argument value

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; this depends on the
                      color mode and image precision (fields 'base_type'
                      and 'precision' of the image header). For
                      instance, some combination values:
                        3: RGB color without alpha in 8-bit precision
                        4: RGB color with alpha in 8-bit precision
                        6: RGB color without alpha in 16-bit precision
                        16: RGB color with alpha in 32-bit precision
                        1: Grayscale without alpha in 8-bit precision
                        4: Grayscale with alpha in 16-bit precision
                        1: Indexed without alpha (always 8-bit)
                        2: Indexed with alpha (always 8-bit)
                      And so on.

  pointer     lptr    Pointer to the "level" structure
  ,--------   ------  Repeat zero or more times
  | 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.

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 bytes for each pixels, after the color information. In RGB color modes, the color information (first bytes for each pixel) is the red intensity, the green intensity, and the blue intensity, in that order. The exact size of each component depends on the ‘precision’ field, for instance 1 byte in 8-bit modes, 2 bytes in 16-bit, and so on.

Tile data, as other data in XCF format, is big-endian. In particular it means that pixel values are stored as big-endian when the precision is 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

  1. never using opcode 0 (but instead opcode 255)
  2. using opcodes 127 and 128 only for lengths larger than 127
  3. 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?

Miscellaneous

The name XCF

The name XCF honors GIMP’s origin at the eXperimental Computing Facility of the University of California at Berkeley.

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?