gSPObjSprite [macro]

Draws a rotating sprite.

Syntax

#include <ultra64.h> /* gs2dex.h */
gSPObjSprite(Gfx *gdl, uObjSprite *sp)
gsSPObjSprite(uObjSprite *sp)

Arguments

• gdl is the pointer to the graphics display list.

• sp is the pointer to the sprite-drawing data structure.

Explanation
References the 2D matrix elements A, B, C, D, X and Y, and draws a rotating sprite. This 2D matrix is set using g*SPObjMatrix.

Notes
When a non-rotating sprite is enlarged, the drawing result may differ slightly from the drawing result of g*SPObjRectangle. This is unavoidable because the drawing methods differ (sticking polygons together is different from drawing rectangles).

Cautions
The uObjMtx structure is shown below. For information about the uObjSprite structure, see g*SPObjRectangle and also refer to the Readme file of the latest version of the S2DEX microcode.

typedef struct {
  s32 A, B, C, D;  /* s15.16 */
  s16 X, Y;        /* s10.2 */
  u16 BaseScaleX;  /* u5.10 */
  u16 BaseScaleY;  /* u5.10 */
} uObjMtx_t;
typedef union {
  uObjMtx_t      m;
  long long int  force_structure_alignment;
} uObjMtx;

2D matrix multiplication moves the point x, y to the location x', y' on a sprite when it is not rotating, as shown below:

Each vertex of the sprite is also moved by this process, and the sprite is drawn in the rectangular area according to the moved vertices. If the rotation matrix is set as follows for the 2D matrix elements A, B, C and D, the sprite will rotate by T.

The sprite will rotate around an origin at the screen coordinates X, Y. To add scaling, multiply each term A, B, C and D by the scaling factor.

The position that corresponds to the sprite's center of rotation (X, Y) is specified by the values of the objX and objY members of the uObjSprite structure. When objX = objY = 0, the sprite rotates around the position that its upper-left vertex takes when the sprite is not rotating. To rotate the sprite around its central axis, set objX and objY as follows:

objX = - (imageW / scaleW) / 2;
objY = - (imageH / scaleH) / 2;

A number of sprites can be rotated together as a single unit by adjusting the objX and objY values in the same manner described for g*SPObjRectangleR. Gaps that appear due to calculation errors can be suppressed by drawing the sprites slightly overlapping, as was described for g*SPObjRectangleR.

For information on setting textures to be placed on sprites, see g*SPObjRectangle.

When a sprite is not rotating (A = D = 1.0, B = C = 0.0), its position is the same as the drawing region of g*SPObjRectangleR when BaseScaleX = BaseScaleY = 1.0. So when a sprite is to be rotated at certain times and not rotated at other times, we recommend switching between the two macros, drawing the sprite with g*SPObjRectangle when it is not rotating, and drawing it with g*SPObjSprite when it is rotating. This is because g*SPObjSprite, which draws a sprite by combining two polygons, makes heavier processing demands on both the RSP and RDP than g*SPObjRectangleR.

See Also
gSPObjMatrix
gSPObjRectangle
gSPObjRectangleR