ilEFSWriteImage(3X)

NAME

ilEFSWriteImage() − add a consumer to the pipe that writes an image to an EFS file

SYNOPSIS

ilBool
ilEFSWriteImage (

ilPipe pipe,

ilEFSFile file,

long xRes,

long yRes,

ilClientImage maskImage,

void *pOptions);

DESCRIPTION

ilEFSWriteImage() adds a consumer to the pipe that writes an image to an EFS file. If the file is being used by another pipe, an IL_ERROR_EFS_IN_USE error is returned; see ilEFSReadImage(3X).

If the file type handler supports writing of multiple pages to the file (that is, the expression ilEFSFileInfo.attributes & IL_EFS_MULTI_PAGE_WRITES is non-zero), each execution of the pipe writes a new page to the file. If multiple page writes are not supported and the pipe is executed more than once, the results are undefined. The file type handler may either write the new image as the only image in the file, (the recommended approach), declare an error, or write no image.

pipe is a pipe created by ilCreatePipe().

file is an ilEFSFile data structure.

xRes, yRes are the X and Y resolution of the image being written, in dots per inch (dpi) times two (2). For example, 150 is 75 dpi. ilEFSWriteImage() is free to ignore the resolution if the file format does not support it.

maskImage is either the client image, which is a mask to the pipe image to be written, or NULL meaning no mask image is to be written. The client image must be an uncompressed bitonal image the size of the pipe image, with a rowBitAlign of 32. A client image created with a descriptor of IL_DES_BITONAL and a format of IL_FORMAT_BIT satisfies these requirements. The zero (0) bits in the mask image correspond to transparent pixels in the pipe image. If the file type handler does not accept writing of mask images, maskImage is ignored.

pOptions is reserved for future use and must be NULL.

RETURN VALUE

Upon successful completion, ilEFSWriteImage() returns TRUE.

ERRORS

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

EXAMPLE

The following example creates a pipe, then uses ilEFSGetPageInfo to get information about the current page in open-for-reading EFS file. The image on that page is read, filtered, and written to an EFS file that is open-for-writing.

The given pipe is now complete, and ready to be executed with ilExecutePipe.

ilContext context;

ilPipe pipe;

ilEFSFile inFile, outfile;

ilEFSPageInfo pageInfo;
.
.
.

if (!(pipe = ilCreatePipe (context, 0))
|| !ilEFSGetPageInfo (inFile, &pageInfo)
|| !ilEFSReadImage (pipe, inFile, IL_EFS_READ_MAIN,

0, 0, NULL)

|| !AddConverterFilter (pipe)
|| !ilEFSWriteImage (pipe, outFile, pageInfo.xRes,

pageInfo.yRes, (ilClientImage)NULL, NULL)

AUTHOR

ilEFSWriteImage() was developed by HP.

Museum

Related Articles