Function
Renders background image (BG)
Syntax
#include <ultra64.h> /* gs2dex.h */
gSPBgRectCopy(Gfx *gdl, uObjBg *bg)
gsSPBgRectCopy( uObjBg *bg)
Arguments
Description
This macro is the dedicated BG image drawing macro for use in copy mode. It has the following special features and limitations:
The greatest advantage of this macro is that it offers the fastest drawing speed, since it assumes that drawing is being performed in copy mode. Accordingly, in order to use this macro the cycle type must be copy mode. For information about modes, see Section 2.2.7, "Drawing Cycle Modes" in the N64 Kantan Manual. For information about setting the cycle type, see gDPSetCycleType. If you want to enlarge or reduce an image, use gSPBgRect1Cyc. For additional details, please see the latest readme for S2DEX microcode Section 4.1, "BG Drawing GBIs".
Note
It is allowable for the BG image to be larger than the transfer frame. However, operation cannot be guaranteed if the transfer frame is larger than the BG image. Make sure that the transfer frame is not larger than the BG image.
The right and left ends of the BG image are connected in the y-direction with a one-step shift. That is, the pixel to the right of the right-edge pixel (imageW-1, n) of the BG image becomes (0, n+1). This is necessary to boost RDRAM access efficiency when loading a texture. For information about the uObjBg structure, see the Comment section below.
Also note that operation is not currently guaranteed for G_IM_FMT_YUV (YUV format).
Comment
The uObjBg structure is shown below:
typedef struct { u16 imageX; /* x-coordinate of upper-left position of texture (u10.5) */ u16 imageW; /* Texture width (8-byte alignment, u10.2) */ s16 frameX; /* x-coordinate of upper-left position of transfer destination frame (s10.2) */ u16 frameW; /* Transfer destination frame width (u10.2) */ u16 imageY; /* y-coordinate of upper-left position of texture (u10.5) */ u16 imageH; /* Texture height (u10.2) */ s16 frameY; /* y-coordinate of upper-left position of transfer destination frame (s10.2) */ u16 frameH; /* Transfer destination frame height (u10.2) */ u64 *imagePtr; /* Address of texture source in DRAM */ u16 imageLoad; /* Method for loading the BG image texture G_BGLT_LOADBLOCK (use LoadBlock) G_BGLT_LOADTILE (use LoadTile) */ u8 imageFmt; /* Texel format G_IM_FMT_RGBA (RGBA format) G_IM_FMT_YUV (YUV format) G_IM_FMT_CI (CI format) G_IM_FMT_IA (IA format) G_IM_FMT_I (I format) */ u8 imageSiz; /* Texel size G_IM_SIZ_4b (4 bits/texel) G_IM_SIZ_8b (8 bits/texel) G_IM_SIZ_16b (16 bits/texel) G_IM_SIZ_32b (32 bits/texel) */ u16 imagePal; /* Position of palette for 4-bit color index texture (4-bit precision, 0~15) */ u16 imageFlip; /* Image inversion on/off (horizontal direction only) 0 (normal display (no inversion)) G_BG_FLAG_FLIPS (horizontal inversion of texture image) */ /* The following is set in the initialization routine guS2DInitBg */ u16 tmemW; /* TMEM width for one frame line (word size) u16 tmemH; /* TMEM height for a single load (quadruple value, s13.2) u16 tmemLoadSH; /* SH value u16 tmemLoadTH; /* TH value or Stride value u16 tmemSizeW; /* imagePtr skip value for one image line u16 tmemSize; /* imagePtr skip value for a single load */ } uObjBg_t; /* 40 bytes */ typedef union { uObjBg_t b; uObjScaleBg_t s; long long int force_structure_alignment; } uObjBg;
The BG function in the S2DEX microcode transfers data from the BG image buffer to the actual rectangular area in the frame buffer (see the figure below). You can scroll by using imageX, imageY to specify which position in the BG image buffer corresponds to the upper-left corner of the rectangular area in the frame buffer at the time (the transfer frame). imageX, imageY can be specified in u10.5 format, but note that the values are rounded to integer values due to copy mode restrictions.
The size of the BG image is set by imageW, imageH. The starting address (address of the upper-left corner) is specified by imagePtr. In other words, the BG image can be regarded as texture data that starts at address imagePtr and is imageW wide and imageH tall.
The size of the transfer frame is specified by frameW, frameH and the position on the screen of the upper-left corner of the transfer frame is specified by frameX, frameY. These latter two values (frameX, frameY) can take negative numbers. If the transfer frame protrudes from the scissor box specified by g*DPSetScissor, the microcode will clip the protruding portion.
imageSizvalue | imageWrestriction |
G_IM_SIZ_4b | Multiple of 64 |
G_IM_SIZ_8b | Multiple of 32 |
G_IM_SIZ_16b | Multiple of 16 |
G_IM_SIZ_32b | Multiple of 8 |
imageSizvalue | imageWvalue |
G_IM_SIZ_4b | frameW+64 <= imageW |
G_IM_SIZ_8b | frameW+32 <= imageW |
G_IM_SIZ_16b | frameW+16 <= imageW |
G_IM_SIZ_32b | frameW+ 8 <= imageW |
G_IM_SIZ_ (size) | |||||
4b | 8b | 16b | 32b | ||
G_IM_FMT_ (format) |
RGBA | X (5/5/5/1) |
X (8/8/8/8) |
||
YUV | X | ||||
CI | X | X | |||
IA | X (3/1) |
X (4/4) |
X (8/8) |
||
I | X | X | |
4, 8, 12, 16, 20, 24, 28, 32, 36, 40, 48, 64, 72, 76, 100, 108, 128, 144, 152, 164, 200, 216, 228, 256, 304, 328, 432, 456, 512, 684, 820, 912
See Also
Revision History
02/01/99 Entirely revised.