GXInitTexObjLOD

Syntax

#include <revolution/gx.h>

void GXInitTexObjLOD(
    GXTexObj*      obj,
    GXTexFilter    min_filt,
    GXTexFilter    mag_filt,
    f32            min_lod,
    f32            max_lod,
    f32            lod_bias,
    GXBool         bias_clamp,
    GXBool         do_edge_lod,
    GXAnisotropy   max_aniso );

Arguments

obj Pointer to a texture object.
min_filt Filter mode to use when the texel/pixel ratio is >= 1.0. Accepted values are:
Name Filter Type
GX_NEAR Point sampling, no mipmap.
GX_LINEAR Bi-linear filtering, no mipmap.
GX_NEAR_MIP_NEAR Point sampling, discreet mipmap.
GX_LIN_MIP_NEAR Bi-linear filtering, discreet mipmap
GX_NEAR_MIP_LIN Point sampling, linear mipmap
GX_LIN_MIP_LIN Tri-linear filtering
mag_filt Filter mode to use when the texel/pixel ratio is < 1.0. Accepted values are:
Name Filter Type
GX_NEAR Point sampling
GX_LINEAR Bi-linear filtering.
min_lod Minimum LOD value. The hardware uses MAX ( min_lod, lod ). Range is 0.0 to 10.0.
max_lod Maximum LOD value. The hardware uses MIN ( max_lod, lod ). Range is 0.0 to 10.0.
lod_bias Bias added to calculated LOD value.
bias_clamp If GX_ENABLE, clamp the (LOD + lod_bias) so that it can never be smaller than the reduced area of the pixel projection in texture space. Prevents over-biasing the LOD when the polygon is perpendicular to the line of sight.
do_edge_lod If GX_ENABLE is set, the LOD is calculated using texel interpolation. Otherwise, use diagonal texels. This must be set to GX_ENABLE when using a bias clamp (when GX_ENABLE is set for bias_clamp) or when performing anisotropic filtering (when GX_ANISO_2 or GX_ANISO_4 is set for max_aniso).
max_aniso The maximum anisotropic filter to use. Accepted values are:
Name Filter Type
GX_ANISO_1 Max anisotropy = 1. (No anisotropic filtering.)
GX_ANISO_2 maximum anisotropy = 2
GX_ANISO_4 maximum anisotropy = 4
This only functions when GX_LIN_MIP_LIN has been set for min_filt.

Return Values

None.

Description

This function explicitly sets texture level of detail (LOD) controls for a texture object. It is the application's responsibility to provide memory for a texture object. When initializing a texture object using GXInitTexObj or GXInitTexObjCI, this information is set to default values based on the mipmap flag. This function allows the programmer to override those defaults. Be aware that this function should be called after calling the GXInitTexObj or GXInitTexObjCI function for a particular texture object.

The hardware supports anisotropic texture filtering. The default max_aniso setting of GX_ANISO_1 uses a standard square filter to approximate the quadrilateral formed when a pixel is projected into texture space. This type of filter is said to be isotropic.
Anisotropic filtering is accomplished by iterating the square filter along the direction of anisotropy to better approximate the quadrilateral. This type of filtering results in sharper textures at the expense of multiple cycles per quad. The hardware will only use multiple cycles when necessary, and the maximum number of cycles is clamped by the max_aniso argument. So setting max_aniso to GX_ANISO_2 will use, at most, two filter cycles per texture. Be aware that these filter cycles are internal to the texture filter hardware and do not effect the available number of TEV stages. When setting max_aniso to GX_ANISO_2 or GX_ANISO_4, the min_filt parameter must be set to GX_LIN_MIP_LIN.

The LOD computed by the graphics hardware can be biased using the lod_bias argument. lod_bias is added to the calculated LOD and the result is clamped between min_lod and max_lod. If bias_clamp is enabled, the effect of lod_bias will diminish as the polygon becomes more perpendicular to the view direction. This prevents over-sharpening the texture in this situation, but allows LOD biasing for oblique polygons.

Performance Notes

Theoretically, there is no performance difference amongst various magnification/minimization filter settings except the use of the GX_LIN_MIP_LIN filter with the GX_TF_RGBA8 texture format which takes twice as much as other formats. However, this assumes an environment where the texture cache can always be hit. On real environments, you will see some performance differences by changing the filter modes (especially the reduction filter) because cache-hit ratio changes according to which filter mode is being used.

The following is the list of minification filters sorted in the order of performance in common case:

See Also

GXLoadTexObj, GXInitTexObj, GXInitTexObjCI, GXGetTexObjLODAll, GXTexObj Initialization Flow

Revision History

2008/06/03 Corrected errors.
2006/03/01 Initial version.

CONFIDENTIAL