NAME

ilChangeXWC() − control the use of an X Write context

SYNOPSIS

ilBool
ilChangeXWC (

ilXWC XWC,

unsigned int code,

ilPtr pData);

DESCRIPTION

ilChangeXWC() controls the use of an ilXWC. 

XWC identifies an ilXWC (X Write context) structure created by ilCreateXWC(). 

code determines how the XWC is to be changed.  Use one of the following values:

IL_XWC_ALLOC_GRAYS if the visual associated with the ilXWC is an 8 bit PseudoColor, StaticGray, or GrayScale visual, allocates the default number of grays (currently 32) using the colormap associated with the ilXWC.  The call returns TRUE if the allocation succeeds, or FALSE if the allocation fails. 

If the visual is another kind, no allocation occurs, but the call returns TRUE if IL_GRAY images can be displayed using this ilXWC.  If IL_GRAY images cannot be directly displayed, the call returns FALSE indicating that IL_GRAY images will be converted to IL_BITONAL for display with this ilXWC. 

IL_XWC_FREE_GRAYS frees any grays that were allocated by IL_XWC_ALLOC_GRAYS. 

IL_XWC_ALLOC_COLORS allocates default colors from the colormap associated with the ilXWC.  The call returns TRUE if the allocation succeeds, or FALSE if either the allocation fails or the visual is not a color visual.  If FALSE is returned, the image is displayed as IL_GRAY or IL_BITONAL.  If the given ilXWC is associated with a DirectColor visual, using this option before the program allocates colors may display the image more efficiently. 

IL_XWC_FREE_COLORS frees any dither colors that were allocated by IL_XWC_ALLOC_COLORS. 

IL_XWC_SET_DITHER_METHOD changes the dither method associated with the ilXWC, which determines how color images will be dithered for display if the visual associated with the ilXWC is an 8 bit PseudoColor visual; see ilConvert(3X).  pData must point to an unsigned int containing the new dither method, which is either IL_AREA_DITHER, IL_DIFFUSION, or IL_QUICK_DIFFUSION.  The default when the ilXWC is created is IL_AREA_DITHER, the fastest method.  IL_DIFFUSION is slower but generally yields better results. 

IL_XWC_SET_RAW_MODE enables or disables raw mode for future calls to ilConvertForXWrite() or ilWriteXDrawable() using this ilXWC.  If raw mode is enabled, image pixels are not translated; they are output directly to the X drawable.  Disable is the default when the ilXWC is created.  pData must point to an ilBool containing zero (0) to disable raw mode or one (1) to enable raw mode. 

pData points to optional data that depends on the value of code.

RETURN VALUE

ilChangeXWC() returns TRUE or FALSE depending on the code and kind of visual supplied.  See the preceding description of code. 

ERRORS

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

EXAMPLE

The following example sets raw mode for future calls to ilConvertForXWrite() or ilWriteXDrawable() using this ilXWC. 

ilXWC XWC;

ilBool pData;

XWC = ilCreateXWC( ... );
.
.
.

pData = 1;

ilChangeXWC(XWC, IL_XWC_SET_RAW_MODE, (ilPtr) &pData);

if (context->error) return (context->error);

AUTHOR

ilChangeXWC() was developed by HP. 

SEE ALSO

ilCreateXWC(3X). 

Using the Image Developer’s Kit.

Hewlett-Packard Company  —  Image Library: February, 1995