ilWriteFileImage(3X)

NAME

ilWriteFileImage() − write a pipe image to a TIFF file

SYNOPSIS

ilBool
ilWriteFileImage (

ilPipe pipe,

ilFile file,

unsigned int method,

ilFileImage fileImage,

unsigned int compression,

ilPtr pCompData,

long stripHeight,

long xRes,

long yRes,

short page,

short nPages,

int nTags,

ilFileTag *pTags,

unsigned long mustBeZero);

DESCRIPTION

ilWriteFileImage() writes a pipe image to a TIFF file.

pipe is an Image Library pipe created by ilCreatePipe().

file is an ilFile returned by ilConnectFile().

method is either IL_WRITE_MAIN, IL_WRITE_MASK or IL_WRITE_CHILD, which are defined as follows:

IL_WRITE_MAIN
means that fileImage is ignored and the pipe image is written as one page in the TIFF file.

IL_WRITE_MASK
means that the pipe image is written as a mask image associated with fileImage, which is called the main image. The main image must be an element from the list returned by ilListFileImages() for the given file. The pipe image must have nSamplesPerPixel and nBitsPerSample[0] equal to one (1), and the main image must not already have a mask image or itself be a mask image; otherwise, an IL_ERROR_FILE_WRITE_METHOD error is returned.

Mask images determine the transparency of the pixels in the main image. A zero (0) in the mask image indicates that the corresponding pixel in the main image is transparent (should not be displayed) while a one (1) indicates it should be displayed.

IL_WRITE_CHILD
means the pipe image is written as a child image associated with fileImage, which is called the main image. The main image must be an element from the list returned by ilListFileImages() for the given file. The main image must not be a mask image; otherwise, an IL_ERROR_FILE_WRITE_METHOD error is returned.

Child images are images that are somehow associated with the main image. For example, a child image could be the main image stored at a different resolution or format.

fileImage is an ilFileImage structure returned by ilListFileImages(), if method is IL_WRITE_MASK or IL_WRITE_CHILD. fileImage should be NULL (0) if method is IL_WRITE_MAIN.

compression is the one of the following compression methods:

IL_G3 is the CCITT Group 3 lossless compression, for bitonal images only. See the description of pCompData.

IL_LZW is the LZW lossless compression, for all image types.

IL_PACKBITS
is the byte-oriented run length encoding for bitonal, gray and palette images.

IL_JPEG is the JPEG baseline lossy compression for gray, R.C and YCbCr images. Color images are frequently stored in YCbCr format rather than RGB, because YCbCr images compress better with JPEG, and they can be subsampled before compression for further compression. To convert the pipe image to YCbCr subsampled by 2, use ilConvert() as follows:

ilConvert (pipe, IL_DES_YCBCR_2, 0, 0, 0)

Note that the TIFF 6.0 specification states that if an image containing subsampled YCbCr data is written to TIFF, the image width and height must be a multiple of the subsampling factor. However, ilWriteFileImage() does not enforce this restriction. For example, if the image is subsampled by two (2) as in the preceding example, the image width and height must both be even. A crop could be performed by using ilCrop() before the above subsampling to make the image the correct size.

IL_UNCOMPRESSED
is the value for no compression.

IL_WRITE_CURRENT_COMPRESSION
uses the compression type of the current pipe image. This compression should be used when copying images into a TIFF file, to avoid needlessly decompressing and recompressing the image.

pCompData points to the specific format for JPEG or G3 compression; use his parameter based on the value of compression as follows:

If compression is neither IL_JPEG nor lL_G3, pCompData must be NULL.

If you supply lL_G3 for compression, pCompData must point to an unsigned long that contains either IL_G3M_TIFF, which stores the image in TIFF format, or IL_G3M_CLASS_F, which stores the image in FAX format. If pCompData is NULL, IL_G3M_TIFF is assumed.

If you supply lL_JPEG for compression, pCompData must point to an ilJPEGEncodeControl data structure that has the following fields:

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

Q is the Quantization factor, which determines the quantity of compression. If Q is zero (0), a default quantization of 50 is used. The same effect is achieved by passing pCompData as NULL. Otherwise, Q can range from a minimum compression of 1 to a maximum compression of 255.

stripHeight indicates the height of the strips to write to the file. A value of zero (0), which is recommended, causes the Image Library to set the height of the strips; otherwise, strips of the height indicated by stripHeight are written.

xRes is the horizontal resolution of the image being written, in terms of dots per inch (dpi) times two; for example, use 147 to indicate 73.5 dpi.

yRes is the vertical resolution of the image being written, in terms of dots per inch (dpi) times two.

page indicates the page number of this image, or −1 if page numbers are not to be written. If page numbers are to be written, the first page is zero (0).

nPages indicates the total number of pages in this image, or −1 if page numbers are not to be written.

nTags is the number of additional application-defined TIFF tags to be written to the file as part of this image. This value should be zero (0) for most callers.

*pTags if nTags is greater than zero (0), points to an array of nTags additional application-defined tags to be written as part of this image. The tag values must be as returned by ilReadFileTags(). Tags written by the Image Library are listed in the include file ilfile.h. Tags in the pTags array that have the same identifier as tags in the include file will be ignored. This value should be NULL for most callers.

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

RETURN VALUE

Upon successful completion, ilWriteFileImage() returns TRUE.

ERRORS

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

EXAMPLE

The following example adds a consumer filter to write the pipe image to a TIFF file, using the recommended strip height, at 300 dots per inch resolution, not writing page numbers, and adding no special tags.

ilContext context;

ilPipe pipe;

ilFile dstFile

unsigned int compression;

ilPtr pCompData;

long xRes, yRes;
.
.
.

ilWriteFileImage (pipe, dstFile, IL_WRITE_MAIN, (ilFileImage)NULL,

compression, pCompData, 0, 600, 600,

-1, -1, 0, (ilFileTag *)NULL, 0);

return (context->error);

AUTHOR

ilWriteFileImage() was developed by HP.

Museum

Related Articles