gSPCullDisplayList

gSPCullDisplayList [Macro]

Function

gSPCullDisplayList

Does volume culling

Syntax

#include <ultra64.h>        /* gbi.h */
gSPCullDisplayList(Gfx *gdl, u32 v0, u32 vn)
gsSPCullDisplayList(         u32 v0, u32 vn)

Arguments

gdl
the display list pointer.
v0
the index of first vertex to check (v0 < vn)
F3DEX
F3DEX.NoN
F3DLX
F3DLX.NoN
L3DEX		 0~31
F3DLX.Rej 0~63
F3DLP.Rej 0~79

* For the F3DEX2 microcode group (F3DEX2, F3DLX2, F3DLP2, and L3DEX2), the values are as follows:
F3DEX2
F3DEX2.NoN
F3DLX2
F3DLX2.NoN
L3DEX2		 0~31
F3DEX2.Rej
F3DLX2.Rej		 0~63

vn
the index of last vertex check (vn > v0)
F3DEX
F3DEX.NoN
F3DLX
F3DLX.NoN
L3DEX		 0~31
F3DLX.Rej 0~63
F3DLP.Rej 0~79

* F3DEX2 microcode group (F3DEX2, F3DLX2, F3DLP2, and L3DEX2), the values are as follows:
F3DEX2
F3DEX2.NoN
F3DLX2
F3DLX2.NoN
L3DEX2		 0~31
F3DEX2.Rej
F3DLX2.Rej		 0~63

Description

This macro measures whether or not the viewing volume and bounding volume intersect. If the bounding volume of an object is completely outside of the viewing volume, this function operates like the gSPEndDisplayList macro, and the remaining portion of the display list is skipped.

The vertices of the bounding volume form a complete boundary around the object to be culled. Although normally eight vertices are used as the object bounding cube, any number of vertices can be used within the allowable range. These bounding vertices are specified before this macro with gSPVertex and can be placed anywhere in the vertex buffer.

v0 and vn indicate the first and last index within the bounding volume. The bounding volume vertices can be the same as the object vertices, but whatever the case the entire object must be contained in the bounding volume.

For details, please see Section 11.6.4 "Volume Culling" in the N64 Online Programming Manual.

Note

Make sure that v0 and vn satisfy the relationship (v0 < vn).

To load the bounding volume vertices only for use by this macro, set the RSP rendering state lighting to OFF so the lighting calculation is not performed when the vertices are loaded.

Basically, not much processing time is required for execution of this command, other than for bounding volume vertex transformations. The RSP geometry engine maintains the various clipping codes inside the vertex buffer. This macro performs culling by simply using those clipping codes. Also, it is not affected by gSPClipRatio; the clipping volume becomes the viewing volume defined by the projection matrix and the viewport.

Comment

To use this macro properly, the properties of the object must be carefully considered. For example, if level ground is always visible, then there is no need to use this macro. But the macro is extremely effective for objects that perform complex movements, such as when a complicated character or viewing volume enters or leaves.

Example

Volume culling of an object with a cubic bounding volume stored in the 8-vertex array "bound_vtx" can be performed as follows: 

gSPVertex(glist++, bound_vtx, 8, 0);    /* Load vertex indices 0~8 */
gSPCullDisplayList(glist++, 0, 7);    /* Cull using vertices 0~7 */

See Also

gSPVertex

Revision History

02/01/99 Entirely revised.