GXInitTexObjLOD

C Specification

#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 used when 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, mipmap without interpolation
`GX_LIN_MIP_NEAR`	bi-linear filtering, mipmap without interpolation
`GX_NEAR_MIP_LIN`	point sampling, linear mipmap
`GX_LIN_MIP_LIN`	tri-linear filtering

mag_filt

filter mode used 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). The range is from 0.0 to 10.0.

max_lod the maximum LOD value The hardware uses MIN(max_lod, lod). The range is from 0.0 to 10.0.

lod_bias the bias to add to computed LOD value

bias_clamp clamps (LOD + lod_bias) so that it can never be smaller than the reduced area of the pixel projection in texture space for GX_ENABLE
Prevents over-biasing the LOD when the polygon is perpendicular to the line of sight.

do_edge_lod the LOD is calculated using texel interpolation for GX_ENABLE
Use diagonal texels when GX_TRUE is not in use. This must be GX_ENABLE when using a bias clamp (when bias_clamp is set to GX_ENABLE) or when performing anisotropic filtering (when max_aniso is set to GX_ANISO_2 or GX_ANISO_4).

max_aniso

the maximum anisotropic filter to use
Accepted values are:

Name	Filter Type
`GX_ANISO_1`	maximum anisotropy = 1 (no anisotropic filtering)
`GX_ANISO_2`	maximum anisotropy = 2
`GX_ANISO_4`	maximum anisotropy = 4

This functions only 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. The application must 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 GXInitTexObj or GXInitTexObjCI for each 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 in 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. Setting max_aniso to GX_ANISO_2 will therefore use a maximum of 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 argument 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/reduction filter settings except for the GX_LIN_MIP_LIN filter with the GX_TF_RGBA8 texture format, which requires twice as much processing 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 the cache-hit ratio changes with the filter mode in use.

The following is the list of reduction filters sorted in ordinary performance order:

GX_NEAR_MIP_NEAR (fastest)
GX_LIN_MIP_NEAR
GX_NEAR_MIP_LIN
GX_LIN_MIP_LIN
GX_NEAR
GX_LINEAR (slowest)

Revision History

03/01/2006 Initial version.