gSPCullDisplayList

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

• gdl is the display list pointer.

• v0 is 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 is 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

  * 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

Explanation
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 viewing volume defined by the projection matrix and the viewport becomes the clipping volume.

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