components/x11/libXext/srcs/man/XSolarisOvlSelectPair.man

   1 .\" Copyright (c) 1995, 2008, Oracle and/or its affiliates. All rights reserved.
   2 .\"
   3 .\" Permission is hereby granted, free of charge, to any person obtaining a
   4 .\" copy of this software and associated documentation files (the "Software"),
   5 .\" to deal in the Software without restriction, including without limitation
   6 .\" the rights to use, copy, modify, merge, publish, distribute, sublicense,
   7 .\" and/or sell copies of the Software, and to permit persons to whom the
   8 .\" Software is furnished to do so, subject to the following conditions:
   9 .\"
  10 .\" The above copyright notice and this permission notice (including the next
  11 .\" paragraph) shall be included in all copies or substantial portions of the
  12 .\" Software.
  13 .\"
  14 .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15 .\" IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16 .\" FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
  17 .\" THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  18 .\" LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  19 .\" FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
  20 .\" DEALINGS IN THE SOFTWARE.
  21 .\"
  22 .TH XSolarisOvlSelectPair __libmansuffix__ __xorgversion__ "X FUNCTIONS"
  23 .IX "XSolarisOvlSelectPair" "" "\f3XSolarisOvlSelectPair\f1(3) \(em selects an optimal overlay/underlay visual pair that best meets the criteria.
  24 .SH NAME
  25 XSolarisOvlSelectPair \- selects an optimal overlay/underlay visual pair that best meets the criteria
  26 .SH SYNOPSIS
  27 .LP
  28 \&#include <X11/extensions/transovl.h>
  29
  30 .IP \f3XSolarisOvlSelectStatus\f1
  31 .B XSolarisOvlSelectPair
  32 .B (Display
  33 .I *display,
  34 .B int
  35 .I screen,
  36 .B int
  37 .I numCriteria,
  38 .B XSolarisOvlPairCriteria
  39 .I *pCriteria,
  40 .B XVisualInfo
  41 .I *ovVisinfoReturn,
  42 .B XVisualInfo
  43 .I *unVisinfoReturn,
  44 .B unsigned long
  45 .I *unmetOvCriteriaReturn,
  46 .B unsigned long
  47 .I *unmetUnCriteriaReturn)
  48 .SH Arguments
  49 .TP
  50 .I display
  51 Specifies the connection to the X server.
  52 .TP
  53 .I screen
  54 An integer specifying the screen on which the visuals are to be searched.
  55 .TP
  56 .I numCriteria
  57 The number of
  58 .B XSolarisOvlPairCriteria
  59 structures in the
  60 .I pCriteria
  61 array.
  62 .TP
  63 .I pCriteria
  64 An array of pair criteria structures in priority order from high to low
  65 specifying the criteria to be used in selecting the pair.
  66 .TP
  67 .I ovVisinfoReturn
  68 A pointer to a caller provided
  69 .I XVisualInfo
  70 structure.  On successful return, this structure contains a description of
  71 the chosen overlay visual.
  72 .TP
  73 .I unVisinfoReturn
  74 A pointer to a caller provided
  75 .I XVisualInfo
  76 structure.  On successful return, this structure contains a description of
  77 the chosen underlay visual.
  78 .TP
  79 .I unmetOvCriteriaReturn
  80 A pointer to a bitmask that describes the criteria that were not satisfied
  81 for the overlay visual.  This return argument is only meaningful when the
  82 routine returns a value of
  83 .B XSolarisOvlQualifiedSuccess,
  84 or
  85 .B XSolarisOvlCriteriaFailure.
  86 .TP
  87 .I unmetUnCriteriaReturn
  88 A pointer to a bitmask that describes the criteria that were not satisfied
  89 for the underlay visual.  This return argument is only meaningful when the
  90 routine returns a value of
  91 .B XSolarisOvlQualifiedSuccess,
  92 or
  93 .B XSolarisOvlCriteriaFailure.
  94 .SH Argument Types
  95 .LP
  96 See the Description section for a full description of how these types
  97 should be used.
  98 .TP
  99 .B XSolarisOvlPairCriteria
 100 A structure defining various criteria to be used during visual selection,
 101 along with indications of the stringency of the criteria.
 102 .LP
 103 .nf
 104 typedef struct {
 105 .br
 106         XSolarisOvlVisualCriteriaoverlayCriteria;
 107         XSolarisOvlVisualCriteriaunderlayCriteria;
 108 .br
 109 } XSolarisOvlPairCriteria;
 110 .fi
 111 .LP
 112 .B XSolarisOvlVisualCriteria
 113 is defined in the specification of
 114 .BR XSolarisOvlSelectPartner (3) .
 115 .SH Return Types
 116 .TP
 117 .B XSolarisOvlSelectStatus
 118 Refer to the specification of
 119 .BR XSolarisOvlSelectPartner (3)
 120 for the definition of this type.
 121 .LP
 122 .B XSolarisOvlSuccess
 123 is returned if the search is completely successful in finding a pair that
 124 meets all hard and soft criteria of one of the
 125 .B XSolarisOvlPairCriteria
 126 structures.
 127 .LP
 128 .B XSolarisOvlQualifiedSuccess
 129 is returned if the chosen pair satisfies all hard criteria of one of the
 130 .B XSolarisOvlPairCriteria
 131 structures, but doesn't meet all soft criteria.  In this case,
 132 .I unmetOvCriteriaReturn
 133 and
 134 .I unmetUnCriteriaReturn
 135 contains the logical OR of the soft criteria that were not met for the overlay
 136 and underlay, respectively.
 137 .LP
 138 .B XSolarisOvlCriteriaFailure
 139 indicates that no pair could be found that meets all the hard criteria of any
 140 of the
 141 .B XSolarisOvlPairCriteria
 142 structures.  In this case,
 143 .I unmetOvCriteriaReturn
 144 and
 145 .I unmetUnCriteriaReturn
 146 contains the logical OR of the hard criteria that were not met by the
 147 .B XSolarisOvlPairCriteria
 148 structure with the fewest hard failures, for the overlay and underlay,
 149 respectively.
 150 .LP
 151 .B XSolarisOvlFailure
 152 is returned if some other error is encountered besides criteria match failure.
 153 .SH DESCRIPTION
 154 .LP
 155 This routine is similar to
 156 .BR XSolarisOvlSelectPartner (3) .
 157 However, instead of selecting a partner visual given another visual, this
 158 routine simultaneously selects both the overlay and underlay visual from the
 159 set of all visual pairs for the given screen.  The pair selected will be the
 160 one that best matches the given criteria.
 161 .LP
 162 The client is assured that, short of X errors not related to overlays,
 163 it can successfully create windows with the returned visuals.
 164 .LP
 165 This routine searches through all optimal visual pairs for a given screen,
 166 and then through all pairs of visuals (optimal and non-optimal), applying the
 167 specified criteria.  These criteria are specified in
 168 .I pCriteria.
 169 Each element of
 170 .I pCriteria
 171 specifies criteria for both the overlay and underlay.  It returns a success or
 172 failure status depending on whether it finds a pair that meets all the given
 173 criteria.
 174 .LP
 175 The selected pair will have an overlay that satisfies all the hard criteria
 176 specified for the overlay.  The pair will have an underlay visual that
 177 satisfies all the hard criteria for the underlay.  The attributes of the
 178 overlay visual are returned in
 179 .I ovVisinfoReturn.
 180 Likewise, the attributes of the underlay visual are specified in
 181 .I unVisinfoReturn.
 182 If two or more pairs are found that meet all of the hard criteria (both
 183 overlay and underlay) and the same number of soft criteria (either overlay or
 184 underlay), one of them will be chosen and returned.  It is implementation
 185 dependent which one is chosen.
 186 .LP
 187 Like
 188 .BR XSolarisOvlSelectPartner (3) ,
 189 .B XSolarisOvlSelectPair
 190 supports a degradation sequence of criteria sets.  This means that multiple
 191 criteria sets can be specified in a single call.  First, an attempt is made
 192 to find a pair matching the first criteria set for both the overlay and the
 193 underlay.  If a pair is found which meets all of the hard criteria of the first
 194 set, this pair is chosen.  If no pair meets all hard criteria of the first set,
 195 a search is performed using the second criteria set.  This process continues
 196 until either a pair is found that meets the all of the hard criteria of some
 197 criteria set, or all sets have been used to search.  This degradation sequence
 198 allows clients to specify the criteria for the most preferred pair as the
 199 first criteria set.  Pairs that are acceptable but which are less desirable can
 200 be specified in criteria sets following the first.  This allows the search to
 201 proceed through a progressive relaxation in the client's requirements for the
 202 pair with a single subroutine call.
 203 .LP
 204 The criteria masks that can be specified are described in the specification of
 205 .BR XSolarisOvlSelectPartner (3) .