.TH gspSuper3D 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gspSuper3D, gspSuper3D.dram, gspSuper3D.fifo
\- accelerated 3D polygonal geometry RSP microcode.

.SH DESCRIPTION
This is an optimized, reduced-featured 3D polygonal geometry RSP microcode.
It supports 3D clipping, lighting, texture-coordinate generation, fog,
a matrix stack, etc.
.PP
This version of the microcode combines some of the optimizations
of 
.I gspTurbo3D
with the regular
.I gspFast3D.
This allows for an increased performance with the same display
list format as
.I gspFast3D.
.PP
The specific optimizations performed include reduced precision in the
edge slope and attribute calculations, and no perspective-correction
of the texture coordinates.
.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 gspSuper3D microcode (generally more efficient).
.PP

.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 and pipelined, so
generation of any attribute 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 gspSuper3D:
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 gspSuper3D.dram:
Tasks using this microcode need to set the 
.I OS_TASK_DP_WAIT 
flag *ONLY* if they follow a task using gspSuper3D or gspSuper3D.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 gspSuper3D or gspSuper3D.fifo task until the display list is finished.
.PP
.I gspSuper3D.fifo:
Tasks using this microcode should set the
.I OS_TASK_DP_WAIT 
flag ONLY if following a gspSuper3D 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 0x100 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 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 gspFast3D (3P),
.IR gspTurbo3D (3P)
.IR gspLine3D (3P),
.IR osSpTaskStart (3P)