Page 1 of 1

Structure of the IM source code

Posted: 2012-09-17T04:29:19-07:00
by whugemann
I took the question viewtopic.php?f=1&t=21866 as an occasion to have a view on the IM source files (which I have been wanting for years). At the moment, I don't want to compile IM myself, just look up some code. As expected, this is a rather complex task. I have two questions for a start:

1) Is there an overview on the logical structure of the entire project somewhere?
2) There are two directores named "magick", which seem to contain the fundamental C code, one below the root directory and one below "ImageMagick-6" directory -- why that?

Re: Structure of the IM source code

Posted: 2012-09-20T19:20:37-07:00
by anthony
The way I go into source code for IM, is start with "mogrify.c" (or in IMv7 "operation.c", which is simplier), in the MagickWand source directory.

I then follow the function call for that command line option, use pre-generated 'tags' in VIM.

If I don't follow the tag. I search for the function in Core *.h files, but then jump to the *.c file to look at the function and its documentation comments.



Note that a understanding of how the Image and WandInfo structures fit together helps a lot.

WandInfo structure has pointers to a image sequence, but also holds all the user supplied global 'options', generally in a splay tree of key-value strings. In IMv7 CLI-Wand is also a Wand but with extra structure items for CLI command line processing, so that Imv7 can report exactly which CLI option is being processed when an error occurse, and its location on the CLI or from a Magick Script

Each Image in the linked list pointed to by the 'Wand' holds, the image data and attribute (non-strings, like width, height, colorspace, background color), properities (saved image meta-data such as profiles) splay tree, and a per-image artifact splay tree. NOTE: properitys are saved with images to disk, artifacts are not, and are internal use only)

You can see these values using -verbose info:.

In IMv6 all global 'option' values are copied into every individual image's 'artifact' splay tree that the 'wand' was holding, so Core function (which generally do not have access to 'WandInfo') can find the user supplied options.

In IMv7 this changed. 'options' are no long copied, but a link was added to the image structure which 'may' point back to the parent wand info. This allows a lookup of some 'attribute' (or percent escape) to return (in this order of search), attribute, properity, artifact, or global option. This avoids a lot of un-nessary copying of values for Wand or CLI image processing, going on with IMv6.

This means also that in IMv7 you will eventually be able to set a global 'option' but also a specific per-image 'artifact' for the same value. That means you can for example distort a set of images all the same way (using a percent escape), except for one specific image which will be distorted using a different percent escape. :-) at least in theory. I will make it that setting a global option will delete any existing per-image artifact of the same name, but that has not been done yet.