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.

Choosing Visuals for Overlay/Underlay Windows

The Solaris transparent overlay API supports multiple plane group (MPG) and single plane group (SPG) devices. Display devices come in a wide variety of configurations. Some have multiple plane groups. Some have multiple hardware color lookup tables (LUTs). Some dedicate color LUTs to particular plane groups and some share color LUTs between plane groups. This wide variety makes it difficult for an application writer to construct portable overlay applications.

For a given type of underlay window, some devices can provide some types of overlay windows with high-performance rendering. Other devices provide the same type of overlay window but with slower rendering. Some devices can support overlays with many colors, and some devices cannot. Some devices can support simultaneous display of both overlay and underlay colors for all types of overlays and underlays. Others support simultaneous display of colors but not for all overlay/underlay combinations. Still others support a certain degree of simultaneous color display. These devices support more than one hardware color LUT. Hardware might not contain enough color LUTs to enable all applications to display their colors simultaneously.

The following routines enable an application to negotiate with the system for a suitable overlay/underlay visual pair:

• XSolarisOvlSelectPartner

• XSolarisOvlSelectPair

These routines are described in the section "Designing an Application for Portability" .

The assumption is made that each application has an ideal configuration of windows and colors. An application should start out by asking for the "best" overlay/underlay pair. If this can be satisfied by the device, then the negotiation is complete, and the application proceeds to create windows on the selected underlay and overlay visuals. But if no visual pair satisfies the query, the application must relax its demands. To this end, it should specify the "next best" pair. The application may choose to ask for less colorful visuals, or it may accept lower rendering performance on one of the visuals. The process continues until either a satisfactory visual is found, or the application decides it's not worth running in this environment without certain criteria being met.

The transparent overlay API provides routines that enable the application to conduct such a negotiation in a single subroutine call. The application specifies criteria to be matched for either the overlay visual, the underlay visual, or both. Application programmers are encouraged to use these routines to ensure portability to the widest range of graphics devices.

Example Program

The program below demonstrates a simple example of a transparent overlay. The program creates a transparent overlay window, draws the window border in white, displays a text string in white, and draws a white filled rectangle. The paint type is opaque by default, and the window background is transparent by default. Use the following Makefile to compile and link the program.

simple:

simple.c   cc -I../ -I/usr/openwin/include -o simple simple.c \ 

 -L/usr/openwin/lib -lX11 -lXext

Example 6-1 Transparent Overlay Example Program

#include <stdio.h> #include 

<X11/Xlib.h>  #include "X11/Xmd.h"  #include

<X11/extensions/transovl.h>  #include

<X11/extensions/transovlstr.h> Display       *display;  Window

window;  XSetWindowAttributes       attribs; GC       gc;  XGCValues

      gcvalues; main()  {   display = XOpenDisplay("");

attribs.override_redirect = True;

attribs.border_pixel = WhitePixel(display,0);

window = XSolarisOvlCreateWindow(display,      DefaultRootWindow(display),

100, 100, 500, 500, 10,      CopyFromParent, InputOutput,CopyFromParent, 

CWBorderPixel | CWOverrideRedirect, &attribs); gcvalues.font =

XLoadFont(display, "fixed");

gcvalues.foreground =WhitePixel(display, 0);

gc = XCreateGC(display, window, GCFont | GCForeground,&gcvalues);

XMapWindow(display, window); XDrawString(display, window,

gc, 50, 50, "This is a test", 14);

XFillRectangle(display,window, gc, 70, 70, 100, 100); 

XFlush(display); while   (1);}

Overview of the Solaris Transparent Overlay Window API

The transparent overlay window API includes the routines listed in Table 6-2. These routines are provided by libXext.so. To use the Solaris overlay routines, do the following:

• Include the file /usr/openwin/include/X11/extensions/transovl.h

• Link the library device handler with the library /usr/openwin/lib/libXext.so

Table 6-2 List of Transparent Overlay Window Routines

The remainder of this chapter discusses the transparent overlay API routines.

Creating Transparent Overlay Windows

You can create a transparent overlay using XSolarisOvlCreateWindow. This routine behaves exactly as XCreateWindow except that the resulting window is a transparent overlay window. The newly created window can be rendered into with both opaque and transparent paint, and the background of the overlay window is transparent.

The class argument to XSolarisOvlCreateWindow should be InputOutput. An overlay window can be created as an InputOnly window but, in this case, it will behave like a standard InputOnly window. It is only for InputOutput windows that there is a difference between overlay and non-overlay.

The syntax and arguments for XSolarisOvlCreateWindow are shown below.

Window

XSolarisOvlCreateWindow(Display *display, Window parent, int x, int y,

  unsigned int width, unsigned int height,   unsigned int border_width, int

depth, unsigned int class,   Visual * visual, unsigned long valuemask,    

XSetWindowAttributes * attr)

The arguments for this routine are the same as those for XCreateWindow.