XSolarisOvlSelectPair(3)XSolarisOvlSelectPair(3)NAMEXSolarisOvlSelectPair - selects an optimal overlay/underlay visual pair
that best meets the criteria
SYNOPSIS
XSolarisOvlSelectStatus
XSolarisOvlSelectPair (Display *display, int screen, int numCri‐
teria, XSolarisOvlPairCriteria *pCriteria, XVisualInfo *ovVisin‐
foReturn, XVisualInfo *unVisinfoReturn, unsigned long
*unmetOvCriteriaReturn, unsigned long *unmetUnCriteriaReturn)
Arguments
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 pCrite‐
ria 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 suc‐
cessful return, this structure contains a description of the
chosen overlay visual.
unVisinfoReturn
A pointer to a caller provided XVisualInfo structure. On suc‐
cessful 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 only
meaningful when the routine returns a value of XSolarisOvlQuali‐
fiedSuccess, or XSolarisOvlCriteriaFailure.
unmetUnCriteriaReturn
A pointer to a bitmask that describes the criteria that were not
satisfied for the underlay visual. This return argument is only
meaningful when the routine returns a value of XSolarisOvlQuali‐
fiedSuccess, or XSolarisOvlCriteriaFailure.
Argument Types
See the Description section for a full description of how these types
should be used.
XSolarisOvlPairCriteria
A structure defining various criteria to be used during visual
selection, along with indications of the stringency of the cri‐
teria.
typedef struct {
XSolarisOvlVisualCriteriaoverlayCriteria;
XSolarisOvlVisualCriteriaunderlayCriteria;
} XSolarisOvlPairCriteria;
XSolarisOvlVisualCriteria is defined in the specification of XSolar‐
isOvlSelectPartner(3).
Return Types
XSolarisOvlSelectStatus
Refer to the specification of XSolarisOvlSelectPartner(3) for
the definition of this type.
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 contains 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 unmetUnCriteriaRe‐
turn contains 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.
DESCRIPTION
This routine is similar to XSolarisOvlSelectPartner(3). However,
instead of selecting a partner visual given another visual, this rou‐
tine simultaneously selects both the overlay and underlay visual from
the set of all visual pairs for the given screen. The pair selected
will be 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-opti‐
mal), 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 will have an overlay that satisfies all the hard cri‐
teria specified for the overlay. The pair will have 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. It is
implementation dependent which one is chosen.
Like XSolarisOvlSelectPartner(3), XSolarisOvlSelectPair supports a
degradation sequence of criteria sets. This means that multiple crite‐
ria sets can be specified in a single call. First, an attempt is made
to find a pair matching the first criteria set for both the overlay and
the underlay. If a pair is found which meets all of the hard criteria
of the first set, this pair is chosen. If no pair meets all hard cri‐
teria of the first set, a search is performed using the second criteria
set. This process continues until either a pair is found that meets
the all of the hard criteria of some criteria set, or all sets have
been used to search. This degradation sequence allows clients to spec‐
ify the criteria for the most preferred pair as the first criteria set.
Pairs that are acceptable but which are less desirable can be specified
in criteria sets following the first. This allows the search to pro‐
ceed 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 the specifi‐
cation of XSolarisOvlSelectPartner(3).
11 July 1995 XSolarisOvlSelectPair(3)
