.TH gDPFillRectangle 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gDPFillRectangle, gsDPFillRectangle, gDPScisFillRectangle
\- render a solid color rectangle in screen coordinates
.SH C SPECIFICATION
.nf
\f3#include "gbi.h"

gDPFillRectangle(Gfx *gdl,
			unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry)

gsDPFillRectangle(unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry)

gDPiScisFillRectangle(Gfx *gdl,
			unsigned int ulx,
			unsigned int uly,
			unsigned int lrx,
			unsigned int lry)


\fP
.fi
.SH PARAMETERS
.TP 10
.I *gdl
graphics display list pointer.
.TP
.I ulx, uly
upper left screen coordinates for the rectangle. 10 bits of precision each.
These must be positive except for gSPScisTextureRectangle where they may be negative.
.TP
.I lrx, lry
lower right screen coordinates for the rectangle. 10 bits of precision each.
These must be positive except for gSPScisTextureRectangle where they may be negative.
.SH DESCRIPTION
This command draws a 2D rectangle with the current fill color in the blender.
The rectangle filled is inclusive of the coordinates specified when rendered in
.B fill
or
.B copy
mode.  For example, ulx=0 and lrx=19 will fill 20 columns of pixels in fill or 
copy mode. 
The rectangle does
.B not
include the bottom and right edges when rendered in
.B one 
or 
.B two cycle
mode.  For example, ulx=0 and lrx=19 will fill 19 columns in one or two cycle mode.
.PP
Copy mode is intended for rendering using the
.IR gSPTextureRectangle (3P)
command.  Rendering a 
.I gDPFillRectangle
in copy mode will have undefined results.  To set the cycle type see
.IR gDPSetCycleType (3P).   
.PP
This command is typically used for clearing the screen, initializing 
the color buffer or the depth (Z) buffer.
.SH NOTE
The screen coordinate (0,0) represents the upper left corner.
.PP
There are 10 bits of precision for each parameter.
Therefore, you cannot address a framebuffer with a dimension longer than 1024 pixels.
.PP
All screen coordinates are integer, you cannot address fractional
pixels.
.PP
If the cycle type is set to G_CYC_FILL then the rendering mode 
must not be set to zbuffer, even when clearing the depth
buffer. When clearing the depth buffer, we treat the area of memory as
if it were a color buffer, writing the appropriate pixel value into
memory.
.PP
If the cycle type is set to G_CYC_FILL 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_FILL 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 gDPFillRectangle
and gsDPFillRectangle macros cannot take negative arguments.  If the
corners of the rectangle may be to the left or above the top of the
screen (negative values) then use the gDPiScisFillRectangle macro.
This macro can only be used dynamically. There is no static version
(ie gsDPiScisFillRectangle does not exist).
.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 in the display list
(1 or 2 64-bit
words compared with dozens of words for complex triangles), it is
possible to fill the internal FIFO between RSP and 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 gDPSetFillColor (3P),
.IR gDPSetScissor (3P),
.IR gSPTextureRectangle (3P),
.IR gDPSetCycleType (3P)