devel-docs/parasites.txt

   1
   2 PARASITE REGISTRY
   3 =================
   4
   5 This document describes parasites in GIMP.
   6
   7
   8 Table of contents
   9 -----------------
  10 Parasite registry
  11   Table of contents
  12   Audience
  13
  14 1. Namespace
  15
  16 2. Known prefixes
  17
  18 3. Known global parasites
  19
  20 4. Known image parasites
  21
  22 5. Known layer/drawable parasites
  23
  24 6. Parasite format
  25
  26
  27 Audience
  28 --------
  29 This document is designed for the convenience of GIMP developers.
  30 It does not need to concern users.
  31
  32 >>>> If your plug-in or script writes parasites, please
  33 >>>> amend this file in the Git repository or submit patches to
  34 >>>> gimp-developer-list@gnome.org
  35
  36
  37 1. NAMESPACE
  38 ============
  39
  40 Plug-in-specific data should be prefixed by the plug-in function name and
  41 a slash, i.e. private data of plug_in_displace should be named like:
  42
  43 plug_in_displace/data1
  44 plug_in_displace/data2
  45 etc.
  46
  47 Global data follows no strict rules.
  48
  49
  50 2. KNOWN PREFIXES
  51 =================
  52
  53 "tiff"    : The standard GIMP TIFF plugin
  54 "jpeg"    : The standard GIMP JPEG plugin
  55 "png"     : The standard GIMP PNG plugin
  56 "dcm"     : The standard GIMP DICOM plugin
  57 "gimp"    : For common and standard parasites
  58
  59
  60 3. KNOWN GLOBAL PARASITES
  61 =========================
  62
  63 "jpeg-save-defaults" (GLOBAL, PERSISTENT)
  64         Default save parameters used by the JPEG plug-in.
  65
  66 "png-save-defaults" (GLOBAL, PERSISTENT)
  67         Default save parameters used by the PNG plug-in.
  68
  69 "<plug-in>/_fu_data" (GLOBAL, IMAGE, DRAWABLE, PERSISTENT)
  70         The Gimp::Fu module (Perl) might store the arguments of the
  71         last plug-in invocation. It is usually attached to images,
  72         but might also be found globally. The data format is either
  73         pure character data (Data::Dumper) or a serialized data
  74         stream created by Storable::nfreeze.
  75
  76 "exif-orientation-rotate" (GLOBAL, PERSISTENT)
  77         Whether a load plug-in should automatically rotate the image
  78         according to the orientation specified in the EXIF data. This
  79         has values "yes" or "no". If the parasite is not set, the
  80         plug-in should ask the user what to do. This parasite may be
  81         removed in a future version (assuming always yes).
  82
  83
  84 4. KNOWN IMAGE PARASITES
  85 ========================
  86
  87 "gimp-comment" (IMAGE, PERSISTENT)
  88         Standard GIF-style image comments.  This parasite should be
  89         human-readable text in UTF-8 encoding.  A trailing \0 might
  90         be included and is not part of the comment.  Note that image
  91         comments may also be present in the "gimp-metadata" parasite.
  92
  93 "gimp-brush-name" (IMAGE, PERSISTENT)
  94         A string in UTF-8 encoding specifying the name of a GIMP brush.
  95         Currently, the gbr plug-in uses this parasite when loading and
  96         saving .gbr files. A trailing \0 might be included and is not
  97         part of the name.
  98
  99 "gimp-brush-pipe-name" (IMAGE, PERSISTENT)
 100         A string in UTF-8 encoding specifying the name of a GIMP brush
 101         pipe. Currently, the gih plug-in uses this parasite when loading and
 102         saving .gih files. A trailing \0 might be included and is not
 103         part of the name.
 104
 105 "gimp-brush-pipe-parameters" (IMAGE, PERSISTENT)
 106         This is all very preliminary:
 107
 108         A string, containing parameters describing how an brush pipe
 109         should be used. The contents is a space-separated list of
 110         keywords and values. The keyword and value are separated by a
 111         colon.
 112
 113         This parasite is currently attached to an image by the psp
 114         plug-in when it loads a .tub file (Paint Shop Pro picture
 115         tube). It is used (first attached with values asked from the
 116         user, if nonexistent) by the gpb plug-in when it saves a .gih
 117         file. The .gih file contains the same text in it.
 118
 119         The keywords are:
 120         ncells: the number of brushes in the brush pipe
 121         step: the default spacing for the pipe
 122         dim: the dimension of the pipe. The number of cells
 123                 in the pipe should be equal to the product
 124                 of the ranks of each dimension.
 125         cols: number of columns in each layer of the image,
 126                 to be used when editing the pipe as a GIMP image
 127         rows: ditto for rows. Note that the number of columns and rows
 128                 not necessarily are identical to the ranks of the
 129                 dimensions of a pipe, but in the case of two-
 130                 and three-dimensional pipes, it probably is.
 131         rank0, rank1, ...: (one for each dimension): the index range
 132                 for that dimension
 133         placement: "default", "constant" or "random". "constant" means
 134                 use the spacing in the first brush in the pipe.
 135                 "random" means perturb that with some suitable
 136                 random number function. (Hmm, would it be overdoing it
 137                 if the pipe also could specify what random function
 138                 and its parameters...?)
 139         sel0, sel1, ...: "default", "random", "incremental", "angular",
 140                 "pressure", "velocity", and whatever else suitable we might
 141                 think of ;-) Determines how one index from each dimension is
 142                 selected (until we have pinpointed the brush to use).
 143
 144 "gimp-image-grid" (IMAGE, PERSISTENT)
 145         The GimpGrid object serialized to a string. Saved as parasite
 146         to keep the XCF files backwards compatible. Although gimp-1.2
 147         does not know how to handle the image grid, it keeps the grid
 148         information intact.
 149
 150 "gimp-pattern-name" (IMAGE, PERSISTENT)
 151         A string in UTF-8 encoding specifying the name of a GIMP pattern.
 152         Currently, the pat plug-in uses this parasite when loading and
 153         saving .pat files. A trailing \0 might be included and is not
 154         part of the name.
 155
 156 "tiff-save-options" (IMAGE)
 157         The TiffSaveVals structure from the TIFF plugin.
 158
 159 "jpeg-save-options" (IMAGE)
 160         The JpegSaveVals structure from the JPEG plugin.
 161
 162 "jpeg-exif-data" (IMAGE) (deprecated)
 163         The ExifData structure serialized into a uchar* blob from
 164         libexif. This is deprecated in favor of "exif-data".
 165
 166 "jpeg-original-settings" (IMAGE, PERSISTENT)
 167         The settings found in the original JPEG image: quality (IJG),
 168         color space, component subsampling and quantization tables.
 169         These can be reused when saving the image in order to minimize
 170         quantization losses and keep the same size/quality ratio.
 171
 172 "gamma" (IMAGE, PERSISTENT)
 173         The original gamma this image was created/saved. For JPEG; this is
 174         always one, for PNG it's usually taken from the image data. GIMP
 175         might use and modify this. The format is an ascii string with the
 176         gamma exponent as a flotingpoint value.
 177
 178         Example: for sRGB images this might contain "0.45454545"
 179
 180 "chromaticity" (IMAGE, PERSISTENT)
 181         This parasite contains 8 floatingpoint values (ascii, separated by
 182         whitespace) specifying the x and y coordinates of the whitepoint, the
 183         red, green and blue primaries, in this order.
 184
 185         Example: for sRGB images this might contain
 186         "0.3127 0.329 0.64 0.33 0.3 0.6 0.15 0.06"
 187          wx     wy    rx   ry   gx  gy  bx   by
 188
 189 "rendering-intent" (IMAGE, PERSISTENT)
 190         This specifies the rendering intent of the image. It's a value
 191         between 0 and 3, again in ascii:
 192
 193         0 - perceptual                  (e.g. for photographs)
 194         1 - relative colorimetric       (e.g. for logos)
 195         2 - saturation-preserving       (e.g. for business charts)
 196         3 - absolute colorimetric
 197
 198 "hot-spot" (IMAGE, PERSISTENT)
 199         Use this parasite to store an image's "hot spot". Currently
 200         used by the XBM plugin to store mouse cursor hot spots.
 201
 202         Example: a hot spot at coordinates (5,5) is stored as "5 5"
 203
 204 "exif-data" (IMAGE, PERSISTENT)
 205         The ExifData structure serialized into a character array by
 206         libexif (using exif_data_save_data). If a "gimp-metadata"
 207         parasite is present, it should take precedence over this one.
 208
 209 "gimp-metadata" (IMAGE, PERSISTENT)
 210         The metadata associated with the image, serialized as one XMP
 211         packet.  This metadata includes the contents of any XMP, EXIF
 212         and IPTC blocks from the original image, as well as
 213         user-specified values such as image comment, copyright,
 214         license, etc.
 215
 216 "icc-profile" (IMAGE, PERSISTENT | UNDOABLE)
 217         This contains an ICC profile describing the color space the
 218         image was produced in. TIFF images stored in PhotoShop do
 219         oftentimes contain embedded profiles. An experimental color
 220         manager exists to use this parasite, and it will be used
 221         for interchange between TIFF and PNG (identical profiles)
 222
 223 "icc-profile-name" (IMAGE, PERSISTENT | UNDOABLE)
 224         The profile name is a convenient name for referring to the
 225         profile. It is for example used in the PNG file format.  The
 226         name must be stored in UTF-8 encoding. If a file format uses
 227         a different character encoding, it must be converted to UTF-8
 228         for use as a parasite.
 229
 230 "decompose-data" (IMAGE, NONPERSISTENT)
 231         Starting with GIMP 2.4, this is added to images produced by
 232         the decompose plug-in, and contains information necessary to
 233         recompose the original source RGB layer from the resulting
 234         grayscale layers.  It is ascii; a typical example would be
 235         "source=2 type=RGBA 4 5 6 7".  This means that layer 2 was
 236         decomposed in RGBA mode, giving rise to layers 4, 5, 6, and 7.
 237
 238 "print-settings" (IMAGE, NONPERSISTENT)
 239         This parasite is stored by the Print plug-in and holds settings
 240         done in the Print dialog. It also has a version field so that
 241         changes to the parasite can be done. GIMP 2.4 used version 0.3.
 242         The format is GKeyFile. A lot of the contents are identical to
 243         what is stored in ~/.gimp-2.x/print-settings but the parasite
 244         has some additional image-related fields.
 245
 246 "print-page-setup" (IMAGE, NONPERSISTENT)
 247         This parasite is stored by the Print plug-in and holds settings
 248         done in the Page Setup dialog. The format is GKeyFile as created
 249         from GtkPageSetup. The content is identical to what is stored in
 250         ~/.gimp-2.x/print-page-setup.
 251
 252 "dcm/XXXX-XXXX-AA" (IMAGE, PERSISTENT)
 253         These parasites are stored by the Dicom plug-in and hold the DICOM
 254         element information for that image. The format is raw binary data
 255         as read from the original image.
 256         where: XXXX is a 4-digit ascii encoded hexadecimal number
 257                AA is a two character ascii value representing the Dicom
 258                  element's Value Representation (VR)
 259
 260
 261 5. KNOWN LAYER/DRAWABLE PARASITES
 262 =================================
 263
 264 "gimp-text-layer" (LAYER, PERSISTENT)
 265         The associated GimpText object serialized to a string. For
 266         convenience the string is terminated by a trailing '\0'.
 267         The idea of using a parasite for text layers is to keep the XCF
 268         files backward compatible. Although gimp-1.2 doesn't know how
 269         to handle the text layer, it keeps the parasite intact.
 270
 271 "gfig" (LAYER, PERSISTENT)
 272         As of GIMP 2.2, the gfig plug-in creates its own layers, and
 273         stores a representation of the figure as a layer parasite.
 274         The parasite contains a GFig save file, in an ascii format.
 275         If gfig is started while the active layer contains a "gfig"
 276         parasite, the contents of the parasite are loaded at startup.
 277
 278
 279 6. PARASITE FORMAT
 280 ==================
 281
 282 The parasite data format is not rigidly specified. For non-persistent
 283 parasites you are entirely free, as the parasite data does not survive the
 284 current gimp session. If you need persistent data, you basically have to
 285 choose between the following alternatives (also, having some standard for
 286 non-persistent data might be fine as well):
 287
 288 - Cook your own binary data format
 289
 290   You can invent your own data format. This means that you will either
 291   loose totally (consider endian-ness or version-ness issues) or you will
 292   get yourself into deep trouble to get it "right" in all cases.
 293
 294 - Use character (string) data
 295
 296   Obvious to Perl people but less so to C programmers: just sprintf your
 297   data into a string (e.g. "SIZE 100x200 XRES 300 YRES 300") and store
 298   that in the parasite, and later sscanf it again. This often solves most
 299   of the problems you might encounter, makes for easier debugging and
 300   more robustness (consider the case when you add more entries to your
 301   persistent data: older plug-ins might be able to read the relevant
 302   parts and your application can detect missing fields easily). The
 303   drawback is that your data is likely to be larger than a compact binary
 304   representation would be. Not much a problem for most applications,
 305   though.
 306
 307   You could also use one parasite per field you store, i.e. foo-size,
 308   foo-offset-x, foo-offset-y etc...
 309
 310 - Use the libgimpconfig serialize functions
 311
 312   This is a special case of the previous one, using the convenience
 313   functions provided by libgimpconfig.  If you are not concerned about
 314   the size of the string representation of your data, you can use
 315   gimp_config_serialize_to_string() and other functions to easily
 316   convert your data to/from a character string.