gSPTextureRectangle

#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)

• gdl is the display list pointer.

• ulx is the x-coordinate of upper-left corner of rectangle (10.2, 0.0~1023.75)

• uly is the y-coordinate of upper-left corner of rectangle (10.2, 0.0~1023.75)

• lrx is the x-coordinate of lower-right corner of rectangle (10.2, 0.0~1023.75)

• lry is the y-coordinate of lower-right corner of rectangle (10.2, 0.0~1023.75)

• tile is the tile descriptor index (3-bit precision, 0 - 7)

• s is the texture coordinate s of upper-left corner of rectangle (s10.5)

• t is the texture coordinate t of upper-left corner of rectangle (s10.5)

• dsdx is the change in s for each change in x (s5.10)

• dtdy is the change in t for each change in y (s5.10)

Explanation
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 Kantan 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.

Comments
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
gSPTextureRectangleFlip

Revision History
2/1/1999 Completely rewritten.

Nintendo® Confidential Warning: all information in this document is confidential and covered by a non-disclosure agreement. You are responsible for keeping this information confidential and protected. Nintendo will vigorously enforce this responsibility. Copyright © 1998 Nintendo of America Inc. All rights reserved Nintendo and N64 are registered trademarks of Nintendo Last updated March 1999