ilEFSReadImage(3X)

NAME

ilEFSReadImage() − add to the pipe a producer that reads the current page (image) from an EFS file

SYNOPSIS

ilBool
ilEFSReadImage (

ilPipe pipe,

ilEFSFile file,

unsigned int readMode,

long width,

long height,

void *pOptions);

DESCRIPTION

ilEFSReadImage() adds a producer to the pipe to read the current page (image) from the EFS file. The page read will be the current page, as described by the information returned from ilEFSGetPageInfo(). If no more pages are available from the file (ilEFSPageInfo.attributes & IL_EFS_EOF) an IL_ERROR_EFS_EOF error is declared.

For multi-page files, a call to ilEFSReadImage() with a readMode of IL_EFS_READ_MAIN advances the current page to the next page unless no more pages exist; in which case it sets IL_EFS_EOF in ilEFSPageInfo.attributes. To position to a specific page, open the file requesting random access. (using an openMode of IL_EFS_READ); then use ilEFSSeek().

pipe is a pipe created by ilCreatePipe().

file is a file opened by ilEFSOpen() with an openMode of IL_EFS_READ or IL_EFS_READ_SEQUENTIAL. If the file was opened with an openMode of IL_EFS_READ, the same page is read from the file each time the pipe is run. If the file was opened with an openMode of IL_EFS_READ_SEQUENTIAL then the pipe must not be run more than once; the results of doing so are undefined.

readMode is the mode for reading. Use either:

IL_EFS_READ_MAIN
reads the main image and, in a multi-page file advances the file position to the next page or to IL_EFS_EOF.

IL_EFS_READ_MASK
reads the mask image associated with the current main image. The current page must have a mask image (ilEFSPageInfo.attributes & IL_EFS_MASKED) or an error occurs. If the mask image is read, it will be in a format acceptable to writing the mask image along with the associated main image; see ilEFSWriteImage(3X). If the file was opened with an openMode of IL_EFS_READ_SEQUENTIAL and the mask image is read, it must be present and it must be read before the main image.

width, height are ignored if the current page is not scaleable (the IL_EFS_SCALEABLE_READS bit in ilEFSPageInfo.attributes is not set) and should be zero (0).

For scaleable pages, if either width or height are zero (0), the default image size is generated using the fields width and height in ilEFSPageInfo. If default size is not desired, width and height should indicate that size. The width and height should have the same aspect ratio as the width and height fields in ilEFSPageInfo. That is, the width to height ratio should match for both sets of sizes.

pOptions is reserved for future use and must be NULL.

RETURN VALUE

Upon successful completion, ilEFSReadImage() 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 an 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

ilEFSReadImage() was developed by HP.

Museum

Related Articles