Transparent Overlay Windows

This chapter presents information on the Transparent Overlay Extension application programming interface (API) that provides transparent overlay window capabilities in the Solaris OpenWindows environment. The chapter includes information on the following topics:

• How overlay windows differ from standard X windows

• How to create and draw to overlay windows

• How to ensure that applications using transparent overlay windows are portable to a wide range of devices

Note - It is recommended that you use server overlays if supported by your hardware. Server overlays are supported on FFB devices. For more information about server overlays, see Chapter 5, Server Overlay Windows.

What are Transparent Overlay Windows?

The transparent overlay extension allows the creation and manipulation of transparent overlay windows. These windows are X windows that allow the user to see through to the underlying window on a per-pixel basis. No special hardware is needed to create and use transparent overlay windows, as this functionality has been implemented in software. Complex transparent overlay manipulation on simple hardware may be time consuming; however, the X server can make use of special overlay hardware if available and the client chooses the correct visuals. Note that, depending on your hardware and needs, you may have to adapt the client color allocations for transparent overlay windows.

Overlay windows allow applications to display temporary imagery in a display window. Users of an application that provides overlays can annotate an image with text or graphical figures, temporarily highlight certain portions of the imagery, or animate figures that appear to move against the background of the imagery. When geometry in the overlay is cleared, any underlying graphics do not need to be regenerated.

The transparent overlay extension allows the client to use standard X requests to draw primitives in opaque paint, which is a name for the standard way of drawing, or transparent paint, which makes affected pixels invisible. The paint type is associated with a standard X graphics context. Window backgrounds may also be set to transparent paint. Transparent overlay windows obey all regular window rules and operating procedures. For example, a transparent overlay window can be positioned anywhere in the window stacking order, regardless of what hardware the windows are associated with. This is implemented in software with the Solaris X server multiple plane group (MPG) functionality.

The server's multiple plane group capability allows windows from different parts of the hardware to coexist. Each window is associated with a visual, which in turn is associated with hardware. Although some hardware is physically created such that there is a definite "layering" (for example, windows created in a hardware overlay plane might be expected to always be seen above the regular windows), MPG works around this limitation in software. MPG allows the stacking order of the windows to be unaffected by the physical imitations of the hardware. As a result, stacking is simply the same as in the standard server. If overlay hardware is available and requested, MPG takes care of minimizing the work and increasing performance.

In general, an overlay is a pixel buffer (either physical or software simulated) into which graphics can be drawn. When the overlay is physical (that is, not simulated in software), erasing the overlay graphics does not damage the underlying graphics. This provides a performance advantage when the underlying graphics is complex and requires much time to repaint. When the overlay is in software, erasing the overlay graphics may generate an Expose event.

Basic Characteristics of Transparent Overlay Windows

A transparent overlay window is a special class of an X InputOutput window into which pixels can be rendered transparently. Handles to transparent overlay windows have the X window type Window. Just like standard X windows, overlay windows are drawables, and an overlay window handle can be passed to any Xlib drawing routine that takes a Drawable.

Transparent overlay windows have extended the set of graphics context attributes to include an attribute for paint type. With the transparent overlay extension, transparent overlay windows can be rendered to with either opaque or transparent paint.

Paint Type

While standard X InputOutput windows and other drawables (such as pixmaps) accept only opaque paint, transparent overlay windows permit pixels to be rendered with transparent paint. Valid pixel values painted opaquely obscure pixels in underlying windows. Such pixels have associated color values that are displayed. Pixels rendered transparently have no intrinsic color; they derive their displayed color from the pixels that lie beneath.

Valid pixel values for pixels painted opaquely are obtained via XAllocColor() or another standard pixel allocation mechanism. Painting opaquely with a non-valid pixel value, for example a value that falls outside the valid colormap entries for a visual, produces undefined results for both transparent overlay windows and standard X InputOutput windows.

Paint type is defined with the data structure XSolarisOvlPaintType. By default, the paint type of a GC is opaque. The XSolarisOvlPaintType data structure is defined as:

typedef

enum { 	XSolarisOvlPaintTransparent, 	XSolarisOvlPaintOpaque, }

XSolarisOvlPaintType;

Viewability

A transparent overlay window is considered viewable even if all its pixels are fully transparent. For viewable pixels in a transparent overlay window that are fully transparent, the underlying pixels in the underlay will be displayed.

If an overlay window is unmapped or moved, the underlay beneath may receive exposure events. This, for example, is the case on devices that cannot display the overlay window and underlay window in different plane groups.

More on Transparent Overlay Characteristics

In most respects, a transparent overlay window is just like a standard X InputOutput window. Specifically, a transparent overlay window has these characteristics:

• It can be mapped or unmapped. The routines XMapWindow, XUnmapWindow, XMapSubwindows, and XUnmapSubwindows apply.

• An overlay window can possess its own cursor or use its parent's cursor. In other words, XDefineCursor and XUndefineCursor apply to overlay windows.

• An overlay window appears in the output of XQueryTree.

• The event_mask and do_not_propagate_mask window attributes function normally. An overlay window can express interest in any type of event.

• XTranslateCoordinates and XQueryPointer apply to overlay windows.

• save_under applies as for standard X windows.

• override_redirect applies as for standard X windows.

A transparent overlay window also has some characteristics that make it unique as a window. The following sections describe these characteristics.

Background

As defined in the X specification, windows can have a background. The main purpose of window background is to display something in the exposed areas of a window in case the client is slow to repaint these areas. This background is rendered whenever the window receives an Expose event. The background is rendered before the Expose event is sent to the client. The background is also rendered when the client makes an XClearArea or XClearWindow request.

Like standard X InputOutput windows, transparent overlay windows can also have a background. The background of a transparent overlay window is rendered just like a non-overlay window in response to Expose events, XClearArea requests, or XClearWindow requests. In addition to the standard types of background (None, pixmap, pixel, or parent relative), transparent overlay windows can also be assigned a new type of background: transparent. A new routine, XSolarisOvlSetWindowTransparent, is available to set the background type to transparent.

The background of a transparent overlay window is transparent by default. However, the application can still specify one of the usual X types of background: None, a pixmap XID, a pixel value, or ParentRelative, as shown in Table 6-1 .

Table 6-1 Background Values for a Transparent Overlay Window

Attempts to set the background of a non-overlay window with XSolarisOvlSetTransparent generates a BadMatch error. If an underlay window has a ParentRelative background and the parent window is an overlay with a transparent background, the underlay child is treated as if it has a background of None.

Window Border

The border of overlay windows is opaque. It is always drawn with opaque paint. Just like standard X InputOutput windows, the border width can be controlled with XSetWindowBorderWidth.

Backing Store

Backing store is disabled for overlay windows.

Window Gravity

The bit and window gravity attributes (bit_gravity and win_gravity) apply to transparent overlay windows. However, if the gravity calls for the movement of pixels, the transparency information is moved, along with the pixel color information.

Colormaps

Overlay colormap installation follows the X rules. If your application uses pixel-sharing overlay/underlay pairs, create a single colormap for both windows. Refer to "Choosing Visuals for Overlay/Underlay Windows" and "Designing an Application for Portability" for more on the subject of pixel-sharing pairs.

If the pair is known never to share hardware color LUTs, different colormaps can be safely assigned to the overlay and underlay window without the occurrence of colormap flashing.

Note - To improve the portability of applications and to minimize color flashing, use colormaps with the same colors in both the overlay and underlay window colormaps. If this is not possible, use one of the visual inquiry routines to determine whether different colormaps can be assigned without producing flashing.