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 Drive

Nintendo® Confidential

   

gDPScisFillRectangle

Format
#include "gbi.h"

gDPiScisFillRectangle(Gfx *gdl,
   unsigned int ulx,
   unsigned int uly,
   unsigned int lrx,
   unsigned int lry)
Arguments
  • gdl is the pointer to the graphics display list
  • ulx, uly are the upper-left screen coordinates for the rectangle with 10 bits of precision each. These must be positive for gDPFillRectangle but may be negative for gDPScisFillRectangle.
  • lrx, lryare the lower-right screen coordinates for the rectangle with 10 bits of precision each. These must be positive for gDPFillRectangle but may be negative for gDPScisFillRectangle.
What This Macro Does
These macros render a solid-color 2D rectangle using the current fill color in the blender. The filled rectangle is inclusive of the coordinates specified when rendered in fill or copy mode. For example, ulx=0 and lrx=19 will fill 20 columns of pixels in fill or copy mode. The rectangle does not include the bottom and right edges when rendered in one- or two-cycle mode. For example, ulx=0 and lrx=19 fill 19 columns in one- or two-cycle mode.

Copy mode is intended for rendering using the gSPTextureRectangle macro. Rendering a gDPFillRectangle in copy mode gives unpredictable results. To set the cycle type see gDPSetCycleType.

One of these macros is typically used to clear the screen and initialize the color buffer or the depth (Z) buffer.

Notes
Keep the following in mind when using these macros:
  • The screen coordinate (0,0) represents the upper left corner.
  • There are 10 bits of precision for each parameter. Therefore, you cannot address a framebuffer with a dimension longer than 1024 pixels.
  • All screen coordinates are integers, you cannot address fractional pixels.
  • If the cycle type is set to G_CYC_FILL, the rendering mode must not be set to Z-Buffer, even when clearing the depth buffer. When clearing the depth buffer, N64 treats the area of memory as if it were a color buffer, writing the appropriate pixel value into memory.
  • If the cycle type is set to G_CYC_FILL, 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.
  • When you render in one-cycle mode (G_CYC_1CYCLE) or two-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), use the gDPiScisFillRectangle macro. This macro can only be used dynamically. There is no static version (that is, gsDPiScisFillRectangle does not exist).
Performance Caution
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 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 that fill the entire screen cannot fit in the internal FIFO 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 commands (with several other commands or no-ops 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').

This situation is relatively contrived, and can be worked around, so it is possible to live with this restriction in order to retain the benefits of the non-asynchronous interruptability of the RCP.

See Also
gDPSetFillColor
gDPSetScissor
gSPTextureRectangle
gDPSetCycleType



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