PEXUtCreateWindowAndColormap(3G)

Name

PEXUtCreateWindowAndColormap − choose a Visual and create a Window and Colormap for PEX

Syntax

#include <pexutcmap.h>

int PEXUtCreateWindowAndColormap(Display *display, int screen, PEXUtVisualCriteria *criteria, PEXUtWindowSpecification *window_info, Window *window_return, XVisualInfo *vis_info_return, XStandardColormap *cmap_info_return, PEXColorApproxEntry *capx_info_return, unsigned int *unmet_criteria_return, Atom *std_prop_atom_return, XColor *background_color_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;
typedef struct {
        unsigned longattr_mask;
        XSetWindowAttributesattrs;
        char*title;
        XSizeHintssize_hints;
        Windowparent;
        unsigned intborder_width;
        char*background_color_name;
        char*border_color_name;
} PEXUtWindowSpecification;

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 where the Window is to be created.

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.

window_info
A pointer to a structure specifying attributes of the Window to be created. See the description section below for details.

window_return
A pointer to a Window identifier. The created Window identifier is returned via this parameter.

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. The identifier of the Colormap attached to the created Window is in cmap_info_return->colormap.

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 describes the colormap contents, 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.

background_color_return
A pointer to an structure. Upon successful return, this structure is written with the description of the background color used in creation of the Window.

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 Colormap or Window creation. 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 encompasses the functionality of several other PEXUt utilities into a single-call interface that meets the needs of many PEX applications. It selects a Visual on the specified display and screen using the specified criteria, creates or acquires the ID of a Colormap resource in that visual that is initialized to match a supported color approximation setup ( on color Visuals, on gray Visuals, unless specified otherwise in the criteria), and creates a Window using the Visual and Colormap. Information is returned to the caller about these resources via the *_return parameters. In most cases, an application should be able to simply call this procedure, check for its success, and go on to create and bind PEX Renderers, Lookup Tables, etc.

The created Window ID is returned in window_return. The created Colormap is described in cmap_info_return, including the ID in cmap_info_return->colormap. All cells in the colormap are allocated read-only if the region needed for color approximation consumes the entire Colormap; if the region only consumes part of the Colormap, all cells except those in the region are unallocated or read-only. (This behavior allows XAllocColor to be used with the Colormap.) If a standard colormap property was used during Visual selection, the Atom is returned in std_prop_atom_return. The background_color_return structure is written with the description of the color that was chosen for the window background. Note that all storage for returned values must be allocated by the caller.

Note that in the case where a color approximation entry is derived, the utility initializes the colormap to contain a gray ramp. If the application plans to load other colors into the color approximation region, it may encounter color cell permission errors since the cells in the region may be read-only. (See the See Also list for a list of the lower-level procedures that may be called directly to choose a Visual, create a writeable Colormap (into which colors can be loaded), and create a Window.

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. Also, if the criterion is specified, this utility will avoid creating a Colormap (if possible) and will instead try to use the Colormap resource identified in the standard colormap property. If is specified but the standard colormap property entry does not contain a Colormap ID, a new colormap is created. This procedure does not place the ID into the property, but does return the property Atom so that the calling application can do so. (Application writers must be aware of the need to ensure persistence of the resource if the Colormap is to be shared.)

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 Colormap and color approximation entry are 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.

The window_info structure is used as follows:

The and structure function exactly as they do in a direct call to XCreateWindow, with the following exceptions:

is not used, because this procedure finds or creates a Colormap to use.

and are not used, since this procedure may create a new Colormap. Instead, these pixel values will be looked up name using the and strings. Specifying or will have normal effects, although their compatibility with the Colormap that is used cannot be guaranteed.

Fields related to backing storage should be used with caution, since many PEX implementations do not support backing store for PEX rendering.

The string is assigned as the name of the Window.

describes desired window size and placement in a manner that can be relayed to any window manager that is running. The procedure calls XSetNormalHints to pass this information on.

The field specifies the ID of the parent for the Window to be created, just as in XCreateWindow.

The field specifies the width of the window border in pixels, again as in XCreateWindow.

and are color names as found in the X RGB color data base. The utility procedure uses XAllocNamedColor with the created Colormap in order to derive pixel values for the window background and border. If the strings are empty or invalid, a background of "Black" and a border of "White" are used by default.

Restrictions

This utility issues XMapWindow and XSync calls after the Window creation, but does not modify the event selection mask or wait for any X event. Since X/PEX programs normally operate in an environment where a window manager is running (to which some of the generated requests will be redirected), it is strongly recommended that the application wait for the proper events to be assured that the Window has been mapped, before going on to make PEXlib calls. If the initial exposure event due to the window mapping is needed by the application for correct behavior, it should specify the necessary event mask in window_info->attr_mask and window_info->attrs.

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