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)

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

• 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)

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.