PEXGenerateMipmap - Creates a Prefiltered Texture Map from Base Map

Synopsis

     int PEXGenerateMipmap(
            int domain,
            PEXTMDomainData *domain_data,
            unsigned long int power_of_two_tm_required,
            unsigned long int square_tm_required,
            PEXMipmapLevel *base_map,
            PEXMipmapLevel **texel_array
        )

Arguments

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.
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 is required (True or False).
base_map: The texel data of the desired filtered texture map's base level.
texel_array: Texel data created by this utility.

Returns

Zero if successful; otherwise, one of the following:

PEXBadDomain: Domain is not valid.
PEXBadDimension: Dimension is not valid.
PEXBadTexelType: Texel type is not valid.
PEXBadParamerization: Parameterization type is not valid.
PEXBadTMAlloc: Memory allocation error.
PEXBadTexelDimension: Texel dimensions are not valid.
PEXBadTexelData: Texel data is not valid.

Description

Invoke PEXGenerateMipmap to create a prefiltered texture map and get a list of texel arrays suitable for the PEXCreateMipmapTM function.

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. At present, color mipmaps are the only type of domain supported. Subsequent releases of PEX may support others.

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.

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