 N64® Functions Menu |
al - Audio Library Functions gDP - DP GBI Macros gdSP - General GBI Macros gSP - SP GBI Macros gt - Turbo Microcode RDP gu - Graphics Utilities Math - Math Functions nuSys - NuSystem os - N64 Operating System sp - Sprite Library Functions uh - Host to Target IO 64DD - N64 Disk DriveNintendo® Confidential |
|
|
|
|
|
gSPScisTextureRectangle
Format#include "gbi.h" 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)Arguments
- gdl is the pointer to the graphics display list
- ulx, uly specify the upper-left screen coordinates for the rectangle with fixed-point format 10.2 (10 integer, 2 fractional bits) each. These must be positive except for gSPScisTextureRectangle
- where they can be negative
- lrx, lry specify the lower-right screen coordinates for the rectangle with fixed-point format 10.2 each. These must be positive except for gSPScisTextureRectangle where they can be negative
- tile is the texture tile number that selects one of 8 texture tiles descriptors in the RDP
- s, t specify the texture coordinates of the upper-left corner of the rectangle (S10.5 format)
- dsdx, dtdy specify the change in s,t per the change in x,y (S5.10 format)
gSPTextureRectangle and gSPScisTextureRectangle both draw a textured 2D rectangle. Then you can call the gDPFillRectangle macro to fill rectangles with a solid color. The rectangle drawn is inclusive of the coordinates specified in copy mode. In 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.
The gSPTextureRectangleFlip macro flips the texture so that the s coordinate changes in the y direction and the t coordinate changes in the x direction.
Notes
The screen coordinate (0,0) represents the upper left corner.
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.
When using a texture rectangle in COPY mode, the two fractional bits of the x, y coordinates are ignored because in COPY mode, there is a one-to-one correspondence of texels to pixels. Also, in copy mode the dsdx should be set to (4 << 10). This is because in copy mode, four 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 usually set to step one texel per pixel (1<<10). See the Restrictions section of the Texture Mapping chapter of the N64 Programming Manual for more information on legal texture types while in copy mode. To guarantee that texels are stepped correctly, turn off texture perspective by calling the gDPSetTexturePersp macro when rendering textured rectangles.
If the cycle type is set to G_CYC_COPY, the rendering mode must not be set to Z-Buffer.
Also if the cycle type is set to G_CYC_COPY, the scissor rectangle will not correctly scissor rectangles (it will scissor to multiples of four pixels only). Therefore, the scissor rectangle must be larger than or equal to the rectangle filled when rendering in G_CYC_COPY mode.
When rendering in one-cycle mode (G_CYC_1CYCLE) or two-cycle mode (G_CYC_2CYCLE) the scissor rectangle will correctly scissor the rectangle. However only the gSPScisTextureRectangle macro can take negative arguments. If the corners of the rectangle may be to the left or above the top of the screen (negative values), use the gSPScisTextureRectangle macro, which can only be used dynamically. There is no static version (that is, gsSPScisTextureRectangle does not exist)
Performance
There is an unusual restriction regarding rectangles. Primitives that 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 that fill the entire screen cannot fit in the internal FIFO's in large enough quantity to lock out the CPU and the RSP.
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 consecutive full-screen rectangle primitives to the RDP. Non-full-screen rectangles, or non-consecutive rectangle macros (with several other macros or no-ops in between) will be fine, assuming the entire frame-rendering time does not exceed 1/60th of a second, and your scheduling algorithm can handle this case (such as 'yield').
This situation is relatively contrived, and you can work around it, so Nintendo believes this restriction is acceptable in order to have the benefits of the non-asynchronous interruptability of the RCP.
See Also
gSPTextureRectangle
gSPTextureRectangleFlip
gDPFillRectangle
gDPSetScissor
gDPSetTexturePersp
|
|
|
|
|
|
|
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
 |
|
|
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 January 1998 |