Solaris X Window System Developer's Guide

Server Overlays

The Server Overlays API provides a simple way for applications to find overlay visuals and corresponding transparent pixel values. The overlay visual is used to create an overlay window, and the transparent pixel is a special pixel value the client may use to cause the underlays to show through. This pixel value is used in the standard way for foreground or background of any drawing operation, or the background of the overlay window.

The Server Overlays API specifies that the SERVER_OVERLAY_VISUALS property on the root window shall contain the following information. The size of the information returned by the server dictates how many instances of this structure are returned: one instance for every visual listed.

typedef struct { 

	unsigned int visualid;  	unsigned int

trans_type;  	unsigned int

value;  	unsigned int

layer;  } ServerOverlaysInfoRec;

`visualid`	The visual ID referenced by the X server. Usually returned to the client via `XGetVisualInfo`.
`trans_type`	The transparency type: 0 None, 1 Transparent Pixel, 2 Transparent Mask
`value`	The transparent pixel value or mask value
`layer`	The relative hardware layer of the visual with respect to transparent effects.

The trans_type value exists because there are provisions for other transparency types that are uncommon in the spec. The trans_type may be zero if a transparent pixel is not available, yet the X server wishes to advertise the visual as existing at a different set of plane groups than the usual windows, for the purpose of preventing exposes.

The layer is usually zero for normal windows, but the layer is really a relative number, with greater number representing plane groups above lower numbers. Negative numbers are possible.

Visuals not listed in the SERVER_OVERLAY_VISUALS property may be assumed to have a layer of zero and a transparency ability of none. These default values are only applicable to server overlay operations.

The transparent pixel shows through to the first window in the next layer. Layers do not affect stacking order in any way, but only apply to the transparency effect. It is strongly recommended to use overlays as a direct and only child of the designated underlay. This provides the best performance and the least confusion.

Server overlays support is device-dependent and may be a full hardware port or partial software emulation or a combination of software and hardware.

Server overlays are specified in “Programming X Overlay Windows” by Mark J. Kilguard, in the July/August 1993 issue of The X Journal.