"Fossies" - the Fresh Open Source Software Archive

Member "gimp-2.10.28/devel-docs/parasites.txt" (14 Sep 2021, 12719 Bytes) of package /linux/misc/gimp-2.10.28.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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.