int PEXSelectVisual(
Display *display,
int screen,
int criteria_count,
PEXUtVisualCriteria *criteria,
XVisualInfo *vis_info_return,
XStandardColormap *cmap_info_return,
PEXColorApproxEntry *capx_info_return,
int *select_criteria_return,
unsigned int *unmet_criteria_return,
Atom *std_prop_atom_return
)
Invoke PEXSelectVisual as a utility that attempts to select an X Visual on the specified display and screen that meets the criteria of one of the criteria sets specified.
This utility returns a success/failure indicator and if successful, it returns information about the Visual and PEX color support for the Visual in structure storage provided by the caller.
PEXSelectVisual supports a "degradation" sequence of criteria sets: specify the "preferred" Visual in the first element of the criteria array, and progressively weaker or less desirable sets in subsequent elements. If the hard criterion from the first element of the criteria array is not met, then the utility evaluates the next criteria set.
The function returns colormap initialization information and color approximation information in cmap_info_return and capx_info_return. When no color approximation type is specified as a criterion, and no property is available to describe a colormap, then this utility returns a PEXColorRange color approximation entry for GrayScale and StaticGray Visuals, and a PEXColorSpace entry otherwise.
If a standard colormap property was used during Visual selection, then the Atom is returned in std_prop_atom_return. All storage for returned values must be allocated by the caller.
Criteria for Visual selection are specified by two masks inside the criteria structure: (see Mask Bits for the Hard and Soft Criteria.)
If a bit for a particular criterion is present in both masks then it is treated as a hard criterion.
For each bit that is set in a criteria mask, a corresponding field in the PEXUtVisualCriteria structure is expected to be set to appropriate values:
PEXUtDepth depth PEXUtMinColors min_colors PEXUtMinRed min_red PEXUtMinGreen min_green PEXUtMinBlue min_blue PEXUtVisualClass visual_class PEXUtStandardColormapProperty standard_colormap_property PEXUtDynamicVisual dynamic_visual PEXUtDBCapability double_buffering_capability PEXUtColorApproxType color_approx_type PEXUtZBufferDepth z_buffer_depth PEXUtAlphaBufferDepth alpha_buffer_depth PEXUtAccumBufferDepth accum_buffer_depth PEXUtAccumBufferMinRed accum_buffer_min_red PEXUtAccumBufferMinGreen accum_buffer_min_green PEXUtAccumBufferMinBlue accum_buffer_min_blue
The depth, min_colors, and (min_red,min_green,min_blue) criteria fields interact with one another, and typically only some subset of these should be specified. Depth refers to the depth of the Visual, and may be combined with visual_class if the application must have a specific Visual type (e.g., depth 8 PseudoColor). The depth field may have any valid depth (number of planes) as a value; the value of the visual_class field must be one of the standard X Visual classes (PseudoColor, DirectColor, GrayScale, StaticColor, TrueColor, StaticGray). Min_colors specifies a minimum number of total colors (i.e., cells in a PseudoColor Visual, or combinations in a DirectColor Visual). Min_red, min_green, and min_blue can be used to indicate more specific requirements of a DirectColor or TrueColor visual, or of a color space sampling specified in a standard colormap property. Allowed values for all these fields are positive integers.
When the standard_colormap_property criterion is specified (allowed values are True and False), the procedure searches for defined standard colormap properties in a predefined order: first RGB_BEST_MAP, then RGB_DEFAULT_MAP. It is recommended that standard_colormap_property be specified as a "soft" criterion, since some PEX servers do not define standard colormap properties.
This utility may choose a Visual with more than the requested number of colors unless some other criterion prevents it from doing so.
You can use the dynamic_visual criterion as a hard criterion to enforce selection of a Visual that you can write to, or as a soft criterion to indicate a preference. Conflict is possible between this criterion and the visual_class field. Allowed values are True and False.
The double_buffering_capability criterion may be important to many interactive graphics applications. Allowed values are True and False.
Color_approx_type is mainly useful to applications that need PEXColorRange color approximation. If not specified, then this utility assumes that PEXColorSpace is acceptable, since this is the most common and natural method for most PEX applications. If it is set to PEXColorRange, the returned color approximation entry is initialized for an appropriate gray ramp.
Use the Z buffer depth criterion to specify a minimum depth criterion in terms of bits. If you intend to read the contents of a Z buffer, the function PEXGetAncillaryBufferInfo is useful for determining the format and range of the Z buffer values.
Specify alpha buffer depth as a criterion if you expect to use alpha blending functions that utilize a destination alpha buffer or intend to use alpha buffer transparency.
Specify some combination of the four accumulation buffer criteria if you intend to use accumulation buffers for multi-pass rendering.
For good application portability and interoperability, the following recommendation is made: always specify standard_colormap_property as a soft criterion. If the application has a need for a certain amount of color resolution, specify either min_colors or (min_red,min_green,min_blue) but not both. Double_buffering_capability may be specified as hard or soft criteria depending on the application. Other criteria should be specified as soft criteria unless particular application needs cause them to be absolute requirements.
The ability of this procedure to verify that criteria are met depends on information available from the PEX server, including its support for various interoperability conventions. In general, if a hard criterion cannot be determined to have been satisfied or not, it is considered to have not been met; if a soft criterion cannot be verified, then the utility acts as though it had been met but still returns the corresponding bit in unmet_criteria_return.
If two or more visuals meet all the hard criteria, then the visual that meets the largest number of soft criteria is selected. If there is more than one visual that meets the same number of soft criteria, then the visual with the highest color resolution is chosen. In the event that the visuals are equivalent in these three respects, a static visual is preferred over a dynamic one. The final criterion is that preference is given to visuals in the order that they are listed by the server.
See function return values.
For an overview, see PEXlib Access and Information Functions.