Solaris X Window System Developer's Guide

Pixel Transfer Routines

The transparent overlay API provides three pixel transfer routines:

XSolarisOvlCopyPaintType – Renders opaque and transparent point into a destination drawable based on the paint type attributes of the source drawable.
XSolarisCopyAreaAndPaintType – Copies an area and its paint type from one pair of drawables to another.
XReadScreen – Returns the colors displayed in a given area of the screen.

The existing Xlib pixel transfer routines XGetImage, XCopyArea, and XCopyPlane can also be used with overlay windows. The use of these routines is described below.

Filling an Area Using the Source Area Paint Type

The XSolarisOvlCopyPaintType routine uses the paint type information of a specified rectangle in a source rectangle to control a fill operation in a specified rectangle in a destination rectangle. The source rectangle and destination rectangle can be any type of drawable. If the source rectangle is a transparent overlay, the paint type attribute of its pixels is used as the source of the copy, and the color information is ignored. If the source rectangle is any other type of drawable, the bit plane specified in the routine is treated as if it were paint type data and it is used for the copy. In this case, the bit plane must have only one bit set.

The syntax and arguments are shown below.

void

XSolarisOvlCopyPaintType(Display *display, Drawable src, 

		Drawable dst, GC gc, int src_x, int src_y, 

		unsigned int width, unsigned int height, int dest_x,

		int dest_y, unsigned long action, unsigned long

plane)

`display`	Specifies the connection to the X server.
`src`	Specifies the source drawable from which to obtain the paint type information.
`dst`	Specifies the destination drawable.
`gc`	Specifies the GC.
`src_x`, `src_y`	Specify the x and y coordinates of the upper-left corner of the source rectangle relative to the origin of the source drawable.
`width`, `height`	Specify the width and height of both the source and destination rectangles.
`dest_x`, `dest_y`	Specify the x and y coordinates of the upper-left corner of the destination rectangle relative to the origin of the destination drawable.
`action`	Specifies which paint type data is to be copied. This can be one of `XSolarisOvlCopyOpaque`, `XSolarisOvlCopyTransparent`, or `XSolarisOvlCopyAll`.
`plane`	Specifies the bit-plane of the `src` drawable to be used as paint type information when the source is not a transparent overlay.

src and dst must have the same screen, or a BadMatch error results.

Table 6–3 summarizes the possible combinations of src and dst and their actions. The left side of the table shows the possible src combinations. The top of the table shows the possible dst combinations. The actions A1-A4 are explained following the table.

Table 6–3 XSolarisOvlCopyPaintType Source/Destination Combinations and Actions


Source/Destination	Overlay	Drawable
overlay	A1	A2
drawable	A3	A4

A1—Opaque pixels in the source overlay cause the corresponding pixels in the destination to be filled with opaque color as specified by the fill attributes of the GC. Transparent pixels in the source cause the corresponding pixels in the destination to be filled with transparent paint.
A2—Opaque pixels in the source overlay cause the corresponding pixels in the destination to be filled according to the fill attributes of the GC. Transparent pixels in the source overlay cause the corresponding pixels in the destination to be filled according to the same fill attributes of the GC, but with the foreground and background pixels swapped.
A3—The pixels in the destination overlay are filled with opaque paint or made transparent as in A1 above depending on the bit values of the source drawable's plane. Bit values of 1 in the source are treated as if they were opaque pixels and bit values of 0 are treated as if they were transparent.
A4—The pixels in the destination drawable are filled with paint as in A2 above depending on the bit values of the source drawable's plane. Bit values of 1 in the source bit plane are treated as if they were opaque pixels and bit values of 0 are treated as if they were transparent.

The action argument specifies whether opaque paint (XSolarisOvlCopyOpaque), transparent paint (XSolarisOvlCopyTransparent), or both (XSolarisOvlCopyAll) should be operated upon. This allows a client to accumulate opaque or transparent paint.

If portions of the source rectangle are obscured or are outside the boundaries of the source drawable, the server generates Expose events, using the same semantics as XCopyArea.

This routine uses these GC components: function, plane-mask, fill-style, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask. It might use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, tile-stipple-y-origin.

XSolarisOvlCopyPaintType can generate BadDrawable, BadGC, BadMatch, and BadValue errors.

Copying an Area and Its Paint Type

The XSolarisCopyAreaAndPaintType routine copies the specified area of source drawable for the color information to the specified area of destination drawable for color information. If the destination drawable is not an overlay, it also fills the specified areas of paint type information destination drawable according to the paint type information specified in the paint type information source drawable.

You can use XSolarisOvlCopyAreaAndPaintType to combine an image in the client's memory space (consisting of color and/or paint type information) with a rectangle of the specified overlay window. To do this, first move the image and paint type data into the server: use XPutImage to copy the data into two pixmaps of the appropriate depths. Then call XSolarisOvlCopyAreaAndPaintType with the color and paint type drawables to copy information to the overlay.

You can also use XSolarisOvlCopyAreaAndPaintType to retrieve pixel information (color and/or paint type information) from a specified drawable. To do this, call XSolarisOvlCopyAreaAndPaintType with two separable destination drawables. To get the data from the server into the client's memory space, call XGetImage on each of the drawables.

The syntax and arguments for XSolarisCopyAreaAndPaintType are shown below.

void

XSolarisOvlCopyAreaAndPaintType(Display * display, Drawable colorsrc,

  Drawable painttypesrc, Drawable colordst,   Drawable painttypedst, GC

colorgc, GC painttypegc,   int colorsrc_x, int colorsrc_y, int

painttypesrc_x,   int painttypesrc_y, unsigned int width,

unsigned int height,   int colordst_x, int colordst_y, int

painttypedst_x,   int painttypedst_y, unsigned long action, unsigned long

plane)

`display`	Specifies the connection to the X server.
`colorsrc`	The color information source drawable. `colorsrc` can be any depth drawable or an overlay window.
`painttypesrc`	The paint type information source drawable. `painttypesrc` can be any drawable or an overlay window. If `painttypesrc` is not an overlay window, the bit plane of `painttypesrc` specified in `plane` is treated as if it were paint type data and it is used for the copy. `plane` must have only one bit set in this case.
`colordst`	The color information destination drawable.
`painttypedst`	The paint type information destination drawable. If `colordst` is an overlay, this drawable will be ignored.
`colorgc`	The GC to use for the color information copy.
`painttypegc`	The GC to use to fill areas in `painttypedst`. If `colordst`/`painttypedst` is an overlay, this GC will be ignored.
`colorsrc_x` `colorsrc_y`	The X and Y coordinates of the upper-left corner of the source rectangle for color information relative to the origin of the color source drawable.
`painttypesrc_x` `painttypesrc_y`	The X and Y coordinates of the upper-left corner of the source rectangle for paint type information relative to the origin of the paint type source drawable.
`width, height`	The dimensions in pixels of all the source and destination rectangles.
`colordst_x` `colordst_y`	The X and Y coordinates of the upper-left corner of the destination rectangle for color information relative to the origin of the color destination drawable.
`painttypedst_x` `painttypedst_y`	The X and Y coordinates of the upper-left corner of the destination rectangle for paint type information relative to the origin of the paint type destination drawable. If `colordst`/`painttypedst` is an overlay, colordst_x and colordst_y will be used.
`action`	Specifies which paint type data is to be copied. This can be one of XSolarisOvlCopyOpaque, XSolarisOvlCopyTransparent, or XSolarisOvlCopyAll.
`plane`	Specifies the source bit-plane in `painttypesrc` to be used as paint type information when `painttypesrc` is not an overlay.

colordst can be any drawable, but must be of the same depth and have the same root as colorsrc, otherwise, a BadMatch error results. If colordst is an overlay, then painttypedst is ignored, otherwise painttypedst can be any type of drawable.

Table 6–4 summarizes the possible combinations of sources and destinations and their respective actions. The left side of the table shows the possible colorsrc/painttypesrc combinations and the top of the table shows the possible colordst/painttypedst combinations. The actions A1-A8 are explained below the table. An Impossible entry in the table indicates that the given combination is impossible, since the painttypedst is ignored when the colordst is an overlay.

Table 6–4 XSolarisOvlCopyAreaAndPaintType Source/Destination Combinations and Actions


	Overlay/ Overlay	Overlay/ Drawable	Drawable/ Overlay	Drawable/ Drawable
overlay/overlay	A1	Impossible	A5	A5
overlay/drawable	A2	Impossible	A6	A6
drawable/overlay	A3	Impossible	A7	A7
drawable/drawable	A4	Impossible	A8	A8

A1—The paint type information from painttypesrc is used as a mask to copy the color information from colorsrc to colordst. Opaque pixels in painttypesrc cause the corresponding pixel in colorsrc to be copied to colordst, transparent pixels cause the corresponding pixel in colordst to be made transparent. If a transparent pixel from colorsrc is copied to colordst, the actual color transferred will be undefined.
A2—Same as A1 except that the paint type information is extracted from the bit-plane of painttypesrc specified by plane. A bit value of 1 indicates an opaque pixel whereas a bit value of 0 indicates transparent.
A3—Same as A1 except that a non-overlay drawable is used to obtain the color information so there will be no undefined colors due to transparent pixels.
A4—Same as A3 except that the paint type information is taken from the specified bit-plane of painttypesrc as in A2.
A5—The paint type information from painttypesrc is used as a mask to copy the color information from colorsrc to colordst as in A1. In addition, the paint type information controls rendering to the painttypedst drawable as in XSolarisOvlCopyPaintType.
A6—Same as A5 except that the paint type information is taken from the specified bit-plane of painttypesrc as in A2.
A7—Same as A5 except that there will be no undefined colors due to transparent color source pixels.
A8—Same as A7 except that the paint type information is taken from the specified bit-plane of painttypesrc as in A2.

The action argument specifies whether opaque paint (XSolarisOvlCopyOpaque), transparent paint (XSolarisOvlCopyTransparent), or both (XSolarisOvlCopyAll) should be copied. This allows a client to accumulate opaque or transparent paint.

NoExpose and GraphicsExpose events are generated in the same manner as XSolarisOvlCopyPaintType.

If an overlay is used for the colordst argument, the painttypedst, painttypegc, painttypedst_x and painttypedst_y arguments will all be ignored. A NULL pointer can be used for painttypegc and a value of None can be used for painttypedst. The overlay will have the exact paint type defined by the pixels in the area specified in painttypesrc. The color information copy will not affect the destination paint type.

This function uses these GC components from colorgc: function, plane-mask, subwindow-mode, graphics-exposures, clip-x-origin, clip-y-origin, and clip-mask.

If colordst is not an overlay then this function will use these GC components from painttypegc: function, plane-mask, fill-style, subwindow-mode, clip-x-origin, clip-y-origin, and clip-mask. In addition, it may also use these GC mode-dependent components: foreground, background, tile, stipple, tile-stipple-x-origin, and tile-stipple-y-origin.

XSolarisOvlCopyAreaAndPaintType can generate BadDrawable, BadGC, BadMatch, and BadValue errors.

Retrieving Overlay Color Information

The routine XReadScreen returns the displayed colors in a rectangle of the screen. It thus provides access to the colors displayed on the screen of the given window.

On some types of advanced display devices, the displayed colors can be a composite of the data contained in several different frame stores, and these frame stores can be of different depth and visual types. In addition, there can be overlay/underlay window pairs in which part of the underlay is visible beneath the overlay. Because the data returned by XGetImage is undefined for portions of the rectangle that have different depths, XGetImage is inadequate to return the picture the user is actually seeing on the screen. In addition, XGetImage cannot composite pixel information for an overlay/underlay window pair because the pixel information lies in different drawables. XReadScreen addresses these problems.

Rather than returning pixel information, XReadScreen returns color information—the actual displayed colors visible on the screen. The routine returns the color information from any window within the boundaries of the specified rectangle. Unlike XGetImage, the returned contents of visible regions of inferior or overlapping windows of a different depth than the specified window's depth are not undefined. Instead, the actual displayed colors for these windows is returned.

Note –

The colors returned are the ones that would be displayed if an unlimited number of hardware color LUTs were available on the screen. Thus, the colors returned are the theoretical display colors. If colormap flashing is present on the screen because there aren't enough hardware color LUTs to display all of the software colormaps simultaneously, the returned colors may be different from the colors that are actually displayed.

The syntax and arguments for this routine are shown below.

XImage

* XReadScreen (Display *display, Window w, int x, int y,

   unsigned int width, unsigned int height,

  Bool includeCursor)

`display`	Specifies the connection to the X server.
`w`	Specifies the window from whose screen the data is read.
`x`, `y`	Specify the X and Y coordinates of the upper-left corner of the rectangle relative to the origin of the window `w`.
`width`, `height`	Specify the width and height of the rectangle.
`includeCursor`	Specifies whether the cursor image is to be included in the colors returned.

If w is an overlay window, the overlay color information is returned wherever there is opaque paint in the specified rectangle. The color information of the underlay is returned wherever there is transparent paint in the overlay. In general, since this underlay can be an overlay window containing transparent paint, the color information for a coordinate (x, y) that contains transparent paint is the youngest non-inferior that has opaque paint at (x, y).

The color data is returned as an XImage structure. The returned image has the same width and height as the arguments specified. The format of the image is ZPixmap. The depth of the image is 24 and the bits_per_pixel is 32. The most significant 8 bits of color information for each color channel (red, green, blue) are returned in the bit positions defined by red_mask, green_mask, and blue_mask in the XImage. The values of the following attributes of the XImage are server dependent: byte_order, bitmap_unit, bitmap_bit_order, bitmap_pad, bytes_per_line, red_mask, green_mask, blue_mask.

If includeCursor is True, the cursor image is included in the returned colors. Otherwise, it is excluded.

Note that the borders of the argument window (and other windows) can be included and read with this request.

If a problem occurs, XReadScreen returns NULL.

Using Existing Xlib Pixel Transfer Routines

The Xlib pixel transfer routines XGetImage, XCopyArea, and XCopyPlane can also be used with transparent overlay windows.

XGetImage

On non-overlay drawables, the XGetImage routine works as defined in the X11 specification. The same is true for overlay windows, with the exception that, on these windows, the color information returned for transparent pixels is undefined. Clients who simply want to retrieve the display colors for a region on the screen should use XReadScreen.

XCopyArea and XCopyPlane

When both the source and destination drawables are non-overlay, the XCopyArea and XCopyPlane routines work as defined in the X11 specification. However, note the following for the cases in which either the source or the destination drawable is an overlay window.

When the source drawable is overlay and the destination drawable is non-overlay, only the color information is copied; the paint type information in the source is ignored. Color information for transparent pixels is undefined.
When the source drawable is non-overlay and the destination drawable is overlay, the copy is performed as the paint type in the GC indicates. If the paint type is XSolarisOvlPaintOpaque, the color information is copied into the destination with opaque paint. If the paint type is XSolarisOvlPaintTransparent, the color information is ignored, and the destination pixels are transparent.
When both the source drawable and destination drawable are overlay, the paint type of the source is ignored, and this behaves as if the source were not an overlay. If copying both color and paint type information is the desired result, use XSolarisOvlCopyAreaAndPaintType.