ImageMagick MagickInfo Structure

The MagickInfo structure is used by ImageMagick to register support for an Image format. The MagickInfo structure is allocated with default parameters by calling SetMagickInfo(). Image formats are registered by calling RegisterMagickInfo() which adds the initial structure to a linked list (at which point it is owned by the list). A pointer to the structure describing a format may be obtained by calling GetMagickInfo(). Pass the argument NULL to obtain the first member of this list. A human-readable list of registered image formats may be printed to a file descriptor by calling ListMagickInfo().

Support for formats may be provided as a module which is part of the ImageMagick library, provided by a module which is loaded dynamically at run-time, or directly by the linked program. Users of ImageMagick will normally want to create a loadable-module, or support encode/decode of an image format directly from within their program.

Sample Module:

The following shows sample code for a module called "GIF" (gif.c). Note that the names of the Register and Unregister call-back routines are calculated at run-time, and therefore must follow the rigid naming scheme RegisterFORMATImage and UnregisterFORMATImage, respectively, where FORMAT is the upper-cased name of the module file:

/* Read image */
Image *ReadGIFImage(const ImageInfo *image_info)
{
[ decode the image ... ]
}

/* Write image */
unsigned int WriteGIFImage(const ImageInfo *image_info,Image *image)
{
[ encode the image ... ]
}

/* Module call-back to register support for formats */
void RegisterGIFImage(void)
{
MagickInfo
*entry;

entry=SetMagickInfo("GIF");
entry->decoder=ReadGIFImage;
entry->encoder=WriteGIFImage;
entry->description=AllocateString("CompuServe graphics interchange format");
entry->module=AllocateString("GIF");
RegisterMagickInfo(entry);
entry=SetMagickInfo("GIF87");
entry->decoder=ReadGIFImage;
entry->encoder=WriteGIFImage;
entry->adjoin=False;
entry->description=
AllocateString("CompuServe graphics interchange format (version 87a)");
entry->module=AllocateString("GIF");
RegisterMagickInfo(entry);
}

/* Module call-back to unregister support for formats */
Export void UnregisterGIFImage(void)
{
UnregisterMagickInfo("GIF");
UnregisterMagickInfo("GIF87");
}

Sample Application Code

Image format support provided within the user's application does not need to implement the RegisterFORMATImage and UnregisterFORMATImage call-back routines. Instead, the application takes responsibility for the registration itself. An example follows:

/* Read image */
Image *ReadGIFImage(const ImageInfo *image_info)
{
[ decode the image ... ]
}

/* Write image */
unsigned int WriteGIFImage(const ImageInfo *image_info,Image *image)
{
[ encode the image ... ]
}

#include <stdio.h>
int main( void )
{
struct MagickInfo* info;

info = SetMagickInfo("GIF");

if ( info == (MagickInfo*)NULL )
exit(1);

info->decoder = ReadGIFImage;
info->encoder = WriteGIFImage;
info->adjoin = False;
info->description = AllocateString("CompuServe graphics interchange format");
/* Add MagickInfo structure to list */
RegisterMagickInfo(info);

info = GetMagickInfo("GIF");
[ do something with info ... ]

ListMagickInfo( stdout );
return;
}

MagickInfo Structure Definition

The members of the MagickInfo structure are shown in the following table:

**MagickInfo Structure Members**
Member	Type	Description
adjoin	unsigned int	Set to non-zero (True) if this file format supports multi-frame images.
blob_support	unsigned int	Set to non-zero (True) if the encoder and decoder for this format supports operating on arbitrary BLOBs (rather than only disk files).
data	void *	User specified data. A way to pass any sort of data structure to the endoder/decoder. To set this, GetMagickInfo() must be called to first obtain a pointer to the registered structure since it can not be set via a RegisterMagickInfo() parameter.
decoder	Image (decoder)(const ImageInfo *)	Function to decode image data and return ImageMagick Image.
description	char *	Long form image format description (e.g. "CompuServe graphics interchange format").
encoder	unsigned int (encoder)(const ImageInfo , Image *)	Function to encode image data with options passed via ImageInfo and image represented by Image.
module	char *	Name of module (e.g. "GIF") which registered this format. Set to NULL if format is not registered by a module.
name	const char *	Magick string (e.g. "GIF") which identifies this format.
next	MagickInfo	Next MagickInfo struct in linked-list. NULL if none.
previous	MagickInfo	Previous MagickInfo struct in linked-list. NULL if none.
raw	unsigned int	Image format does not contain size (must be specified in ImageInfo).