ilCreateClientImage(3X)

NAME

ilCreateClientImage() − create an empty client image

SYNOPSIS

ilClientImage
ilCreateClientImage (

ilContext context,

ilImageInfo *pInfo,

unsigned long mustBeZero);

DESCRIPTION

ilCreateClientImage() creates a client image that allows the client to have direct access to the image pixels. (If direct access is not required, ilCreateInternalImage() should be used instead of ilCreateClientImage() to create the image. Compressed internal images can be handled more efficiently, because they can be saved and read in strips; compressed client images are always a single strip.) The image pixels are defined when the client passes a pointer to their address in client memory or when a call to ilWriteImage() is used on the image.

The image can have a private type created by ilGetPrivateType() or a standard Image Library type.

To free the image, use ilDestroyObject(), or use ilDestroyContext() on the associated context.

context identifies a context created by IL_CREATE_CONTEXT().

*pInfo identifies an ilImageInfo structure, which describes the form, content, and attributes of the image as follows:

*pDes identifies a structure which describes the image; see ilImageDes(3X).

*pFormat identifies a structure which defines the format of the image; see ilImageFormat(3X).

width the width of the image in pixels.

height the height of the image in scan lines.

*pPalette identifies the palette for this image, if the image is a palette image (pDes->type is equal to IL_PALETTE) and clientPalette is TRUE. A palette is an array (of 768 short values) that defines the colors for the image: 256 red values, 256 green values and 256 blue values, in that order. Each pixel in the image indexes into the red, green and blue sections of the palette to determine the color of the pixel. For example pixel 0 has a red index value of entry 0 in the palette, a green index value of entry 256 and a blue index value of entry 512.

The data space pointed to by *pPalette must persist as long as the image exists; it should be created by using malloc (3 * 256 * sizeof (short)). The space is not freed by the Image Library when the image is destroyed when ilDestroyObject is used on the image or ilDestroyContext is used on the context. ilWriteImage() overwrites the palette values in the image, because the colors in the palette define the colors of the image. For a palette image, the colors can change as a result of executing ilWriteImage(), just as the pixels in the image are overwritten.

If clientPalette is FALSE and the image being created is a palette image, the Image Library creates a palette and initializes it to all black pixels.

pCompData reserved for future use; must be NULL.

clientPalette if TRUE and the image type is palette (pDes->type is equal to IL_PALETTE), causes *pPalette to be interpreted as a pointer to the palette for this image. If FALSE and the image type is palette (pDes->type is equal to IL_PALETTE), causes the Image Library to create a new palette of all black pixels.

clientCompData reserved for future use; must be FALSE (0).

clientPixels if TRUE, the pixels for the image already exist in the clients address space and plane[].pPixels points to them (see below). The Image Library does not free these pixels when the image is destroyed.

If FALSE, the Image Library creates a buffer for the pixels; call ilQueryClientImage(3X) to get the buffer address. The Image Library destroys this buffer when the image is destroyed.

filler is reserved for future use; must be zero (0)

plane an array describing the pixels of the image, used only if clientPixels is TRUE. If the image to be created is a pixel image (pFormat->sampleOrder is equal to IL_SAMPLE_PIXELS; (recommended), then plane[0] defines the pixels of the image.

If the image to be created is a planar image (pFormat->sampleOrder is equal to IL_SAMPLE_PLANES) then elements 0 through pDes->nSamplesPerPixel - 1 of plane define each plane of the image. plane contains the following fields:

*pPixels points to the pixel buffer for this plane.

nBytesPerRow for uncompressed images only (pDes->compression is equal to IL_UNCOMPRESSED): the number of bytes per row (scan line) in the image. The image buffer must be at least nBytesPerRow times height bytes in size.

bufferSize for compressed images only (pDes->compression is not equal to IL_UNCOMPRESSED): the total number of bytes in the image.

filler reserved for future use; must be zero (0)

mustBeZero identifies a value that must be zero; this parameter is reserved for future use.

RETURN VALUE

Upon completion, ilCreateClientImage() returns an ilClientImage, if successful, and a NULL, if unsuccessful.

ERRORS

If the call fails, context->error receives a non-zero error code.

EXAMPLE

The following example allocates a client image that is width times height, in size, with 1 byte per pixel and rows that are rounded up to 4-byte lengths.

ilContext context;

ilImageInfo infoBlock;

ilClientImage pImage;

int width, height;

int nBytesPerRow;
.
.
.

nBytesPerRow = ((width + 3) & (~3));

infoBlock.pDes = IL_DES_GRAY;

infoBlock.pFormat = IL_FORMAT_BYTE;

infoBlock.width = width;

infoBlock.height = height;

infoBlock.pPalette = NULL;

infoBlock.pCompData= NULL;

infoBlock.clientPalette = FALSE;

infoBlock.clientCompData= FALSE;

infoBlock.clientPixels = TRUE;

if (!(infoBlock.plane[0].pPixels =

(ilPtr) malloc (nBytesPerRow * height)))

return(IL_ERROR_MALLOC);

infoBlock.plane[0].nBytesPerRow = nBytesPerRow;
if (!(pImage = ilCreateClientImage (context, infoBlock, 0)))

return(context->error);

AUTHOR

ilCreateClientImage() was developed by HP.

Museum

Related Articles