PEXSelectPixmapDepth - Choose a Pixmap Depth for Use with PEXlib Applications (Utility) (5.2)

Synopsis

 
   int PEXSelectPixmapDepth(
       Display *display,
       int screen,
       int criteria_count,
       PEXUtPixmapDepthCriteria *criteria,
       int *depth_return,
       PEXColorApproxEntry *capx_info_return,
       int *select_criteria_return,
       unsigned int *unmet_criteria_return
   )

Arguments

display: A pointer to a display structure returned by a successful XOpenDisplay call.
screen: The screen number of the display for which a pixmap depth is to be chosen.
criteria_count The number of PEXUtPixmapDepthCriteria structures in the array pointed to by the criteria argument.
criteria: A pointer to a set of PEXUtPixmapDepthCriteria structures in priority order from high to low specifying the criteria to be used in selecting the pixmap depth. See the section entitled "Description" below for a complete description of how to use the data structure.
depth_return: A pointer to an integer allocated by the client. On a successful return, this function stores the pixmap depth value that best satisfies the criteria in this location.
capx_info_return: A pointer to a PEXColorApproxEntry structure allocated by the client. On a successful return, this structure is written with a color approximation setup that is compatible with the pixmap depth and the color approximation type (if specified as a criterion), and can be used in a PEXSetTableValues call.
select_criteria_return: A pointer to an index into the list of criteria specified indicating the criteria selected, to which the other return arguments correspond. The visual, colormap and color approximation information returned will correspond to the criteria indexed by this return argument. An index value of 0 references the first criteria and index value of criteria_count - 1 references the last criteria.
unmet_criteria_return: A pointer to a mask that describes the criteria that were not satisfied in the selected criteria referenced by select_criteria_return. This return argument is meaningful when the function return value is any of PEXUtSuccess, PEXUtQualifiedSuccess, or PEXUtCriteriaFailure.

Returns

PEXUtSuccess: Indicates that the function was completely successful in finding a pixmap depth that meets all hard and soft criteria of the selected depth and encountered no errors during X or PEX inquiries.
PEXUtQualifiedSuccess: Indicates that the chosen depth satisfies all hard criteria but does not meet all soft criteria of the selected criteria. In this case, unmet_criteria_return mask includes the soft criteria that were not satisfied.
PEXUtCriteriaFailure: Indicates that no depth 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 in the first criteria set specified.
PEXUtXFailure: Indicates that an error was encountered during an Xlib function call.
PEXUtPEXFailure: Indicates 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.
PEXUtBadAlloc: Indicates that the function ran out of memory.

Description

Invoke PEXSelectPixmapDepth as a utility that attempts to select a pixmap depth 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 pixmap depth and PEX color approximation support for the pixmap depth in structure storage provided by the caller.

PEXSelectPixmapDepth supports a "degradation" sequence of criteria sets: specify the "preferred" characteristics 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 color approximation information in capx_info_return. When no color approximation type is specified as a criterion, then this utility returns a suitable PEXColorSpace entry.

Criteria for pixmap depth selection are specified by two masks inside the criteria structure: Mask Bits for the Hard and Soft Criteria.

hard_criteria_mask -: indicates what fields in the criteria structure contain valid values to be considered absolute ("hard") criteria during depth selection.
soft_criteria_mask -: 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 PEXUtPixmapDepthCriteria structure is expected to be set to appropriate values:

  PEXUtDepth                    depth
  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

Depth refers to the depth of the pixmap.

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.

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 pixmap depths meet all the hard criteria, then the depth that meets the largest number of soft criteria is selected. If there is more than one depth that meets the same number of soft criteria, then the depth with the highest color resolution is chosen. The final criterion is that preference is given to visuals in the order that they are listed by the server.

Errors