[gimp/osx-build: 48/50] Review, amend and update the XCF file format spec and parasites.txt
- From: Sven Claussner <sclaussner src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gimp/osx-build: 48/50] Review, amend and update the XCF file format spec and parasites.txt
- Date: Tue, 15 Jul 2014 03:18:20 +0000 (UTC)
commit fc467600b8c85400241b5c61716c8d2aa707136b
Author: Sven Claussner <sclaussner src gnome org>
Date: Sat Jul 12 07:26:36 2014 +0200
Review, amend and update the XCF file format spec and parasites.txt
XCF spec:
- Update to GIMP 2.8.10
- Clarify role of file formats in the save-vs.-export-context
- Rearrange outline
- Collect infos on basic concepts in one chapter
- Add table of contents
- Add File format version history
- Add note on image size
- Add open questions and TODOs
- Sort properties alphabetically
- Unify tiles and hierarchy examples
- Wording
- Cosmetic cleanups
Update parasites.txt:
- Replace SVN->Git
- Update contact e-mail address
- Add table of contents
devel-docs/compositing.txt | 274 +++++++
devel-docs/parasites.txt | 62 ++-
devel-docs/xcf.txt | 1841 ++++++++++++++++++++++----------------------
3 files changed, 1238 insertions(+), 939 deletions(-)
---
diff --git a/devel-docs/compositing.txt b/devel-docs/compositing.txt
new file mode 100644
index 0000000..d98b049
--- /dev/null
+++ b/devel-docs/compositing.txt
@@ -0,0 +1,274 @@
+===================================
+Compositing and layer modes in GIMP
+===================================
+
+This document describes the process of compositing layers and the layer modes
+in GIMP.
+
+License
+-------
+This is free documentation; you can modify and/or redistribute
+it according to the terms of the GNU General Public License
+as published by the Free Software Foundation, either version
+2 of the license, or (at your option) any later version.
+
+About this document
+-------------------
+
+This document was originally written by Henning Makholm and part of the
+XCF file format specification. Because the topics here are more general
+in the context of GIMP they have been moved into a separate document.
+
+9. COMPOSITING AND LAYER MODES
+===============================
+
+This section describes the "flattening" process that GIMP applies
+when a multi-layer image is displayed in the editor or exported to
+other image file formats. It is present for reference only; an XCF
+consumer may well elect to do something different with pixel data from
+the layers than flattening them.
+
+Most XCF consumers will need to react to the layer mode property of
+each layer; such a reaction must be informed by knowledge of how the
+different layer modes affect the flattening process. In some
+applications it might be acceptable for an XCF consumer to refuse
+processing images with layer modes other than "Normal", but such an
+application will probably not be considered fully XCF capable by its
+users.
+
+In this section we consider primary color (or grayscale) intensities
+and alpha values for pixels to be real numbers ranging from 0.0 to
+1.0. This makes many of the formulas easier; the reader is asked to
+keep in mind that a (linear) conversion from the integral 0..255 scale
+of the actual XCF scale is implied whenever data from the XCF file is
+mentioned.
+
+Any practical implementation of the computations specified below may
+suffer rounding errors; this specification do not detail how these are
+to be handled. GIMP itself rounds values to an integral number of
+255ths at many points in the computation. This specification does not
+specify exactly which these points are, and authors of XCF renderers
+that aim to reproduce the effects of GIMP's flattening down to the
+least significant bits are referred to studying its source code.
+
+In the description below, the variable letter "a" is used for alpha
+values. The variable letter "r", "g", "b" are used for primary
+intensities, "y" is used for grayscale intensities, and "i" is used
+for color map indexed. The letter "c" is used for the complete
+color information for a pixel; depending on the color mode of the
+image that is either an (r,g,b) triple, a y, or a c.
+
+The flattening process works independently for each pixel in the
+canvas area. The description of some layer modes in the GIMP manual
+may give the impression that they involve filters that let pixels
+influence neighbor pixels, but that is not true.
+
+This description does not attempt to preserve the color information
+for completely transparent pixels in a layer. If an application uses
+this color information, it should document explicitly how it behaves
+when transparent pixels from several different layers cover the same
+point of the canvas.
+
+Flattening overview
+-------------------
+
+This is how to compute the flattened result for a single pixel
+position (in theory, that is - efficient implementations will of
+course follow this procedure or an equivalent one for many pixels in
+parallel):
+
+1. Initialize a "working pixel" (a1,c1) to be completely transparent
+ (that is, a1=0.0 and the value of c1 is immaterial).
+
+2. Do the following for each visible layer in the image, starting with
+ the one that comes LAST in the master layer list:
+
+ 3. Ignore the layer if it is the floating selection, or if it
+ does not overlap the pixel position in question.
+
+ 4. Let (a2,c2) be the pixel data for the layer at the pixel
+ position in question. If the layer does not have an alpha
+ channel, then set a1 to 1.0.
+
+ 5. If the layer is the one that the floating selection is attached
+ to and the floating selection overlaps the pixel position in
+ question, then do the following:
+
+ 6. Let (a3,c3) be the pixel data for the floating selection
+ layer at the pixel position in question.
+
+ 7. If there is a selection channel, then let x be its value
+ at the pixel position in question, and set a3 to a3*x.
+
+ 8. Let m3 be the layer mode of the floating selection.
+
+ 9. Set (a2,c2) to COMPOSITE(a2,c2, a3,c3,m3).
+ The COMPOSITE function is defined below.
+
+ 10. If the layer has a layer mask and it is enabled, then let x be
+ the value of the layer mask at the pixel position in question,
+ and set a2 to a2*x.
+
+ 11. Let m2 be the layer mode of the layer.
+
+ 12. If the layer is the bottommost visible layer (i.e., if it is
+ the last visible layer in the master layer list) and m2 is not
+ "Normal" or "Dissolve", then set m2 to "Normal".
+
+ 13. Set (a1,c1) to COMPOSITE(a1,c1, a2,c2,m2).
+ The COMPOSITE function is defined below.
+
+14. If the flattened image is to be shown against a background of
+ color c0, then actually visible pixel is
+ COMPOSITE(1.0,c0, a1,c1,Normal).
+
+ Note that unless all layers have mode Normal, it would give the
+ wrong result to start by initializing (a1,c1) to (1.0,c0).
+
+Helper functions
+----------------
+
+The following auxiliary functions are used in the definition of
+COMPOSITE below:
+
+ MIN(x1,...,xn) is the least value of x1...xn
+
+ MAX(x1,...,xn) is the largest value of x1..xn
+
+ MID(x1,...,xn) = (MIN(x1,...,xn)+MAX(x1,...,xn))/2
+
+ CLAMP(x) = if x < 0 then 0.0 else if x > 1 then 1.0 else x
+
+ BLEND(a1,x1, a2,x2) = (1-k)*x1 + k*x2
+ where k = a2/(1-(1-a1)*(1-a2))
+
+Layer modes
+-----------
+
+This and the following sections define the COMPOSITE function used in
+the general flattening algorithm.
+
+"Normal" mode for RGB or grayscale images is the usual mode of
+compositing in computer graphics with alpha channels. In indexed
+mode, the alpha value gets rounded to either 1.0 or 0.0 such that
+no colors outside the color map get produced:
+
+ COMPOSITE(a1,y1, a2,y2,Normal)
+ = ( 1-(1-a1)*(1-a2), BLEND(a1,y1, a2,y2) )
+
+ COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,Normal)
+ = ( 1-(1-a1)*(1-a2), BLEND(a1,r1, a2,r2),
+ BLEND(a1,g1, a2,g2),
+ BLEND(a1,b1, a2,b2) )
+
+ COMPOSITE(a1,i1, a2,i2,Normal) = if a2 > 0.5 then (1.0,i2) else (a1,i1)
+
+"Dissolve" mode corresponds to randomly dithering the alpha channel to
+the set {0.0, 1.0}:
+
+ COMPOSITE(a1,c1, a2,c2,Dissolve) = chose pseudo-randomly between
+ (1.0,c2) with probability a2
+ (a1,c1) with probability 1-a2
+
+These two modes are the only ones that make sense for all of the RGB,
+grayscale and indexed color models. In the indexed color model, all
+layer modes except Dissolve are treated as Normal.
+
+Most layer modes belong to the following group, which makes sense for
+RGB and grayscale images, but not for indexed ones:
+
+ COMPOSITE(a1,y2, a2,y2,m)
+ = ( a1, BLEND(a1,y1, MIN(a1,a2),f(y1,y2, m)) )
+
+ COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,m)
+ = ( a1, BLEND(a1,r2, MIN(a1,a2),f(r1,r2, m)),
+ BLEND(a1,g1, MIN(a1,a2),f(g1,g2, m)),
+ BLEND(a1,b1, MIN(a1,a2),f(b1,g2, m)) )
+
+when 3 <= m <= 10 or 15 <= m <= 21.
+
+The following table defines f(x1,x2,m):
+
+ Multiply: f(x1,x2, 3) = x1*x2
+ Screen: f(x1,x2, 4) = 1-(1-x1)*(1-x2)
+ Overlay: f(x1,x2, 5) = (1-x2)*x1^2 + x2*(1-(1-x2)^2)
+ Difference: f(x1,x2, 6) = if x1 > x2 then x1-x2 else x2-x1
+ Addition: f(x1,x2, 7) = CLAMP(x1+x2)
+ Subtract: f(x1,x2, 8) = CLAMP(x1-x2)
+ Darken Only: f(x1,x2, 9) = MIN(x1,x2)
+ Lighten Only: f(x1,x2, 10) = MAX(x1,x2)
+ Divide: f(x1,x2, 15) = CLAMP(x1/x2)
+ Dodge: f(x1,x2, 16) = CLAMP(x1/(1-x2))
+ Burn f(x1,x2, 17) = CLAMP(1-(1-x1)/x2)
+ Hard Light: f(x1,x2, 18) = if x2 < 0.5 then 2*x1*x2 else 1-2*(1-x1)(1-x2)
+ Soft Light: f(x1,x2, 19) = (1-x2)*x1^2 + x2*(1-(1-x2)^2)
+ Grain Extract: f(x1,x2, 20) = CLAMP(x1-x2+0.5)
+ Grain Merge: f(x1,x2, 21) = CLAMP(x1+x2-0.5)
+
+Note that the "Overlay" and "Soft Light" modes have identical effects.
+In the "Divide", "Dodge", and "Burn" modes, division by zero should
+be considered to produce a number so large that CLAMP(x/0) = 1 unless
+x=0, in which case CLAMP(0/0) = 0.
+
+The remaining four layer modes only make sense in the RGB color model;
+if the color mode of the image is grayscale or indexed they will be
+interpreted as Normal.
+
+ COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,m)
+ = ( a1, BLEND(a1,r2, MIN(a1,a2),r0),
+ BLEND(a1,g1, MIN(a1,a2),g0),
+ BLEND(a1,b1, MIN(a1,a2),b0) )
+ where (r0,g0,b0) = h(r1,g1,b1, r2,g2,b2, m)
+
+when 11 <= m <= 14.
+
+For defining these modes, we say that
+
+(r,g,b) has the _hue_ of (r',g',b')
+ if r' = g' = b' and r >= g = b
+ or there exist p and q such that p>=0 and r=p*r'+q and b=p*b'+q and g=p*g'+q
+
+(r,g,b) has the _value_ of (r',g',b')
+ if MAX(r,g,b) = MAX(r',g',b')
+
+(r,g,b) has the _HSV-saturation_ of (r',g',b')
+ if r' = g' = b' = 0 and r = g = b
+ or MIN(r,g,b) = MAX(r,g,b)*MIN(r',g',b')/MAX(r',g',b')
+
+(r,g,b) has the _luminosity_ of (r',g',b')
+ if MID(r,g,b) = MID(r',g',b')
+
+(r,g,b) has the _HSL-saturation_ of (r',g',b')
+ if r' = g' = b' and r = g = b
+ or MAX(r,g,b)-MIN(r,g,b) = MIN(MID(r,g,b),1-MID(r,g,b)) *
+ (MAX(r',g',b')-MIN(r',g',b'))/MIN(MID(r',g',b'),1-MID(r',g',b'))
+
+Mode 11: Hue (H of HSV)
+
+ h(r1,g1,b1, r2,g2,b2, 11) is
+ if r2=g2=b2 then (r1,g1,b1) unchanged
+ otherwise: the color that has
+ the hue of (r1,g2,b2)
+ the value of (r1,g1,b1)
+ the HSV-saturation of (r1,g1,b1)
+
+Mode 12: Saturation (S of HSV)
+
+ h(r1,g1,b1, r2,g2,b2, 12) is the color that has
+ the hue of (r1,g1,b1)
+ the value of (r1,g1,b1)
+ the HSV-saturation of (r2,g2,b2)
+
+Mode 13: Color (H and S of HSL)
+
+ h(r1,g1,b1, r2,g2,b2, 13) is the color that has
+ the hue of (r2,g2,b2)
+ the luminosity of (r1,g1,b1)
+ the HSL-saturation of (r2,g2,b2)
+
+Mode 14: Value (V of HSV)
+
+ h(r1,g1,b1, r2,g2,b2, 14) is the color that has
+ the hue of (r1,g1,b1)
+ the value of (r2,g2,b2)
+ the HSV-saturation of (r1,g1,b1)
\ No newline at end of file
diff --git a/devel-docs/parasites.txt b/devel-docs/parasites.txt
index 40c2c1b..0399796 100644
--- a/devel-docs/parasites.txt
+++ b/devel-docs/parasites.txt
@@ -1,17 +1,41 @@
-PARASITE REGISTRY - 2007-10-18
+PARASITE REGISTRY
=================
+This document describes parasites in GIMP.
+
+
+Table of contents
+-----------------
+Parasite registry
+ Table of contents
+ Audience
+
+1. Namespace
+
+2. Known prefixes
+
+3. Known global parasites
+
+4. Known image parasites
+
+5. Known layer/drawable parasites
+
+6. Parasite format
+
+
+Audience
+--------
This document is designed for the convenience of GIMP developers.
It does not need to concern users.
->>>> If your plugin or script writes parasites, please
->>>> amend this file in SVN or submit patches to
->>>> gimp-developer scam xcf berkeley edu
+>>>> If your plug-in or script writes parasites, please
+>>>> amend this file in the Git repository or submit patches to
+>>>> gimp-developer-list gnome org
-------------------------------------------------------------------
-*** NAMESPACE
+1. NAMESPACE
+============
Plug-in-specific data should be prefixed by the plug-in function name and
a slash, i.e. private data of plug_in_displace should be named like:
@@ -22,8 +46,9 @@ etc.
Global data follows no strict rules.
-------------------------------------------------------------------
-*** KNOWN PREFIXES:
+
+2. KNOWN PREFIXES
+=================
"tiff" : The standard GIMP TIFF plugin
"jpeg" : The standard GIMP JPEG plugin
@@ -31,8 +56,9 @@ Global data follows no strict rules.
"dcm" : The standard GIMP DICOM plugin
"gimp" : For common and standard parasites
-------------------------------------------------------------------
-*** KNOWN GLOBAL PARASITES:
+
+3. KNOWN GLOBAL PARASITES
+=========================
"jpeg-save-defaults" (GLOBAL, PERSISTENT)
Default save parameters used by the JPEG plug-in.
@@ -54,8 +80,9 @@ Global data follows no strict rules.
plug-in should ask the user what to do. This parasite may be
removed in a future version (assuming always yes).
-------------------------------------------------------------------
-*** KNOWN IMAGE PARASITES:
+
+4. KNOWN IMAGE PARASITES
+========================
"gimp-comment" (IMAGE, PERSISTENT)
Standard GIF-style image comments. This parasite should be
@@ -224,8 +251,9 @@ Global data follows no strict rules.
AA is a two character ascii value representing the Dicom
element's Value Represenation (VR)
-------------------------------------------------------------------
-*** KNOWN LAYER/DRAWABLE PARASITES:
+
+5. KNOWN LAYER/DRAWABLE PARASITES
+=================================
"gimp-text-layer" (LAYER, PERSISTENT)
The associated GimpText object serialized to a string. For
@@ -242,8 +270,8 @@ Global data follows no strict rules.
parasite, the contents of the parasite are loaded at startup.
-------------------------------------------------------------------
-*** PARASITE FORMAT:
+6. PARASITE FORMAT
+==================
The parasite data format is not rigidly specified. For non-persistant
parasites you are entirely free, as the parasite data does not survive the
@@ -259,7 +287,7 @@ non-persistant data might be fine as well):
- Use character (string) data
- Obvious to perl people but less so to C programmers: just sprintf your
+ Obvious to Perl people but less so to C programmers: just sprintf your
data into a string (e.g. "SIZE 100x200 XRES 300 YRES 300") and store
that in the parasite, and later sscanf it again. This often solves most
of the problems you might encounter, makes for easier debugging and
diff --git a/devel-docs/xcf.txt b/devel-docs/xcf.txt
index 8e54ceb..edc718d 100644
--- a/devel-docs/xcf.txt
+++ b/devel-docs/xcf.txt
@@ -1,113 +1,158 @@
====================================
-SPECIFICATION OF THE XCF FILE FORMAT
+DOCUMENTATION OF THE XCF FILE FORMAT
====================================
-This document specifies the native image file format of GIMP.
+This document describes the native image file format of GIMP.
+
+
+License
+-------
+
+Copyright Henning Makholm <henning makholm net>, 2006-07-11
+
+This is free documentation; you can modify and/or redistribute
+it according to the terms of the GNU General Public License
+as published by the Free Software Foundation, either version
+2 of the license, or (at your option) any later version.
+
Table of contents
-----------------
-Specification of the XCF file format
- Table of contents
+Documentation of the XCF file format
License
+ Table of contents
+ Audience
+ Scope
Status
- Distinctions
- The name XCF
+ Version history
-1. Basic data model
- Layers
- Channels
-
-2. Format concepts and data types
+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
-3. The master image structure
+2. General properties
-4. The layer structure
- Layer properties
+3. The Image structure
+ Header
+ Image properties
-5. The channel structure
+4. The Channel structure
Channel properties
-6. The hierarchy structure
+5. The Layer structure
+ Layer properties
+
+6. The Hierarchy structure
Levels
- Tiles
7. Tile data organization
Uncompressed tile data
RLE compressed tile data
-8. Generic properties
+8. Miscellaneous
+ The name XCF
-9. Compositing and layer modes
- Flattening overview
- Helper functions
- Layer modes
+Audience
+--------
-License
--------
+Audience of this document are developers of GIMP and other software that
+reads and writes XCF files.
-Copyright Henning Makholm <henning makholm net>, 2006-07-11
-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.
+Scope
+-----
+
+The XCF format is designed to store the whole state of GIMP that is specific to
+one image (i.e., not the cut buffer, tool options, key bindings, etc.) and
+is not undo data. This makes the full collection of data stored in an XCF file
+rather heterogeneous and tied to the internals of GIMP.
+
+Use of the XCF format by third-party software is recommended only as a way
+to get data into and out of GIMP for which it would be impossible or
+inconvenient to use a more standard interchange format.
+Authors of third-party XCF-creating software in particular should take
+care to write files that are as indistinguishable as possible from
+ones saved by GIMP. The GIMP developers take care to make each
+version of GIMP able to read XCF files produced by older GIMP versions,
+but they make no special efforts to allow reading of XCF files created by
+other software.
+
+Interchanging image data with other applications is not goal of the XCF format.
+For this use case GIMP opens and exports common images formats, like JPEG,
+PNG and PSD.
+TODO: Role of the ORA format in this context?
+
+For the stated reasons and clarification GIMP _saves_ XCF files,
+but _exports_ to other image formats.
+
+Beware that CinePaint's native file format is called XCF, too. While it is
+derived from the format described here, both formats differ in many details
+and are _not_ mutually compatible.
+This document does not describe the CinePaint XCF format.
+For more information on that see http://www.cinepaint.org/more/docs/xcf.html
- ---------------------------------------------
- T H I S I S A D R A F T O N L Y !
- ---------------------------------------------
Status
------
This specification is an unofficial condensation and extrapolation of
-the XCF-writing and -reading code in version 2.2.11 of GIMP. As of
+the XCF-writing and -reading code in version 2.8.10 of GIMP. As of
this writing, it has not been approved or proofread by any GIMP
developer, though it has been written with the intention of
contributing it to the GIMP project for use as official documentation.
Some of the normative statements made below are enforced by the XCF
-reader in GIMP; others are just the author's informed guess about
+code in GIMP; others are just the author's informed guess about
"best practices" that would be likely to maximize interoperability
with future versions of GIMP.
-Distinctions
-------------
-Beware that CinePaint's native file format is called XCF too.
-While the latter is derived from the format described here, the two formats
-differ in many details and are not mutually compatible.
-See http://www.cinepaint.org/more/docs/xcf.html for more information.
+Version history
+---------------
+This section lists the changes between file format versions in bigger terms.
+Details are denoted in the text.
-The XCF format is designed to store the entire part of the state of
-GIMP that is specific to one image (i.e., not the cut buffer, tool
-options, key bindings, etc.) and is not undo data. This makes the
-full collection of data stored in an XCF file rather heterogeneous and
-tied to the internals of GIMP. Use of the 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.
+Version 0:
+Since GIMP 0.99.16, released on 15.12.1997.
+The initial file format. Everything that is not listed in the following versions
+is part of this.
-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.
+Version 1:
+Since GIMP 0.99.16, released on 15.12.1997.
+Adds color maps. Chapter 3 "The image structure" describes the PROP_COLOR_MAP
+property.
-The name XCF
-------------
+Version 2:
+Since GIMP 1.3.10, released on 07.11.2002.
+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 (releases on 5.10.2003).
+Chapter 1 "Basic concepts" describes the path handling in general and
+chapter 2 "General concepts" introduces the PROP_VECTORS property.
-The name XCF honors GIMP's origin at the eXperimental Computing
-Facility of the University of California at Berkeley.
+Version 3:
+Since GIMP 2.7.1, released on 29.06.2010.
+Adds layer groups. The chapter 5 "The layer structure" describes the new
+properties PROP_GROUP_ITEM, PROP_GROUP_ITEM_FLAGS and PROP_ITEM_PATH.
-1. BASIC DATA MODEL
-===================
+1. BASIC CONCEPTS
+=================
It is recommended that a software developer who wants to take full
advantage of the XCF format be deeply familiar with GIMP at least
@@ -115,77 +160,157 @@ 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.
-In general an XCF file describes a stack of _layers_ and _channels_ on
-a _canvas_, which is just an abstract rectangular viewport for the
-layers and channels.
-Layers
+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.
+
+
+Canvas
------
-A layer is a named rectangular area of pixels which has a definite
-position with respect to the canvas. A layer 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:
-
- 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 Section 8 below) implicitly treat the intensities
- as _linear_ samples. The XCF file format currently has no support
- for storing the intended gamma of the samples.
-
- 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.
-
-All layers in an image must use the same color model. Exception: if
-the "floating selection" belongs to a channel or layer mask, it will
-be represented as grayscale pixels independently of the image's
-overall color model.
+A canvas is an abstract rectangular viewport for the layers and channels.
+The image header stores the canvas' dimensions.
-Each pixel of a layer also has an alpha component which specifies the
-opacity of the pixel on a linear scale from 0 (denoting an alpha of
-0.0, or completely transparent) to 255 (denoting an alpha of 1.0, or
-completely opaque). The color values do not use "premultiplied alpha"
-storage. The color information for pixels with alpha 0 _may_ be
-meaningful; GIMP preserves it when parts of a layer are erased and
-provides (obscure) ways of recovering it in its user interface.
-The bottommost layer _only_ in an image may not contain alpha
-information; in this case all pixels in the layer have an alpha value
-of 255. (Even if the bottommost layer does not cover the entire
-canvas, it is the only layer that can be without an explicit alpha
-channel).
+Color
+-----
-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.
+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
+-----------------
-Layers have certain other properties such as a visibility flag, a
-global opacity (which is multiplied with individual pixel alphas) and
-various editing state flags.
+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:
-Channels
---------
+ +-----------------+-----------------+------------------+-----------------+
+ | Tile 0: 64 x 64 | Tile 1: 64 x 64 | Tile 2: 64 x 64 | Tile 3: 8 x 64 |
+ +-----------------+-----------------+------------------+-----------------+
+ | Tile 4: 64 x 64 | Tile 5: 64 x 64 | Tile 6: 64 x 64 | Tile 7: 8 x 64 |
+ +-----------------+-----------------+------------------+-----------------+
+ | Tile 8: 64 x 22 | Tile 9: 64 x 22 | Tile 10: 64 x 22 | Tile 11: 8 x 22 |
+ +-----------------+-----------------+------------------+-----------------+
+
+As can be seen from this example, the tiles appear in the XCF file in
+row-major, top-to-bottom, left-to-right order. The dimensions of the
+individual tiles are not stored explicitly in the XCF file, but must
+be computed by the reader.
+
+The tiles that are pointed to by a single level structure must be
+contiguous in the XCF file, because GIMP's XCF reader uses the
+difference between two subsequent tile pointers to judge the amount of
+memory it needs to allocate for internal data structures.
+
+
+Pixel data: Levels of detail hierarchy
+--------------------------------------
+
+The tiles themselves are organized in levels of detail. These levels
+build a hierarchy.
+
+Only the first level structure is used by GIMP's XCF reader,
+except that the reader checks that a terminating zero for the
+level-pointer list can be found. GIMP's XCF writer creates a
+series of dummy level structures (with NULL-pointers to the tiles), each
+declaring a height and width half of the previous one (rounded down),
+until the height and with are both less than 64. Thus, for a layer of
+200 x 150 pixels, this series of levels will be saved:
+
+ A level of 200 x 150 pixels with 12 tiles: the actually used one
+ A level of 100 x 75 pixels with no tiles
+ A level of 50 x 37 pixels with no tiles
+
+Third-party XCF writers should probably mimic this entire structure;
+robust XCF readers should have no reason to even read past the pointer
+to the first level structure.
+
+TODO: The XCF file holds (for unclear historical reasons)
+a level-of-detail hierarchy, but we only use the
+lowest hierarchy level of it and other XCF consumers
+are told to do the same. This looks like a mipmap. Would
+using it to save an image pyramid or the thumbnail
+for the File dialogs get us some benefits?
+
+
+Channel
+-------
A channel is a named object that contains a single byte of information
for each pixel in the canvas area. Channels have a variety of use as
intermediate objects during editing; they are not meant to be rendered
directly when the final image is displayed or exported to layer-less
-formats.
+formats. A major use of channels is as a store for saved selections.
A channel can be edited as if it was a grayscale layer with the same
dimensions as the canvas. When it is shown in the GIMP editor UI
@@ -195,81 +320,84 @@ 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.
-The current _selection_ in the editor is stored as a channel in the
-XCF file if it is nonempty. Pixels with a value of 255 belong to the
-selection; pixels with a value of 0 don't, an pixels with intermediate
-values are partially selected. A major use of channels is as a store
-for saved selections.
-
Though the channel data structure in the XCF file contains a height
and width field, these must always be the same as the canvas width and
height.
+TODO: does this apply to any channel or only to selections?
-Related to channels is the _layer mask_ that can be attached to a
-layer. The layer mask is in fact represented as a channel structure in
-the XCF file, but it is not listed in the master list of channels.
-Its dimensions and placement coincide with those of its parent layer.
-Unless disabled by the PROP_APPLY_MASK property, the layer mask
-functions as an extra alpha channel for the layer, in that for each
-pixel the layer's alpha byte and the layer mask byte are multiplied to
-find the extent to which the layer obscures the background. Thus a
-layer mask can make parts of the layer more transparent, but never
-more opaque.
+Layer
+-----
+A layer is a named rectangular area of pixels which has a definite
+position with respect to the canvas. It may extend beyond the canvas or
+(more commonly) only cover some of it. Each pixel of the layer has a color
+which is specified in one of three ways as described in the "Color" section.
-2. FORMAT CONCEPTS AND DATA TYPES
-=================================
+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.
-An XCF file is a sequence of bytes. 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 files, and that the tile data blocks for each
-drawable must follow each other directly.
+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.
-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 pointed-to structure.
+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).
-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.
+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?
-Basic data types
-----------------
+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.
-A WORD is a 32-bit integer stored as 4 bytes in network byte 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. In this specification unsigned words are denoted
-"uint32" and signed words are denoted "int32".
-A FLOAT is stored as a 32-bit IEEE 754 single-precision floating-point
-number in network byte order.
+Layer mask
+----------
-A STRING is stored as follows:
+The layer mask can be attached to a layer.
+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.
- uint32 n+1 The number of bytes that follow, including the zero byte
- byte[n] ... The string data in Unicode, encoded using UTF-8
- byte 0 A terminating zero byte
+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.
-Exception: the empty string is stored simply as an uint32 with the
-value 0.
Properties
----------
-As an extension mechanism, most kinds of structures in an XCF file
-include a variable-length series of variable-length PROPERTY records
-which have the following general format
+Properties are an extension mechanism to attribute the image, channels
+and layers. Some are attributes for general use, such as PROP_END,
+others are specific to the image, a channel or a layer.
+
+Technically properties are implemented as variable-length series of
+variable-length PROPERTY records which have the following general format
- uint32 t A magic number that identifies the type of property
- uint32 n They payload length (but BEWARE! see below)
- byte[n] ... Payload - interpretation depends on the type
+ uint32 type Numerical type identifier
+ uint32 plength Payload length in bytes (but BEWARE! see below)
+ byte[n] ... Payload - interpretation depends on the type
The authoritative source for property type numbers is the file
-app/xcf/xcf-private.h in the GIMP sources.
+app/xcf/xcf-private.h in the GIMP sources. Only GIMP itself should define
+new property types.
The number of properties in a property list is not stored explicitly;
the last property in the list is identified by having type 0; it must
@@ -292,57 +420,239 @@ unknown property types.
There is not supposed to be more than one instance of each property in
a property list, but some versions of GIMP will erroneously emit
duplicate properties. An XCF reader that meets a duplicated property
-should let the contents of the later instance take precedence, except
+should let the content of the later instance take precedence, except
for properties that contain lists of subitems, in which the lists
should generally be concatenated. An XCF writer should never
deliberately duplicate properties within a single property list.
+
Parasites
---------
-A second level of extensibility is provided by the "parasite"
-concept. A parasite is analogous to a property (and is usually stored
-in a special property in the XCF file) but is identified by a string
+Parasites provide a second level of extensibility.
+A parasite is analogous to a property, but is identified by a string
rather than a number. This makes a larger namespace available for
parasites. GIMP plug-ins can access the parasites of an image
-component through a generic API and can define their own parasite
-names which will be ignored by other plug-ins. In contrast, only
-GIMP itself should define new property types.
+component through the API and can define their own parasite
+names which will be ignored by other plug-ins.
A list of known parasites and their data formats can be found in the
file devel-doc/parasites.txt of the GIMP source tree.
+The PROP_PARASITE property stores the parasites of the image, layers
+and channels and the PROP_VECTORS property those of the paths.
+
+The number of parasites there is not directly encoded; the list ends when
+the total length of the parasite data read equals the property payload length.
+
+GIMP's XCF reader checks that the combined size of all parasites
+in the property precisely equals the length word, so it is safe for
+a reader to use the length word to skip the property without parsing
+the individual parasites.
+
+The parasite content may be binary, but often a textual encoding is
+chosen in order to spare the writing and reading code of having to deal
+with byte ordering.
+
+There can only be one parasite with a given name attached to
+each element of the image. Some versions of GIMP will
+erroneously write some parasites twice in the same property list;
+XCF readers must be prepared to gracefully ignore all but the
+last instance of a parasite name in each property list.
+
+TODO: How shall parasite readers handle lists in duplicate parasites?
+
+Selection
+---------
+
+If the current selection in the editor is nonempty, then GIMP stores it
+as a channel in the XCF file. Pixels with a value of 255 belong to the
+selection; pixels with a value of 0 don't, and pixels with intermediate
+values are partially selected.
+
+
+Floating selection
+------------------
+
+A floating selection is a selection, that is attached to a particular
+layer, channel or layer mask.
+
+Technically it is handled as a layer with alpha.
+
+If a floating selection exists, it must always be the first layer in
+the layer list, but it is not rendered at that position in the layer stack.
+Instead it is logically attached to another layer, or a channel or layer mask,
+and the content of the floating selection is combined with ("anchored to")
+that drawable before it is used to render the visible image.
+
+The floating selection must not have a layer mask of its own, but if
+an ordinary (not floating) selection also exists, it will be used as
+a layer mask for the floating selection.
+
+If a floating selection exists, it must also be the active layer.
+
+Because the floating selection is modal and ephemeral, users rarely
+save XCF files containing a floating selection. It may be acceptable
+for third-party XCF consumers to ignore the floating selection or
+explicitly refuse to process it.
+
+
+Tattoos
+-------
+
+A tattoo is a unique and permanent identifier attached to a drawable or path
+that can be used to uniquely identify it within an image even between sessions.
+
+The tattoo of the image, a layer or channel is stored in the PROP_TATTOO
+property, a tattoo for a path in the PROP_VECTORS property.
+
+The PROP_TATTOO property of the entire image stores a "high-water
+mark" for the entire image; it is greater than OR EQUAL TO any
+tattoo for an element of the image. It allows efficient generation
+of new unused tattoo values and also prevents old tattoo numbers
+from being reused within a single image, lest plug-ins that use
+the tattoos for bookkeeping get confused.
+
+An XCF file must either provide tattoo values for all its elements
+or for none of them. GIMP will invent fresh tattoos when it
+reads in tattoo-less elements, but it does not attempt to keep them
+different from ones specified explicitly in the file.
+TODO: can this cause confusion and hard-to-find errors? If so, fix.
+
+
+Text
+----
+
+GIMP stores text in plain layers with parasites for the text and formattting
+and PROP_TEXT_LAYER_FLAGS for flags.
+
+
+Vector paths
+------------
+
+GIMP stores vector paths as properties of the image.
+If all paths are continuous sequences of Bezier strokes, then GIMP uses
+the PROP_PATHS property, otherwise PROP_VECTORS. PROP_PATHS is for old
+files from GIMP up to version 1.2.
+
+
+2. GENERAL PROPERTIES
+=====================
+
+This chapter describes the formats of the defined property records that
+can appear in more than one context in an XCF file.
+
+PROP_END
+ uint32 0 Type identification
+ uint32 0 PROP_END has no payload.
+
+ The PROP_END pseudo-property marks the end of any property list.
+
+PROP_LINKED (editing state)
+ uint32 9 Type identification
+ uint32 4 Four bytes of payload
+ uint32 linked 1 if the layer is linked; 0 if not
+
+ PROP_LINKED controls the behavior of Transform tools with a layer,
+ channel or path. If a Transform tool is used to transform one of them
+ all other linked elements will be transformed the same way.
+ It appears in the property list for layers, channels and paths.
+
+PROP_LOCK_CONTENT (since version 3, editing state)
+ uint32 28 Type identification
+ uint32 4 Four bytes of payload
+ uint32 locked 1 if the content is locked; 0 if not
+
+ PROP_LOCK_CONTENT specifies whether the layer, channel or path is locked,
+ i.e. cannot be edited.
+
+PROP_OPACITY (essential)
+ uint32 6 Type identification
+ uint32 4 Four bytes of payload
+ uint32 opacity Opacity on a scale from 0 (fully transparent) to
+ 255 (fully opaque)
+
+ PROP_OPACITY records the overall opacity setting for the layer or channel.
+ It appears in the property list of layers and channels.
+
+ Note that though GIMP's user interface displays the opacity as a percentage,
+ it is actually stored on a 0-255 scale. Also note that this opacity value
+ is stored as a 32-bit quantity even though it has been scaled to
+ fit exactly in a single byte.
+
+ When reading old XCF files that lack this property, full opacity
+ should be assumed.
+
+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 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 MASTER IMAGE STRUCTURE
-=============================
+3. THE IMAGE STRUCTURE
+======================
+
+Header
+------
The image structure always starts at offset 0 in the XCF file.
- byte[9] "gimp xcf " File type magic
- byte[4] version XCF version
- "file" - version 0
- "v001" - version 1
- "v002" - version 2
- byte 0 Zero-terminator for version tag
- uint32 width With of canvas
+ 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
- (enum GimpImageBaseType in libgimpbase/gimpbaseenums.h)
- property-list Image properties (details below)
- ,------------------- Repeat once for each layer, topmost layer first:
- | uint32 layer Pointer to the layer structure
+ 0: RGB color
+ 1: Grayscale
+ 2: Indexed color
+ (see enum GimpImageBaseType
+ in libgimpbase/gimpbaseenums.h)
+ property-list Image properties
+ ,----------------- Repeat once for each layer, topmost layer first:
+ | uint32 lptr Pointer to the layer structure
`--
- uint32 0 Zero marks the end of the array of layer pointers
- ,------------------- Repeat once for each channel, in no particular order:
- | uint32 channel1 Pointer to the channel structure
+ uint32 0 Zero marks the end of the array of layer pointers.
+ ,------------------ Repeat once for each channel, in no particular order:
+ | uint32 cptr Pointer to the channel structure
`--
- uint32 0 Zero marks the end of the array of channel pointers
+ uint32 0 Zero marks the end of the array of channel pointers.
-The last four characters of the initial 13-character magic string are
-a version indicator. The version will be higher than 2 if the correct
+The last 4 characters of the initial 13-character identification string are
+a version indicator. The version will be higher than 3 if the correct
reconstruction of pixel data from the file requires that the reader
understands features not described in this specification. On the other
hand, optional extra information that can be safely ignored will not
@@ -353,29 +663,30 @@ allow the image to be represented. Third-party XCF writers should do
likewise.
Version numbers from v100 upwards have been used by CinePaint, which
-originated as a 16-bit fork of GIMP. That format is not described
-by this specification.
+originated as a 16-bit fork of GIMP, see "Scope".
+
Image properties
----------------
The following properties are found only in the property list of the
-image structure. In addition to these, the list can also contain the
-properties PROP_TATTOO, PROP_PARASITES and PROP_END, described in
-section 8 below.
+image structure. Additionally the list can also contain the properties
+PROP_END, PROP_PARASITES and PROP_TATTOO, defined in chapter 2.
PROP_COLORMAP (essential)
- uint32 1 The type number for PROP_COLORMAP is 1
- uint32 3n+4 The payload length
- uint32 n The number of colors in the color map (should be <256)
- ,------------ Repeat n times:
- | byte r The red component of a color map color
- | byte g The green component of a color map color
- | byte b The blue component of a color map color
+ 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
`--
- Appears in all indexed images and stores the color map. The property
- will be ignored if it is encountered in an RGB or grayscale
+ PROP_COLORMAP stores the color map.
+ It appears in all indexed images.
+
+ The property will be ignored if it is encountered in an RGB or grayscale
image. The current GIMP will not write a color map with RGB or
grayscale images, but some older ones occasionally did, and readers
should be prepared to gracefully ignore it in those cases.
@@ -385,7 +696,7 @@ PROP_COLORMAP (essential)
there is no color map entry for "transparent"; the alpha channel of
layers that have one is always represented separately.
- The structure here is that of XCF version >= 1. Comments in the
+ The structure here is that of since XCF version 1. Comments in the
GIMP source code indicate that XCF version 0 could not store indexed
images in a sane way; contemporary GIMP versions will complain and
reinterpret the pixel data as a grayscale image if they meet a
@@ -393,300 +704,313 @@ PROP_COLORMAP (essential)
Beware that the payload length of the PROP_COLORMAP in particular
cannot be trusted: some historic releases of GIMP erroneously
- wrote n+4 instead of 3n+4 into the length word (but still actually
- followed it by 3n+4 bytes of payload).
+ wrote n+4 instead of 3*n+4 into the length word (but still actually
+ followed it by 3*n+4 bytes of payload).
PROP_COMPRESSION (essential)
- uint32 17 The type number for PROP_COMPRESSION is 17
- uint32 1 One byte of payload
- byte c Compression indicator; one of
- 0: No compression
- 1: RLE encoding
- 2: (Never used, but reserved for zlib compression)
- 3: (Never used, but reserved for some fractal compression)
+ uint32 17 Type identification
+ uint32 1 One byte of payload
+ byte comp Compression indicator; one of
+ 0: No compression
+ 1: RLE encoding
+ 2: (Never used, but reserved for zlib compression)
+ 3: (Never used, but reserved for some fractal compression)
- Defines the encoding of pixels in tile data blocks in the entire XCF
- file. See section 6 below for details.
+ PROP_COMPRESSION defines the encoding of pixels in tile data blocks in the
+ entire XCF file. See chapter 7 for details.
Note that unlike most other properties whose payload is always a
small integer, PROP_COMPRESSION does _not_ pad the value to a full
32-bit integer.
- Contemporary GIMP versions always write files with c=1. It is unknown to the
- author of this document whether versions that wrote completely
- uncompressed (c=0) files ever existed.
+ 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.
+ TODO: Why do we use zlib compression to compress only the whole file (.xcf.gz)
+ if it is a built-in feature?
PROP_GUIDES (editing state)
- uint32 18 The type number for PROP_GUIDES is 18
- uint32 5*n Five bytes of payload per guide
- ,---------- Repeat n times:
- | int32 c Guide coordinate
- | byte o Guide orientation; one of
- | 1: The guide is horizontal, and c is a y coordinate
- | 2: The guide is vertical, and c is an x coordinate
+ 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)
`--
- Appears if any guides have been defined.
+ PROP_GUIDES stores the horizontal or vertical positions of guides.
+ It appears if any guides have been defined.
Some old XCF files define guides with negative coordinates; those
should be ignored by readers.
-PROP_RESOLUTION (not editing state, but not _really_ essential either)
- uint32 19 The type number for PROP_RESOLUTION is 19
- uint32 8 Eight bytes of payload
- float x Horizontal resolution in pixels per 25.4 mm
- float y Vertical resolution in pixels per 25.4 mm
-
- 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_UNIT (editing state)
- uint32 22 The type number for PROP_UNIT is 22
- uint32 4 Four bytes of payload
- uint32 c Magic number specifying the unit; one of
- 1: Inches (25.4 mm)
- 2: Millimeters (1 mm)
- 3: Points (127/360 mm)
- 4: Picas (127/30 mm)
-
- 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 pixels
- per 25.4 mm.
-
- Instead of this property, PROP_USER_UNIT can be used to specify a
- unit not on the list of standard units.
-
PROP_PATHS
- uint32 23 The type number for PROP_PATHS is 23
- uint32 len The total length of the following payload
- uint32 a The index of the active path
- uint32 n The number of paths that follow
+ uint32 23 Type identification
+ uint32 plength Total length of the following payload in bytes
+ uint32 aindex Index of the active path
+ uint32 n Number of paths that follow
path_1
path_2
...
path_n
+ PROP_PATHS stores the paths.
+
Each path has one of three formats
Format 1: Format 2: Format 3:
- string string string name
- uint32 uint32 uint32 locked
- byte byte byte state 4 if closed, 2 otherwise
- uint32 uint32 uint32 closed
- uint32 uint32 uint32 n The number of points
- uint32=1 uint32=2 uint32=3 v A version indicator
+ string string string name Name of the path
+ uint32 uint32 uint32 locked (TODO: correct to 'linked')
+ byte byte byte state 4 if closed; 2 otherwise
+ (for GIMP 1.2 compatibility)
+ uint32 uint32 uint32 closed 1 if path is closed;
+ 0 otherwise
+ uint32 uint32 uint32 np Number of points
+ uint32=1 uint32=2 uint32=3 version Version indicator
uint32 uint32 dummy Ignored; always set to 1
uint32 tattoo 0 if none, or see PROP_TATTOO
- ,---------- ,---------- ,------------------ Repeat for n points:
- | int32 | int32 | int32 typ Type of point; one of
- | | | 0: an anchor
- | | | 1: a Bezier control point
+ ,---------- ,---------- ,------------------ Repeat for np points:
+ | int32 | int32 | int32 type Type of point; one of
+ | | | 0: Anchor
+ | | | 1: Bezier control point
+ | | | (for GIMP 1.2 compatibility)
| int32 | float | float x X coordinate
| int32 | float | float y Y coordinate
`-- `-- `--
This format is used to save path data if all paths in the image are
- continuous sequences of Bezier strokes. Otherwise PROP_VECTORS is
- used instead.
+ continuous sequences of Bezier strokes. Otherwise GIMP stores the paths in
+ PROP_VECTORS.
+
+ A closed path is a path which has the last and the first point connected,
+ for instance a triangle.
- (Hmmm... PROP_PATHS cannot represent parasites for paths, but the
+ GIMP's XCF reader _does not_ check that the total size of all path
+ specifications in the property precisely equals the plength word.
+ Note that this is different to PROP_VECTORS.
+
+ TODO: Clarify: PROP_PATHS cannot represent parasites for paths, but the
XCF writer does not check whether all paths are parasite-less when
choosing which property to use, so path parasites may be lost upon
- saving).
+ saving). Is this by design or a bug?
There may be paths that declare a length of 0 points; these should
be ignored.
+PROP_RESOLUTION (not editing state, but not _really_ essential either)
+ uint32 19 Type identification
+ uint32 8 Eight bytes of payload
+ float hres Horizontal resolution in pixels per inch (ppi)
+ float vres Vertical resolution in pixels per inch (ppi)
+
+ PROP_RESOLUTION gives the intended physical size of the image's pixels.
+
+ Note that for many images, such as graphics created for the web, the
+ creator does not really have an intended resolution in mind but
+ intends the image to be shown at whatever the natural resolution of
+ the viewer's monitor is. Similarly, photographs commonly do not have
+ a well-defined target size and are intended to be scaled to fit the
+ available space instead. Therefore readers should not interpret the
+ information in this property too rigidly; GIMP writes it to XCF
+ files unconditionally, even if the user has not explicitly chosen a
+ resolution.
+
+PROP_UNIT (editing state)
+ uint32 22 Type identification
+ uint32 4 Four bytes of payload
+ uint32 uid Unit identifier; one of
+ 1: Inches (25.4 mm)
+ 2: Millimeters (1 mm)
+ 3: Points (127/360 mm)
+ 4: Picas (127/30 mm)
+
+ PROP_UNIT specifies the units used to specify resolution in the Scale Image
+ and Print Size dialogs. Note that this is used only in the user interface;
+ the PROP_RESOLUTION property is always stored in ppi.
+
+ To specify non-standard units use PROP_USER_UNIT.
+
PROP_USER_UNIT (editing state)
- uint32 24 The type number for PROP_USER_UNIT is 24
- uint32 length The total length of the following payload
- float factor 25.4 mm divided by the length of the unit
- uint32 digits The number of decimal digits used with the unit
- string id An identifier for the unit
- string sym The short symbol for the unit
- string abbr The abbreviation for the unit
- string sing The name of the unit in singular
- string plur The name of the unit in plural
-
- An alternative to PROP_UNIT which allows the use of units not on the
- standard list.
+ uint32 24 Type identification
+ uint32 plength Total length of the following payload in bytes
+ float factor 1 inch divided by the length of the unit
+ uint32 digits Number of decimal digits used with the unit
+ string id An identifier for the unit
+ string symbol Short symbol for the unit
+ string abbrev Abbreviation for the unit
+ string sname Unit name in singular form
+ string pname Unit name in plural form
+
+ PROP_USER_UNIT allows the use of units that are not on the standard list.
+ It is an alternative to PROP_UNIT.
+ TODO: How is this related to the unitrc file?
PROP_VECTORS
- uint32 25 The type number for PROP_VECTORS is 25
- uint32 length The total length of the following payload
- uint32 1 A version tag; so far always 1
- uint32 a The index of the active path
- uint32 n The number of paths that follow
+ uint32 25 Type identification
+ uint32 plength Total length of the following payload in bytes
+ uint32 1 Version tag; so far always 1
+ uint32 aindex Index of the active path
+ uint32 n Number of paths that follow
,---------------------- Repeat n times:
| string name Name of the path
| uint32 tattoo Tattoo of the path (see PROP_TATTOO), or 0
- | uint32 visible
- | uint32 linked
- | uint32 m The number of parasites for the path
- | uint32 k The number of strokes in the first path
+ | uint32 visible 1 if path is visible, 0 if not
+ | uint32 linked 1 if path is linked, 0 if not
+ | uint32 m Number of parasites for the path
+ | uint32 k Number of strokes in the first path
| ,-------------------- Repeat m times:
- | | parasite ... In same format as in PROP_PARASITES (q.v.)
+ | | parasite ... In same format as in PROP_PARASITES.
| `--
| ,-------------------- Repeat k times:
- | | uint32 1 The stroke is a Bezier stroke (p.t., all are)
- | | uint32 closed Closed flag
- | | uint32 na Number of floats given for each point;
+ | | uint32 1 The stroke is a Bezier stroke
+ | | uint32 closed 1 if path is closed; 0 otherwise
+ | | uint32 nf Number of floats given for each point;
| | must be >= 2 and <= 6.
| | uint32 np Number of control points for this stroke
| | ,------------------ Repeat np times:
| | | uint32 type Type of the first point; one of
- | | | 0: an anchor
- | | | 1: a Bezier control point
+ | | | 0: Anchor
+ | | | 1: Bezier control point
| | | float x X coordinate
| | | float y Y coordinate
- | | | float pressure Only if na >= 3; otherwise defaults to 1.0
- | | | float xtilt Only if na >= 4; otherwise defaults to 0.5
- | | | float ytilt Only if na >= 5; otherwise defaults to 0.5
- | | | float wheel Only if na == 6; otherwise defaults to 0.5
+ | | | 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
| | `--
| `--
`--
- Appears unless all paths can be stored in the PROP_PATHS format.
+ PROP_VECTORS stores the paths.
+
+ It appears if all paths are continuous sequences of Bezier strokes;
+ otherwise PROP_PATHS is used.
GIMP's XCF reader checks that the total size of all path
- specifications in the property precisely equals the length word, so
- it is safe for a reader to use the length word to skip the property
+ specifications in the property precisely equals the plength word, so
+ it is safe for a reader to use the plength word to skip the property
without parsing the individual parasites. (Note that this is _not_
the case for PROP_PATHS).
-4. THE LAYER STRUCTURE
+4. THE CHANNEL STRUCTURE
+========================
+
+Channel structures are pointed to from layer structures (in case of
+layer masks) or from the master image structure (for all other
+channels).
+
+ uint32 width Width of the channel
+ uint32 height Height of the channel
+ string name Name of the channel
+ property-list Channel properties
+ uint32 hptr Pointer to the hierarchy structure with the pixels
+
+The width and height of the channel must be the same as those of its
+parent structure (the layer in the case of layer masks; the canvas for
+all other channels).
+
+
+Channel properties
+------------------
+
+The following properties are found only in the property list of
+channel structures. Additionally the list can also contain the properties
+PROP_END, PROP_LINKED, PROP_LOCK_CONTENT, PROP_OPACITY, PROP_PARASITES,
+PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.
+
+PROP_ACTIVE_CHANNEL (editing state)
+ uint32 3 Type identification
+ uint32 0 PROP_ACTIVE_CHANNEL has no payload
+
+ The presence of PROP_ACTIVE_CHANNEL indicates that the channel is the
+ currently active channel.
+ It appears in the property list of the currently active channel.
+ Only zero or one channel must have this property at any time.
+
+PROP_COLOR
+ uint32 16 Type identification
+ uint32 3 Three bytes of payload
+ byte r Red component of color
+ byte g Green component of color
+ byte b Blue component of color
+
+ PROP_COLOR gives the color of the screen that is used to represent the channel
+ when it is visible in the UI.
+ (The alpha of the screen is given as the channel's PROP_OPACITY).
+ TODO: What exactly does "screen" mean here?
+
+PROP_SELECTION (editing state?)
+ uint32 4 Type identification
+ uint32 0 PROP_SELECTION has no payload
+
+ PROP_SELECTION appears in the property list of the channel structure that
+ represents the selection mask.
+
+PROP_SHOW_MASKED (editing state)
+ uint32 14 Type identification
+ uint32 4 Four bytes of payload
+ uint32 masked 1 if the channel is shown as a mask, 0 if not
+
+ PROP_SHOW_MASKED specifies whether a channel is shown as a mask.
+
+
+5. THE LAYER STRUCTURE
======================
Layer structures are pointed to from a list of layer pointers in the
master image structure.
- uint32 width The width of the layer
- uint32 height The height of the layer
+ 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; 3 bytes per pixel
- 1: RGB color with alpha; 4 bytes per pixel
- 2: Grayscale without alpha; 1 byte per pixel
- 3: Grayscale with alpha; 2 bytes per pixel
- 4: Indexed without alpha; 1 byte per pixel
- 5: Indexed with alpha; 2 bytes per pixel
- (enum GimpImageType in libgimpbase/gimpbseenums.h)
- string name The name of the layer
- property-list Layer properties (details below)
- uint32 hptr Pointer to the hierarchy structure containing the pixels
+ 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
+ uint32 hptr Pointer to the hierarchy structure with the pixels
uint32 mptr Pointer to the layer mask (a channel structure), or 0
-The color mode of a layer must match that of the entire image. All
-layers except the bottommost one _must_ have an alpha channel.
+The 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).
-Exception: If the layer is a floating selection (see
-PROP_FLOATING_SELECTION) and is attached to a channel or layer mask,
-its color mode must be 3 (grayscale with alpha).
Layer properties
----------------
The following properties are found only in the property list of layer
-structures. In addition to these, the list can also contain the
-properties PROP_OPACITY, PROP_VISIBLE, PROP_LINKED, PROP_TATTOO,
-PROP_PARASITES, and PROP_END, defined in section 8 below.
+structures. Additionally the list can also contain the properties
+PROP_END, PROP_LINKED, PROP_LOCK_CONTENT, PROP_OPACITY, PROP_PARASITES,
+PROP_TATTOO and PROP_VISIBLE, defined in chapter 2.
PROP_ACTIVE_LAYER (editing state)
- uint32 2 The type number for PROP_ACTIVE_LAYER is 2
- uint32 0 PROP_ACTIVE_LAYER has no payload
-
- Appears in the property list for the currently active layer. Only
- one layer must have this property.
-
-PROP_FLOATING_SELECTION (essential)
- uint32 5 The type number for PROP_FLOATING_SELECTION is 5
- uint32 4 Four bytes of payload
- uint32 ptr Pointer to the layer or channel that the floating
- selection is attached to.
-
- Appears in the property list for the layer that is the floating
- selection. 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 contents 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 floating selections are modal and ephemeral, users rarely
- save XCF files containing a floating selection. It may be acceptable
- for third-party XCF consumers to ignore floating selections or
- explicitly refuse to process them.
+ uint32 2 Type identification
+ uint32 0 PROP_ACTIVE_LAYER has no payload
-PROP_MODE (essential)
- uint32 7 The type number for PROP_MODE is 7
- uint32 4 Four bytes of payload
- unit32 m The layer mode; one of
- 0: Normal
- 1: Dissolve (random dithering to discrete alpha)
- 2: (Behind: not selectable in the GIMP UI)
- 3: Multiply
- 4: Screen
- 5: Overlay
- 6: Difference
- 7: Addition
- 8: Subtract
- 9: Darken Only
- 10: Lighten Only
- 11: Hue (H of HSV)
- 12: Saturation (S of HSV)
- 13: Color (H and S of HSL)
- 14: Value (V of HSV)
- 15: Divide
- 16: Dodge
- 17: Burn
- 18: Hard Light
- 19: Soft Light (XCF version >= 2 only)
- 20: Grain Extract (XCF version >= 2 only)
- 21: Grain Merge (XCF version >= 2 only)
-
- When reading old XCF files that lack this property, assume m=0.
- The effects of the various layer modes is defined in Section 8, below.
-
- Beware that GIMP ignores all other layer modes than Normal and
- Dissolve for the bottommost visible layer of the image; if m>=3 has
- been specified for this layer it will interpreted as m==0 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.
-
-
-PROP_LOCK_ALPHA (editing state)
-(called PROP_PRESERVE_TRANSPARENCY in GIMP before 2.3)
- uint32 10 The type number for PROP_PRESERVE_TRANSPARENCY is 10
- uint32 4 Four bytes of payload
- uint32 b 1 if the Preserve Transparency flag is set; 0 if not
-
- The Preserve Transparency flag prevents all drawing tools in
- GIMP from increasing the alpha of any pixel in the layer.
+ The presence of PROP_ACTIVE_LAYER indicates that the channel is the
+ currently active layer.
+ Only zero or one layer must have this property at any time.
PROP_APPLY_MASK (essential)
- uint32 11 The type number for PROP_APPLY_MASK is 11
- uint32 4 Four bytes of payload
- uint32 b 1 if the layer mask should be applied, 0 if not
+ uint32 11 Type identification
+ uint32 4 Four bytes of payload
+ uint32 apply 1 if the layer mask should be applied, 0 if not
+ PROP_APPLY_MASK specifies whether the layer mask shall be applied
+ to the layer.
If the property does not appear for a layer which has a layer mask,
it defaults to true.
@@ -695,10 +1019,11 @@ PROP_APPLY_MASK (essential)
layer mask.
PROP_EDIT_MASK (editing state)
- uint32 12 The type number for PROP_EDIT_MASK is 12
- uint32 4 Four bytes of payload
- uint32 b 1 if the layer mask is currently being edited, 0 if not
+ uint32 12 Type identification
+ uint32 4 Four bytes of payload
+ uint32 editing 1 if the layer mask is currently being edited, 0 if not
+ PROP_EDIT_MASK specifies whether the layer mask is currently being edited.
If the property does not appear for a layer which has a layer mask,
it defaults to false.
@@ -706,198 +1031,197 @@ PROP_EDIT_MASK (editing state)
mask. Writers should never save this as true unless the layer has a
layer mask.
-PROP_SHOW_MASK (editing state)
- uint32 13 The type number for PROP_APPLY_MASK is 13
- uint32 4 Four bytes of payload
- uint32 b 1 if the layer mask is visible, 0 if not
-
- If the property does not appear for a layer which has a layer mask,
- it defaults to false.
-
- Robust readers should force this to false if the layer has no layer
- mask. Writers should never save this as true unless the layer has a
- layer mask.
-
-PROP_OFFSETS (essential)
- uint32 15 The type number for PROP_OFFSETS is 15
- uint32 8 Eight bytes of payload
- int32 dx Horizontal offset
- int32 dy Vertical offset
-
- Gives the coordinates of the topmost leftmost corner of the layer
- relative to the topmost leftmost corner of the canvas. The
- coordinates can be negative; this corresponds to a layer that
- extends to the left of or above the canvas boundary.
-
- When reading old XCF files that lack this property, assume (0,0).
-
-PROP_TEXT_LAYER_FLAGS
- uint32 26 The type number for PROP_TEXT_LAYER_FLAGS is 26
- uint32 4 Four bytes of payload
- uint32 f Flags, or'ed together from the following set:
- 0x00000001 Do _not_ change the layer name if the text
- contents is changed
- 0x00000002 The pixel data has been painted to or
- otherwise modified since the text was rendered
-
- Appears in property lists for text layers. The actual text (and
- other parameters such as font and color) appears as a parasite
- rather than a property.
-
-
-5. 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).
+PROP_FLOATING_SELECTION (essential)
+ uint32 5 Type identification
+ uint32 4 Four bytes of payload
+ uint32 ptr Pointer to the layer or channel the floating selection is
+ attached to
+
+ PROP_FLOATING_SELECTION indicates that the layer is the floating selection
+ and specifies the pointer to the layer, channel and layer mask it is attached
+ to.
+ It appears in the property list for the layer that is the floating selection.
+ Only zero or one layer must have this property at any time.
+
+PROP_GROUP_ITEM (since version 3)
+ uint32 29 Type identification
+ uint32 0 PROP_GROUP_ITEM has no payload
+
+ PROP_GROUP_ITEM indicates that the layer is a layer group.
+ It appears in the property list if the layer is a layer group.
+
+PROP_ITEM_PATH (since version 3)
+ uint32 30 Type identification
+ uint32 plength Total length of the following payload in bytes
+ item-path List of pointers, represented as uint32 values
+
+TODO: The code reads that it is a list of pointers, represented as uint32
+integers and somehow in the context of layers. What this is for and what
+do the property values mean?
+
+PROP_GROUP_ITEM_FLAGS (since version 3)
+ uint32 31 Type identification
+ uint32 4 Four bytes of payload
+ uint32 flags Flags for the layer, or'ed together from the following set:
+ 0x00000001 Layer group is expanded.
+ (see enum XcfGroupItemFlagsType in app/xcf/xcf-private.h)
+
+ PROP_GROUP_ITEM_FLAGS specifies flags for the layer group.
+ It appears in the property list if the layer is a layer group.
- uint32 width The width of the channel
- uint32 height The height of the channel
- string name The name of the channel
- property-list Layer properties (see below)
- uint32 hptr Pointer to the hierarchy structure containing the pixels
+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
-The with 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).
+ PROP_LOCK_ALPHA prevents all drawing tools in GIMP from increasing the alpha
+ of any pixel in the layer. Decreasing the alpha is possible.
-Channel properties
-------------------
+PROP_MODE (essential)
+ uint32 7 Type identification
+ uint32 4 Four bytes of payload
+ unit32 mode Layer mode; one of
+ 0: Normal
+ 1: Dissolve (random dithering to discrete alpha)
+ 2: (Behind: not selectable in the GIMP UI. TODO: why not?)
+ 3: Multiply
+ 4: Screen
+ 5: Overlay
+ 6: Difference
+ 7: Addition
+ 8: Subtract
+ 9: Darken Only
+ 10: Lighten Only
+ 11: Hue (H of HSV)
+ 12: Saturation (S of HSV)
+ 13: Color (H and S of HSL)
+ 14: Value (V of HSV)
+ 15: Divide
+ 16: Dodge
+ 17: Burn
+ 18: Hard Light
+ 19: Soft Light (since version 2)
+ 20: Grain Extract (since version 2)
+ 21: Grain Merge (since version 2)
+
+ 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.
-The following properties are found only in the property list of
-channel structures. In addition to these, the list can also contain
-the properties PROP_OPACITY, PROP_VISIBLE, PROP_LINKED, PROP_TATTOO,
-PROP_PARASITES, and PROP_END, defined in section 8 below.
+ 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.
-PROP_ACTIVE_CHANNEL (editing state)
- uint32 3 The type number for PROP_ACTIVE_CHANNEL is 3
- uint32 0 PROP_ACTIVE_CHANNEL has no payload
+TODO: The layer modes 'Overlay' and 'Soft light' are identical.
+If this information is still valid - is this state subject to change in GEGL?
+Should we continue providing two different names for the same thing?
- Appears in the property list for the currently active channel.
+PROP_OFFSETS (essential)
+ uint32 15 Type identification
+ uint32 8 Eight bytes of payload
+ int32 xoffset Horizontal offset
+ int32 yoffset Vertical offset
+
+ PROP_OFFSETS gives the coordinates of the upper left corner of the layer
+ relative to the upper left corner of the canvas.
+ The coordinates can be negative; this corresponds to a layer that
+ extends to the left of or above the canvas boundary.
-PROP_SELECTION (editing state?)
- uint32 4 The type number for PROP_SELECTION is 4
- uint32 0 PROP_SELECTION has no payload
+ When reading old XCF files that lack this property, assume (0,0).
- Appears in the property list for the channel structure that
- represents the selection mask.
+PROP_SHOW_MASK (editing state)
+ uint32 13 Type identification
+ uint32 4 Four bytes of payload
+ uint32 visible 1 if the layer mask is visible, 0 if not
-PROP_SHOW_MASKED (editing state)
- uint32 14 The type number for PROP_SHOW_MASKED is 14
- uint32 4 Four bytes of payload
- uint32 b 1 if the channel is shown as a mask, 0 if not
+ PROP_SHOW_MASK specifies whether the layer mask is visible.
+ If the property does not appear for a layer which has a layer mask,
+ it defaults to false.
- Appears in the property list for channels.
+ Robust readers should force this to false if the layer has no layer
+ mask. Writers should never save this as true unless the layer has a
+ layer mask.
-PROP_COLOR
- uint32 16 The type number for PROP_COLOR is 16
- 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_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)
- Appears in the property list for channels and 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).
+ PROP_TEXT_LAYER_FLAGS specifies the text layer behavior by flags.
+ It appears in property lists for text layers.
+ The actual text (and other parameters such as font and color) is a
+ parasite rather than a property.
6. THE HIERARCHY STRUCTURE
==========================
-A hierarchy contains data for a rectangular array of pixels. It is
-pointed to from a layer or channel structure.
+A hierarchy contains data for a rectangular array of pixels.
+It appears in a context: each layer and channel has a pointer to its hierarchy.
+
+ uint32 width Width of the pixel array
+ uint32 height Height of the pixel array
+ uint32 bpp Number of bytes per pixel given
+ 3: RGB color without alpha
+ 4: RGB color with alpha
+ 1: Grayscale without alpha
+ 2: Grayscale with alpha
+ 1: Indexed without alpha
+ 2: Indexed with alpha
- uint32 width The with of the pixel array
- uint32 height The height of the pixel array
- uint32 bpp The number of bytes per pixel given
uint32 lptr Pointer to the "level" structure
,--------------- Repeat zero or more times
- | uint32 dlevel Pointer to an unused level structure
+ | uint32 dlevel Pointer to an unused level structure (dummy level)
`--
- uint32 0 A zero ends the list of level pointers
+ uint32 0 Zero marks the end of the list of level pointers.
-The width, height, and bpp values are for consistency checking; their
+The width, height and bpp values are for consistency checking; their
correct values can always be inferred from the context, and are
checked when GIMP reads the XCF file.
+
Levels
------
-For some unknown historical reason, the hierarchy structure contains
-an extra indirection to a series of "level" structures, described
-below. 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 no tile pointers), 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
-3 x 266 pixels, this series of levels will be saved:
-
- A level of 3 x 266 pixels, with 5 tiles: the actually used one
- A level of 1 x 133 pixels with no tiles
- A level of 0 x 66 pixels with no tiles
- A level of 0 x 33 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.
-
The level structure is laid out as follows:
- uint32 width The width of the pixel array
- uint32 height The height of the pixel array
+ 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
| uint32 tptr Pointer to tile data
`--
- uint32 0 A zero marks the end of the array of tile pointers
+ uint32 0 Zero marks the end of the array of tile pointers.
The width and height must be the same as the ones recorded in the
hierarchy structure (except for the aforementioned dummy levels).
-Tiles
------
-
-The pixels in the hierarchy are organized in a grid of "tiles", each
-with a width and height of up to 64 pixels. The only tiles that have a
-width less than 64 are those in the rightmost column, and the only
-tiles that have a height less than 64 are those in the bottommost row.
-Thus, a layer measuring 200 x 150 pixels will be divided into 12
-tiles:
-
- +-----------------+-----------------+------------------+-----------------+
- | Tile 0: 64 x 64 | Tile 1: 64 x 64 | Tile 2: 64 x 64 | Tile 3: 8 x 64 |
- +-----------------+-----------------+------------------+-----------------+
- | Tile 4: 64 x 64 | Tile 5: 64 x 64 | Tile 6: 64 x 64 | Tile 7: 8 x 64 |
- +-----------------+-----------------+------------------+-----------------+
- | Tile 8: 64 x 22 | Tile 9: 64 x 22 | Tile 10: 64 x 22 | Tile 11: 8 x 22 |
- +-----------------+-----------------+------------------+-----------------+
-
-As can be seen from this example, the tiles appear in the XCF file in
-row-major, top-to-bottom, left-to-right order. The dimensions of the
-individual tiles are not stored explicitly in the XCF file, but must
-be computed by the reader.
-
-The tiles that are pointed to by a single level structure must be
-contiguous in the XCF file, because GIMP's XCF reader uses the
-difference between two subsequent tile pointers to judge the amount of
-memory it needs to allocate for internal data structures.
-
+Ceil(x) is the smallest integer not smaller than x.
7. TILE DATA ORGANIZATION
=========================
The format of the data blocks pointed to by the tile pointers in the
-level structure of the previous section differs according to the value
-of the PROP_COMPRESSION property of the main image structure. Current
+level structure of hierarchy differs according to the value of the
+PROP_COMPRESSION property of the main image structure. Current
GIMP versions always use RLE compression, but readers should nevertheless
be prepared to meet the older uncompressed format.
Both formats assume the width, height and byte depth of the tile are
known from the context (namely, they are stored explicitly in the
-hierarchy structure). Both encodings store a linear sequence of
-with*height pixels, extracted from the tile in row-major,
+hierarchy structure for regular tiles). Both encodings store a linear sequence
+of width*height pixels, extracted from the tile in row-major,
top-to-bottom, left-to-right order (the same as the reading direction
of multi-line English text).
@@ -905,13 +1229,16 @@ 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.
+TODO: How is this in master, when we work with higher bit depths?
+
Uncompressed tile data
----------------------
-In the uncompressed format, the file first contains all the bytes for
+In the uncompressed format the file first contains all the bytes for
the first pixel, then all the bytes for the second pixel, and so on.
+
RLE compressed tile data
------------------------
@@ -921,7 +1248,7 @@ second byte of each pixel, and so forth. In each of the streams,
multiple occurrences of the same byte value are represented in
compressed form. The representation of a stream is a series of
operations; the first byte of each operation determines the format and
-meaning of the operation:
+meaning of the operation (opcode):
byte n For 0 <= n <= 126: a short run of identical bytes
byte v Repeat this value n+1 times
@@ -944,7 +1271,7 @@ following similar streams) must occur at the end of one of these
operations; it is not permitted to have one operation span the
boundary between streams.
-The RLE encoding allows "degenerate" encodings in which the original
+The RLE encoding can cause degenerated encodings in which the original
data stream may double in size (or grow to arbitrarily large sizes if
(128,0,0) operations are inserted). Such encodings must be avoided, as
GIMP's XCF reader expects that the size of an encoded tile is
@@ -957,359 +1284,29 @@ A simple way for an XCF creator to avoid overflow is
c) never emitting two "different bytes" opcodes next to each other
in the encoding of a single stream.
+TODO: If each tile has a maximum of 64 pixels (resulting in a maximum of 64
+bytes for each color in this tile), do values>64 and long runs apply at all?
-8. GENERIC PROPERTIES
-=====================
-
-This section lists the formats of the defined property records that
-can appear in more than one context in an XCF file.
-
-PROP_END
- uint32 0 The type number for PROP_END is 0
- uint32 0 PROP_END has no payload
-
- This pseudo-property marks the end of a property list in the XCF
- file.
-
-PROP_OPACITY (essential)
- uint32 6 The type number for PROP_OPACITY is 6
- uint32 4 Four bytes of payload
- uint32 x The opacity on a scale from 0 (fully transparent) to 255
- (fully opaque)
-
- Appears in the property list of layers and channels, and records the
- overall opacity setting for the layer/channel. 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.
-
-PROP_VISIBLE (essential)
- uint32 8 The type number for PROP_VISIBLE is 8
- uint32 4 Four bytes of payload
- uint32 b 1 if the layer/channel is visible; 0 if not
-
- Appears in the property list for layers and channels.
- When reading old XCF files that lack this property, assume that
- layers are visible and channels are not.
-
-PROP_LINKED (editing state)
- uint32 9 The type number for PROP_LINKED is 9
- uint32 4 Four bytes of payload
- uint32 b 1 if the layer is linked; 0 if not
-
- Appears in the property list for layers and channels. "Linked" is a
- UI property: if the Move tool is used to move a linked layer, all
- other linked layers will be moved in parallel.
-
-PROP_TATTOO (internal GIMP state)
- uint32 20 The type number for PROP_TATTOO is 20
- uint32 4 Four bytes of payload
- uint32 4 The tattoo, a nonzero unsigned integer
-
- Appears in the property list of layers, channels, and entire images.
-
- A tattoo is a unique and permanent identifier attached to a drawable
- (or vector element) that can be used to uniquely identify a drawable
- within an image even between sessions.
-
- 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.
-
-PROP_PARASITES
- uint32 21 The type number for PROP_PARASITES is 21
- uint32 length Total length of the following payload data
- ,---------------- Repeat for each parasite:
- | string name Name of the parasite
- | uint32 flags ?????
- | uint32 n Size of the payload data
- | byte[n] ... Parasite-specific payload
- `--
-
- This property can appear in any property list. It can contain
- multiple "parasites" which are named extension records. See "Basic
- concepts and datatypes" above. The number of parasites 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 contents may be binary, but often a textual encoding is
- chosen in order to free the creator/consumer 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.
-
-
-9. COMPOSITING AND LAYER MODES
-===============================
-
-This section describes the "flattening" process that GIMP applies
-when a multi-layer image is displayed in the editor or exported to
-other image file formats. It is present for reference only; an XCF
-consumer may well elect to do something different with pixel data from
-the layers than flattening them.
-
-Most XCF consumers will need to react to the layer mode property of
-each layer; such a reaction must be informed by knowledge of how the
-different layer modes affect the flattening process. In some
-applications it might be acceptable for an XCF consumer to refuse
-processing images with layer modes other than "Normal", but such an
-application will probably not be considered fully XCF capable by its
-users.
-
-In this section we consider primary color (or grayscale) intensities
-and alpha values for pixels to be real numbers ranging from 0.0 to
-1.0. This makes many of the formulas easier; the reader is asked to
-keep in mind that a (linear) conversion from the integral 0..255 scale
-of the actual XCF scale is implied whenever data from the XCF file is
-mentioned.
-
-Any practical implementation of the computations specified below may
-suffer rounding errors; this specification do not detail how these are
-to be handled. GIMP itself rounds values to an integral number of
-255ths at many points in the computation. This specification does not
-specify exactly which these points are, and authors of XCF renderers
-that aim to reproduce the effects of GIMP's flattening down to the
-least significant bits are referred to studying its source code.
-
-In the description below, the variable letter "a" is used for alpha
-values. The variable letter "r", "g", "b" are used for primary
-intensities, "y" is used for grayscale intensities, and "i" is used
-for color map indexed. The letter "c" is used for the complete
-color information for a pixel; depending on the color mode of the
-image that is either an (r,g,b) triple, a y, or a c.
-
-The flattening process works independently for each pixel in the
-canvas area. The description of some layer modes in the GIMP manual
-may give the impression that they involve filters that let pixels
-influence neighbor pixels, but that is not true.
-
-This description does not attempt to preserve the color information
-for completely transparent pixels in a layer. If an application uses
-this color information, it should document explicitly how it behaves
-when transparent pixels from several different layers cover the same
-point of the canvas.
-
-Flattening overview
--------------------
-
-This is how to compute the flattened result for a single pixel
-position (in theory, that is - efficient implementations will of
-course follow this procedure or an equivalent one for many pixels in
-parallel):
-
-1. Initialize a "working pixel" (a1,c1) to be completely transparent
- (that is, a1=0.0 and the value of c1 is immaterial).
-
-2. Do the following for each visible layer in the image, starting with
- the one that comes LAST in the master layer list:
-
- 3. Ignore the layer if it is the floating selection, or if it
- does not overlap the pixel position in question.
-
- 4. Let (a2,c2) be the pixel data for the layer at the pixel
- position in question. If the layer does not have an alpha
- channel, then set a1 to 1.0.
-
- 5. If the layer is the one that the floating selection is attached
- to and the floating selection overlaps the pixel position in
- question, then do the following:
-
- 6. Let (a3,c3) be the pixel data for the floating selection
- layer at the pixel position in question.
-
- 7. If there is a selection channel, then let x be its value
- at the pixel position in question, and set a3 to a3*x.
-
- 8. Let m3 be the layer mode of the floating selection.
-
- 9. Set (a2,c2) to COMPOSITE(a2,c2, a3,c3,m3).
- The COMPOSITE function is defined below.
-
- 10. If the layer has a layer mask and it is enabled, then let x be
- the value of the layer mask at the pixel position in question,
- and set a2 to a2*x.
-
- 11. Let m2 be the layer mode of the layer.
-
- 12. If the layer is the bottommost visible layer (i.e., if it is
- the last visible layer in the master layer list) and m2 is not
- "Normal" or "Dissolve", then set m2 to "Normal".
-
- 13. Set (a1,c1) to COMPOSITE(a1,c1, a2,c2,m2).
- The COMPOSITE function is defined below.
-
-14. If the flattened image is to be shown against a background of
- color c0, then actually visible pixel is
- COMPOSITE(1.0,c0, a1,c1,Normal).
-
- Note that unless all layers have mode Normal, it would give the
- wrong result to start by initializing (a1,c1) to (1.0,c0).
-
-Helper functions
-----------------
-
-The following auxiliary functions are used in the definition of
-COMPOSITE below:
-
- MIN(x1,...,xn) is the least value of x1...xn
-
- MAX(x1,...,xn) is the largest value of x1..xn
-
- MID(x1,...,xn) = (MIN(x1,...,xn)+MAX(x1,...,xn))/2
+8. MISCELLANEOUS
+================
- CLAMP(x) = if x < 0 then 0.0 else if x > 1 then 1.0 else x
- BLEND(a1,x1, a2,x2) = (1-k)*x1 + k*x2
- where k = a2/(1-(1-a1)*(1-a2))
-
-Layer modes
------------
-
-This and the following sections define the COMPOSITE function used in
-the general flattening algorithm.
-
-"Normal" mode for RGB or grayscale images is the usual mode of
-compositing in computer graphics with alpha channels. In indexed
-mode, the alpha value gets rounded to either 1.0 or 0.0 such that
-no colors outside the color map get produced:
-
- COMPOSITE(a1,y1, a2,y2,Normal)
- = ( 1-(1-a1)*(1-a2), BLEND(a1,y1, a2,y2) )
-
- COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,Normal)
- = ( 1-(1-a1)*(1-a2), BLEND(a1,r1, a2,r2),
- BLEND(a1,g1, a2,g2),
- BLEND(a1,b1, a2,b2) )
-
- COMPOSITE(a1,i1, a2,i2,Normal) = if a2 > 0.5 then (1.0,i2) else (a1,i1)
-
-"Dissolve" mode corresponds to randomly dithering the alpha channel to
-the set {0.0, 1.0}:
-
- COMPOSITE(a1,c1, a2,c2,Dissolve) = chose pseudo-randomly between
- (1.0,c2) with probability a2
- (a1,c1) with probability 1-a2
-
-These two modes are the only ones that make sense for all of the RGB,
-grayscale and indexed color models. In the indexed color model, all
-layer modes except Dissolve are treated as Normal.
-
-Most layer modes belong to the following group, which makes sense for
-RGB and grayscale images, but not for indexed ones:
-
- COMPOSITE(a1,y2, a2,y2,m)
- = ( a1, BLEND(a1,y1, MIN(a1,a2),f(y1,y2, m)) )
-
- COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,m)
- = ( a1, BLEND(a1,r2, MIN(a1,a2),f(r1,r2, m)),
- BLEND(a1,g1, MIN(a1,a2),f(g1,g2, m)),
- BLEND(a1,b1, MIN(a1,a2),f(b1,g2, m)) )
-
-when 3 <= m <= 10 or 15 <= m <= 21.
-
-The following table defines f(x1,x2,m):
-
- Multiply: f(x1,x2, 3) = x1*x2
- Screen: f(x1,x2, 4) = 1-(1-x1)*(1-x2)
- Overlay: f(x1,x2, 5) = (1-x2)*x1^2 + x2*(1-(1-x2)^2)
- Difference: f(x1,x2, 6) = if x1 > x2 then x1-x2 else x2-x1
- Addition: f(x1,x2, 7) = CLAMP(x1+x2)
- Subtract: f(x1,x2, 8) = CLAMP(x1-x2)
- Darken Only: f(x1,x2, 9) = MIN(x1,x2)
- Lighten Only: f(x1,x2, 10) = MAX(x1,x2)
- Divide: f(x1,x2, 15) = CLAMP(x1/x2)
- Dodge: f(x1,x2, 16) = CLAMP(x1/(1-x2))
- Burn f(x1,x2, 17) = CLAMP(1-(1-x1)/x2)
- Hard Light: f(x1,x2, 18) = if x2 < 0.5 then 2*x1*x2 else 1-2*(1-x1)(1-x2)
- Soft Light: f(x1,x2, 19) = (1-x2)*x1^2 + x2*(1-(1-x2)^2)
- Grain Extract: f(x1,x2, 20) = CLAMP(x1-x2+0.5)
- Grain Merge: f(x1,x2, 21) = CLAMP(x1+x2-0.5)
-
-Note that the "Overlay" and "Soft Light" modes have identical effects.
-In the "Divide", "Dodge", and "Burn" modes, division by zero should
-be considered to produce a number so large that CLAMP(x/0) = 1 unless
-x=0, in which case CLAMP(0/0) = 0.
-
-The remaining four layer modes only make sense in the RGB color model;
-if the color mode of the image is grayscale or indexed they will be
-interpreted as Normal.
-
- COMPOSITE(a1,r1,g1,b1, a2,r2,g2,b2,m)
- = ( a1, BLEND(a1,r2, MIN(a1,a2),r0),
- BLEND(a1,g1, MIN(a1,a2),g0),
- BLEND(a1,b1, MIN(a1,a2),b0) )
- where (r0,g0,b0) = h(r1,g1,b1, r2,g2,b2, m)
-
-when 11 <= m <= 14.
-
-For defining these modes, we say that
-
-(r,g,b) has the _hue_ of (r',g',b')
- if r' = g' = b' and r >= g = b
- or there exist p and q such that p>=0 and r=p*r'+q and b=p*b'+q and g=p*g'+q
-
-(r,g,b) has the _value_ of (r',g',b')
- if MAX(r,g,b) = MAX(r',g',b')
-
-(r,g,b) has the _HSV-saturation_ of (r',g',b')
- if r' = g' = b' = 0 and r = g = b
- or MIN(r,g,b) = MAX(r,g,b)*MIN(r',g',b')/MAX(r',g',b')
-
-(r,g,b) has the _luminosity_ of (r',g',b')
- if MID(r,g,b) = MID(r',g',b')
-
-(r,g,b) has the _HSL-saturation_ of (r',g',b')
- if r' = g' = b' and r = g = b
- or MAX(r,g,b)-MIN(r,g,b) = MIN(MID(r,g,b),1-MID(r,g,b)) *
- (MAX(r',g',b')-MIN(r',g',b'))/MIN(MID(r',g',b'),1-MID(r',g',b'))
-
-Mode 11: Hue (H of HSV)
+The name XCF
+------------
- h(r1,g1,b1, r2,g2,b2, 11) is
- if r2=g2=b2 then (r1,g1,b1) unchanged
- otherwise: the color that has
- the hue of (r1,g2,b2)
- the value of (r1,g1,b1)
- the HSV-saturation of (r1,g1,b1)
+The name XCF honors GIMP's origin at the eXperimental Computing
+Facility of the University of California at Berkeley.
-Mode 12: Saturation (S of HSV)
+TODO: Integrate this document into the API doc.
- h(r1,g1,b1, r2,g2,b2, 12) is the color that has
- the hue of (r1,g1,b1)
- the value of (r1,g1,b1)
- the HSV-saturation of (r2,g2,b2)
+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?
-Mode 13: Color (H and S of HSL)
+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.?
- h(r1,g1,b1, r2,g2,b2, 13) is the color that has
- the hue of (r2,g2,b2)
- the luminosity of (r1,g1,b1)
- the HSL-saturation of (r2,g2,b2)
-Mode 14: Value (V of HSV)
-
- h(r1,g1,b1, r2,g2,b2, 14) is the color that has
- the hue of (r1,g1,b1)
- the value of (r2,g2,b2)
- the HSV-saturation of (r1,g1,b1)
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
