NAME

constitute - Methods to Constitute an Image

SYNOPSIS

Image * ConstituteImage( const unsigned int width, const unsigned int height, const char *map, const StorageType type, const void *pixels, ExceptionInfo *exception );

unsigned int DispatchImage( Image *image, const int x, const int y, const unsigned int columns, const unsigned int rows, const char *map, const StorageType type, void *pixels );

Image * PingImage( const ImageInfo *image_info, ExceptionInfo *exception );

Image * ReadImage( const ImageInfo *image_info, ExceptionInfo *exception );

Image * ReadImages( const ImageInfo *image_info, ExceptionInfo *exception );

unsigned int WriteImage( const ImageInfo *image_info, Image *image );

FUNCTION DESCRIPTIONS

ConstituteImage

Method ConstituteImage is a convenience routine that creates an image from the pixel data you supply and returns it. It allocates the memory necessary for the new Image structure and returns a pointer to the new image. The pixel data must be in scanline order top-to-bottom. The data can be character, short int, integer, float, or double. Float and double require the pixels to be normalized [0..1]. The other types are [0..MaxRGB]. For example, to create a 640x480 image from unsigned red-green-blue character data, use

image=ConstituteImage ( 640, 480, "RGB", 0, pixels, &exception );;

The format of the Constitute method is:

Image *ConstituteImage ( const unsigned int width, const unsigned int height, const char *map, const StorageType type, const void *pixels, ExceptionInfo *exception );

A description of each parameter follows:

image:

Method Constitute returns a pointer to the image. A null image is returned if there is a memory shortage or if the image cannot be read.

width:

Specifies the width in pixels of the image.

height:

Specifies the height in pixels of the image.

map:

This character string can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, and K = black. The ordering reflects the order of the pixels in the supplied pixel array.

type:

pixel type where 0 = unsigned char, 1 = short int, 2 = int, 3 = float, and 4 = double. Float and double types are expected to be normalized [0..1] otherwise [0..MaxRGB].

pixels:

This array of values contain the pixel components as defined by the map and type parameters. The length of the arrays must equal the area specified by the width and height values and type parameters.

exception:

return any errors or warnings in this structure.

DispatchImage

Method DispatchImage is a convenience routine. Use it to extract pixel data from an image and place it in a buffer you supply. The data is saved either as char, short int, integer, float or double format in the order specified by the type parameter. For example, we want to extract scanline 1 of a 640x480 image as character data in red-green-blue order:

DispatchImage ( image, 0, 0, 640, 1, "RGB", 0, pixels );;

The format of the DispatchImage method is:

unsigned int DispatchImage ( Image *image, const int x, const int y, const unsigned int columns, const unsigned int rows, const char *map, const StorageType type, void *pixels );

A description of each parameter follows:

image:

Specifies a pointer to a Image structure; returned from ReadImage.

x,y,columns,rows:

These values define the perimeter of a region of pixels you want to extract.

map:

type:

pixel type where 0 = unsigned char, 1 = short int, 2 = int, 3 = float, and 4 = double. Float and double types are expected to be normalized [0..1] otherwise [0..MaxRGB].

pixels:

This array of values contain the pixel components as defined by the map and type parameters. The length of the arrays must equal the area specified by the width and height values and type parameters.

PingImage

Method PingImage returns the image size in bytes if it exists and can be the image is returned as well. Note, only the first image in a multi-frame image file is pinged.

The format of the PingImage method is:

Image *PingImage ( const ImageInfo *image_info, ExceptionInfo *exception );

A description of each parameter follows:

Image:

Method PingImage returns the image size in bytes if the image file exists and it size can be determined otherwise 0.

image_info:

Specifies a pointer to an ImageInfo structure.

exception:

return any errors or warnings in this structure.

ReadImage

Method ReadImage reads an image and returns it. It allocates the memory necessary for the new Image structure and returns a pointer to the new image. By default, the image format is determined by its magic number. To specify a particular image format, precede the filename with an explicit image format name and a colon (i.e. ps:image) or as the filename suffix (i.e. image.ps).

The format of the ReadImage method is:

Image *ReadImage ( const ImageInfo *image_info, ExceptionInfo *exception );

A description of each parameter follows:

image:

Method ReadImage returns a pointer to the image after reading. A null image is returned if there is a memory shortage or if the image cannot be read.

image_info:

Specifies a pointer to an ImageInfo structure.

exception:

return any errors or warnings in this structure.

ReadImages

Method ReadImages reads a list of image names from a file and then returns the images as a linked list.

The format of the ReadImage method is:

Image *ReadImages ( const ImageInfo *image_info, ExceptionInfo *exception );

A description of each parameter follows:

image:

Method ReadImage returns a pointer to the image after reading. A null image is returned if there is a memory shortage or if the image cannot be read.

image_info:

Specifies a pointer to an ImageInfo structure.

WriteImage

Method WriteImage writes an image to a file as defined by image->filename. You can specify a particular image format by prefixing the file with the image type and a colon (i.e. ps:image) or specify the image type as the filename suffix (i.e. image.ps). The image may be modified to adapt it to the requirements of the image format. For example, DirectClass images must be color-reduced to PseudoClass if the format is GIF.

The format of the WriteImage method is:

unsigned int WriteImage ( const ImageInfo *image_info, Image *image );

A description of each parameter follows:

status:

Method WriteImage return True if the image is written. False is returned is there is a memory shortage or if the image file fails to write.

image_info:

Specifies a pointer to an ImageInfo structure.

image:

A pointer to a Image structure.