The pointer lists after the header lead to
layer, channel and (from version 18) path structures. A layer or channel points to a
hierarchy, the hierarchy to a level, and the level to the tiles that hold the pixels.
POINTER is 4 bytes up to version 10 and 8 bytes from version 11. The
properties are on their own page.
Layer
| Type | Name | Description |
|---|---|---|
UINT32 | width | Layer width in pixels. |
UINT32 | height | Layer height in pixels. |
UINT32 | type | Colour type, below. |
STRING | name | Layer name. |
| property list | properties | Ended by PROP_END. The position on the canvas is PROP_OFFSETS. |
POINTER | hptr | The hierarchy holding the pixels. A layer group has a hierarchy too, which readers ignore. |
POINTER | mptr | The layer mask, a channel structure; 0 if none. |
POINTER[] | effects | Version 20 and later: pointers to effects, ended by a 0 pointer. |
| Type | Pixels |
|---|---|
| 0 | RGB |
| 1 | RGB with alpha |
| 2 | Greyscale |
| 3 | Greyscale with alpha |
| 4 | Indexed |
| 5 | Indexed with alpha |
Layers are listed top first. Groups are not nested in the file: every layer is in
the one list, and PROP_ITEM_PATH gives each one’s place in the tree of
PROP_GROUP_ITEM layers.
Channel and layer mask
| Type | Name | Description |
|---|---|---|
UINT32 | width | Must equal the canvas width, or the layer width for a mask. |
UINT32 | height | Likewise for the height. |
STRING | name | Channel name. |
| property list | properties | Ended by PROP_END. |
POINTER | hptr | The hierarchy holding the channel’s one component per pixel. |
A layer mask is a channel reached through the layer’s mptr, not through
the image’s channel list. Unless PROP_APPLY_MASK turns it off, the mask is
multiplied into the layer’s alpha, so it can only make the layer more transparent.
The selection is the channel with PROP_SELECTION. Version 26 saves
effects on channels and masks as well; GIMP’s format page does not yet show where
their pointers go in the channel structure.
Hierarchy
| Type | Name | Description |
|---|---|---|
UINT32 | width | Same as the layer or channel; a check. |
UINT32 | height | Likewise. |
UINT32 | bpp | Bytes per pixel: the number of components (including alpha) times the bytes per component of the precision. 8-bit RGB is 3, 8-bit RGBA 4, 16-bit RGB 6, 32-bit RGBA 16; indexed is always 1 or 2. |
POINTER | lptr | The first level, the only one used. |
POINTER[] | dlevels | Pointers to dummy levels, which old GIMP wrote as smaller copies; ignored. |
POINTER | 0, ending the list. |
Level
| Type | Name | Description |
|---|---|---|
UINT32 | width | Width of this level. |
UINT32 | height | Height of this level. |
POINTER[] | tptr | One pointer per tile: ceil(width / 64) × ceil(height / 64) of them, row by row from the top, left to right. |
POINTER | 0, ending the list. |
Tiles are 64 by 64 pixels, except those in the right column and bottom row, which are cut to the edge. The tiles of one level are stored one after another, so the size of a compressed tile is the distance to the next pointer. Dummy levels use 4-byte pointers even in version 11 and later, an oversight that readers must allow for.
Tile data
The encoding is set for the whole file by PROP_COMPRESSION. Pixels are
in the order red, green, blue (or grey, or index), then alpha last; components wider
than one byte are big-endian.
| Value | Encoding |
|---|---|
| 0 | None: the tile’s pixels one after another, bpp bytes each. |
| 1 | RLE, what GIMP writes by default. Below. |
| 2 | zlib: the uncompressed tile, as above, compressed as one zlib stream per tile. Version 8 and later. |
| 3 | Reserved; never used. |
RLE
The tile is split into bpp streams: first byte 0 of every pixel, then
byte 1 of every pixel, and so on. Each stream is run-length encoded on its own; a run
never crosses into the next stream. Each operation starts with an opcode byte
n:
| Opcode | Followed by | Meaning |
|---|---|---|
| 0 to 126 | v | Repeat v n + 1 times. |
| 127 | p, q, v | Repeat v p × 256 + q times. |
| 128 | p, q, data | Copy the next p × 256 + q bytes. |
| 129 to 255 | data | Copy the next 256 − n bytes. |
GIMP’s format page asks that an encoded tile stay under 24 KB, and to keep within that it advises writers to use opcode 255 rather than 0 for a single byte, the long forms 127 and 128 only for lengths over 127, and never two copy operations in a row.
Effect
Version 20 and later. A non-destructive filter on a layer (and from version 26 on a channel or mask), run by a GEGL operation.
| Type | Name | Description |
|---|---|---|
STRING | name | Name shown to the user. |
STRING | icon | Icon name. |
STRING | operation | GEGL operation, such as gegl:gaussian-blur. |
STRING | version | Version 22 and later: the operation’s version. |
| property list | properties | PROP_FILTER_REGION, one PROP_FILTER_ARGUMENT per argument, PROP_FILTER_CLIP, and the shared visible, opacity, mode, blend space, composite space and composite mode properties. |
POINTER | mptr | The effect’s mask, a channel structure; 0 if none. |
Path (version 18 and later)
| Type | Name | Description |
|---|---|---|
STRING | name | Path name. |
UINT32 | plength | Length of the rest of the structure. |
| property list | properties | Tattoo, visible, locks, colour tag, selected and parasites. |
UINT32 | version | 1. |
UINT32 | k | Number of strokes. |
| stroke[k] | strokes | The strokes, below. |
Stroke
| Type | Name | Description |
|---|---|---|
UINT32 | type | 1 Bézier stroke (0 is defined in the source as a plain stroke but not written). |
UINT32 | closed | 1 closed. |
UINT32 | nf | Floats per point, 2 to 6. |
UINT32 | np | Number of points. |
| point[np] | points | Each: UINT32 type (0 anchor, 1 Bézier control), then FLOAT x, y; with nf ≥ 3 pressure, nf ≥ 4 x tilt and y tilt, nf = 6 wheel. Missing values default to 1.0 for pressure and 0.5 for the others. |
PROP_VECTORS (before version 18)
The image property holds UINT32 version (1), the index of the active
path and the number of paths, then for each path: STRING name,
UINT32 tattoo, visible and linked, a parasite count and the parasites,
the stroke count and the strokes as above.
PROP_PATHS (old format)
A UINT32 index of the active path and the number of paths, then each
path in one of three formats, told apart by its version field:
| Field | Format 1 | Format 2 | Format 3 |
|---|---|---|---|
| name | STRING | STRING | STRING |
| linked | UINT32 | UINT32 | UINT32 |
| state | byte | byte | byte |
| closed | UINT32 | UINT32 | UINT32 |
| np (points) | UINT32 | UINT32 | UINT32 |
| version | 1 | 2 | 3 |
| dummy | UINT32 1 | UINT32 1 | |
| tattoo | UINT32 | ||
| each point | INT32 type, INT32 x, y | INT32 type, FLOAT x, y | INT32 type, FLOAT x, y |
Parasites met in files
GIMP’s format page points to devel-docs/parasites.txt in GIMP’s source for
the list of parasite names. Common ones are gimp-comment (the image
comment), gimp-text-layer (the text and style of a text layer),
icc-profile (the colour profile) and gimp-metadata (Exif, XMP
and IPTC metadata, which may also hold the comment). Each parasite’s flags say whether
it is saved with the file and whether changing it can be undone; their bit values
are not given on the format page.