ilReadXDrawable(3X)

NAME

ilReadXDrawable() − read a pipe image from an X drawable

SYNOPSIS

ilBool
ilReadXDrawable (

ilPipe pipe,

Display *display,

Drawable drawable,

Visual *visual,

Colormap colormap,

ilBool blackIsZero,

ilRect *pSrcRect,

ilBool copyToPixmap,

unsigned long flags);

DESCRIPTION

ilReadXDrawable() reads an image from the pixels in an X drawable (pixmap or window) and feeds the image to the next element in the pipe. The pipe state must be IL_PIPE_EMPTY. The application must already have access to the X drawable; see the man page for XGetSubImage().

To eliminate any translation in reading the drawable pixels into a pipe, raw mode can be enabled by setting the IL_READ_X_RAW_MODE bit in flags. Use raw mode only if the client can translate the image pixels; X pixels must be translated to yield a meaningful image. The affect of raw mode is described for each drawable visual type under visual.

If visual is NULL or colormap is zero (0), then the drawable must be a bitmap (a pixmap of depth one), and blackIsZero determines whether zero or one is a black pixel in the image. The resulting image is bitonal and using raw mode has no affect.

pipe identifies a pipe created by ilCreatePipe().

*display identifies the required X display, a value returned by XOpenDisplay().

drawable identifies an X drawable (pixmap or window).

*visual is the visual that will be used with colormap to derive color values from the pixels read from drawable. If visual is NULL (0), drawable must be a bitmap (a pixmap of depth one) and blackIsZero determines whether zero or one is a black pixel in the image. The resulting image is IL_BITONAL.

If visual is not NULL and colormap is not zero (0), but the IL_READ_X_RAW_MODE bit in flags is set, raw mode is enabled. The following paragraphs describe the effect of raw mode on each visual type.

GrayScale, StaticGray
With raw mode enabled, if drawable depth is neither one (1) nor eight (8), results in an IL_ERROR_UNSUPPORTED_VISUAL error. If the drawable depth is one (1), raw mode has no affect; the pipe image is defined to be IL_DES_BITONAL and, if entry zero (0) in the colormap is black, ilImageDes.blackIsZero is set to TRUE. If the drawable depth is eight (8), the pipe image is defined to be IL_DES_GRAY. The pixels are read from the drawable into the pipe. If raw mode is disabled, ilMap() is called to insert a filter which remaps the X pixels to gray values, using the X pixel value as an index into the colormap array.

StaticColor, PseudoColor
are unaffected by raw mode. If the drawable depth is not eight (8) an IL_ERROR_UNSUPPORTED_VISUAL error is declared. Otherwise the pipe image is defined to be of type IL_DES_PALETTE, the pixels are read into the pipe with no translation and the pipe image’s palette is loaded with the colors from the colormap.

DirectColor, TrueColor
With raw mode enabled, if the drawable depth is not 24 or the red, green and blue masks (as defined in XVisualInfo for the visual) are not 0xff0000, 0xff00 and 0xff respectively, IL_ERROR_UNSUPPORTED_VISUAL error is declared and the pixels in the pipe are written out to the drawable without translation. Otherwise the pipe image is defined to be IL_DES_RGB and the pixels are read into the pipe.

If raw mode is disabled, the X pixels are translated into image pixels by using their values as indices into the colormap array. The ilMap() filter is inserted into the pipeline.

colormap identifies the colormap needed for interpreting the pixel values of the drawable. If colormap is zero (0), drawable must be a bitmap (a pixmap of depth one) and blackIsZero determines whether zero or one is a black pixel in the image. The resulting image is IL_BITONAL. If colormap is not zero (0), it points to an array of 256*3 unsigned shorts which contain three 256 sections of red, green, and blue. X pixels are used as indices into these sections to form an image pixel that is either a grayscale or an R.C value.

blackIsZero used only if visual is NULL or colormap is zero (0); the same field in ilImageDes for this image is set to this value. If true, zeros in the bitmap are considered black; if FALSE, they are considered white (recommended). If TRUE, sets black to zero; if FALSE, sets white to zero.

*pSrcRect defines how much of the image to read. If *pSrcRect is NULL, the entire X drawable is read; otherwise, *pSrcRect identifies an ilRect structure that defines the part of the drawable to read.

copyToPixmap if TRUE, creates a temporary pixmap to which the pixels of drawable are copied, using XCopyArea(), before using XGetImage() to read the pixels from the server. If FALSE, uses XGetImage() to read the pixels directly from the window. FALSE is recommended if the drawable is a pixmap. TRUE is recommended if the drawable is a window other than the root window, because protocol errors may occur if any part of the window lies off-screen.

flags contains flag (option) bits. If the IL_READ_X_RAW_MODE bit is set, raw mode is enabled, otherwise it is disabled. All other bits must be zero (0).

RETURN VALUE

Upon successful completion, ilReadXDrawable() returns TRUE.

ERRORS

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

EXAMPLE

The following example adds a producer filter to read the pixels from an X window (drawable) into a pipe.

ilPipe pipe;

Display *display;

Window window;

Visual *visual;

Colormap colormap;
.
.
.

if (!ilReadXDrawable (pipe, display, window, visual,
colormap, 0, (ilRect *)0, 0, 0))

return(context->error);

AUTHOR

ilReadXDrawable() was developed by HP.

Museum

Related Articles