Function
gSPTextureRectangle
Renders a textured 2D rectangle
Syntax
#include <ultra64.h> /* gbi.h */
gSPTextureRectangle(
Gfx *gdl,
u32 ulx,
u32 uly,
u32 lrx,
u32 lry,
s32 tile,
s32 s,
s32 t,
s32 dsdx,
s32 dtdy)
gsSPTextureRectangle(
u32 ulx,
u32 uly,
u32 lrx,
u32 lry,
s32 tile,
s32 s,
s32 t,
s32 dsdx,
s32 dtdy)Arguments
Description
gSPTextureRectangle draws a textured 2D rectangle. When the rectangle is drawn in copy mode, the specified coordinates are included. When it is drawn in 1-cycle mode or 2-cycle mode, the lower edge and right-side edge are not included because anti-aliasing is performed as appropriate.
For example, when ulx=(0<<2) and lrx=(9<<2) 10 columns of pixels will be filled in copy mode and 9 columns of pixels will be filled in 1-cycle mode or 2-cycle mode.
For details, please see Section 11.9.3, "Rectangles" in the N64 Online Programming Manual. See also, Section 14.2, "Simple Texture Effects" for examples of other effects. For information about each mode, see Section 2-7, "Rendering Cycle Modes" in Step 2 of the N64 Introductory Manual. To read how to set the cycle type, see gDPSetCycleType. To read about tile descriptors, see gDPSetTile and Section 13.5, "Tile Descriptor Loading" in the N64 Online Programming Manual.
Note
The screen coordinates (0,0) indicate the upper left corner of the screen. Because each coordinate (ulx, uly, lrx, lry) has 10-bit precision for the integer part and 2-bit precision for the fractional part, you cannot address a frame buffer larger than 1024 pixels square. Also, since coordinates cannot take negative values, use gSPScisTextureRectangle if there is a chance a negative value might be generated for a screen coordinate.
In copy mode, there is a 1:1 correspondence between texels and pixels, so when you use texture rendering, the two fractional bits of the x,y coordinates are ignored. Moreover, because four horizontally adjacent texels are copied in each clock tick, make sure to set dsdx to (4<<10). When the copied image can be expanded in the t direction (dtdy < (1<<10)), dtdy is set to (1<<10) so 1 texel is attached for each pixel. Finally, rendering modes using Z buffering cannot be used in copy mode. To learn which texture types are appropriate for copy mode, see Section 13.11, "Restrictions" in the N64 Online Programming Manual.
To ensure that textures are attached appropriately when texture rectangles are being drawn, disable perspective correction in texture sampling mode using gDPSetTexturePersp.
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.
See Also
gDPFillRectangle, gDPSetScissor, gDPSetTexturePersp, gSPScisTextureRectangle, and gSPTextureRectangleFlip
Revision History
02/01/99 Completely rewritten.