.TH gspFast3D 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gspFast3D, gspFast3D.dram, gspFast3D.fifo, gspF3DNoN, gspF3DNoN.dram, gspF3DNoN.fifo
\- high-quality 3D polygonal geometry RSP microcode.

.SH DESCRIPTION
This is the optimized, full-featured 3D polygonal geometry RSP microcode.
It supports 3D clipping, lighting, texture-coordinate generation, fog,
a matrix stack, etc.
.PP
The
.I dram
version of the microcode directs the output (RDP display list) to
a memory (dram) buffer, instead of sending it to the RDP.
.PP
The
.I fifo
version of the microcode directs the output (RDP display list) to
the rdp through a memory buffer (dram) which is bigger than the buffer
used in the gspFast3D microcode (generally more efficient).
.PP
The 
.I gspFast3D, gspFast3D.dram, 
and
.I gspFast3D.fifo
versions of the microcode are equivalent to the 
.I gspF3DNoN, gspF3DNoN.dram, 
and
.I gspF3DNoN.fifo
versions (respectively) with the difference that near clipping is performed
at the near clipping plane in the former 3 versions, and performed at the
eyepoint in the latter 3 versions. (See the Notes On Near Clipping below.)
.PP
All computations are performed with as much precision as is practical,
in order to create the highest quality images.

.SH GBI
The following GBI commands are
.I not
supported with this microcode:
.nf
.ta 5 28
.sp
.I	gSPLine3D
.fi
.PP
All
.I gSPLine3D
commands are turned into noops and swallowed harmlessly.

.SH PERFORMANCE
In order from fastest to slowest, the following types of triangles can
be generated by this ucode:
.nf
.ta 5 20
.I	Filled Flat Shaded
		(must set primitive color in DP appropriately)
.I	Gouraud Shaded
.I	Gouraud Shaded, Z-buffered
.I	Gouraud Shaded, Textured
.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
Vertex transformations and lighting calculations are heavily
vectorized, so it is best to operate on as many vertices
as possible. Even number-sized loads are more efficient
because vertices are processed in groups of two.
.PP
If you are doing lighting, and any vertices are clipped,
clipping and lighting are implemented as ucode overlays, using a 
most recently used algorithm. Since lighting happens at vertex load
time, and clipping happens at triangle draw time, this division of
ucode is acceptable. However, a display list which loads only a
few vertices at a time, then draws a small number of triangles,
would not amortize the ucode swapping overhead very effectively.
.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 NOTES ON DIFFERENT VERSIONS
There are some differences in invoking the dram and fifo versions of the
microcode:
.PP
.I gspFast3D:
the flags field of any task following this task should have 
.I OS_TASK_DP_WAIT 
set.  If more than one task using this microcode is invoked in the same frame then only the last task should contain a 
.I gSPFullSync
in its display list.  This microcode takes care of sending all its output
to the RDP.  If you use this microcode you do not need to specify an 
.I output_buff
or an
.I output_buff_size
(you can use 0 in these fields of the task header).
.PP
.I gspFast3D.dram:
Tasks using this microcode need to set the 
.I OS_TASK_DP_WAIT 
flag *ONLY* if they follow a task using gspFast3D or gspFast3D.fifo.  This
microcode sends its data to a buffer in dram and NOT to the RDP.
The CPU must then cause the buffer to be sent to the RDP.  The buffer
is pointed to by 
.I output_buff
in the task header.  This must point to a buffer which is at least as big
as the maximum RDP display list that can be generated by the task.  Remember
that when geometry gets clipped RDP display lists will expand, so leave
extra room.  If the buffer is not big enough to hold all the RDP display list
then other parts of memory will be overwritten!  When the RSP has completed
you can send the buffer to the RSP using the 
.I osDpSetNextBuffer 
command.  The length of the data in the buffer (needed for the 
.I osDpSetNextBuffer 
command) is written to the address pointed to by 
.I rdp_output_len 
in the task header.  While the display list is being sent to the RDP
another RSP task using .dram microcode (and a different output_buff) or an
audio task may be run.  If the display list sent to the RDP does not contain
any 
.I gDPFullSync 
then another RDP display list (in another buffer, eg from
another RSP task) may be sent using another 
.I osDpSetNextBuffer 
command.  However, if the display list contains a 
.I gDPFullSync 
then do not send another RDP display list using 
.I osDpSetNextBuffer 
or begin a gspFast3D or gspFast3D.fifo task until the display list is finished.
.PP
.I gspFast3D.fifo:
Tasks using this microcode should set the
.I OS_TASK_DP_WAIT 
flag ONLY if following a gspFast3D task or a osDpSetNextBuffer command.
This micorocode takes care of sending the RDP display list to the RDP.  It uses
a buffer which is pointed to by
.I output_buff
in the task header.  This buffer should be cache aligned (eg put it in its own 
.c file) and can be almost any length (an absolute minimum of 0x180 bytes is 
reccommended).  The 
.I output_buff_size
must be a *Pointer* to the byte following the last byte in the buffer.  The
larger the buffer, the more efficient the interface between the RSP and the RDP
will be.  If you string multiple tasks using .fifo microcode together, put a
.I gDPFullSync
ONLY in the LAST task of the frame.  When you string multiple tasks using the
.fifo microcode use the same output_buff buffer for all the tasks (you could 
use a separate buffer for each task but it is much more efficient to use 1 big
buffer for all the tasks).

.SH NOTES ON NEAR CLIPPING 
Near clipping removes geometry which is behind the viewer or between the
viewer and the near clipping plane.  Because in real life objects do not 
dissappear when they get close to a viewer's eye it is important to keep 
this case from occuring on the Ultra64.  One way to do this is to make the
near plane very close to the eye (small values of
.I near
in the
.I guPerspective
call).  This does not always work well beacuse Z precision and 
texture mapping accuracy get worse as the near/far ratio gets smaller.
Another solution is to use the 
.I gspF3DNoN 
microcode (or its .dram/.fifo equivalent) which performs near clipping 
differently.  Objects which are behind the viewer are still clipped away
and objects farther than the near plane are still visible, but objects
between the near plane and the viewer are also visible.  This allows 
you to increase your 
.I near 
value without losing geometry which falls between the eye and the near plane.
There is a catch, of course:  Z buffering does not work in the area between
the eye and the near plane. Therefore objects between the near plane and the
viewer will not obscure each other correctly.  For example, in an asteroids
type game one asteroid can come closer to the eye than the near plane
and it will be drawn correclty (obscuring objects which are farther than 
the near plane); but if 2 asteroids are both closer than the near plane then 
they will not 
correctly obscure each other.



.SH DEFAULT RDP STATE
Everytime a graphics task is initially started, some of
the RDP state is initialized to a default state.
The remaining state settings retain their previous values.
After restarting from a yield, the RDP state is restored to the state set at
the time of the yield.
Here is the list of the default RDP settings:
.nf
.ta 5 20
.B	
.B	gsDPSetAlphaCompare(G_AC_NONE)
.B	gsDPSetDepthSource(G_ZS_PIXEL)
.B	gsDPSetRenderMode(RM_NOOP,RM_NOOP2)
.B	gsDPSetAlphaDither(G_AD_DISABLE)
.B	gsDPSetColorDither(G_CD_DISABLE)
.B	gsDPSetCombineKey(G_CK_NONE)
.B	gsDPSetTextureConvert(G_TC_FILT)
.B	gsDPSetTextureFilter(G_TF_POINT)
.B	gsDPSetTextureLUT(G_TT_NONE)
.B	gsDPSetTextureLOD(G_TL_TILE)
.B	gsDPSetTextureDetail(G_TD_CLAMP)
.B	gsDPSetTexturePersp(G_TP_PERSP)
.B	gsDPSetCycleType(G_CYC_1CYCLE)
.B	gsDPPipelineMode(G_PM_NPRIMITIVE)
.fi

.SH BUGS
None outstanding.

.SH SEE ALSO
.IR gspLine3D (3P),
.IR gspTurbo3D (3P)
.IR osSpTaskStart (3P)