Function
gSPObjRectangle
Draws a sprite
Syntax
#include <ultra64.h> /* gs2dex.h */
gSPObjRectangle(Gfx *gdl, uObjSprite *sp)
gsSPObjRectangle( uObjSprite *sp)Arguments
Description
Draws a non-rotating sprite. The data of the specified uObjSprite structure (see the Comment section below) is processed inside the RSP to create a TextureRectangle command which is sent to the RDP. For information about sprites, see "4.2 Sprite Drawing GBIs" in the latest version of the readme file of the S2DEX microcode.
Note
This macro can be used in 1-cycle and 2-cycle mode, and in copy mode. When it is used in copy mode, the drawing speed is faster than in the other modes. However, bilinear interpolation, subpixel processing and x-direction enlargement/reduction processing are not supported. (Operation is not guaranteed if these functions are used, and in the worst case, RDP runaway may occur.) You should use the proper mode that corresponds to the needed functions.
The result of drawing with this macro varies, depending on the use of bilinear interpolation and the other render mode settings. For details, refer to the "4.4. Object render mode settings" in the ReadMe file of the latest version of the S2DEX microcode. For information about modes, see Section 2.2.7, "Drawing Cycle Modes" in the N64 Introductory Manual. For information about setting the cycle type, see gDPSetCycleType.
Also, please note that operation is not currently guaranteed for G_IM_FMT_YUV (YUV format).
Comment
The uObjSprite structure is shown below:
typedef struct {
s16 objX; /* x-coordinate of upper-left corner of OBJ (s10.2) */
u16 scaleW; /* Width-direction scaling (u5.10) */
u16 imageW; /* Texture width (length in s direction, u10.5) */
u16 paddingX; /* Unused (always 0) */
s16 objY; /* y-coordinate of upper-left corner of OBJ (s10.2) */
u16 scaleH; /* Height-direction scaling (u5.10) */
u16 imageH; /* Texture height (length in t direction, u10.5) */
u16 paddingY; /* Unused (always 0) */
u16 imageStride; /* Texel wrapping width (In units of 64-bit words) */
u16 imageAdrs; /* Texture starting position in TMEM (In units of 64-bit words) */
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~7) */
u8 imageFlags; /* Display flag
(*) Multiple flags can be specified as the bit sum of the flags:
0 (Normal display (no inversion))
G_OBJ_FLAG_FLIPS (s-direction (x) inversion)
G_OBJ_FLAG_FLIPT (t-direction (y) inversion) */
} uObjSprite_t; /* 24 bytes */
typedef union {
uObjSprite_t s;
long long int force_structure_alignment;
} uObjSprite;
This macro draws a texture in the rectangular area with the upper-left corner screen coordinates (objX, objY) and the lower-right corner screen coordinates (objX+imageW/scaleW-1, objY+imageH/scaleH-1). (See the figure below.) The drawn texture region has its upper-left corner at (0, 0) and its lower-right corner at (imageW-1, imageH-1). When scaleW and scaleH are 1<<10, the texture will be drawn to the same proportions, without scaling.
GS_PIX2TMEM(u16 pix, u8 siz)
You can select the texture to be drawn by using the imageAdrs and imageStride specifications. To do this, load a number of small textures (sub-textures) in TMEM and set the following value for imageAdrs:
imageW = Sub-texture width
imageH = Sub-texture height
imageAdrs = GS_PIX2TMEM ((s-coordinate in TMEM) + (t-coordinate in TMEM) * (texture width at the time of loading, G_IM_SIZ_*))
imageStride = GS_PIX2TMEM (texture width at the time of loading, G_IM_SIZ_*)
To give a specific example, first prepare a large texture that combines four textures, like that shown in the figure below. Load this as a 64x32 texture, and when actually drawing a sprite, specify each texture as follows:
Sub-texture A:
imageW = 32;
imageH = 32;
imageAdrs = GS_PIX2TMEM(0+0*64, G_IM_SIZ_16b)
imageStride = GS_PIX2TMEM(64, G_IM_SIZ_16b);
Sub-texture B:
imageW = 16;
imageH = 16;
imageAdrs = GS_PIX2TMEM(32+0*64, G_IM_SIZ_16b)
imageStride = GS_PIX2TMEM(64, G_IM_SIZ_16b);
Sub-texture C:
imageW = 16;
imageH = 16;
imageAdrs = GS_PIX2TMEM(48+0*64, G_IM_SIZ_16b)
imageStride = GS_PIX2TMEM(64, G_IM_SIZ_16b);
Sub-texture D:
imageW = 32;
imageH = 16;
imageAdrs = GS_PIX2TMEM(32+16*64, G_IM_SIZ_16b)
imageStride = GS_PIX2TMEM(64, G_IM_SIZ_16b);
There is one restriction on this method of specification, however. Because the storage format for texture data in TMEM differs for odd-numbered lines and even-numbered lines, you cannot specify for imageAdrs a TMEM address that corresponds to an odd-number line when the texture was loaded. In other words, you cannot set an odd number for (t-coordinate in TMEM) in the imageAdrs calculation formula shown above.
| 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 | ||||
| IA | X (3/1) |
X (4/4) |
X (8/8) |
||
| I | X | ||||
This macro does not reference 2D matrix settings. For this reason, 2D matrix settings do not affect the drawing result of this macro. To reference 2D matrix settings and change the screen coordinate values for drawing, use g*SPObjRectangleR. Also, to rotate a sprite, use g*SPObjSprite.
See Also
gSPObjMatrix, gSPObjRectangleR, gSPObjSprite, and gSPObjSubMatrix
Revision History
02/01/99 Entirely revised.