Copying an Area and Its Paint Type (Solaris X Window System Developer's Guide)

Solaris X Window System Developer's Guide

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.