Commands

• guSprite2DInit initializes a specified a sprite structure.It allows the application to be run without directly initializing the sprite structure.
• gSPSprite2DBase sends the sprite microcode to the sprite structure to start actual processing. It initializes the common sprite parameters. It does not perform actual screen drawing.
• gSPSprite2DScaleFlip is used to specify the X/Y scaling and/or flipping parameters for a sprite. It does not perform actual screen drawing.
• gSPSprite2DDraw specifies the screen coordinates where the sprite is to be drawn, and starts actual screen drawing using the parameters specified by gSPSprite2DBase and gSPSprite2DScaleFlip.

Simple Code for Displaying a Sprite

#include "gu.h"

#include "gbi.h"
     uSprite MySprite;
     guSprite2DInit(Mysprite, ImagePointer,
        TlutPointer, ImageWidth,
        RectangleWidth, RetangleHeight, 
        ImageType, ImageSize, 
        TextureStartS, TextureStartT);

gSPSprite2DBase(glistp++,
    OS_K0_TO_PHYSICAL(MySprite));

gSPSprite2DScaleFlip (glistp++, ScaleX, ScaleY, 
   FlipTextureX, FlipTextureY); 

gSPSprite2DDraw (glistp++, PScreenX, PScreenY)

typedef struct {
     void *SourceImagePointer;
     void *TlutPointer;
     short Stride;
     short SubImageWidth;
     short SubImageHeight;
     char  SourceImageType;
     char  SourceImageBitSize;
     short SourceImageOffsetS;
     short SourceImageOffsetT;
   /* 20 bytes for above */
 
   /* padding to bring structure size to
      64-bit alignment */;
     char dummy[4];
 
} uSprite_t;
 
typedef union {
     uSprite_t  s;
    /* Ensure this is 64-bit aligned */;
     long long int force_structure_alignment[3];
} uSprite;
 
     void guSprite2DInit(uSprite *SpritePointer,
     void *SourceImagePointer,
     void *TlutPointer,
     int Stride,
     int SubImageWidth,
     int SubImageHeight,
     int SourceImageType,
     int SourceImageBitSize,
     int SourceImageOffsetS,
     int SourceImageOffsetT);

Arguments

• SpritePointer is the pointer to the sprite structure that sets the parameters.
• SourceImagePointer is the base pointer of the texture image in memory containing the rectangle to be displayed.
• TlutPointer is the pointer to the color index used for CI images. Set it to Null when CI images will not be used.
• Stride is the texel width of the base image in memory.
• SubImageWidth is the texel width of the image to be displayed.
• SubImageHeight is the texel height of the image to be displayed.
• SourceImageType specifies the format of the texture image in memory. All texture formats supported by the hardware are allowed, such as G_IM_FMT_RGB or G_IM_FMT_CI.
• SourceImageBitSize is the number of bits per texel of the input image. All texture sizes supported by the hardware are allowed, such as G_IM_SIZ_32b or G_IM_SIZ_4b.
• ScaleX specifies the scale in the X axis for the input screen image as a s 5.10 fixed-point number. A value of 1024 specifies 1 to 1 scaling. A value of 512 enlarges the input texels by 2 times in the output scaling pixels.
• Scale values should be (1024 in order to avoid an unnatural feel. Scale values must be positive. Use the FlipTextureX variable to create negatively scaled images.
• ScaleY specifies the scale in the Y axis for the input screen image as a s 5.10 fixed-point number. A value of 1024 specifies 1 to 1 scaling. A value of 512 enlarges the input texels by 2 times in the output scaling pixels. Scale values should be (1024 in order to avoid an unnatural feel. Scale values must be positive. Use the FlipTextureY variable to create negatively scaled images.
• FlipTextureX specifies whether the image to be displayed should be inverted in the X direction.
• FlipTextureY specifies whether the image to be displayed should be inverted in the Y direction.
• SourceImageOffsetS is the offset in texel columns from the origin of the base image. It specifies the starting point of the rectangular region for texel display within the base image.
• SourceImageOffsetT is the offset in texel lines from the origin of the base image. It specifies the starting point of the rectangular region for texel display within the base image.
• PScreenX specifies the X location in the screen coordinates of the output image. The origin is in the upper-left corner of the screen.
• PScreenY Specifies the Y location in the screen coordinates of the output image. The origin is in the upper-left corner of the screen.

GBI

Note

gDPSetRenderMode(glistp++,
   G_RM_AA_ZB_OPA_SURF,
   G_RM_AA_ZB_OPA_SURF2);

gDPSetDepthSource(glistp++,
   _ZS_PRIM);

gDPSetCombineMode(glistp++,
   G_CC_DECALRGB, G_CC_DECALRGB);

gDPSetPrimDepth(glistp++,
   ZBufferValue, 0);

guSprite2DInit(MySprite, ImagePointer,
   TlutPointer, ImageWidth,
   RectangleWidth, RectangleHeight, 
   ImageType, ImageSize, 
   TextureStartS, TextureStartT); 

gSPSprite2DBase(glistp++,
   OS_K0_TO_PHYSICAL(MySprite)); 

gSPSprite2DScaleFlip(glistp++,
   ScaleX, ScaleY, 
   FlipTextureX, FlipTextureY); 

gSPSprite2DDraw(glistp++, PScreenX, PScreenY);

Warnings, Limitations, and Workarounds

• 32 bit subrectangles that are scaled in the Y direction are clamped by the microcode to a maximum of 512 texels wide.
• 32 bit subrectangles that are placed at the beginning of a subpixel boundary in the Y direction and that are larger than 512 texels in width are clamped by the microcode to being on an integral scan line boundary.
• These filtering conditions also mean that, when displaying a Y-scaled image, you will need to add 1 to the T value to prevent filtering of texels outside the range.
• Y flipped images that have been scaled vertically by a non-squared value will be slightly different in height than their non-flipped versions. If you are doing an animation involving scaled flipped and non-flipped textures, restrict the Y scale value to a squared value.

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