Using Existing Xlib Pixel Transfer Routines
The Xlib pixel transfer routines XGetImage, XCopyArea, and XCopyPlane can also be used with transparent overlay windows.
XGetImage
On non-overlay drawables, the XGetImage routine works as defined in the X11 specification. The same is true for overlay windows, with the exception that, on these windows, the color information returned for transparent pixels is undefined. Clients who simply want to retrieve the display colors for a region on the screen should use XReadScreen.
XCopyArea and XCopyPlane
When both the source and destination drawables are non-overlay, the XCopyArea and XCopyPlane routines work as defined in the X11 specification. However, note the following for the cases in which either the source or the destination drawable is an overlay window.
When the source drawable is overlay and the destination drawable is non-overlay, only the color information is copied; the paint type information in the source is ignored. Color information for transparent pixels is undefined.
When the source drawable is non-overlay and the destination drawable is overlay, the copy is performed as the paint type in the GC indicates. If the paint type is XSolarisOvlPaintOpaque, the color information is copied into the destination with opaque paint. If the paint type is XSolarisOvlPaintTransparent, the color information is ignored, and the destination pixels are transparent.
When both the source drawable and destination drawable are overlay, the paint type of the source is ignored, and this behaves as if the source were not an overlay. If copying both color and paint type information is the desired result, use XSolarisOvlCopyAreaAndPaintType.
Designing an Application for Portability
The Solaris overlay API provides two routines that help ensure application portability across devices. These routines are:
XSolarisOvlSelectPartner - Enables the application to select the visual that is the best partner for an existing overlay or underlay visual.
XSolarisOvlSelectPair - Enables the application to select the optimal overlay and underlay visual pair from the set of all visual pairs for the screen.
These routines are described below.
Selecting a Visual for an Overlay/Underlay Window
Portable applications using overlays can search for an appropriate overlay visual to use for a given underlay visual, or vice versa. Each X screen supporting the overlay extension defines a set of overlay visuals whose windows are best for use as children of underlay windows. For each underlay visual, there is a set of optimal overlay visuals. Together, all combinations of underlay visuals and their optimal overlay visuals form the set of optimal overlay/underlay pairs for that screen. The overlay and underlay visuals of an optimal pair are partners of each other.
The routine XSolarisOvlSelectPartner allows the client to select, given an underlay visual, an optimal overlay that meets certain criteria. Inversely, it also allows the client to select an optimal underlay visual given an overlay visual. The client is assured that, short of X errors not related to overlays, it can successfully create a window with the returned visual.
This routine searches through the optimal partners of the given visual, applying the criteria specified. It returns a success or failure status depending on whether it finds a visual that meets the criteria. A criterion can be one of two types:
Hard criterion - A criterion that must be satisfied. Only visuals that meet hard criteria are candidates for successful matches.
Soft criterion - A desirable criterion, but one that is not required.
The visual that matches all hard criteria and the most soft criteria is chosen, and its attributes are returned. If two or more visuals are found that meet all of the hard criteria and the same number of soft criteria, one of them will be chosen and returned. It is implementation dependent which one is chosen.
The syntax and arguments for XSolarisOvlSelectPartner are shown below.
XSolarisOvlSelectStatus XSolarisOvlSelectPartner (Display *display, int screen, VisualID vid, XSolarisOvlSelectType seltype, int numCriteria, XSolarisOvlVisualCriteria *pCriteria, XVisualInfo *visinfoReturn, unsigned long *unmetCriteriaReturn) |
display | Specifies the connection to the X server. |
screen | An integer specifying the screen for the visual vid. |
vid | The XID of the visual to find a partner for. |
seltype | The type of selection that is to be done. |
numCriteria | The number of XSolarisOvlVisualCriteria structures in the pCriteria array. |
pCriteria | An array of criteria structures in priority order from high to low specifying the criteria to be used in selecting the visual. |
visinfoReturn | A pointer to a caller provided XVisualInfo structure. On successful return, this structure contains a description of the chosen visual. |
unmetCriteriaReturn | A pointer to a bitmask that describes the criteria that were not satisfied. This return argument is meaningful only when the routine returns a value of XSolarisOvlQualifiedSuccess, or XSolarisOvlCriteriaFailure. |
Argument Types
XSolarisOvlSelectType is an enumeration defining two types of selections that can be done in XSolarisOvlSelectPartner. It is defined as:
typedef
enum { XSolarisOvlSelectBestOverlay, XSolarisOvlSelectBestUnderlay, }
XSolarisOvlSelectType;
|
XSolarisOvlVisualCriteria is a structure defining various criteria to be used during visual selection, along with indications of the stringency of the criteria. This structure is defined as:
typedef
struct { unsigned long hardCriteriaMask;
unsigned long softCriteriaMask;
int c_class; unsigned int depth; unsigned
int minColors; unsigned int minRed; unsigned int minGreen;
unsigned int minBlue; unsigned int minBitsPerRGB;
unsigned int minBuffers; }
XSolarisOvlVisualCriteria;
|
hardCriteriaMask and softCriteriaMask are bitmasks whose values can be the logical OR of any of the following bitmasks:
#define XSolarisOvlVisualClass (1L<<0) #define XSolarisOvlDepth (1L<<1) #define XSolarisOvl MinColors (1L<<2) #define XSolarisOvlMinRed (1L<<3) #define XSolarisOvl MinGreen (1L<<4) #define XSolarisOvl MinBlue (1L<<5) #define XSolarisOvlMinBitsPerRGB (1L<<6) #define XSolarisOvl MinBuffers (1L<<7) #define XSolarisOvlUnsharedPixels (1L<<8) #define XSolarisOvlUnsharedColors (1L<<9) #define XSolarisOvlPreferredPartner (1L<<10) |