.TH gSPCullDisplayList 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPCullDisplayList, gsSPCullDisplayList
\- Cull display lists which are offscreen.
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gSPCullDisplayList(Gfx *gdl, unsigned int v0, unsigned int vn)

gsSPCullDisplayList(unsigned int v0, unsigned int vn)
\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I v0 
index of first vertex to check.
.TP
.I vn
index of last vertex to check.  Must be greater than v0.
.SH DESCRIPTION
This command determines whether a bounding volume intersects
the viewing volume.  If the bounding volume is entirely
outside of the viewing volume then the remainder of the 
current display list is not executed.
.PP
The bounding volume is specified with up to 16 vertices.
The vertices should describe a shape which completely bounds
the object to be culled.  Generally 8 vertices should be used 
and should be the vertices of the objects bounding cube, although
any number of vertices up to 16 may be used.  These 
bounding vertices should be specified in a 
.IR gSPVertex (3P)
command
which precedes the 
.IR gSPCullDisplayList (3P)
command.  They may be placed anywhere in the 16 vertex buffer
(see the 
.IR gSPVertex (3P)
command).  Use the 
.I v0
and
.I vn
parameters to indicate the indices of the first and last
vertices (respectively) in the
bounding volume.  The vertices in the bounding volume may or
may not be used in the model itself.  The entire bounded model
(and nothing else) should be contained in the remainder of the
display list.
.PP
Note that it is important to maintain
.PP
0 <=
.I v0
<
.I vn
<= 15

.SH EXAMPLE
To volume cull a model whose bounding box is a cube whose
vertices are contained in bound_vtx which is an array of
8 Vtx (see
.IR gSPVertex (3P)
):
.Ex
gSPVertex(glist++, bound_vtx, 8, 0); /* load 8 vtx @ index 0 */
gSPCullDisplayList(glist++, 0, 7);   /* cull using vtx 0-7   */

/* the remainder of the display list should be devoted to */
/* displaying the culled model.                           */
.Ee
.SH NOTE
If the bounding volume vertices are loaded only for the purpose of
this test, be sure to set the RSP rendering state to turn off
lighting, since lighting calculations are done at vertex load time.

Except for the extra transformations of the volume vertices,
implementation of this command is essentially for free. The RSP
geometry engine retains the clip codes for each vertex in the
vertex buffer, this cull test is simply a trivial rejection
of those clip codes.

This command is NOT affected by 
.IR gSPClipRatio (3P),
the clipping volume used for trivial rejection is the
viewing frustum defined by the projection matrix and the viewport.
.PP
Proper use of this command requires some planning of the data base.
Some data, a horizon ground plane for example, would not benefit from
this test since it would nearly always be visible (it could be subdivided, 
however). This test is most useful for complex characters or 
features that are likely to move in and out of the viewing frame.
.SH SEE ALSO
.IR gSPVertex (3P)