Chapter 5 Server Overlay Windows

This chapter includes information on the following topics:

• Server overlays versus Solaris transparent overlays

• Suggestions for implementing overlays

• Description of server overlays

Server Overlays Versus Transparent Overlays

There are two different APIs that may be used to render transparent pixel values to an overlay window. The Transparent Overlay Extension is a Sun proprietary method to provide overlay capability in the X Window System. Transparent overlays can provide overlay functionality without hardware overlay support. Another well-known method known as server overlays can be used if your hardware supports it.

The Transparent Overlay Extension is a full X extension which requires extension calls to provide the transparency effect. The model is robust enough to emulate transparency on most systems, even if the hardware does not support real overlays. However, the operation of transparent windows is considerably slower when not supported in hardware.

Server Overlays is not an X extension, but instead the API provides a means for the X client to determine which visuals are overlays, and what pixel values to use for transparency. This API requires hardware support.

The Transparent Overlay Extension and server overlays may both be supported on the same screen, but they should never be used within the same window. Results are undefined. Trying to create a transparent overlay window in a visual specifically designed for server overlays may result in a BadMatch. Transparent overlays can avoid this by following the proper procedure to locating a partner overlay visual, as described in Chapter 6, Transparent Overlay Windows.

Tips for Programming Overlays

The following information may be useful when deciding which model to use, and how to manage stacking.

Parent-Child Model

It is strongly suggested that all transparency and overlays designs follow the simple underlay-parent overlay-child model. The desired underlay window is created first, and then the overlay is created as a child of the underlay. The overlay window is the only child of the underlay. This eliminates a number of odd cases for the X server, and also helps make sure there are no incidental interfering windows between the underlay and the overlay.

If using Xlib and/or programming your own XCreateWindow for these calls, it is important to understand that the client must provide extra information when creating a window that does not have the same visual as its parent. If the visual is not the default visual, you must provide a colormap or, if the colormaps are equivalent, assign the parent visual's colormap to the child. If the depths are different, you must provide a BorderPixel or BorderPixmap. Failure to do so may cause a BadMatch to return as the result of the create window.

For information about colormap equivalence, see the X Server Device Developer's Guide.

Stacking

When you raise a window, it does not matter if the window is an overlay window or not, it will raise to the top of the stack. If you lower a window, it does not matter if it is an overlay window, it will lower to the bottom of the stack.

This brings up the confusing notion of an overlay window being below an underlay window. This actually happens all the time. This is because the X server is enforcing the simple stacking policy, and it will do whatever is necessary to make that overlay window appear below the other windows, even if it has to software clip it.

Problems are best avoided by using the underlay-parent overlay-child model. That way, an underlay-overlay pair is treated as an entire application from the parent window, and it raises and lowers together.

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;

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.