You can use any visual to create the overlay. However, not all overlay/underlay visual pairs may be optimal. Each screen defines a set of optimal overlay/underlay visual pairs. These define the optimal visuals of the overlay windows that can be created with a particular underlay visual. Likewise, they define the optimal visuals of underlay windows that can be created with a particular overlay visual. You can determine the optimal pairs using XSolarisOvlSelectPair and XSolarisOvlSelectPartner.

The definition of optimal varies from device to device, but it will usually refer to the ability of a device to create an overlay window in a different plane group than that of an underlay window. See "Selecting an Optimal Overlay/Underlay Visual Pair" for more information on overlay/underlay visual pairs.

Overlay windows are destroyed with the Xlib routines XDestroyWindow or XDestroySubwindows.

Setting the Paint Type of a Graphics Context

You can set a GC's paint type with the XSolarisOvlSetPaintType routine. XSolarisOvlSetPaintType specifies the type of paint rendered by subsequent Xlib drawing with the given GC. It controls whether Xlib drawing routines using this GC produce opaque or transparent pixels on overlay windows. The paint type specified applies to the GC until it is changed by another call to this routine. The paint type attribute applies to both the foreground and background GC attributes. The syntax and arguments are shown below.

void

XSolarisOvlSetPaintType (Display *display, GC gc,   XSolarisOvlPaintType

paintType)

The value of paintType can be XSolarisOvlPaintOpaque or XSolarisOvlPaintTransparent.

• If the value of paintType is XSolarisOvlPaintOpaque, the pixels generated by subsequent Xlib drawing routines with this GC will be opaque. This means the pixels will obscure underlying pixels. This is the default.

• If the value of paintType is XSolarisOvlPaintTransparent, the pixels generated by subsequent Xlib drawing routines with this GC will be transparent. This means that, for these pixels, the color of the underlying pixels is displayed.

Setting the Background State of a Transparent Overlay Window

You can set the background state of a transparent overlay window to be transparent with the XSolarisOvlSetWindowTransparent routine. Any background rendering that occurs after this request causes the background to be transparent. To change background state to any other value, use XChangeWindowAttributes(), XSetWindowBackground(), or XSetWindowBackgroundPixmap().

The syntax and arguments of XSolarisOvlSetWindowTransparent are shown below.

void

XSolarisOvlSetWindowTransparent (Display *display, Window

w)

Note - If w is not a transparent overlay window, a BadMatch error results.

Rendering to a Transparent Overlay Window

Once a transparent overlay window is created, you can use all the standard Xlib primitive rendering routines, such as XDrawLines and XFillRectangles, to draw into the window. When drawing to transparent overlay windows, the paint type attribute of the GC is used to control the quality of the pixels rendered. The paint type attribute applies to both the foreground and background GC attributes. To set the paint type, use the XSolarisOvlSetPaintType routine; for information on this routine, see "Setting the Paint Type of a Graphics Context".

The paint type of the GC also controls the type of pixels rendered with XPutImage. If the paint type of the argument GC is XSolarisOvlPaintOpaque, the color information from the source image is used and the pixels are rendered with opaque paint. However, if the paint type is XSolarisOvlPaintTransparent, the source color information is ignored, and the pixels are rendered with transparent paint.

If a GC with a paint type of XSolarisOvlPaintTransparent is used to render to a drawable other than a transparent overlay window, such as an underlay window or pixmap, the GC paint type is ignored, and the pixels are rendered with opaque paint.

Querying the Characteristics of a Transparent Overlay Window

You can determine whether a window is an overlay window using the routine XSolarisOvlIsOverlayWindow. You can also determine a GC's current paint type using the routine XSolarisOvlGetPaintType.

Determining Whether a Window is an Overlay Window

You can use the routine XSolarisOvlIsOverlayWindow to determine whether a window is an overlay window. The routine returns True if the given window w is a transparent overlay and returns False otherwise.

Bool

XSolarisOvlIsOverlayWindow (Display *display, Window

w)

Determining the Paint Type of a Graphics Context

The routine XSolarisOvlGetPaintType returns the GC's current paint type.

XSolarisOvlPaintType

XSolarisOvlGetPaintType (Display *display, GC

gc)

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)

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

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