.TH gSPTextureRectangle 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gSPTextureRectangle, gsSPTextureRectangle,
gSPTextureRectangleFlip, gsSPTextureRectangleFlip,
gSPScisTextureRectangle
\- render a textured rectangle in screen coordinates (sprite)
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gSPTextureRectangle(Gfx *gdl,
			unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry,
			int tile, int s, int t,
			int dsdx, int dtdy)

gsSPTextureRectangle(unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry,
			int tile, int s, int t,
			int dsdx, int dtdy)

gSPTextureRectangleFlip(Gfx *gdl,
			unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry,
			int tile, int s, int t,
			int dsdx, int dtdy)

gsSPTextureRectangleFlip(unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry,
			int tile, int s, int t,
			int dsdx, int dtdy)

gSPScisTextureRectangle(Gfx *gdl,
			unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry,
			int tile, int s, int t,
			int dsdx, int dtdy)

\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I ulx, uly
upper left screen coordinates for the rectangle. fixed point format 10.2
(10 integer, 2 fractional bits) each.  These must be positive except for
gSPScisTextureRectangle(3P) where they may be negative.
.TP
.I lrx, lry
lower right screen coordinates for the rectangle. fixed point format 10.2 each.
These must be positive except for gSPScisTextureRectangle(3P) where they may be negative.
.TP
.I tile
texture tile number. Selects one of 8 texture tiles descriptors in the RDP.
.TP
.I s, t
the texture coordinates of the upper-left corner of the rectangle 
(S10.5 format).
.TP
.I dsdx, dtdy
change in s,t per change in x,y (S5.10 format).
.SH DESCRIPTION
This command draws a textured 2D rectangle.  Another command, 
.I gDPFillRectangle (3P)
is used to fill rectangles with a solid color.
The rectangle drawn is inclusive of the coordinates specified in
.B copy mode.
In
.B one-cycle or two-cycle mode,
the rectangle is drawn exclusive of the bottom and right edges in order
to provide proper anti-aliasing in these modes.
For example, ulx=(0<<2) and lrx=(19<<2) will fill 20 columns of pixels in
copy mode, but only 19 columns in one- or two-cycle mode.
.PP
The
.I gSPTextureRectangleFlip (3P)
command flips the texture so that the
.B s
coordinate changes in the y direction and the
.B t
coordinate changes in the x direction.
.SH NOTE
The screen coordinate (0,0) represents the upper left corner.
.PP
There are 10 integer and 2 fractional bits of precision for each x,y 
parameter.  Therefore, you cannot address a framebuffer bigger than 1024 
in either axis.
.PP
When using a texture rectangle in COPY mode, the 2 fractional bits of
the x, y coordinates are ignored because in COPY mode, there is a one-to-one
correspondance of texels to pixels.  Also, in copy mode the dsdx should be
set to (4 << 10).  This is because in copy mode, 4 horizontally adjacent texels
are copied every clock.  While it is legal to enlarge a copied image in the
t direction (make dtdy < (1<<10)), dtdy is normally set to step one texel per
pixel (1<<10).  See the
.B Restrictions
section of the 
.B Texture Mapping 
chapter of the
.I NU64 Programming Manual
for more information on legal texture types while in copy mode.  In order to
guarantee that texels are stepped correctly, texture perspective should be
turned off using the
.I gDPSetTexturePersp (3P)
command when rendering textured rectangles.

.PP
If the cycle type is set to G_CYC_COPY then the rendering
mode must not be set to zbuffer.
.PP
Also if the cycle type is set to G_CYC_COPY then the scissor
rectangle will not correctly scissor rectangles (it will scissor
to multiples of four pixels).  Therefore, the scissor rectangle 
must be larger than or equal to the rectangle filled when rendering 
in G_CYC_COPY mode.
.PP
When rendering in one cycle mode (G_CYC_1CYCLE) or 2 cycle mode (G_CYC_2CYCLE)
the scissor rectangle will correctly scissor the rectangle.  However the
macros do not take negative arguments with the exception of the 
gSPScisTextureRectangle(3P) macro.  If the corners of the rectangle may be
to the left or above the top of the screen (negative values)
then use the gSPScisTextureRectangle(3P) macro.  This macro can
only be used dynamically. There is no static version (ie
gsSPScisTextureRectangle does not exist)
.PP
.SH PERFORMANCE
There is an unusual restriction regarding rectangles. Primitives which
fill the entire screen obviously take maximum time in the RDP to
render. Because rectangle primitives are so compact (1 or 2 64-bit
words compared with dozens of words for complex triangles), it is
possible to fill the internal FIFO of the RDP with a series of
primitives that will take a very long time to render. While the RDP is
busy rendering these primitives, the RSP and CPU will not be able to
get the attention of the RDP to request a freeze or a yield in order
to process any higher priority tasks (such as audio) at vertical
retrace time. This can only happen with rectangles; triangles which
fill the entire screen cannot fit in the internal FIFO's in large
enough quantity to lock out the CPU and the RSP.
.PP
In a practical sense, if you are using a typical frame scheduling
algorithm that processes audio every vertical retrace (1/60) of
a second, you should not send more than 8 or 9
.I consecutive
full-screen rectangle primitives to the RDP. Non-full-screen rectangles,
or non-consecutive rectangle commands (with several other commands
or noops in between) will be fine, assuming the entire frame rendering
time does not exceed 1/60th of a second, and/or your scheduling algorithm
can handle this case (such as 'yield').
.PP
This situation is relatively contrived, and can be worked around, so
it is judged to be acceptable to live with this restriction in order
to achieve the benefits of the non-asynchronous interruptability of
the RCP.
.SH SEE ALSO
.IR gDPFillRectangle (3P),
.IR gDPSetScissor (3P),
.IR gDPSetTexturePersp (3P)