PEXUtFindVisual(3G)

Name

PEXUtFindVisual − choose a Visual for PEX

Syntax

#include <pexutcmap.h>

int PEXUtFindVisual(Display *display, int screen, PEXUtVisualCriteria *criteria, XVisualInfo *vis_info_return, XStandardColormap *cmap_info_return, PEXColorApproxEntry *capx_info_return, unsigned int *unmet_criteria_return, Atom *std_prop_atom_return)

typedef struct {
        unsigned inthard_criteria_mask;
        unsigned intsoft_criteria_mask;
        unsigned intdepth;
        intmin_colors;
        intmin_red;
        intmin_green;
        intmin_blue;
        intvisual_class;
        intlayer;
        intstandard_colormap_property;
        intsharable_colormap;
        intdouble_buffering_capability;
        PEXEnumTypeIndexcolor_approx_type;
} PEXUtVisualCriteria;

Parameters

display
A pointer to a display structure returned by a successful XOpenDisplay call, on which PEXlib has been initialized.

screenThe screen number of the display for which a Visual is to be chosen.

criteria
A pointer to a structure specifying the criteria to be used in selecting the Visual. See below for a complete description of how to use the data structure.

vis_info_return
A pointer to an structure in the caller’s domain. On successful return, this structure is written with a description of the chosen Visual.

cmap_info_return
A pointer to an structure in the caller’s domain. On successful return, this structure is written with a copy of the standard colormap property entry that was used to choose the Visual, if was specified in the hard or soft criteria mask and such an entry was found. If no property was found or the criteria masks do not include this structure is written with information derived from the attributes of the Visual.

capx_info_return
A pointer to a structure in the caller’s domain. On a successful return, this structure is written with a color approximation setup that is compatible with the contents, the Visual, and the color approximation type (if specified as a criterion), and can be used in a PEXSetTableEntries call.

unmet_criteria_return
A pointer to a mask that describes the criteria that were not satisfied. This return parameter is valid when the function return value is any of or

std_prop_atom_return
A pointer to an Upon successful return, this location contains the Atom value for the property whose entry is described in *cmap_info_return, or if no property entry was used.

Returns

The function returns a value of if it is completely successful in finding a Visual that meets all hard and soft criteria, and encounters no errors during X or PEX inquiries. It returns if the chosen Visual satisfies all hard criteria, but does not meet all soft criteria. In this case, the unmet_criteria_return mask includes the soft criteria that were not satisfied.

A negative return value indicates failure. The following are the meanings of the different failure values:

•A return value of indicates that no Visual could be found that meets all the hard criteria. In this case, the unmet_criteria_return mask includes the hard and soft criteria that were not satisfied.

•A return value of means that an error was encountered during an Xlib call.

•means that an error was encountered during a PEXlib call. One possible cause of this failure is that PEXInitialize has not been called for the display connection.

•means that the utility ran out of memory.

Description

This procedure attempts to select an X Visual (on the specified display and screen) that supports PEX and that meets the criteria specified by the criteria masks and structure. It 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.

A colormap initialization and color approximation setup that are likely to be supported by PEX in the Visual are described in cmap_info_return and capx_info_return. However, in the case where no interoperability property was used to obtain the colormap description, these return structures both describe what amounts to an "educated guess" about what color setup might be supported by PEX. In the case where no color approximation type is specified as a criterion, and no property is available to describe a colormap, the utility return a color approximation entry for GrayScale and StaticGray Visuals, and a may be used to verify that the PEX server does support the color approximation entry. If a standard colormap property was used during Visual selection, the Atom is returned in std_prop_atom_return. Note that all storage for returned values must be allocated by the caller.

Criteria for Visual selection are specified by two masks inside the criteria structure: indicates what fields in the criteria structure contain valid values to be considered absolute ("hard") criteria during Visual selection. Similarly, contains bits for criteria that are desirable but not absolutely required for success. 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 structure that is expected to be set to a reasonable value. (Allowed values are described below.) The bits that can be set in these masks and the corresponding field names are:

It is assumed on entry that PEXInitialize has already been successfully called on the display connection. PEXGetExtensionInfo may be called and if it indicates that the protocol version is 5.1 or later, PEXMatchRenderingTargets may be called by the utility to test the "implicit" criterion that PEX is supported on the returned Visual. If the protocol version is 5.0, this verification cannot be made, and the application should be prepared to handle a returned Visual that may not be supported for PEX. (The procedure makes a "best guess" selection based on available information and other specified criteria.) Other PEXlib calls may also be made.

The and criteria fields interact with one another, and typically only some subset of these should be specified. refers to the depth of the Visual, and may be combined with if the application must have a specific Visual type (e.g. depth 8 PseudoColor). The field may have any valid depth (number of planes) as a value; the value of the field must be one of the standard X Visual classes (PseudoColor, DirectColor, GrayScale, StaticColor, TrueColor, StaticGray). specifies a minimum number of total colors (i.e., cells in a PseudoColor Visual, or combinations in a DirectColor Visual). and 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.

The criterion may have some value for applications that plan to do overlay-layer annotation of an image using PEX, or otherwise need to control the screen layer in which PEX drawing is done. Note, however, that vendor support for overlays, and for PEX drawing to such layers, is unpredictable. Furthermore, not all servers supply enough information (e.g. the SERVER_OVERLAY_VISUALS property) for this procedure to determine what layer a Visual is in. Allowed values are and

When the criterion is specified (allowed values are and ), the procedure searches for defined standard colormap properties in a predefined order determined by convention (as yet unestablished). It is recommended that be specified as a "soft" criterion, since some PEX servers do not define standard colormap properties, and conventions for their use in conjunction with PEX are not yet established.

The utility may choose a Visual with more than the requested number of colors unless some other criterion prevents it from doing so, however preference is given to visuals listed first in an ordering supplied by the server (e.g., via PEXMatchRenderingTargets) over visuals that simply have a large number of available colors. When the criterion is preference is given to a Visual that is named in a standard colormap property, even if it means that the number of available colors cannot be maximized. This criterion should be set when the application needs to allow the possibility of sharing a single Colormap resource with other clients, usually to avoid "color flashing". When it is a Visual does not need to appear in a standard colormap property entry in order to be a candidate for selection.

The criterion may be important to many interactive graphics applications. Whether or not this utility can determine the degree of X and PEX support for double-buffering depends on the double-buffering methods supported by the server. (The PEXUtDB utilities provide a degree of isolation from the variety of means by which double-buffering may be supported.) Allowed values for this field are and

is mainly useful to applications that need color approximation. If not specified, the utility assumes that is acceptable, since this is the most common and natural method for most PEX applications. If it is set to the returned color approximation entry is initialized for an appropriate gray ramp.

For good application portability and interoperability, the following recommendation is made: always specify as a soft criterion. If the application has a need for a certain amount of color resolution, specify either or (but not both). may be specified as hard or soft depending on the application. Other criteria should be specified as soft criteria unless particular application needs cause them to be absolute requirements.

Restrictions

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 can not be determined to have been satisfied or not, it is considered to have not been met; if a soft criterion cannot be verified, the utility acts as though it had been met but still returns the corresponding bit in unmet_criteria_return.

Museum