xcf.txt 63.8 KB
Newer Older
1
====================================
2
DOCUMENTATION OF THE XCF FILE FORMAT
3
====================================
Elliot Lee's avatar
Elliot Lee committed
4

5 6 7
Introduction
------------

8 9
This document describes the native image file format of GIMP.

10 11 12 13 14 15 16 17
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/

18 19 20 21

License
-------

22
Copyright Henning Makholm <henning@makholm.net>, 2006-07-11
23
Copyright various GIMP developers (see git log), 2009-2018
Elliot Lee's avatar
Elliot Lee committed
24

25 26 27 28 29 30
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.


31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85
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.
86 87


88 89 90 91 92 93 94 95
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.

96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111
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.
112

113 114 115 116 117 118 119
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.
120 121
For more information on that see:
https://web.archive.org/web/20161024115140/http://www.cinepaint.org/more/docs/xcf.html
122

123 124 125

Status
------
126 127

This specification is an unofficial condensation and extrapolation of
128 129 130
the XCF-writing and -reading code in version 2.10.0 of GIMP. Yet we
remind that the ultimate reference is the loading and saving code of the
XCF format.
131 132

Some of the normative statements made below are enforced by the XCF
133
code in GIMP; others are just the authors' informed guess about
134
"best practices" that would be likely to maximize interoperability
135
with future versions of GIMP.
136 137


138 139 140 141 142 143
Version history
---------------
This section lists the changes between file format versions in bigger terms.
Details are denoted in the text.

Version 0:
144
Since GIMP 0.99.16, released on 1997-12-15.
145 146 147 148
The initial file format. Everything that is not listed in the following versions
is part of this.

Version 1:
149
Since GIMP 0.99.16, released on 1997-12-15.
150 151 152 153
Adds color maps. Chapter 3 "The image structure" describes the PROP_COLOR_MAP
property.

Version 2:
154
Since GIMP 1.3.10, released on 2002-11-07.
155 156 157 158 159 160 161 162
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:
163
Since GIMP 2.7.1, released on 2010-06-29.
164 165 166
Adds layer groups. The chapter 5 "The layer structure" describes the new
properties PROP_GROUP_ITEM, PROP_GROUP_ITEM_FLAGS and PROP_ITEM_PATH.

167 168 169 170 171
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.
172 173 174

1. BASIC CONCEPTS
=================
175 176

It is recommended that a software developer who wants to take full
177
advantage of the XCF format be deeply familiar with GIMP at least
178 179 180 181 182
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.


183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225
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
32-bit "pointers" that count the number of bytes between the beginning of
the XCF file and the beginning of the target structure. Note that therefore
the maximum address of a layer, channel, hierarchy or tile set is 2^32 - 1,
i.e. at 4 GB. Everything after will be lost. Currently this doesn't play a
role yet.

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.

226 227 228
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.
229 230

Canvas
231 232
------

233 234
A canvas is an abstract rectangular viewport for the layers and channels.
The image header stores the canvas' dimensions.
235 236


237 238
Color
-----
239

240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290
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.
291

292 293 294 295
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.
296

297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329

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
-------
330 331 332 333 334

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
335
formats. A major use of channels is as a store for saved selections.
336 337

A channel can be edited as if it was a grayscale layer with the same
338
dimensions as the canvas. When it is shown in the GIMP editor UI
339 340 341 342 343 344 345 346 347
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.
348
TODO: does this apply to any channel or only to selections?
349 350


351 352
Layer
-----
353

354 355 356 357
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.
358

359 360 361 362
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.
363

364 365 366 367 368 369 370
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.
371

372 373 374 375 376
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).
377

378 379 380 381 382
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?
383

384 385 386
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.
387 388


389 390
Layer mask
----------
391

Jehan's avatar
Jehan committed
392 393
The layer mask can be attached to a layer (since GIMP 2.10.0, layer
group can also have a layer mask).
394 395 396 397
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.
398

399 400 401 402 403 404
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.
405

Elliot Lee's avatar
Elliot Lee committed
406 407 408 409

Properties
----------

410 411 412
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.
Elliot Lee's avatar
Elliot Lee committed
413

414 415 416 417 418 419
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
Elliot Lee's avatar
Elliot Lee committed
420

421
The authoritative source for property type numbers is the file
422 423
app/xcf/xcf-private.h in the GIMP sources. Only GIMP itself should define
new property types.
Elliot Lee's avatar
Elliot Lee committed
424

425 426 427
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.
Elliot Lee's avatar
Elliot Lee committed
428

429 430
XCF readers must skip and ignore property records of unrecognized
type, and the length word is there to support such skipping. However,
431
GIMP's own XCF reader will _ignore_ the length word of most
432 433 434 435
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
436
historical versions of GIMP actually stored the wrong length for
437 438 439 440 441
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.
Elliot Lee's avatar
Elliot Lee committed
442

443
There is not supposed to be more than one instance of each property in
444
a property list, but some versions of GIMP will erroneously emit
445
duplicate properties. An XCF reader that meets a duplicated property
446
should let the content of the later instance take precedence, except
447 448 449
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.
Elliot Lee's avatar
Elliot Lee committed
450

451

452 453
Parasites
---------
Elliot Lee's avatar
Elliot Lee committed
454

455 456
Parasites provide a second level of extensibility.
A parasite is analogous to a property, but is identified by a string
457
rather than a number. This makes a larger namespace available for
458 459 460
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.
Elliot Lee's avatar
Elliot Lee committed
461

462
A list of known parasites and their data formats can be found in the
463
file devel-doc/parasites.txt of the GIMP source tree.
Elliot Lee's avatar
Elliot Lee committed
464

465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548
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
----

549
GIMP stores text in plain layers with parasites for the text and formatting
550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567
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.

568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584
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.

585 586 587 588 589 590
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.

591 592 593 594 595 596 597 598 599 600 601 602 603
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.

604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621
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.

622 623 624 625 626 627 628 629
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.).

630 631 632 633 634 635 636 637
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.
Elliot Lee's avatar
Elliot Lee committed
638

639 640 641 642 643 644 645 646
  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.

647 648 649 650
  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.

651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691
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
------
Elliot Lee's avatar
Elliot Lee committed
692

693
The image structure always starts at offset 0 in the XCF file.
Elliot Lee's avatar
Elliot Lee committed
694

695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747
  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".
748 749
  property-list        Image properties
  ,-----------------   Repeat once for each layer, topmost layer first:
750
  | pointer lptr       Pointer to the layer structure.
751
  `--
752 753
  uint32   0           Zero marks the end of the array of layer pointers.
  ,------------------  Repeat once for each channel, in no particular order:
754
  | pointer cptr       Pointer to the channel structure.
755
  `--
756
  uint32   0           Zero marks the end of the array of channel pointers.
Elliot Lee's avatar
Elliot Lee committed
757

758 759
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
760 761 762 763
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.
Elliot Lee's avatar
Elliot Lee committed
764

765
GIMP's XCF writer dynamically selects the lowest version that will
766 767
allow the image to be represented. Third-party XCF writers should do
likewise.
Elliot Lee's avatar
Elliot Lee committed
768

769
Version numbers from v100 upwards have been used by CinePaint, which
770 771
originated as a 16-bit fork of GIMP, see "Scope".

Elliot Lee's avatar
Elliot Lee committed
772

773 774
Image properties
----------------
Elliot Lee's avatar
Elliot Lee committed
775

776
The following properties are found only in the property list of the
777 778
image structure. Additionally the list can also contain the properties
PROP_END, PROP_PARASITES and PROP_TATTOO, defined in chapter 2.
Elliot Lee's avatar
Elliot Lee committed
779

780
PROP_COLORMAP (essential)
781 782 783 784 785 786 787
  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
788 789
  `--

790 791 792 793 794
  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
795 796 797 798
  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
799 800
  PNG format, an XCF color map does not contain alpha components, and
  there is no color map entry for "transparent"; the alpha channel of
801 802
  layers that have one is always represented separately.

803
  The structure here is that of since XCF version 1.  Comments in the
804
  GIMP source code indicate that XCF version 0 could not store indexed
805
  images in a sane way; contemporary GIMP versions will complain and
806 807
  reinterpret the pixel data as a grayscale image if they meet a
  version-0 indexed image.
808

809
  Beware that the payload length of the PROP_COLORMAP in particular
810
  cannot be trusted: some historic releases of GIMP erroneously
811 812
  wrote n+4 instead of 3*n+4 into the length word (but still actually
  followed it by 3*n+4 bytes of payload).
813 814

PROP_COMPRESSION (essential)
815 816 817 818 819
  uint32  17       Type identification
  uint32  1        One byte of payload
  byte    comp     Compression indicator; one of
                     0: No compression
                     1: RLE encoding
820
                     2: zlib compression
821
                     3: (Never used, but reserved for some fractal compression)
822

823 824
  PROP_COMPRESSION defines the encoding of pixels in tile data blocks in the
  entire XCF file. See chapter 7 for details.
825 826 827 828 829

  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.

830 831 832 833
  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.

834
PROP_GUIDES (editing state)
835 836 837 838 839 840 841 842
  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)
843 844
  `--

845 846
  PROP_GUIDES stores the horizontal or vertical positions of guides.
  It appears if any guides have been defined.
847 848 849 850 851

  Some old XCF files define guides with negative coordinates; those
  should be ignored by readers.

PROP_PATHS
852 853 854 855
  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
856 857 858 859 860
    path_1
    path_2
    ...
    path_n

861 862
  PROP_PATHS stores the paths.

863 864 865
  Each path has one of three formats

    Format 1:   Format 2:   Format 3:
866 867 868 869 870 871 872 873 874
     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
875 876
                 uint32      uint32     dummy    Ignored; always set to 1
                             uint32     tattoo   0 if none, or see PROP_TATTOO
877 878 879 880 881
     ,---------- ,---------- ,------------------ Repeat for np points:
     | int32     | int32     | int32    type     Type of point; one of
     |           |           |                    0: Anchor
     |           |           |                    1: Bezier control point
     |           |           |                   (for GIMP 1.2 compatibility)
882 883 884 885 886
     | 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
887 888 889 890 891 892 893 894 895 896 897 898
  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.
899

900
  TODO: Clarify: PROP_PATHS cannot represent parasites for paths, but the
901 902
  XCF writer does not check whether all paths are parasite-less when
  choosing which property to use, so path parasites may be lost upon
903 904
  saving). Is this by design or a bug?

905 906
  There may be paths that declare a length of 0 points; these should
  be ignored.
907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948

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.

949
PROP_USER_UNIT (editing state)
950 951 952 953 954 955 956 957 958 959 960 961 962 963
  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?

964
PROP_VECTORS
965 966 967 968 969
  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
970 971 972
  ,---------------------- Repeat n times:
  | string     name       Name of the path
  | uint32     tattoo     Tattoo of the path (see PROP_TATTOO), or 0
973 974 975 976
  | 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
977
  | ,-------------------- Repeat m times:
978
  | | parasite ...        In same format as in PROP_PARASITES.
979 980
  | `--
  | ,-------------------- Repeat k times:
981 982 983
  | | 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;
984 985 986 987
  | |                     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
988 989
  | | |                     0: Anchor
  | | |                     1: Bezier control point
990 991
  | | | float  x          X coordinate
  | | | float  y          Y coordinate
992 993 994 995
  | | | 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
996 997 998
  | | `--
  | `--
  `--
999 1000 1001 1002 1003

  PROP_VECTORS stores the paths.

  It appears if all paths are continuous sequences of Bezier strokes;
  otherwise PROP_PATHS is used.
1004

1005
  GIMP's XCF reader checks that the total size of all path
1006 1007
  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
1008 1009 1010 1011
  without parsing the individual parasites. (Note that this is _not_
  the case for PROP_PATHS).


1012 1013 1014 1015 1016 1017 1018
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).

1019 1020 1021 1022
  uint32    width  Width of the channel
  uint32    height Height of the channel
  string    name   Name of the channel
  property-list    Channel properties
1023
  pointer   hptr   Pointer to the hierarchy structure with the pixels.
1024 1025 1026 1027 1028 1029 1030 1031 1032 1033

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
1034 1035 1036
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,
1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059
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?

1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079
  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.

1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095
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
1096 1097 1098 1099 1100
======================

Layer structures are pointed to from a list of layer pointers in the
master image structure.

1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112
  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
1113 1114
  pointer    hptr   Pointer to the hierarchy structure with the pixels
  pointer    mptr   Pointer to the layer mask (a channel structure), or 0
1115

1116 1117 1118 1119 1120 1121 1122 1123
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).
1124 1125 1126 1127 1128 1129


Layer properties
----------------

The following properties are found only in the property list of layer
1130 1131 1132
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,
1133
PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.
1134 1135

PROP_ACTIVE_LAYER (editing state)
1136 1137
  uint32  2        Type identification
  uint32  0        PROP_ACTIVE_LAYER has no payload
1138

1139 1140 1141
  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.
1142 1143

PROP_APPLY_MASK (essential)
1144 1145 1146
  uint32  11       Type identification
  uint32  4        Four bytes of payload
  uint32  apply    1 if the layer mask should be applied, 0 if not
1147

1148 1149
  PROP_APPLY_MASK specifies whether the layer mask shall be applied
  to the layer.
1150 1151 1152 1153 1154 1155 1156
  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.

1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226
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.

1227
PROP_EDIT_MASK (editing state)
1228 1229 1230
  uint32  12       Type identification
  uint32  4        Four bytes of payload
  uint32  editing  1 if the layer mask is currently being edited, 0 if not
1231

1232
  PROP_EDIT_MASK specifies whether the layer mask is currently being edited.
1233 1234 1235 1236 1237 1238 1239
  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.

1240
PROP_FLOATING_SELECTION (essential)
1241 1242
  uint32    5      Type identification
  uint32    4      Four bytes of payload
1243 1244
  pointer   ptr    Pointer to the layer or channel the floating selection is
                   attached to
1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285

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

1287 1288 1289 1290
PROP_MODE (essential)
  uint32  7        Type identification
  uint32  4        Four bytes of payload
  unit32  mode     Layer mode; one of
1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360
                   * 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: Substract
                     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
1361 1362 1363 1364 1365 1366

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

1368 1369 1370 1371 1372 1373 1374 1375
  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.

1376 1377 1378 1379 1380 1381 1382 1383 1384
  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

Jehan's avatar
Jehan committed
1385
NOTE: The layer modes 'Old broken Overlay' and 'Soft light (legacy)' are identical.
1386 1387

PROP_OFFSETS (essential)
1388 1389 1390 1391 1392 1393 1394 1395
  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
1396 1397 1398 1399
  extends to the left of or above the canvas boundary.

  When reading old XCF files that lack this property, assume (0,0).

1400 1401 1402 1403
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
1404

1405 1406 1407
  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.
1408

1409 1410 1411
  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.
1412

1413 1414 1415 1416 1417 1418 1419 1420 1421
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)
1422

1423 1424 1425 1426
  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.
1427 1428 1429 1430 1431


6. THE HIERARCHY STRUCTURE
==========================

1432 1433 1434
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.

1435 1436 1437 1438 1439 1440 1441 1442 1443 1444
  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

1445
  pointer     lptr    Pointer to the "level" structure
1446
  ,--------   ------  Repeat zero or more times
1447
  | pointer   dlevel  Pointer to an unused level structure (dummy level)
1448
  `--
1449
  pointer     0       Zero marks the end of the list of level pointers.
1450

1451
The width, height and bpp values are for consistency checking; their
1452
correct values can always be inferred from the context, and are
1453
checked when GIMP reads the XCF file.
1454

1455

1456 1457 1458
Levels
------

1459
The level structure for the first level is laid out as follows:
1460

1461 1462 1463
  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
1464
  | pointer   tptr   Pointer to tile data
1465
  `--
1466
  pointer     0      Zero marks the end of the array of tile pointers.
1467

1468 1469 1470
Due to oversight, in the level structures for the aforementioned
dummy levels, the "pointer" fields are "uint32" instead.

1471
The width and height must be the same as the ones recorded in the
1472
hierarchy structure (except for the dummy levels).
1473

1474
Ceil(x) is the smallest integer not smaller than x.
1475 1476 1477 1478 1479 1480


7. TILE DATA ORGANIZATION
=========================

The format of the data blocks pointed to by the tile pointers in the
1481 1482
level structure of hierarchy differs according to the value of the
PROP_COMPRESSION property of the main image structure. Current
1483 1484 1485
GIMP versions use RLE compression by default, and zlib compression
optionally. Readers should nevertheless be prepared to meet the
older uncompressed format.
1486 1487 1488

Both formats assume the width, height and byte depth of the tile are
known from the context (namely, they are stored explicitly in the
1489 1490
hierarchy structure for regular tiles). Both encodings store a linear sequence
of width*height pixels, extracted from the tile in row-major,
1491 1492 1493 1494 1495 1496 1497
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.
1498

Jehan's avatar
Jehan committed
1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513
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.
1514 1515 1516 1517

Uncompressed tile data
----------------------

1518
In the uncompressed format the file first contains all the bytes for
1519 1520
the first pixel, then all the bytes for the second pixel, and so on.

1521 1522 1523 1524 1525
zlib compressed tile data
------------------------

In the zlib compressed format, each tile is compressed as-is (pixel
after pixel) with zlib.
1526

1527 1528 1529 1530 1531 1532 1533 1534 1535
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
1536
meaning of the operation (opcode):
1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558

  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.

1559
The RLE encoding can cause degenerated encodings in which the original
1560 1561
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
1562
GIMP's XCF reader expects that the size of an encoded tile is
1563 1564 1565 1566 1567 1568 1569 1570 1571
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.

1572 1573
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?
1574 1575


1576 1577
8. MISCELLANEOUS
================
1578 1579


1580 1581
The name XCF
------------
1582

1583 1584
The name XCF honors GIMP's origin at the eXperimental Computing
Facility of the University of California at Berkeley.
1585

1586
TODO: Integrate this document into the API doc.
Elliot Lee's avatar
Elliot Lee committed
1587

1588 1589 1590
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?
Elliot Lee's avatar
Elliot Lee committed
1591

1592 1593 1594 1595 1596
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.?
Elliot Lee's avatar
Elliot Lee committed
1597 1598