Solaris X Window System Developer's Guide

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


Background	Description
`transparent`	Background of transparent overlay window is transparent by default.
`None`	No rendering is performed when the overlay window encounters a condition that invokes background painting. Neither transparent nor opaque paint is rendered.
Pixmap ID	The background is rendered with opaque paint. The rendered pixel values are derived from the pixmap as defined in the X specification.
Single pixel value	The background is a solid color rendered with opaque paint.
`ParentRelative`	The behavior for a `ParentRelative` background depends on the parent window background and its type. If the parent window is an underlay, the background for the overlay window child will be rendered with opaque paint, and the rendered pixels will be as defined in the X specification. If the parent window is an overlay, the background of the overlay child will be the same as that of the parent, either transparent or opaque paint will be rendered.

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.

Input Distribution Model

Overlay windows can express interest in events just like a standard X window. An overlay window receives any event that occurs within its visible shape; the paint type of the pixel at which the event occurs doesn't matter. For example, if the window expresses interest in window enter events, when the pointer enters the window's visible shape, the window receives a window enter event, regardless of whether the pixel is opaque or transparent.

This has some implications for how applications should implement interactive picking (selection) of graphical objects. Applications that draw graphical figures into an overlay window above other graphical figures drawn into the underlay window should express interest in events in either the overlay or underlay window, but not both. When the application receives an input event, it must use its knowledge of the overlay/underlay layering to determine which graphical figure has been picked.

For example, let's say the application expresses interest in events on the underlay window. When the application receives an event at coordinate (x, y), it should first determine if there is a graphical figure at that coordinate in the overlay. If so, the search is over. If not, the application should next see if there is a graphical figure at that coordinate in the underlay.

Print Capture

After graphical imagery has been rendered to an X window, the user may want the window contents to be captured and sent to a printer for hard copy output. The most widespread technique for doing this is to perform a screen dump, that is, to read back the window pixels with XGetImage, and to send the resulting image to the printer. To fit the image to the size of the printed page, some image resampling may be necessary. This can introduce aliasing artifacts into the image.

Another print capture technique that is growing in popularity in the X11 community is to re-render the graphics through a special printer graphics API. This API supports the standard Xlib graphics calls. It converts these calls into a page description language (PDL) format and sends it to the appropriate print spooler. The advantage of this technique is that the graphics can be scaled to fit the printed page by scaling the coordinates themselves rather than the pixels after scan conversion has been applied. As a result, aliasing artifacts are minimized.

The print API technique has a significant drawback when applied to an overlay/underlay window pair. Most PDLs only support the notion of opaque paint; they do not provide for the marking of transparent paint. In the PostScript PDL, for example, the marked pixels always supersede what was previously marked. Given such a limitation, it is not always possible to capture the imagery in an overlay/underlay window pair using this technique. Certainly, in applications where the background of the overlay is completely transparent and only opaque paint is drawn to it, the underlay could be marked first and the overlay marked second. But if transparent paint was drawn to the overlay, erasing other opaque paint in the overlay, this would not work.

Until this issue is resolved, capture overlay windows and send them to the printer using XReadScreen and resampling. Alternatively, do not use overlays to render information that is to be printed.