GXPokeZMode

Syntax

#include <revolution/gx.h>

void GXPokeZMode( 
    GXBool       compare_enable,
    GXCompare    func,
    GXBool       update_enable );

Arguments

compare_enable When GX_TRUE, a comparison of the source and destination Z values is enabled. Disabled if not GX_TRUE.

func

Z comparison function. Accepted values are:

Name	Z comparison process
GX_NEVER	Z test always fails.
GX_LESS	The Z test passes if the new Z value < original Z value.
GX_LEQUAL	The Z test passes if the new Z value <= original Z value.
GX_EQUAL	The Z test passes if the new Z value == original Z value.
GX_NEQUAL	The Z test passes if the new Z value != original Z value.
GX_GEQUAL	The Z test passes if the new Z value >= original Z value.
GX_GREATER	The Z test passes if the new Z value > original Z value.
GX_ALWAYS	Z test always passes.

update_enable When GX_TRUE, allows a Z buffer update. If not, disables Z buffer updating, but comparison functionality continues as enabled.

Return Values

None.

Description

This function sets the Z-buffer compare mode when writing the embedded frame buffer (EFB) using the GXPoke* functions. The GXPoke* functions allow the CPU to directly write the to EFB.

The result of the Z compare is used to conditionally write color values to the EFB. The Z value will be updated according to the result of the compare if Z update is enabled.

When compare_enable is set to GX_DISABLE, Z buffer poking is prohibited and the Z buffer is not updated.

The func parameter determines the comparison that is performed. In the comparison function, the poked Z value is on the left while the Z value from the Z buffer is on the right. If the result of the comparison is false, the poked Z value is discarded.

The parameter update_enable determines whether the Z buffer is updated with the new Z value after a comparison is performed.

The Z mode for normal rendering (the GXSetZMode function) is not affected by this function.

Revision History

2006/03/01 Initial version.