| blob | b2e8f8704b6620dac15cd669753a7e158b206ac0 |
1 ====================================
2 DOCUMENTATION OF THE XCF FILE FORMAT
3 ====================================
5 Introduction
6 ------------
8 This document describes the native image file format of GIMP.
10 Note that the XCF format is a "living" format which follows closely the
11 GIMP software and evolves together. The ultimate reference for the
12 format is therefore its code, even though we will try to update this
13 documentation regularly, to make life simpler to ourselves as well as
14 third-party XCF-reader's developers.
16 The code for reading and writing XCF is found in: app/xcf/
19 License
20 -------
22 Copyright Henning Makholm <henning@makholm.net>, 2006-07-11
23 Copyright various GIMP developers (see git log), 2009-2018
25 This is free documentation; you can modify and/or redistribute
26 it according to the terms of the GNU General Public License
27 as published by the Free Software Foundation, either version
28 2 of the license, or (at your option) any later version.
31 Table of contents
32 -----------------
34 Documentation of the XCF file format
35 License
36 Table of contents
37 Audience
38 Scope
39 Status
40 Version history
42 1. Basic concepts
43 XCF file
44 Basic data types
45 Canvas
46 Color
47 Pixel data: Tiles
48 Pixel data: Levels of detail hierarchy
49 Channels
50 Layers
51 Layer masks
52 Properties
53 Parasites
54 Selections
55 Floating selection
56 Tattoos
58 2. General properties
60 3. The Image structure
61 Header
62 Image properties
64 4. The Channel structure
65 Channel properties
67 5. The Layer structure
68 Layer properties
70 6. The Hierarchy structure
71 Levels
73 7. Tile data organization
74 Uncompressed tile data
75 RLE compressed tile data
77 8. Miscellaneous
78 The name XCF
81 Audience
82 --------
84 Audience of this document are developers of GIMP and other software that
85 reads and writes XCF files.
88 Scope
89 -----
91 The XCF format is designed to store the whole state of GIMP that is specific to
92 one image (i.e., not the cut buffer, tool options, key bindings, etc.) and
93 is not undo data. This makes the full collection of data stored in an XCF file
94 rather heterogeneous and tied to the internals of GIMP.
96 Use of the XCF format by third-party software is recommended only as a
97 way to get data into and out of GIMP for which it would be impossible or
98 inconvenient to use a more standard interchange format. Authors of
99 third-party XCF-creating software in particular should take care to
100 write files that are as indistinguishable as possible from ones saved by
101 GIMP. The GIMP developers take care to make each version of GIMP able to
102 read XCF files produced by older GIMP versions, but they make no special
103 efforts to allow reading of XCF files created by other software.
105 Interchanging image data with other applications is not the goal of the
106 XCF format. Other formats may be more appropriate. For this use case
107 GIMP opens and exports common images formats, like JPEG, PNG and PSD,
108 though they may all miss various features of XCF.
109 OpenRaster (ORA) in particular is meant to be a generic interchange
110 format between software, with as few feature loss as possible, though
111 its standardization is still quite slow.
113 For the stated reasons and clarification GIMP _saves_ XCF files,
114 but _exports_ to other image formats.
116 Beware that CinePaint's native file format is called XCF, too. While it is
117 derived from the format described here, both formats differ in many details
118 and are _not_ mutually compatible.
119 This document does not describe the CinePaint XCF format.
120 For more information on that see:
121 https://web.archive.org/web/20161024115140/http://www.cinepaint.org/more/docs/xcf.html
124 Status
125 ------
127 This specification is an unofficial condensation and extrapolation of
128 the XCF-writing and -reading code in version 2.10.0 of GIMP. Yet we
129 remind that the ultimate reference is the loading and saving code of the
130 XCF format.
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.
138 Version history
139 ---------------
140 This section lists the changes between file format versions in bigger terms.
141 Details are denoted in the text.
143 Version 0:
144 Since GIMP 0.99.16, released on 1997-12-15.
145 The initial file format. Everything that is not listed in the following versions
146 is part of this.
148 Version 1:
149 Since GIMP 0.99.16, released on 1997-12-15.
150 Adds color maps. Chapter 3 "The image structure" describes the PROP_COLOR_MAP
151 property.
153 Version 2:
154 Since GIMP 1.3.10, released on 2002-11-07.
155 Adds layer modes "Soft light", "Grain extract", "Grain merge" and painting
156 mode "Color Erase". In chapter 5 "The layer structure" the description of
157 the property PROP_MODE contains the new layer modes.
158 Improves path handling in GIMP 1.3.21, released on 5.10.2003.
159 Chapter 1 "Basic concepts" describes the path handling in general and
160 chapter 2 "General concepts" introduces the PROP_VECTORS property.
162 Version 3:
163 Since GIMP 2.7.1, released on 2010-06-29.
164 Adds layer groups. The chapter 5 "The layer structure" describes the new
165 properties PROP_GROUP_ITEM, PROP_GROUP_ITEM_FLAGS and PROP_ITEM_PATH.
167 Version 4 to 13:
168 Since GIMP 2.10.0, released on 2018-04-27.
169 Adds many layer modes, layer group masks, high-bit depth (precisions
170 other than 8-bit gamma), zlib compression and 64-bit offsets for XCF
171 files bigger than 4GB.
173 1. BASIC CONCEPTS
174 =================
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 as a user. The following high-level overview is meant to help those
179 non-users who just need to extract pixel data from an XCF file get up
180 to speed.
183 XCF file
184 --------
186 An XCF file is a sequence of bytes. In general an XCF file describes a stack of
187 layers and channels on a canvas.
188 It contains a series of data structures, the order of which is in general not
189 significant. The exception to this is that the main image structure must come at
190 the very beginning of the file, and that the tile data blocks for each drawable
191 must follow each other directly.
193 References _between_ structures in the XCF file take the form of
194 32-bit "pointers" that count the number of bytes between the beginning of
195 the XCF file and the beginning of the target structure. Note that therefore
196 the maximum address of a layer, channel, hierarchy or tile set is 2^32 - 1,
197 i.e. at 4 GB. Everything after will be lost. Currently this doesn't play a
198 role yet.
200 Each structure is designed to be written and read sequentially; many
201 contain items of variable length and the concept of an offset _within_
202 a data structure is not often relevant.
205 Basic data types
206 ----------------
208 A WORD is a 32-bit integer stored as 4 bytes in big-endian order, i.e. with
209 the most significant byte first. The word is not necessarily aligned to an
210 offset within the XCF file that is a multiple of 4.
211 Depending on the context the word can be unsigned or (2's complement) signed.
212 UINT32 denotes unsigned words and INT32 denotes signed words in this document.
214 A FLOAT is stored as a 32-bit IEEE 754 single-precision floating-point number
215 in big-endian order.
217 A STRING is stored as follows:
219 uint32 n+1 Number of bytes that follow, including the zero byte
220 byte[n] ... String data in Unicode, encoded using UTF-8
221 byte 0 Zero marks the end of the string.
223 Exception: the empty string is stored simply as an uint32 with the
224 value 0.
226 A POINTER is stored as a 32-bit integer (4 bytes) in big-endian order
227 for XCF up to 10, and 64-bit (8 bytes), still big-endian, for XCF 11
228 and over, allowing higher than 4GB XCF files since GIMP 2.10.0.
230 Canvas
231 ------
233 A canvas is an abstract rectangular viewport for the layers and channels.
234 The image header stores the canvas' dimensions.
237 Color
238 -----
240 RGB:
241 Three intensity values for red, green, and blue additive color
242 components, each on a scale from 0 to 255. The exact color space
243 is not specified. GIMP displays image data directly on PC
244 display hardware without any software correction, so in most
245 cases the intensity values should be considered nonlinear samples
246 that map to physical light intensities using a power function
247 with an exponent ("gamma") of about 2.5. (This is how PC hardware
248 commonly treat bit values in the video buffer, which incidentally
249 also has the property of making each 1/255th step about equally
250 perceptible to the human eye when the monitor is correctly
251 adjusted).
252 Beware, however, that GIMP's compositing algorithms (as described
253 in the document compositing.txt) implicitly treat the intensities
254 as _linear_ samples. The XCF file format currently has no support
255 for storing the intended gamma of the samples.
257 TODO: Are the statements about color space, gamma and layer modes still valid?
259 Grayscale:
260 One intensity value on a scale from 0 (black) to 255 (white).
261 Gamma considerations as for RGB.
263 Indexed:
264 An 8-bit index into a color map that is shared between all
265 layers. The color map maps each index to an RGB triple which is
266 interpreted as in the RGB model.
269 Pixel data: Tiles
270 -----------------
272 Basically pixels are organized in a grid of "tiles", each
273 with a width and height of up to 64 pixels. The only tiles that have a
274 width less than 64 are those in the rightmost column, and the only
275 tiles that have a height less than 64 are those in the bottommost row.
276 Thus, a layer measuring 200 x 150 pixels will be divided into 12
277 tiles:
279 +-----------------+-----------------+------------------+-----------------+
280 | Tile 0: 64 x 64 | Tile 1: 64 x 64 | Tile 2: 64 x 64 | Tile 3: 8 x 64 |
281 +-----------------+-----------------+------------------+-----------------+
282 | Tile 4: 64 x 64 | Tile 5: 64 x 64 | Tile 6: 64 x 64 | Tile 7: 8 x 64 |
283 +-----------------+-----------------+------------------+-----------------+
284 | Tile 8: 64 x 22 | Tile 9: 64 x 22 | Tile 10: 64 x 22 | Tile 11: 8 x 22 |
285 +-----------------+-----------------+------------------+-----------------+
287 As can be seen from this example, the tiles appear in the XCF file in
288 row-major, top-to-bottom, left-to-right order. The dimensions of the
289 individual tiles are not stored explicitly in the XCF file, but must
290 be computed by the reader.
292 The tiles that are pointed to by a single level structure must be
293 contiguous in the XCF file, because GIMP's XCF reader uses the
294 difference between two subsequent tile pointers to judge the amount of
295 memory it needs to allocate for internal data structures.
298 Pixel data: Levels of detail hierarchy
299 --------------------------------------
301 The tiles themselves are organized in levels of detail. These levels
302 build a hierarchy.
304 Only the first level structure is used by GIMP's XCF reader,
305 except that the reader checks that a terminating zero for the
306 level-pointer list can be found. GIMP's XCF writer creates a
307 series of dummy level structures (with NULL-pointers to the tiles), each
308 declaring a height and width half of the previous one (rounded down),
309 until the height and with are both less than 64. Thus, for a layer of
310 200 x 150 pixels, this series of levels will be saved:
312 A level of 200 x 150 pixels with 12 tiles: the actually used one
313 A level of 100 x 75 pixels with no tiles
314 A level of 50 x 37 pixels with no tiles
316 Third-party XCF writers should probably mimic this entire structure;
317 robust XCF readers should have no reason to even read past the pointer
318 to the first level structure.
320 TODO: The XCF file holds (for unclear historical reasons)
321 a level-of-detail hierarchy, but we only use the
322 lowest hierarchy level of it and other XCF consumers
323 are told to do the same. This looks like a mipmap. Would
324 using it to save an image pyramid or the thumbnail
325 for the File dialogs get us some benefits?
328 Channel
329 -------
331 A channel is a named object that contains a single byte of information
332 for each pixel in the canvas area. Channels have a variety of use as
333 intermediate objects during editing; they are not meant to be rendered
334 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.
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 together with other layers, it is used as if it was the _inverse_
340 alpha channel of a layer with the same color information in all
341 pixels; this color can be stored in the XCF file as a property of the
342 channel. This "mask" representation is generally thought of as an UI
343 feature rather than an intrinsic semantics of a channel.
345 Though the channel data structure in the XCF file contains a height
346 and width field, these must always be the same as the canvas width and
347 height.
348 TODO: does this apply to any channel or only to selections?
351 Layer
352 -----
354 A layer is a named rectangular area of pixels which has a definite
355 position with respect to the canvas. It may extend beyond the canvas or
356 (more commonly) only cover some of it. Each pixel of the layer has a color
357 which is specified in one of three ways as described in the "Color" section.
359 All layers in an image must use the same color model.
360 Exception: if the "floating selection" (see below) belongs to a channel or
361 layer mask, it will be represented as grayscale pixels with alpha independently
362 of the image's overall color model.
364 Each pixel of a layer also has an alpha component which specifies the
365 opacity of the pixel on a linear scale from 0 (denoting an alpha of
366 0.0, or completely transparent) to 255 (denoting an alpha of 1.0, or
367 completely opaque). The color values do not use "premultiplied alpha"
368 storage. The color information for pixels with alpha 0 _may_ be
369 meaningful; GIMP preserves it when parts of a layer are erased and
370 provides (obscure) ways of recovering it in its user interface.
372 The bottommost layer _only_ in an image may not contain alpha
373 information; in this case all pixels in the layer have an alpha value
374 of 255. (Even if the bottommost layer does not cover the entire
375 canvas, it is the only layer that can be without an explicit alpha
376 channel).
378 In images that use the indexed color model, GIMP does not support
379 partial transparency and interprets alpha values from 0 to 127 as
380 fully transparent and values from 128 to 255 as fully opaque. This
381 behavior _may_ change in future versions of GIMP.
382 TODO: has already changed?
384 Layers have certain other properties such as a visibility flag,
385 a global opacity (which is multiplied with individual pixel alphas)
386 a layer group flag and various editing state flags.
389 Layer mask
390 ----------
392 The layer mask can be attached to a layer (since GIMP 2.10.0, layer
393 group can also have a layer mask).
394 Actually it is represented as a channel structure in the XCF file.
395 It is referred to from its parent layer and not listed in the master list
396 of channels.
397 Its dimensions and placement coincide with those of its parent layer.
399 Unless disabled by the PROP_APPLY_MASK property, the layer mask
400 functions as an extra alpha channel for the layer, in that for each
401 pixel the layer's alpha byte and the layer mask byte are multiplied to
402 find the extent to which the layer blankets the background. Thus a
403 layer mask can make parts of the layer more transparent, but never
404 more opaque.
407 Properties
408 ----------
410 Properties are an extension mechanism to attribute the image, channels
411 and layers. Some are attributes for general use, such as PROP_END,
412 others are specific to the image, a channel or a layer.
414 Technically properties are implemented as variable-length series of
415 variable-length PROPERTY records which have the following general format
417 uint32 type Numerical type identifier
418 uint32 plength Payload length in bytes (but BEWARE! see below)
419 byte[n] ... Payload - interpretation depends on the type
421 The authoritative source for property type numbers is the file
422 app/xcf/xcf-private.h in the GIMP sources. Only GIMP itself should define
423 new property types.
425 The number of properties in a property list is not stored explicitly;
426 the last property in the list is identified by having type 0; it must
427 have length 0.
429 XCF readers must skip and ignore property records of unrecognized
430 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 properties that it _does_ recognize, and instead reads the amount of
433 payload it knows this property to have. This means that a property
434 record is not itself extensible: one cannot piggyback extra data onto
435 an existing property record by increasing its length. Also, some
436 historical versions of GIMP actually stored the wrong length for
437 some properties, so there are XCF files with misleading property
438 length information in circulation. For maximal compatibility, an XCF
439 reader should endeavor to know the native lengths of as many
440 properties as possible and fall back to the length word only for truly
441 unknown property types.
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 for properties that contain lists of subitems, in which the lists
448 should generally be concatenated. An XCF writer should never
449 deliberately duplicate properties within a single property list.
452 Parasites
453 ---------
455 Parasites provide a second level of extensibility.
456 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 parasites. GIMP plug-ins can access the parasites of an image
459 component through the API and can define their own parasite
460 names which will be ignored by other plug-ins.
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.
465 The PROP_PARASITE property stores the parasites of the image, layers
466 and channels and the PROP_VECTORS property those of the paths.
468 The number of parasites there is not directly encoded; the list ends when
469 the total length of the parasite data read equals the property payload length.
471 GIMP's XCF reader checks that the combined size of all parasites
472 in the property precisely equals the length word, so it is safe for
473 a reader to use the length word to skip the property without parsing
474 the individual parasites.
476 The parasite content may be binary, but often a textual encoding is
477 chosen in order to spare the writing and reading code of having to deal
478 with byte ordering.
480 There can only be one parasite with a given name attached to
481 each element of the image. Some versions of GIMP will
482 erroneously write some parasites twice in the same property list;
483 XCF readers must be prepared to gracefully ignore all but the
484 last instance of a parasite name in each property list.
486 TODO: How shall parasite readers handle lists in duplicate parasites?
488 Selection
489 ---------
491 If the current selection in the editor is nonempty, then GIMP stores it
492 as a channel in the XCF file. Pixels with a value of 255 belong to the
493 selection; pixels with a value of 0 don't, and pixels with intermediate
494 values are partially selected.
497 Floating selection
498 ------------------
500 A floating selection is a selection, that is attached to a particular
501 layer, channel or layer mask.
503 Technically it is handled as a layer with alpha.
505 If a floating selection exists, it must always be the first layer in
506 the layer list, but it is not rendered at that position in the layer stack.
507 Instead it is logically attached to another layer, or a channel or layer mask,
508 and the content of the floating selection is combined with ("anchored to")
509 that drawable before it is used to render the visible image.
511 The floating selection must not have a layer mask of its own, but if
512 an ordinary (not floating) selection also exists, it will be used as
513 a layer mask for the floating selection.
515 If a floating selection exists, it must also be the active layer.
517 Because the floating selection is modal and ephemeral, users rarely
518 save XCF files containing a floating selection. It may be acceptable
519 for third-party XCF consumers to ignore the floating selection or
520 explicitly refuse to process it.
523 Tattoos
524 -------
526 A tattoo is a unique and permanent identifier attached to a drawable or path
527 that can be used to uniquely identify it within an image even between sessions.
529 The tattoo of the image, a layer or channel is stored in the PROP_TATTOO
530 property, a tattoo for a path in the PROP_VECTORS property.
532 The PROP_TATTOO property of the entire image stores a "high-water
533 mark" for the entire image; it is greater than OR EQUAL TO any
534 tattoo for an element of the image. It allows efficient generation
535 of new unused tattoo values and also prevents old tattoo numbers
536 from being reused within a single image, lest plug-ins that use
537 the tattoos for bookkeeping get confused.
539 An XCF file must either provide tattoo values for all its elements
540 or for none of them. GIMP will invent fresh tattoos when it
541 reads in tattoo-less elements, but it does not attempt to keep them
542 different from ones specified explicitly in the file.
543 TODO: can this cause confusion and hard-to-find errors? If so, fix.
546 Text
547 ----
549 GIMP stores text in plain layers with parasites for the text and formatting
550 and PROP_TEXT_LAYER_FLAGS for flags.
553 Vector paths
554 ------------
556 GIMP stores vector paths as properties of the image.
557 If all paths are continuous sequences of Bezier strokes, then GIMP uses
558 the PROP_PATHS property, otherwise PROP_VECTORS. PROP_PATHS is for old
559 files from GIMP up to version 1.2.
562 2. GENERAL PROPERTIES
563 =====================
565 This chapter describes the formats of the defined property records that
566 can appear in more than one context in an XCF file.
568 PROP_COLOR_TAG (since GIMP 2.10.0, commit 4f9095798d0)
569 uint32 34 Type identification
570 uint32 4 Four bytes of payload
571 uint32 tag Color tag of the layer; one of
572 0: None
573 1: Blue
574 2: Green
575 3: Yellow
576 4: Orange
577 5: Brown
578 6: Red
579 7: Violet
580 8: Gray
582 PROP_COLOR_TAG can be assigned to layers, channels and paths. They are
583 only organisational properties and have no consequence on render.
585 PROP_END
586 uint32 0 Type identification
587 uint32 0 PROP_END has no payload.
589 The PROP_END pseudo-property marks the end of any property list.
591 PROP_FLOAT_OPACITY (essential, since GIMP 2.10.0, commit a2ad257711a)
592 uint32 33 Type identification
593 uint32 4 Four bytes of payload
594 float opacity Opacity on a scale from 0.0 (fully transparent) to
595 1.0 (fully opaque)
597 PROP_FLOAT_OPACITY records the overall opacity setting for the layer
598 or channel. Since GIMP 2.10.0, it always appears in the property list
599 of layers and channels after PROP_OPACITY, which saves the same value,
600 yet with integer precision. This way, new readers can overwrite the
601 8-bit value with proper precision whereas older readers can simply
602 skip PROP_FLOAT_OPACITY if unknown.
604 PROP_LINKED (editing state)
605 uint32 9 Type identification
606 uint32 4 Four bytes of payload
607 uint32 linked 1 if the layer is linked; 0 if not
609 PROP_LINKED controls the behavior of Transform tools with a layer,
610 channel or path. If a Transform tool is used to transform one of them
611 all other linked elements will be transformed the same way.
612 It appears in the property list for layers, channels and paths.
614 PROP_LOCK_CONTENT (since version 3, editing state)
615 uint32 28 Type identification
616 uint32 4 Four bytes of payload
617 uint32 locked 1 if the content is locked; 0 if not
619 PROP_LOCK_CONTENT specifies whether the layer, channel or path is locked,
620 i.e. cannot be edited.
622 PROP_LOCK_POSITION (since GIMP 2.10.0, commit d4933b30526, editing state)
623 uint32 32 Type identification
624 uint32 4 Four bytes of payload
625 uint32 locked 1 if the position is locked; 0 if not
627 PROP_LOCK_POSITION specifies whether the layer, channel or path's
628 position is locked, i.e. cannot be transformed (translation, etc.).
630 PROP_OPACITY (essential)
631 uint32 6 Type identification
632 uint32 4 Four bytes of payload
633 uint32 opacity Opacity on a scale from 0 (fully transparent) to
634 255 (fully opaque)
636 PROP_OPACITY records the overall opacity setting for the layer or channel.
637 It appears in the property list of layers and channels.
639 Note that though GIMP's user interface displays the opacity as a percentage,
640 it is actually stored on a 0-255 scale. Also note that this opacity value
641 is stored as a 32-bit quantity even though it has been scaled to
642 fit exactly in a single byte.
644 When reading old XCF files that lack this property, full opacity
645 should be assumed.
647 While this property continues to be stored for compatibility, the new
648 property PROP_FLOAT_OPACITY since GIMP 2.10.0 must override the value
649 of PROP_OPACITY with float precision.
651 PROP_PARASITES
652 uint32 21 Type identification
653 uint32 plength Total length of the following payload data in bytes
654 ,----------------- Repeat for each parasite:
655 | string name Name of the parasite
656 | uint32 flags Flags of the parasite
657 | uint32 pplength Length of the payload data in bytes
658 | byte[n] ... Parasite-specific payload
659 `--
661 PROP_PARASITES stores parasites. It can contain multiple parasite records.
662 See "Basic concepts" and the file parasites.txt for more information about
663 parasites.
664 This property can appear in any property list.
666 PROP_TATTOO (internal GIMP state)
667 uint32 20 Type identification
668 uint32 4 Four bytes of payload
669 uint32 tattoo Nonzero unsigned integer identifier
671 PROP_TATTOO is an unique identifier for the denoted image, channel or layer.
672 It appears in the property list of layers, channels, and the image.
674 PROP_VISIBLE (essential)
675 uint32 8 Type identification
676 uint32 4 Four bytes of payload
677 uint32 visible 1 if the layer/channel is visible; 0 if not
679 PROP_VISIBLE specifies the visibility of a layer or channel.
680 It appears in the property list for layers and channels.
681 For the visibility of a path see the PROP_VECTORS property.
683 When reading old XCF files that lack this property, assume that
684 layers are visible and channels are not.
687 3. THE IMAGE STRUCTURE
688 ======================
690 Header
691 ------
693 The image structure always starts at offset 0 in the XCF file.
695 byte[9] "gimp xcf " File type identification
696 byte[4] version XCF version
697 "file": version 0
698 "v001": version 1
699 "v002": version 2
700 "v003": version 3
701 byte 0 Zero marks the end of the version tag.
702 uint32 width Width of canvas
703 uint32 height Height of canvas
704 uint32 base_type Color mode of the image; one of
705 0: RGB color
706 1: Grayscale
707 2: Indexed color
708 (see enum GimpImageBaseType
709 in libgimpbase/gimpbaseenums.h)
710 uint32 precision Image precision; this field is only present for
711 XCF 4 or over (since GIMP 2.10.0). Its value for
712 XCF 7 or over is one of:
713 100: 8-bit linear integer
714 150: 8-bit gamma integer
715 200: 16-bit linear integer
716 250: 16-bit gamma integer
717 300: 32-bit linear integer
718 350: 32-bit gamma integer
719 500: 16-bit linear floating point
720 550: 16-bit gamma floating point
721 600: 32-bit linear floating point
722 650: 32-bit gamma floating point
723 700: 64-bit linear floating point
724 750: 64-bit gamma floating point
725 For XCF 4 (which was a development version, hence
726 this format should not be found often and may be
727 ignored by readers), its value may be one of:
728 0: 8-bit gamma integer
729 1: 16-bit gamma integer
730 2: 32-bit linear integer
731 3: 16-bit linear floating point
732 4: 32-bit linear floating point
733 For XCF 5 or 6 (which were development versions,
734 hence these formats may be ignored by readers),
735 its value may be one of:
736 100: 8-bit linear integer
737 150: 8-bit gamma integer
738 200: 16-bit linear integer
739 250: 16-bit gamma integer
740 300: 32-bit linear integer
741 350: 32-bit gamma integer
742 400: 16-bit linear floating point
743 450: 16-bit gamma floating point
744 500: 32-bit linear floating point
745 550: 32-bit gamma floating point
746 NOTE: XCF 3 or older's precision was always
747 "8-bit gamma integer".
748 property-list Image properties
749 ,----------------- Repeat once for each layer, topmost layer first:
750 | pointer lptr Pointer to the layer structure.
751 `--
752 uint32 0 Zero marks the end of the array of layer pointers.
753 ,------------------ 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.
758 The last 4 characters of the initial 13-character identification string are
759 a version indicator. The version will be higher than 3 if the correct
760 reconstruction of pixel data from the file requires that the reader
761 understands features not described in this specification. On the other
762 hand, optional extra information that can be safely ignored will not
763 cause the version to increase.
765 GIMP's XCF writer dynamically selects the lowest version that will
766 allow the image to be represented. Third-party XCF writers should do
767 likewise.
769 Version numbers from v100 upwards have been used by CinePaint, which
770 originated as a 16-bit fork of GIMP, see "Scope".
773 Image properties
774 ----------------
776 The following properties are found only in the property list of the
777 image structure. Additionally the list can also contain the properties
778 PROP_END, PROP_PARASITES and PROP_TATTOO, defined in chapter 2.
780 PROP_COLORMAP (essential)
781 uint32 1 Type identification
782 uint32 3*n+4 Payload length in bytes
783 uint32 n Number of colors in the color map (should be <256)
784 ,------------ Repeat n times:
785 | byte r Red component of a color map color
786 | byte g Green component of a color map color
787 | byte b Blue component of a color map color
788 `--
790 PROP_COLORMAP stores the color map.
791 It appears in all indexed images.
793 The property will be ignored if it is encountered in an RGB or grayscale
794 image. The current GIMP will not write a color map with RGB or
795 grayscale images, but some older ones occasionally did, and readers
796 should be prepared to gracefully ignore it in those cases.
798 Note that in contrast to the palette data model of, for example, the
799 PNG format, an XCF color map does not contain alpha components, and
800 there is no color map entry for "transparent"; the alpha channel of
801 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 reinterpret the pixel data as a grayscale image if they meet a
807 version-0 indexed image.
809 Beware that the payload length of the PROP_COLORMAP in particular
810 cannot be trusted: some historic releases of GIMP erroneously
811 wrote n+4 instead of 3*n+4 into the length word (but still actually
812 followed it by 3*n+4 bytes of payload).
814 PROP_COMPRESSION (essential)
815 uint32 17 Type identification
816 uint32 1 One byte of payload
817 byte comp Compression indicator; one of
818 0: No compression
819 1: RLE encoding
820 2: zlib compression
821 3: (Never used, but reserved for some fractal compression)
823 PROP_COMPRESSION defines the encoding of pixels in tile data blocks in the
824 entire XCF file. See chapter 7 for details.
826 Note that unlike most other properties whose payload is always a
827 small integer, PROP_COMPRESSION does _not_ pad the value to a full
828 32-bit integer.
830 Contemporary GIMP versions always write files with comp=1. It is unknown to
831 the author of this document whether versions that wrote completely
832 uncompressed (comp=0) files ever existed.
834 PROP_GUIDES (editing state)
835 uint32 18 Type identification
836 uint32 5*n Five bytes of payload per guide
837 ,--------------- Repeat n times:
838 | int32 coord Guide coordinate
839 | byte o Guide orientation; one of
840 | 1: The guide is horizontal, and coord is a y coordinate
841 | 2: The guide is vertical, and coord is an x coordinate
842 (see enum XcfOrientationType in /app/xcf/xcf-private.h)
843 `--
845 PROP_GUIDES stores the horizontal or vertical positions of guides.
846 It appears if any guides have been defined.
848 Some old XCF files define guides with negative coordinates; those
849 should be ignored by readers.
851 PROP_PATHS
852 uint32 23 Type identification
853 uint32 plength Total length of the following payload in bytes
854 uint32 aindex Index of the active path
855 uint32 n Number of paths that follow
856 path_1
857 path_2
858 ...
859 path_n
861 PROP_PATHS stores the paths.
863 Each path has one of three formats
865 Format 1: Format 2: Format 3:
866 string string string name Name of the path
867 uint32 uint32 uint32 linked 1 if the path is linked;
868 0 if not
869 byte byte byte state 4 if closed; 2 otherwise
870 (for GIMP 1.2 compatibility)
871 uint32 uint32 uint32 closed 1 if path is closed;
872 0 otherwise
873 uint32 uint32 uint32 np Number of points
874 uint32=1 uint32=2 uint32=3 version Version indicator
875 uint32 uint32 dummy Ignored; always set to 1
876 uint32 tattoo 0 if none, or see PROP_TATTOO
877 ,---------- ,---------- ,------------------ Repeat for np points:
878 | int32 | int32 | int32 type Type of point; one of
879 | | | 0: Anchor
880 | | | 1: Bezier control point
881 | | | (for GIMP 1.2 compatibility)
882 | int32 | float | float x X coordinate
883 | int32 | float | float y Y coordinate
884 `-- `-- `--
886 This format is used to save path data if all paths in the image are
887 continuous sequences of Bezier strokes. Otherwise GIMP stores the paths in
888 PROP_VECTORS.
890 Note: the attribute 'linked' was formerly erroneously called 'locked'
891 (but meant 'linked' anyway).
893 A closed path is a path which has the last and the first point connected,
894 for instance a triangle.
896 GIMP's XCF reader _does not_ check that the total size of all path
897 specifications in the property precisely equals the plength word.
898 Note that this is different to PROP_VECTORS.
900 TODO: Clarify: PROP_PATHS cannot represent parasites for paths, but the
901 XCF writer does not check whether all paths are parasite-less when
902 choosing which property to use, so path parasites may be lost upon
903 saving). Is this by design or a bug?
905 There may be paths that declare a length of 0 points; these should
906 be ignored.
908 PROP_RESOLUTION (not editing state, but not _really_ essential either)
909 uint32 19 Type identification
910 uint32 8 Eight bytes of payload
911 float hres Horizontal resolution in pixels per inch (ppi)
912 float vres Vertical resolution in pixels per inch (ppi)
914 PROP_RESOLUTION gives the intended physical size of the image's pixels.
916 Note that for many images, such as graphics created for the web, the
917 creator does not really have an intended resolution in mind but
918 intends the image to be shown at whatever the natural resolution of
919 the viewer's monitor is. Similarly, photographs commonly do not have
920 a well-defined target size and are intended to be scaled to fit the
921 available space instead. Therefore readers should not interpret the
922 information in this property too rigidly; GIMP writes it to XCF
923 files unconditionally, even if the user has not explicitly chosen a
924 resolution.
926 PROP_SAMPLE_POINTS
927 uint32 17 Type identification
928 uint32 plength Total length of the following payload in bytes
929 ,---------------- Repeat for each sample point:
930 | uint32 x X coordinate
931 | uint32 y Y coordinate
932 `--
934 PROP_UNIT (editing state)
935 uint32 22 Type identification
936 uint32 4 Four bytes of payload
937 uint32 uid Unit identifier; one of
938 1: Inches (25.4 mm)
939 2: Millimeters (1 mm)
940 3: Points (127/360 mm)
941 4: Picas (127/30 mm)
943 PROP_UNIT specifies the units used to specify resolution in the Scale Image
944 and Print Size dialogs. Note that this is used only in the user interface;
945 the PROP_RESOLUTION property is always stored in ppi.
947 To specify non-standard units use PROP_USER_UNIT.
949 PROP_USER_UNIT (editing state)
950 uint32 24 Type identification
951 uint32 plength Total length of the following payload in bytes
952 float factor 1 inch divided by the length of the unit
953 uint32 digits Number of decimal digits used with the unit
954 string id An identifier for the unit
955 string symbol Short symbol for the unit
956 string abbrev Abbreviation for the unit
957 string sname Unit name in singular form
958 string pname Unit name in plural form
960 PROP_USER_UNIT allows the use of units that are not on the standard list.
961 It is an alternative to PROP_UNIT.
962 TODO: How is this related to the unitrc file?
964 PROP_VECTORS
965 uint32 25 Type identification
966 uint32 plength Total length of the following payload in bytes
967 uint32 1 Version tag; so far always 1
968 uint32 aindex Index of the active path
969 uint32 n Number of paths that follow
970 ,---------------------- Repeat n times:
971 | string name Name of the path
972 | uint32 tattoo Tattoo of the path (see PROP_TATTOO), or 0
973 | uint32 visible 1 if path is visible, 0 if not
974 | uint32 linked 1 if path is linked, 0 if not
975 | uint32 m Number of parasites for the path
976 | 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 | | uint32 1 The stroke is a Bezier stroke
982 | | uint32 closed 1 if path is closed; 0 otherwise
983 | | uint32 nf Number of floats given for each point;
984 | | must be >= 2 and <= 6.
985 | | uint32 np Number of control points for this stroke
986 | | ,------------------ Repeat np times:
987 | | | uint32 type Type of the first point; one of
988 | | | 0: Anchor
989 | | | 1: Bezier control point
990 | | | float x X coordinate
991 | | | float y Y coordinate
992 | | | float pressure Only if nf >= 3; otherwise defaults to 1.0
993 | | | float xtilt Only if nf >= 4; otherwise defaults to 0.5
994 | | | float ytilt Only if nf >= 5; otherwise defaults to 0.5
995 | | | float wheel Only if nf == 6; otherwise defaults to 0.5
996 | | `--
997 | `--
998 `--
1000 PROP_VECTORS stores the paths.
1002 It appears if all paths are continuous sequences of Bezier strokes;
1003 otherwise PROP_PATHS is used.
1005 GIMP's XCF reader checks that the total size of all path
1006 specifications in the property precisely equals the plength word, so
1007 it is safe for a reader to use the plength word to skip the property
1008 without parsing the individual parasites. (Note that this is _not_
1009 the case for PROP_PATHS).
1012 4. THE CHANNEL STRUCTURE
1013 ========================
1015 Channel structures are pointed to from layer structures (in case of
1016 layer masks) or from the master image structure (for all other
1017 channels).
1019 uint32 width Width of the channel
1020 uint32 height Height of the channel
1021 string name Name of the channel
1022 property-list Channel properties
1023 pointer hptr Pointer to the hierarchy structure with the pixels.
1025 The width and height of the channel must be the same as those of its
1026 parent structure (the layer in the case of layer masks; the canvas for
1027 all other channels).
1030 Channel properties
1031 ------------------
1033 The following properties are found only in the property list of
1034 channel structures. Additionally the list can also contain the
1035 properties: PROP_COLOR_TAG, PROP_END, PROP_FLOAT_OPACITY, PROP_LINKED,
1036 PROP_LOCK_CONTENT, PROP_LOCK_POSITION, PROP_OPACITY, PROP_PARASITES,
1037 PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.
1039 PROP_ACTIVE_CHANNEL (editing state)
1040 uint32 3 Type identification
1041 uint32 0 PROP_ACTIVE_CHANNEL has no payload
1043 The presence of PROP_ACTIVE_CHANNEL indicates that the channel is the
1044 currently active channel.
1045 It appears in the property list of the currently active channel.
1046 Only zero or one channel must have this property at any time.
1048 PROP_COLOR
1049 uint32 16 Type identification
1050 uint32 3 Three bytes of payload
1051 byte r Red component of color
1052 byte g Green component of color
1053 byte b Blue component of color
1055 PROP_COLOR gives the color of the screen that is used to represent the channel
1056 when it is visible in the UI.
1057 (The alpha of the screen is given as the channel's PROP_OPACITY).
1058 TODO: What exactly does "screen" mean here?
1060 While this property continues to be stored for compatibility, the new
1061 property PROP_FLOAT_COLOR since GIMP 2.10.0 must override the value
1062 of PROP_COLOR with float precision.
1064 PROP_FLOAT_COLOR (since GIMP 2.10.0, essential, commit 10360c9e130)
1065 uint32 38 Type identification
1066 uint32 12 Twelve bytes of payload
1067 float r Red component of color
1068 float g Green component of color
1069 float b Blue component of color
1071 PROP_FLOAT_COLOR gives the color of the screen that is used to
1072 represent the channel when it is visible in the UI. Each component is
1073 in the range 0.0 to 1.0.
1074 PROP_FLOAT_COLOR stores the same property as PROP_COLOR with float
1075 precision. Since GIMP 2.10.0, it always appears in the property list
1076 of channels after PROP_COLOR. This way, new readers can overwrite the
1077 8-bit value with proper precision whereas older readers can simply
1078 skip PROP_FLOAT_COLOR if unknown.
1080 PROP_SELECTION (editing state?)
1081 uint32 4 Type identification
1082 uint32 0 PROP_SELECTION has no payload
1084 PROP_SELECTION appears in the property list of the channel structure that
1085 represents the selection mask.
1087 PROP_SHOW_MASKED (editing state)
1088 uint32 14 Type identification
1089 uint32 4 Four bytes of payload
1090 uint32 masked 1 if the channel is shown as a mask, 0 if not
1092 PROP_SHOW_MASKED specifies whether a channel is shown as a mask.
1095 5. THE LAYER STRUCTURE
1096 ======================
1098 Layer structures are pointed to from a list of layer pointers in the
1099 master image structure.
1101 uint32 width Width of the layer
1102 uint32 height Height of the layer
1103 uint32 type Color mode of the layer: one of
1104 0: RGB color without alpha
1105 1: RGB color with alpha
1106 2: Grayscale without alpha
1107 3: Grayscale with alpha
1108 4: Indexed without alpha
1109 5: Indexed with alpha
1110 (see enum GimpImageType in libgimpbase/gimpbaseenums.h)
1111 string name Name of the layer
1112 property-list Layer properties
1113 pointer hptr Pointer to the hierarchy structure with the pixels
1114 pointer mptr Pointer to the layer mask (a channel structure), or 0
1116 The color mode of a layer must match that of the entire image.
1117 All layers except the bottommost one _must_ have an alpha channel. The bottom
1118 layer _can_ have an alpha channel.
1119 TODO: Check whether the redundant color mode storage potentially causes errors.
1120 Wouldn't a alpha bit/flag be sufficient?
1122 Exception: If the layer is a floating selection and is attached to a channel or
1123 layer mask, then its color mode must be 3 (grayscale with alpha).
1126 Layer properties
1127 ----------------
1129 The following properties are found only in the property list of layer
1130 structures. Additionally the list can also contain the properties:
1131 PROP_COLOR_TAG, PROP_END, PROP_FLOAT_OPACITY, PROP_LINKED,
1132 PROP_LOCK_CONTENT, PROP_LOCK_POSITION, PROP_OPACITY, PROP_PARASITES,
1133 PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.
1135 PROP_ACTIVE_LAYER (editing state)
1136 uint32 2 Type identification
1137 uint32 0 PROP_ACTIVE_LAYER has no payload
1139 The presence of PROP_ACTIVE_LAYER indicates that the channel is the
1140 currently active layer.
1141 Only zero or one layer must have this property at any time.
1143 PROP_APPLY_MASK (essential)
1144 uint32 11 Type identification
1145 uint32 4 Four bytes of payload
1146 uint32 apply 1 if the layer mask should be applied, 0 if not
1148 PROP_APPLY_MASK specifies whether the layer mask shall be applied
1149 to the layer.
1150 If the property does not appear for a layer which has a layer mask,
1151 it defaults to true.
1153 Robust readers should force this to false if the layer has no layer
1154 mask. Writers should never save this as true unless the layer has a
1155 layer mask.
1157 PROP_COMPOSITE_MODE (since GIMP 2.10.0, essential, commit 8634b5cbc31)
1158 uint32 35 Type identification
1159 uint32 4 Four bytes of payload
1160 int32 mode Composite mode of the layer; one of:
1161 1: Union
1162 2: Clip to backdrop
1163 3: Clip to layer
1164 4: Intersection
1165 See below for meaning of negative values.
1167 PROP_COMPOSITE_MODE records the composite mode, for layers only. A
1168 negative value means that the composite mode was left to "Auto",
1169 rather than explicitly set, while we still store the mapping of "Auto"
1170 at the time of saving the XCF, by inverting it. For instance if "mode"
1171 is -2, it means that "Auto" was set, which corresponds to "Clip to
1172 backdrop" for this specific layer mode.
1173 The reason for this is that we must always keep the expected output,
1174 even if we were to change the mapping of "Auto" in the future.
1176 Note: as you may guess, "Auto" maps to different actual composite
1177 modes, depending on PROP_MODE. This system makes so you don't have to
1178 know this mapping. A XCF reader may just use the absolute value of
1179 PROP_COMPOSITE_MODE.
1181 PROP_COMPOSITE_SPACE (since GIMP 2.10.0, essential, commit 8634b5cbc31)
1182 uint32 36 Type identification
1183 uint32 4 Four bytes of payload
1184 int32 space Composite space of the layer; one of:
1185 1: RGB (linear)
1186 2: RGB (perceptual)
1187 3: LAB
1188 See below for meaning of negative values.
1190 PROP_COMPOSITE_SPACE records the composite mode, for layers only. A
1191 negative value means that the composite space was left to "Auto",
1192 rather than explicitly set, while we still store the mapping of "Auto"
1193 at the time of saving the XCF, by inverting it. For instance if "space"
1194 is -3, it means that "Auto" was set, which corresponds to "LAB"
1195 composite space for this specific layer mode.
1196 The reason for this is that we must always keep the expected output,
1197 even if we were to change the mapping of "Auto" in the future.
1199 Note: as you may guess, "Auto" maps to different actual composite
1200 spaces, depending on PROP_MODE. This system makes so you don't have to
1201 know this mapping. A XCF reader may just use the absolute value of
1202 PROP_COMPOSITE_SPACE.
1204 PROP_BLEND_SPACE (since GIMP 2.10.0, essential, commit 8634b5cbc31)
1205 uint32 36 Type identification
1206 uint32 4 Four bytes of payload
1207 int32 space Composite space of the layer; one of:
1208 1: RGB (linear)
1209 2: RGB (perceptual)
1210 3: LAB
1211 See below for meaning of negative values.
1213 PROP_BLEND_SPACE records the blend mode, for layers only. A negative
1214 value means that the composite space was left to "Auto", rather than
1215 explicitly set, while we still store the mapping of "Auto" at the time
1216 of saving the XCF, by inverting it. For instance if "space" is -3, it
1217 means that "Auto" was set, which corresponds to "LAB" composite space
1218 for this specific layer mode.
1219 The reason for this is that we must always keep the expected output,
1220 even if we were to change the mapping of "Auto" in the future.
1222 Note: as you may guess, "Auto" maps to different actual blend spaces,
1223 depending on PROP_MODE. This system makes so you don't have to know
1224 this mapping. A XCF reader may just use the absolute value of
1225 PROP_BLEND_SPACE.
1227 PROP_EDIT_MASK (editing state)
1228 uint32 12 Type identification
1229 uint32 4 Four bytes of payload
1230 uint32 editing 1 if the layer mask is currently being edited, 0 if not
1232 PROP_EDIT_MASK specifies whether the layer mask is currently being edited.
1233 If the property does not appear for a layer which has a layer mask,
1234 it defaults to false.
1236 Robust readers should force this to false if the layer has no layer
1237 mask. Writers should never save this as true unless the layer has a
1238 layer mask.
1240 PROP_FLOATING_SELECTION (essential)
1241 uint32 5 Type identification
1242 uint32 4 Four bytes of payload
1243 pointer ptr Pointer to the layer or channel the floating selection is
1244 attached to
1246 PROP_FLOATING_SELECTION indicates that the layer is the floating selection
1247 and specifies the pointer to the layer, channel and layer mask it is attached
1248 to.
1249 It appears in the property list for the layer that is the floating selection.
1250 Only zero or one layer must have this property at any time.
1252 PROP_GROUP_ITEM (since version 3)
1253 uint32 29 Type identification
1254 uint32 0 PROP_GROUP_ITEM has no payload
1256 PROP_GROUP_ITEM indicates that the layer is a layer group.
1257 It appears in the property list if the layer is a layer group.
1259 PROP_ITEM_PATH (since version 3)
1260 uint32 30 Type identification
1261 uint32 plength Total length of the following payload in bytes
1262 item-path List of pointers, represented as uint32 values
1264 TODO: The code reads that it is a list of pointers, represented as uint32
1265 integers and somehow in the context of layers. What this is for and what
1266 do the property values mean?
1268 PROP_GROUP_ITEM_FLAGS (since version 3)
1269 uint32 31 Type identification
1270 uint32 4 Four bytes of payload
1271 uint32 flags Flags for the layer, or'ed together from the following set:
1272 0x00000001 Layer group is expanded.
1273 (see enum XcfGroupItemFlagsType in app/xcf/xcf-private.h)
1275 PROP_GROUP_ITEM_FLAGS specifies flags for the layer group.
1276 It appears in the property list if the layer is a layer group.
1278 PROP_LOCK_ALPHA (editing state)
1279 (called PROP_PRESERVE_TRANSPARENCY in GIMP before 2.3)
1280 uint32 10 Type identification
1281 uint32 4 Four bytes of payload
1282 uint32 lock_alpha 1 if alpha is locked; 0 if not
1284 PROP_LOCK_ALPHA prevents all drawing tools in GIMP from increasing the alpha
1285 of any pixel in the layer. Decreasing the alpha is possible.
1287 PROP_MODE (essential)
1288 uint32 7 Type identification
1289 uint32 4 Four bytes of payload
1290 unit32 mode Layer mode; one of
1291 * Since "ancient times":
1293 0: Normal (legacy)
1294 1: Dissolve (legacy) [random dithering to discrete alpha)
1295 2: Behind (legacy) [not selectable in the GIMP UI]
1296 3: Multiply (legacy)
1297 4: Screen (legacy)
1298 5: Old broken Overlay
1299 6: Difference (legacy)
1300 7: Addition (legacy)
1301 8: Subtract (legacy)
1302 9: Darken only (legacy)
1303 10: Lighten only (legacy)
1304 11: Hue (HSV) (legacy)
1305 12: Saturation (HSV) (legacy)
1306 13: Color (HSL) (legacy)
1307 14: Value (HSV) (legacy)
1308 15: Divide (legacy)
1309 16: Dodge (legacy)
1310 17: Burn (legacy)
1311 18: Hard Light (legacy)
1313 * Since XCF 2 (GIMP 2.8)
1314 19: Soft light (legacy)
1315 20: Grain extract (legacy)
1316 21: Grain merge (legacy)
1317 22: Color erase (legacy)
1319 * Since XCF 9 (GIMP 2.10.0)
1320 23: Overlay
1321 24: Hue (LCH)
1322 25: Chroma (LCH)
1323 26: Color (LCH)
1324 27: Lightness (LCH)
1326 * Since XCF 10 (GIMP 2.10.0)
1327 28: Normal
1328 29: Behind
1329 30: Multiply
1330 31: Screen
1331 32: Difference
1332 33: Addition
1333 34: Substract
1334 35: Darken only
1335 36: Lighten only
1336 37: Hue (HSV)
1337 38: Saturation (HSV)
1338 39: Color (HSL)
1339 40: Value (HSV)
1340 41: Divide
1341 42: Dodge
1342 43: Burn
1343 44: Hard light
1344 45: Soft light
1345 46: Grain extract
1346 47: Grain merge
1347 48: Vivid light
1348 49: Pin light
1349 50: Linear light
1350 51: Hard mix
1351 52: Exclusion
1352 53: Linear burn
1353 54: Luma/Luminance darken only
1354 55: Luma/Luminance lighten only
1355 56: Luminance
1356 57: Color erase
1357 58: Erase
1358 59: Merge
1359 60: Split
1360 61: Pass through
1362 PROP_MODE specifies the layer mode.
1364 When reading old XCF files that lack this property, assume mode==0.
1365 The effects of the various layer modes are defined in the document
1366 compositing.txt.
1368 Beware that GIMP ignores all other layer modes than Normal and
1369 Dissolve for the bottommost visible layer of the image. If a mode>=3 has
1370 been specified for this layer it will interpreted as mode==0 (Normal) for
1371 display and flattening purposes. This effect happens for one layer
1372 only: even if the bottommost visible layer covers only some (or
1373 none) of the canvas, it will be the only layer to have its mode
1374 forced to Normal.
1376 Implementation note: all layer modes are implemented as GEGL
1377 operations. The list can be found at:
1378 app/operations/layer-modes/gimp-layer-modes.c
1379 The "op_name" value in particular gives the operation name allowing
1380 reader developers to search for this string. For instance, the
1381 "Normal" layer mode is implemented as the "gimp:normal" GEGL operation
1382 whose implementation can be found at:
1383 app/operations/layer-modes/gimpoperationnormal.c
1385 NOTE: The layer modes 'Old broken Overlay' and 'Soft light (legacy)' are identical.
1387 PROP_OFFSETS (essential)
1388 uint32 15 Type identification
1389 uint32 8 Eight bytes of payload
1390 int32 xoffset Horizontal offset
1391 int32 yoffset Vertical offset
1393 PROP_OFFSETS gives the coordinates of the upper left corner of the layer
1394 relative to the upper left corner of the canvas.
1395 The coordinates can be negative; this corresponds to a layer that
1396 extends to the left of or above the canvas boundary.
1398 When reading old XCF files that lack this property, assume (0,0).
1400 PROP_SHOW_MASK (editing state)
1401 uint32 13 Type identification
1402 uint32 4 Four bytes of payload
1403 uint32 visible 1 if the layer mask is visible, 0 if not
1405 PROP_SHOW_MASK specifies whether the layer mask is visible.
1406 If the property does not appear for a layer which has a layer mask,
1407 it defaults to false.
1409 Robust readers should force this to false if the layer has no layer
1410 mask. Writers should never save this as true unless the layer has a
1411 layer mask.
1413 PROP_TEXT_LAYER_FLAGS
1414 uint32 26 Type identification
1415 uint32 4 Four bytes of payload
1416 uint32 flags Flags, or'ed together from the following set:
1417 0x00000001 Do _not_ change the layer name if the text
1418 content is changed
1419 0x00000002 The pixel data has been painted to or otherwise
1420 modified since the text was rendered.
1421 (see the anonymous enum in app/text/gimptextlayer-xcf.c)
1423 PROP_TEXT_LAYER_FLAGS specifies the text layer behavior by flags.
1424 It appears in property lists for text layers.
1425 The actual text (and other parameters such as font and color) is a
1426 parasite rather than a property.
1429 6. THE HIERARCHY STRUCTURE
1430 ==========================
1432 A hierarchy contains data for a rectangular array of pixels.
1433 It appears in a context: each layer and channel has a pointer to its hierarchy.
1435 uint32 width Width of the pixel array
1436 uint32 height Height of the pixel array
1437 uint32 bpp Number of bytes per pixel given
1438 3: RGB color without alpha
1439 4: RGB color with alpha
1440 1: Grayscale without alpha
1441 2: Grayscale with alpha
1442 1: Indexed without alpha
1443 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.
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.
1456 Levels
1457 ------
1459 The level structure is laid out as follows:
1461 uint32 width Width of the pixel array
1462 uint32 height Height of the pixel array
1463 ,----------------- 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.
1468 The width and height must be the same as the ones recorded in the
1469 hierarchy structure (except for the aforementioned dummy levels).
1471 Ceil(x) is the smallest integer not smaller than x.
1474 7. TILE DATA ORGANIZATION
1475 =========================
1477 The format of the data blocks pointed to by the tile pointers in the
1478 level structure of hierarchy differs according to the value of the
1479 PROP_COMPRESSION property of the main image structure. Current
1480 GIMP versions use RLE compression by default, and zlib compression
1481 optionally. Readers should nevertheless be prepared to meet the
1482 older uncompressed format.
1484 Both formats assume the width, height and byte depth of the tile are
1485 known from the context (namely, they are stored explicitly in the
1486 hierarchy structure for regular tiles). Both encodings store a linear sequence
1487 of width*height pixels, extracted from the tile in row-major,
1488 top-to-bottom, left-to-right order (the same as the reading direction
1489 of multi-line English text).
1491 In color modes with alpha information, the alpha value is the last of
1492 the 2 or 4 bytes for each pixel. In RGB color modes, the 3 (first)
1493 bytes for each pixel is the red intensity, the green intensity, and
1494 the blue intensity, in that order.
1496 Tile data, as other data in XCF format, is big-endian. In particular it
1497 means that pixel values are stored as big-endian when the precision is
1498 over 8-bit per channel.
1500 Warning: a bug during development was having pixel data saved in the
1501 host byte order before version 12, which means that any XCF file from
1502 version 7 to 11 may be broken when saved then loaded on machines with
1503 different byte orders (and we cannot know for sure which byte order was
1504 used for storage for these XCF versions, though little-endian may be a
1505 safe assumption, considering most end-user processors are little-endian
1506 nowadays). The stable GIMP 2.10.0 always outputs in big-endian and would
1507 only use XCF version 7 to 11 when precision is 8-bit. Therefore if a XCF
1508 reader tries to load a XCF 7 to 11 using over 8-bit precision, this XCF
1509 was created with a development version of GIMP (therefore unsupported)
1510 and byte-order is unspecified.
1512 Uncompressed tile data
1513 ----------------------
1515 In the uncompressed format the file first contains all the bytes for
1516 the first pixel, then all the bytes for the second pixel, and so on.
1518 zlib compressed tile data
1519 ------------------------
1521 In the zlib compressed format, each tile is compressed as-is (pixel
1522 after pixel) with zlib.
1524 RLE compressed tile data
1525 ------------------------
1527 In the Run-Length Encoded format, each tile consists of a run-length
1528 encoded stream of the first byte of each pixel, then a stream of the
1529 second byte of each pixel, and so forth. In each of the streams,
1530 multiple occurrences of the same byte value are represented in
1531 compressed form. The representation of a stream is a series of
1532 operations; the first byte of each operation determines the format and
1533 meaning of the operation (opcode):
1535 byte n For 0 <= n <= 126: a short run of identical bytes
1536 byte v Repeat this value n+1 times
1537 or
1538 byte 127 A long run of identical bytes
1539 byte p
1540 byte q
1541 byte v Repeat this value p*256 + q times
1542 or
1543 byte 128 A long run of different bytes
1544 byte p
1545 byte q
1546 byte[p*256+q] data Copy these verbatim to the output stream
1547 or
1548 byte n For 129 <= n <= 255: a short run of different bytes
1549 byte[256-n] data Copy these verbatim to the output stream
1551 The end of the stream for "the first byte of all pixels" (and the
1552 following similar streams) must occur at the end of one of these
1553 operations; it is not permitted to have one operation span the
1554 boundary between streams.
1556 The RLE encoding can cause degenerated encodings in which the original
1557 data stream may double in size (or grow to arbitrarily large sizes if
1558 (128,0,0) operations are inserted). Such encodings must be avoided, as
1559 GIMP's XCF reader expects that the size of an encoded tile is
1560 never more than 24 KB, which is only 1.5 times the unencoded size of a
1561 64x64 RGBA tile.
1563 A simple way for an XCF creator to avoid overflow is
1564 a) never using opcode 0 (but instead opcode 255)
1565 b) using opcodes 127 and 128 only for lengths larger than 127
1566 c) never emitting two "different bytes" opcodes next to each other
1567 in the encoding of a single stream.
1569 TODO: If each tile has a maximum of 64 pixels (resulting in a maximum of 64
1570 bytes for each color in this tile), do values>64 and long runs apply at all?
1573 8. MISCELLANEOUS
1574 ================
1577 The name XCF
1578 ------------
1580 The name XCF honors GIMP's origin at the eXperimental Computing
1581 Facility of the University of California at Berkeley.
1583 TODO: Integrate this document into the API doc.
1585 TODO: Some properties are denoted with "essential",
1586 "editing state", "not editing state, but not really
1587 essential either". What did the original author Henning Makholm mean?
1589 TODO: What will happen with the format after the GEGL
1590 port? AFAIK the ORA format will play a big role in
1591 the GEGL context (correct me if I'm wrong).
1592 Will XCF be dropped then or will ORA then be yet
1593 another import/export format like PSD etc.?