Solaris X Window System Developer's Guide

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)

`display`	Specifies the connection to the X server.
`screen`	An integer specifying the screen on which the visuals are to be searched.
`numCriteria`	The number of `XSolarisOvlPairCriteria` structures in the `pCriteria` array.
`pCriteria`	An array of pair criteria structures in priority order from high to low specifying the criteria to be used in selecting the pair.
`ovVisinfoReturn`	A pointer to a caller-provided `XVisualInfo` structure. On successful return, this structure contains a description of the chosen overlay visual.
`unVisinfoReturn`	A pointer to a caller-provided `XVisualInfo` structure. On successful return, this structure contains a description of the chosen underlay visual.
`unmetOvCriteriaReturn`	A pointer to a bitmask that describes the criteria that were not satisfied for the overlay visual. This return argument is meaningful only when the routine returns a value of `XSolarisOvlQualifiedSuccess`, or `XSolarisOvlCriteriaFailure`.
`unmetUnCriteriaReturn`	A pointer to a bitmask that describes the criteria that were not satisfied for the underlay visual. This return argument is meaningful only when the routine returns a value of `XSolarisOvlQualifiedSuccess`, or `XSolarisOvlCriteriaFailure`.

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.