PEXGenerateMipmapFromResources - Creates a Prefiltered Texture Map from Color and Alpha Resources

Synopsis

     int PEXGenerateMipmapFromResources(
            Display *display,
            int domain,
            PEXTMDomainData *domain_data,
            int resource_type,
            PEXTexelDimension *texel_dimension,
            unsigned long int power_of_two_tm_required,
            unsigned long int square_tm_required,
            int luminance_channel,
            XID base_color_map,
            XID base_alpha_map,
            PEXMipmapLevel **texel_array
       )

Arguments

display: A pointer to a display structure returned by a successful XOpenDisplay call.
domain: The texture map domain type (PEXTextureMapTypeMipmap).
domain_data: A pointer to domain information specifying the type of texture map to be created and the type of texel data.
resource_type: Type of resource specified by the XIDs (PEXWindowDrawable, PEXPixmapDrawable or PEXBufferDrawable)
texel_dimension: A pointer to a texture dimension structure that corresponds to the base_color_map.
power_of_two_tm_required: Indicates whether maps with dimensions of power of two is required (True or False).
square_tm_required: Indicates whether square maps are required (True or False).
luminance_channel: Luminance channel source selector (PEXLuminanceChannelLuminance, PEXLuminanceChannelRed, PEXLuminanceChannelGreen or PEXLuminanceChannelBlue)
base_color_map: The X resource identifier of the desired filtered texture map's base level color and/or luminance data.
base_alpha_map: The X resource identifier of the desired filtered texture map's base level alpha data.
texel_array: Texel data created by this utility.

Returns

Zero if successful; otherwise, one of the following:

PEXBadXResource: X resource ID is not valid.
PEXBadDomain: Domain is not valid.
PEXBadDimension: Dimension is not valid.
PEXBadTexelType: Texel type is not valid.
PEXBadParameterization: Parameterization type is not valid.
PEXBadTMAlloc: Memory allocation error.
PEXBadTexelDimension: Texel dimensions are not valid.
PEXBadTexelData: Texel data is not valid.

Description

Invoke PEXGenerateMipmapFromResources to create a prefiltered texture map and get texel data suitable for PEXCreateMipmapTM.

The information contained in domain and domain_data determines if a mipmap or other type of texture map is created from the base level data provided.

You need to set the tm_type, texel_type, and num_levels members of the PEXTMDomainData structure before invoking this function. A value of zero in num_levels indicates to the function that it should generate as many levels as necessary to create a full mipmap pyramid or other type of supported map. If the value is non-zero, then the utility creates either the number of levels requested or all the levels for a full map, whichever is less. Upon exit, the num_levels field is updated to the number of levels actually created by the utility.

You must specify the type of resource referenced by the XID for correct conversion by this utility. It is assumed that both the base color and alpha maps are of the same type. The current supported types are those specified by PEXMatchRenderingTargets.

If the texel type specified in the description indicates luminance is included (i.e., the texel type is (PEXTexelTypeLum, PEXTexelTypeLum8, PEXTexelTypeLum16, PEXTexelTypeLumA, PEXTexelTypeLumA8, PEXTexelTypeLumA16) then the luminance_channel indicates the source of the luminance data. The channels available as source of the luminance data are dependent upon the depth or visual class of the base_color_map resource. If the resource is a 24-bit resource, then red, green and blue channels are available as a source for luminance. If it is an 8-bit resource, then the whole 8-bit channel is used as the source for luminance.

The implementation constraints are observed in the creation of the final texel data. If an implementation requires that maps be created with square dimensions and/or dimensions which are a power of two, then the utility applies the appropriate image sizing to the nearest correct dimension. When shrinking the image, the texels from the source image are sampled down using a box filter to create the destination image. When magnifying the image, the texels from the source image are linearly interpolated to create the destination image.

Texel arrays allocated by this function are disposed of using the PEXFreeMipmap utility after they have been used by the PEXCreateMipmapTM function.

Errors