gDPFillRectangle [Macro]

Function

gDPFillRectangle

Renders a solid-color rectangle in the screen coordinates

Syntax

#include <ultra64.h>        /* gbi.h */
gDPFillRectangle(Gfx *gdl, s32 ulx, s32 uly, s32 lrx, s32 lry)
gsDPFillRectangle(         s32 ulx, s32 uly, s32 lrx, s32 lry)

Arguments

gdl: Display list pointer
ulx: Left edge coordinates of rectangle (10-bit precision, 0~1023)
uly: Top edge coordinates of rectangle (10-bit precision, 0~1023)
lrx: Right edge coordinates of rectangle (10-bit precision, 0~1023)
lry: Bottom edge coordinates of rectangle (10-bit precision, 0~1023)

Description

Renders a 2D rectangle using the fill color set in the blender (BL) in the RDP. When this rectangle is rendered in fill mode, the specified coordinates are included. When it is rendered in 1-cycle or 2-cycle mode, the bottom edge and right edge are not included.

For example, when ulx=0 and lrx=19, 20 columns of pixels will be filled in fill mode and 19 columns of pixels will be filled in 1-cycle or 2-cycle mode.

For information about each mode, see Section 2-7 "Rendering Cycle Modes" in Step 2 of the N64 Introductory Manual. For information about setting the fill color, see gDPSetFillColor, and for information about setting the cycle type, see gDPSetCycleType.

This command can also be used to clear the screen, and to initialize the color frame buffer or the Z buffer.

Note

The screen coordinates (0,0) indicate the upper-left corner of the screen. Since each coordinate has 10-bit precision, you cannot specify a value greater than 1023. Also, since all specifications are integers, you cannot address sub-pixels (a portion of a pixel). Since coordinates cannot take negative values, use gDPScisFillRectangle if there is a chance a negative value might be generated for a screen coordinate.

The following restrictions apply to each mode:

(Copy mode)
	Operation cannot be guaranteed if gDPFillRectangle is used for rendering. Use the gSPTextureRectangle command.
(1-cycle and 2-cycle mode)
	Since the bottom and right edges are not included, one column is missing.
(Copy mode)
	When using this macro to clear the Z buffer, do not set a rendering mode for the Z buffer (see gDPSetRenderMode). When the Z buffer is cleared, the memory area is treated as a color frame buffer, and an appropriate pixel value is written in memory.

Comment

There is a performance-related restriction on the drawing of rectangles. The RDP requires the most drawing time when primitives are being rendered to fill the entire screen. Because the display list of a rectangle is extremely compact, the FIFO between the RSP and RDP can become filled with a consecutive series of rectangle primitives, which will take a long time to render. Although the RSP and CPU will issue instructions to stop or yield the RDP in order to execute high-priority tasks (such as audio tasks) during a vertical retrace, the RDP cannot accept these requests while these consecutive rectangle primitives are being rendered. This only occurs for rectangles, since triangles that fill the entire screen cannot fill the FIFO with a large enough number of primitives to lock-out the CPU and RSP.

When a standard frame-scheduling algorithm is used such as for audio processing during the vertical retrace at every 1/60 of a second, do not send more than eight or nine consecutive full-screen rectangles to the RDP. Non-full-screen rectangles or non-consecutive rectangle commands (another command or a NOOP is inserted between them) do not present a problem. Also, if every frame rendering interval does not exceed 1/60 of a second, the scheduling algorithm is processed in a similar manner as yield.

Revision History

02/01/99 Completely rewritten