.TH gspTurbo3D 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gspTurbo3D, gspTurbo3D.dram, gspTurbo3D.fifo
\- reduced-feature, reduced-precision, optimized, 3D polygonal geometry 
RSP microcode.

.SH DESCRIPTION
This is the optimized, reduced-featured 3D polygonal geometry RSP microcode.
The low precision and reduced features make this ucode most suitable for
"characters"  or objects which always appear near the center of the 
viewing frustum.
.PP
The
.I dram
version of the microcode directs the output (RDP display list) to
a memory buffer, instead of sending it to the RDP.
.PP
The
.I fifo
version of the microcode uses a DRAM FIFO to send data to the RDP.
.PP
All computations are performed with low precision,
in order to have the fastest processing time. This may result in
visible artifacts.
.PP
The following features are not supported:
.TP
.I clipping
the application program is responsible for not 
sending any geometry which does not appear on 
the screen. Scissoring is supported using DP commands.
.TP
.I lighting
no dynamic lighting calculations are performed
in this ucode.
.TP
.I perspective-corrected textures
texture coordinates are
.I
not
perspective-corrected.
.TP
.I matrix stack
there is no matrix stack; a single matrix is part of the object state.
This is used to transform vertices.
.TP
.I anti-aliasing
the reduced-precision calculations make this feature less-useful.
(anti-aliasing
.I is
performed on all edges, but because the vertex positioning has less
precision, the anti-aliasing is not as sucessful)

.SH TURBO DISPLAY LISTS
The turbo ucode uses a simpler display list format that is not
compatible with any other microcode.
.PP
A turbo display list is a linear list of object structures,
terminated by a NULL object (an object whose object state is NULL):
.PP
.nf
\f3#include "gt.h"

/*
 * This structure is a turbo 'object', the turbo display list is
 * simply a list of these. (4 pointers = 16 bytes)
 *
 */
typedef struct {
    gtGlobState *gstatep; /* global state, usually NULL */
    gtState     *statep; /* if this is NULL, end object processing */
    Vtx         *vtxp;   /* if this is NULL, use points in buffer */
    gtTriN      *trip;   /* if this is NULL, don't draw anything */
} gtGfx_t;

typedef union {
    gtGfx_t             obj;
    long long int       force_structure_alignment;
} gtGfx;
\fP
.fi
.PP
Each object structure contains four pointers; one each to the
.I global state, object state, vertex list,
and
.I triangle list.
.PP
If the global state pointer or the vertex list pointer is NULL,
the current contents in DMEM are used. If the triangle list
pointer is NULL, no triangles will be generated. If the object
state pointer is NULL, it is interpreted as the end of the display
list.

.SH TURBO GLOBAL STATE
The turbo global state structure:
.PP
.nf
\f3#include "gt.h"
/*
 * This is the global state structure. It's definition carefully
 * matches the ucode, so if this structure changes, you must
 * also change the ucode.
 */
typedef struct {
    u16         perspNorm;    /* persp normalization */
    u16         pad0;
    u32         flag;
    Gfx         rdpOthermode;
    u32         segBases[16]; /* segment base addrs (SEE NOTE!) */
    Vp          viewport;     /* the viewport to use */
    Gfx         *rdpCmds;     /* block of RDP data, process if !NULL
                               * block terminated by 
                               * gDPEndDisplayList()
                               */
} gtGlobState_t;

/* NOTE:
 * Although there are 16 segment table entries, the first one
 * (segment 0) is reserved for physical memory mapping. You 
 * should not use segment 0.
 */

typedef union {
    gtGlobState_t       sp;
    long long int       force_structure_alignment;
} gtGlobState;
\fP
.fi
.PP
The global state contains data not likely to change on a per-object
basis. The format of the global state structure is exactly the
same as the DMEM, this structure is simply copied into DMEM.
.PP
The
.I perspNorm
field is used during vertex transformations (see
.I gSPPerspNormalize (3P)).
.PP
The
.I rdpOthermode
field contains a DP SetOtherMode command which is sent first
before any other DP commands.
.PP
The
.I segBases
array contains the 16 segment base addresses. Entry 0 is reserved
for physical memory mapping and should not be used.
.PP
The
.I viewport
is used during vertex transformations (see
.I gSPViewport (3P)).
.PP
.I rdpCmds
points to a block of DP commands. If this pointer is non-NULL,
these commands are sent to the RDP. See the list below for
DP commands which should not be used in this command block.
This list must be terminated by a
.I gDPEndDisplay (3P)
command.
.PP

.SH TURBO OBJECT STATE
The turbo object state structure:
.PP
.nf
\f3#include "gt.h"
/*
 * This is the 'state' structure associated with each object
 * to be rendered. It's definition carefully matches the
 * ucode, so if this structure changes, you must also change
 * the gtoff.c tool and the ucode.
 */
typedef struct {
    u32         renderState;    /* render state */
    u32         textureState;   /* texture state */
    u8          vtxCount;       /* how many verts? */
    u8          vtxV0;          /* where to load verts? */
    u8          triCount;       /* how many tris? */
    u8          flag;
    Gfx         *rdpCmds;
    Gfx         rdpOthermode;
    Mtx         transform;   /* the transform matrix to use */
} gtState_t;

typedef union {
    gtState_t           sp;
    long long int       force_structure_alignment;
} gtState;

/* gtStateLite : same as gtState, but no matrix (see flags below) */
/* this structure must track gtState! */
typedef struct {
    u32         renderState;    /* render state */
    u32         textureState;   /* texture state */
    u8          vtxCount;       /* how many verts? */
    u8          vtxV0;          /* where to load verts? */
    u8          triCount;       /* how many tris? */
    u8          flag;
    Gfx         *rdpCmds;       /* ptr (segment address) to RDP DL */
    Gfx         rdpOthermode;
} gtStateL_t;

typedef union {
    gtStateL_t          sp;
    long long int       force_structure_alignment;
} gtStateL;
\fP
.fi
.PP
The
.I gtStateL
version of the state structure can be used if a new matrix is not needed.
This is useful for larger objects which must be broken up among several
turbo objects (due to size or convex complexity). All of the pieces could
use the same transformation matrix, saving DRAM space and computational
time. See
.I GT_FLAG_NOMTX
below.
.PP
The
.I renderState
field is similar to the geometry mode in gbi.h, and is composed
of the following flags, or'd together:
.PP
.nf
.ta 5 28
	GT_ZBUFFER		turn on z-buffering.
	GT_TEXTURE		turn on texture mapping.
	GT_CULL_BACK		turn on backface triangle rejection.
	GT_SHADING_SMOOTH	perform smooth shading (as opposed to 
				flat (faceted) shading).
.fi
.PP
The
.I textureState
holds the texture tile number in the lower 3 bits of this field.
All primitives in an object are drawn with the same tile.
.PP
.I vtxCount
is the size of the vertex list.
.PP
.I vtxV0
load vertices starting at index v0 (0-63) in the vertex buffer.
.PP
.I triCount
is the size of the triangle list.
.PP
.I flags
a group of bits that control state processing. The flag
.I GT_FLAG_NOMTX
must be set when using the gtStateL structure; in this case
the matrix will not be loaded and the previous matrix will
be used to transform the points.
.PP
.I rdpCmds
points to a block of DP commands. If this pointer is non-NULL,
these commands are sent to the RDP. See the list below for
DP commands which should not be used in this command block.
This list must be terminated by a
.I gDPEndDisplay (3P)
command.
.PP
The
.I rdpOthermode
field contains a DP SetOtherMode command which is sent first
before any other DP commands.
.PP
.I transform
is the matrix to use to transform the vertices.
.PP

.SH TURBO VERTICES
The vertex list is an array of vertex structures, using the same
vertex format as in
.I gbi.h.
See
.I gSPVertex (3P)
for more details.
.PP
The vertex cache in the turbo ucode is 64 vertices. Vertices are
transformed when they are loaded.
.PP

.SH TURBO TRIANGLE LISTS
The triangle list is an array of these structures:
.PP
.nf
\f3#include "gt.h"
/*
 * This structure represents a single triangle, part of the
 * triangle list of the object to be rendered.
 *
 * NOTE: The triangle list MUST be aligned to an 8-byte boundary.
 * Since this structure is only 4 bytes, we are REQUIRING that
 * this structure only be used as an array of triangles, and we
 * depend on the MIPS C compiler (which always aligns arrays to
 * 8-byte boundaries). THIS IS DANGEROUS!!!!
 *
 */
typedef struct {
    u8    v0, v1, v2, flag; /* flag is which one for flat shade */
} gtTriN;
\fP
.fi
.PP
This array has a maximum of 64 triangles and must be aligned to an 
8-byte boundary.

.SH GBI
The turbo ucode uses a completely different display list format
and processing strategy; in that sense
.I none
of the GBI commands are supported.
.PP
However, blocks of DP commands are supported within the global and
object state. These commands are the same format (and use the
same macros) as in gbi.h. Some DP commands are not supported
because they either manipulate DP state that is irrelevant to
the turbo geometry or they interfere with the turbo display list
processing.
.PP
The following DP GBI commands are
.I not
supported with this microcode:
.nf
.ta 5 28
.sp
.I	gDPPipelineMode
.I	gDPSetCycleType
.I	gDPSetTexturePersp
.I	gDPSetTextureDetail
.I	gDPSetTextureLOD
.I	gDPSetTextureLUT
.I	gDPSetTextureFilter
.I	gDPSetTextureConvert
.I	gDPSetCombineKey
.I	gDPSetColorDither
.I	gDPSetAlphaDither
.I	gDPSetAlphaCompare
.I	gDPSetDepthSource
.I	gDPSetRenderMode
.fi
.PP
Many of these (those that make sense for the reduced feature set) can
be set using the 
.I gtStateSetOthermode (3P)
interface.

.SH PERFORMANCE
In order from fastest to slowest, the following types of triangles can
be generated by this ucode:
.PP
.nf
.ta 5 20
.I	Filled Flat Shaded
		(must set primitive color in DP appropriately)
.I	Gouraud Shaded
.I	Gouraud Shaded, Textured
.I	Gouraud Shaded, Z-buffered
.I	Gouraud Shaded, Textured, Z-buffered
.fi

.PP
Triangle attribute computation is heavily vectorized, so
generation of Gouraud shading attributes is essentially free,
if you are generating any other attributes.
.PP
Z-buffered triangles require a little additional processing.
.PP
Vertex transformations are heavily
vectorized, so it is best to operate on as many vertices
as possible. Vertices are processed in groups of four, so
loads that are a multiple of four would be the most efficient.
.PP
The RCP is designed to draw high-quality textured primitives.
Where possible, you should use texture-mapping to achieve visual
complexity rather than additional geometry.

.SH BUGS
None

.SH SEE ALSO
.IR gtStateSetOthermode (3P),
.IR gDPClearOtherMode (3P),
.IR gDPEndDisplayList (3P),
.IR gspFast3D (3P),
.IR gspLine3D (3P)