mirror of https://github.com/GNOME/gimp.git
115 lines
4.7 KiB
Plaintext
115 lines
4.7 KiB
Plaintext
|
|
PARASITE REGISTRY - 1998/10/09
|
|
=================
|
|
|
|
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 CVS or submit patches to
|
|
>>>> gimp-developer@scam.xcf.berkeley.edu
|
|
|
|
|
|
------------------------------------------------------------------
|
|
*** PREFIXES:
|
|
|
|
"tiff" : The standard GIMP TIFF plugin
|
|
"jpeg" : The standard GIMP JPEG plugin
|
|
"gimp" : For common and standard parasites
|
|
"perl-fu" : Internal data by the Gimp-perl interface
|
|
|
|
|
|
------------------------------------------------------------------
|
|
*** PARASITES:
|
|
|
|
"gimp-comment" : Standard GIF-style comments. This parasite is
|
|
human-readable text in unspecified 8-bit ASCII. It
|
|
includes a trailing \0 string terminator. The size
|
|
of the parasite data may not exceed 241 bytes. This
|
|
parasite attaches to images only. It is persistent,
|
|
which means it is saved in XCF files.
|
|
|
|
"tiff-save-options" : The TiffSaveVals structure from the TIFF plugin.
|
|
This parasite attaches to images only. It is not
|
|
persistent.
|
|
|
|
"jpeg-save-options" : The JpegSaveVals structure from the JPEG plugin.
|
|
This parasite attaches to images only. It is not
|
|
persistent.
|
|
|
|
"perl-fu-last-vals-<plug-in>" : The Gimp::Fu module might store the
|
|
arguments of the last plug-in invocation. It is usually
|
|
attached to images, but might also be found globally. It
|
|
might also be persistent. The data format is either
|
|
pure character data (Data::Dumper) or a serialized data
|
|
stream created by Storable::nfreeze.
|
|
|
|
|
|
------------------------------------------------------------------
|
|
|
|
*** 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
|
|
current gimp session. If you need persistant data, you basically have to
|
|
choose between the following alternatives (also, having some standard for
|
|
non-persistant data might be fine as well):
|
|
|
|
- cook your own binary data format
|
|
|
|
You can invent your own data format. This means that you will either
|
|
loose totally (consider endian-ness or version-ness issues) or you will
|
|
get yourself into deep trouble to get it "right" in all cases.
|
|
|
|
- use character (string) data
|
|
|
|
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
|
|
more robustness (consider the case when you add more entries to your
|
|
persistant data: older plug-ins might be able to read the relevant
|
|
parts and your application can detect missing fields easily). The
|
|
drawback is that your data is likely to be larger than a compact binary
|
|
representation would be. Not much a problem for most applications,
|
|
though.
|
|
|
|
You could also use one parasite per field you store, i.e. foo-size,
|
|
foo-offset-x, foo-offset-y etc...
|
|
|
|
- use the libgimp serialize functions
|
|
|
|
Look at the stuff in libgimp/gserialize.h. These functions allow for
|
|
relatively easy serializing/deserializing of structs. The advantages
|
|
are that the gimp-developers have already taken care of endian-ness
|
|
issues and other hazzles. The drawback is that you might encounter
|
|
problems when you want to extend your structures later, as you have to
|
|
be prepared for images saved with parasites form a very old version of
|
|
your plug-in, and the gserialize functions do not handle different data
|
|
formats nicely itself.
|
|
|
|
One way out around this is to prefix your data with a version identifier
|
|
(remember to use a guchar, i.e. something without endian-ness problems).
|
|
Depending on that (remember to skip it before deserializing)
|
|
|
|
Another very easy way is to add a version tag to your parasite name,
|
|
i.e. "foo-bar-v1", "foo-bar-v2". Your plug-in could then check for older
|
|
versions and act accordingly and/or attach the new parasite or both the
|
|
new and the old version of your data.
|
|
|
|
The gserialize stuff also makes it possible to just append more fields
|
|
(i.e. more gserialized structs) to your data. You could check the length
|
|
of the parasite data ("anything left?") to decide wether to decode more
|
|
fields. Here's some example:
|
|
|
|
data = parasite_data(p);
|
|
size = parasite_data_size(p);
|
|
length = gdeserialize(...);
|
|
tlength += length;
|
|
data += length;
|
|
if (tlength != size)
|
|
gdeserialize the next one, etc.
|
|
|
|
|
|
|