NAME

ilConvertForXWrite() − add to the pipe a filter that converts the pipe image to XWC-compatible format

SYNOPSIS

ilBool
ilConvertForXWrite (

ilPipe pipe,

ilXWC XWC,

ilBool mapPixels,

unsigned long mustBeZero,

void *mustBeNull);

DESCRIPTION

ilConvertForXWrite() adds to the pipe a filter that converts the pipe image to a format compatible with the given ilXWC data structure.  This function effectively performs many of the translations necessary for ilWriteXDrawable() to display the image as an X drawable. 

For example, an IL_RGB image is dithered if the visual of the ilXWC is PseudoColor. The output from the filter can then be saved to a client or internal image by calling ilWriteImage().  Displaying that image is faster than displaying the original IL_RGB image. Also, the dithered image is smaller than the IL_RGB image; it is one (1) byte per pixel instead of three (3) bytes per pixel. 

If ilConvertForXWrite() succeeds, the writeType field in ilXWCInfo as returned by ilQueryXWC() is updated.  writeType defines the image conversion that took place and the type of the resulting image. 

The conversion performed by ilConvertForXWrite() depends on whether raw mode is enabled or disabled in the given XWC.  Raw mode can be enabled or disabled by calling ilChangeXWC().  The default is disabled. Raw mode allows the pipe image to be output to an X drawable without translation of the pixels or allocation of any X color cells.  This is useful for applications that want to directly control the colormap usage but still use the IL to display images. 

For example, an application could allocate writeable colorcells using XAllocColorCells(), use ilMap() to map the pipe image pixels to X pixels, and then output to a drawable using ilWriteXDrawable() with raw mode enabled.  The application could then directly change the image colors on the screen by modifying the X color values. 

If raw mode is enabled in the given XWC no conversion is performed; instead the pipe image is validated as described in the paragraphs following this paragraph. If the pipe image is not in the correct format, an IL_ERROR_RAW_MODE error is declared and ilConvertForXWrite() returns FALSE.  If the pipe image is bit-per-pixel (nSamplesPerPixel is equal to 1 and nBitsPerSample[0] is equal to 1) it is always valid; otherwise, the required format of the pipe image depends on visualType in the ilXWCInfo structure returned by ilQueryXWC().  The visualTypes and required pipe image formats are as follows:

* For IL_XWC_COLOR_24, IL_SAMPLE_PIXELS must equal sampleOrder. 

If the pipe image is bit-per-pixel, writeType is set to IL_XWC_BITONAL; otherwise, it is set based on visualType as follows:

If raw mode is not enabled in the XWC, writeType is initially determined by the following table, in which image type is the type of the pipe image, and <color> is either IL_PALETTE, IL_R.C or IL_YCBCR:

If writeType is IL_XWC_WRITE_COLOR_DITHER, the default dither colors are allocated from the colormap of the XWC, by calling ilChangeXWC() with the IL_XWC_ALLOC_COLORS option.  If the allocation fails, writeType becomes IL_XWC_WRITE_GRAY.  If the writeType is IL_XWC_WRITE_GRAY, the default grays are allocated from the colormap of the XWC by calling ilChangeXWC() with the IL_XWC_ALLOC_GRAYS option.  If the allocation fails, writeType becomes IL_XWC_WRITE_BITONAL. 

Once the writeType is determined, the pipe image is converted to the following descriptor (ilImageDes) and format (ilFormat) by calling ilConvert() based on writeType:

For conversions to IL_DES_PALETTE, the ilConvert() option IL_CONVERT_TO_PALETTE is used, specifying the default dither levels and the dither method set with the IL_XWC_SET_DITHER_METHOD option to ilChangeXWC().  The default is IL_AREA_DITHER.  Note that if the pipe image is already a dithered palette image with the default dither levels, no conversion is performed on the pipe image. 

pipe is a pipe created by ilCreatePipe() and in the IL_PIPE_FORMING state, so that a filter can be added. 

XWC is an ilXWC data structure created by ilCreateXWC(). 

mapPixels is either TRUE or FALSE.  MapPixels is ignored if raw mode is enabled or the image is bitonal (writeType field of ilXWCInfo as returned by ilQueryXWC() equals IL_XWC_WRITE_BITONAL).  Otherwise, ilMap() is called to map the pixels from image pixels to X pixels. 

For very efficient display or for quickly refreshing an image, set writeType to IL_XWC_WRITE_COLOR_DITHER.  The resulting image type is IL_GRAY and can be displayed to an X drawable with raw mode enabled. While this process results in better display performance, the image is no longer a valid image and operations such as scaling have unpredictable results, because the pixels being scaled are X pixels not image pixels. 

mustBeZero is reserved for future use and must be zero (0). 

*mustBeNull is reserved for future use and must be NULL (0). 

RETURN VALUE

Upon successful completion, ilConvertForXWrite() returns TRUE. 

ERRORS

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

EXAMPLE

The following example converts the image in the given pipe to an XWC compatible format, with no mapping by ilMap() of image pixels to X pixels. 

ilPipe pipe;

ilXWC XWC;
.
.
.

if (!ilConvertForXWrite (pipe, XWC, FALSE, 0, NULL))

return(context->error);

AUTHOR

ilConvertForXWrite() was developed by HP. 

SEE ALSO

ilConvert(3X), ilChangeXWC(3X), ilCreatePipe(3X), ilQueryXWC(3X), ilWriteXDrawable(3X), ilerror(3X). 

Using the Image Developer’s Kit.

Hewlett-Packard Company  —  Image Library: February, 1995