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:

1. Hard criterion – A criterion that must be satisfied. Only visuals that meet hard criteria are candidates for successful matches.

2. 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)

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)

Return Types

XSolarisOvlSelectStatus is a value that indicates whether the routine succeeded in finding a visual and, if it failed, the reason for the failure. The return value can be one of:

typedef

enum { 	XSolarisOvlSuccess, 	XSolarisOvlQualifiedSuccess,

	XSolarisOvlCriteriaFailure, 	XSolarisOvlFailure, }

XSolarisOvlSelectStatus;

• XSolarisOvlSuccess is returned if the search is completely successful in finding a visual that meets all hard and soft criteria of one of the XSolarisOvlVisualCriteria structure.

• XSolarisOvlQualifiedSuccess is returned if the chosen visual satisfies all hard criteria of one of the XSolarisOvlVisualCriteria structure, but doesn't meet all soft criteria. In this case, unmetCriteriaReturn contains the logical OR of the soft criteria that were not met.

• XSolarisOvlCriteriaFailure indicates that no visual could be found that meets all the hard criteria of any of the XSolarisOvlVisualCriteria structures. In this case, unmetCriteriaReturn contains the logical OR of the hard criteria that were not met for the XSolarisOvlVisualCriteria structure with the fewest hard criteria not met.

• XSolarisOvlFailure is returned if some other error is encountered besides criteria match failure.

Multiple Criteria Sets

XSolarisOvlSelectPartner supports a degradation sequence of criteria sets. This means that multiple criteria sets can be specified in a single call. First, the routine attempts to find a visual matching the first criteria set. If a visual is found that meets all of the hard criteria of the first set, this visual is chosen. If no visual meets all hard criteria of the first set, the routine performs a search using the second criteria set. This process continues until either a visual is found that meets the hard criteria of some criteria set, or all sets have been used to search. This degradation sequence allows clients to specify the criteria for the most preferred visual as the first criteria set. Visuals that are acceptable but are less desirable can be specified in criteria sets following the first criteria set. This allows the search to proceed through a progressive relaxation in the client's requirements for the visual with a single subroutine call.

Any of the possible criteria can be specified either as a hard or soft criteria for a particular criteria set. For a given set, hardCriteriaMask is the logical OR of the criteria bitmasks that are to be applied as hard criteria during the search. Likewise, softCriteriaMask is the logical OR of the soft criteria bitmasks.

Some criteria have values associated with them. These values are provided by other data members in the XSolarisOvlVisualCriteria structure. In the criteria descriptions that follow, these data members are mentioned where applicable.

• XSolarisOvlVisualClass specifies that the client wants the selected visual to have a specific visual class. The required class is specified in c_class.

• The following criteria interact within one another: XSolarisOvlDepth, XSolarisOvlMinColors, XSolarisOvlMinRed, XSolarisOvlMinGreen, and XSolarisOvlMinBlue. Typically only some subset of these should be specified.

• XSolarisOvlDepth specifies that the depth of the selected visual is to be equal to depth.

• XSolarisOvlMinColors specifies that the selected visual is to have at least minColors number of total displayable colors.

• XSolarisOvlMinRed, XSolarisOvlMinGreen, and XSolarisOvlMinBlue can be used to indicate more specific color requirements for DirectColor or TrueColor visuals. Their corresponding values are specified in minRed, minGreen, and minBlue, respectively. These indicate that the selected visual must have at least the specified number of reds, greens, and/or blues.

• XSolarisOvlMinBitsPerRGB specifies that the selected visual is to have at least minBitsPerRGB of color channel output from colormaps created on that visual.

• XSolarisOvlMinBuffers specifies that the client wants the selected visual to be able to be assigned at least minBuffers number of accelerated MBX image buffers.

• XSolarisOvlUnsharedPixels selects partner visuals whose window pixels don't lie in the same drawing plane groups as the window pixels of the argument visual vid. If a visual uses the same drawing plane group as the argument visual, it is not matched by this criterion.

• XSolarisOvlUnsharedColors selects partner visuals whose window pixel colors can be displayed simultaneously when the overlay/underlay window pair has the colormap focus. If a visual shares the same color LUT pool and that pool has only one color LUT in it as the argument visual, the visual is not matched by this criterion.

If either hardCriteriaMask of a criteria set is to 0, any visual will match that criteria set with a hard match. Likewise, setting the softCriteriaMask of a criteria set to 0, is sufficient to guarantee at least a soft match for that criteria set.

Selecting an Optimal Overlay/Underlay Visual Pair

The XSolarisOvlSelectPair routine is similar to XSolarisOvlSelectPartner. However, instead of selecting a partner visual given another visual, this routine simultaneously selects both the overlay and underlay visual from the set of all visual pairs for the given screen. The pair selected is the one that best matches the given criteria. The client is assured that, short of X errors not related to overlays, it can successfully create windows with the returned visuals.

This routine searches through all optimal visual pairs for a given screen, and then through all pairs of visuals (optimal and non-optimal), applying the specified criteria. These criteria are specified in pCriteria. Each element of pCriteria specifies criteria for both the overlay and underlay. It returns a success or failure status depending on whether it finds a pair that meets all the given criteria.

The selected pair has an overlay that satisfies all the hard criteria specified for the overlay. The pair has an underlay visual that satisfies all the hard criteria for the underlay. The attributes of the overlay visual are returned in ovVisinfoReturn. Likewise, the attributes of the underlay visual are specified in unVisinfoReturn. If two or more pairs are found that meet all of the hard criteria (both overlay and underlay) and the same number of soft criteria (either overlay or underlay), one of them will be chosen and returned. Which pair is chosen depends on the implementation.

The syntax and arguments are shown below.

XSolarisOvlSelectStatus

XSolarisOvlSelectPair (Display *display, int screen, int numCriteria,

  XSolarisOvlPairCriteria *pCriteria,   XVisualInfo *ovVisinfoReturn,

XVisualInfo *unVisinfoReturn, 		unsigned long *unmetOvCriteriaReturn,

		unsigned long *unmetUnCriteriaReturn)

Argument Types

XSolarisOvlPairCriteria 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 {  XSolarisOvlVisualCriteria      overlayCriteria;

 XSolarisOvlVisualCriteria      underlayCriteria; }

XSolarisOvlPairCriteria;

XSolarisOvlVisualCriteria is defined in the specification of XSolarisOvlSelectPartner.

Return Types

Refer to the specification of XSolarisOvlSelectPartner for the definition of the type XSolarisOvlSelectStatus.

• XSolarisOvlSuccess is returned if the search is completely successful in finding a pair that meets all hard and soft criteria of one of the XSolarisOvlPairCriteria structures.

• XSolarisOvlQualifiedSuccess is returned if the chosen pair satisfies all hard criteria of one of the XSolarisOvlPairCriteria structures, but doesn't meet all soft criteria. In this case, unmetOvCriteriaReturn and unmetUnCriteriaReturn contain the logical OR of the soft criteria that were not met for the overlay and underlay, respectively.

• XSolarisOvlCriteriaFailure indicates that no pair could be found that meets all the hard criteria of any of the XSolarisOvlPairCriteria structures. In this case, unmetOvCriteriaReturn and unmetUnCriteriaReturn contain the logical OR of the hard criteria that were not met by the XSolarisOvlPairCriteria structure with the fewest hard failures, for the overlay and underlay, respectively.

• XSolarisOvlFailure is returned if some other error is encountered besides criteria match failure.

Criteria Sets

Like XSolarisOvlSelectPartner, XSolarisOvlSelectPair supports a degradation sequence of criteria sets. This means that multiple criteria sets can be specified in a single call. First, the routine attempts to find a pair matching the first criteria set for both the overlay and the underlay. If it finds a pair that meets all of the hard criteria of the first set, it chooses this pair. If no pair meets all hard criteria of the first set, the routine searchs using the second criteria set. This process continues until either a pair is found that meets all of the hard criteria of some criteria set, or all sets have been used to search. This degradation sequence allows clients to specify the criteria for the most preferred pair as the first criteria set. Pairs that are acceptable but less desirable can be specified in criteria sets following the first criteria set. This allows the search to proceed through a progressive relaxation in the client's requirements for the pair with a single subroutine call.

The criteria masks that can be specified are described in Selecting a Visual for an Overlay/Underlay Window.