gspSprite2D

-> Changed to the S2DEX microcode (not compatible)

Function

gspSprite2D, gspSprite2D.dram, gspSprite2D.fifo

-> High-quality 2D sprite geometry microcode

Description

this is the optimized, high-quality, full-featured 2D sprite geometry microcode. It supports automatic subdivision and loads any size of all of the texture format sizes and types supported in the gSPTextureRectangle command, and sends it directly to the RDP. Additionally, images can be scaled up or inverted in the X or Y directions.

Commands


The sprite microcode is accessed through a combination of four new commands. The first command, guSprite2DInit initializes a specified a sprite structure. gSPSprite2DBase command sends the sprite structure to the sprite microcode to start actual processing. guSprite2DInit command is a useful function that the application doesn't need to initialize the sprite structure.

gSPSprite2DBase initializes or 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, RectangleHeight,
        ImageType, ImageSize,
        TextureStartS, TextureStartT); 

        gSPSprite2DBase(glistp++, OS_K0_TO_PHYSICAL(&MySprite));
        gSPSprite2DScaleFlip(glistp++, ScaleX, ScaleY,
                    FlipTextureX, FlipTextureY);
        gSPSprite2DDraw(glistp++, PScreenX, PScreenY)

Each of the arguments is explained below.

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 allignment */;
        char dummy[4];

        } uSprite_t;

typedef union {
        uSprite_t s; 
        /* Need to make sure this is 64 bit aligned */; 
        long long int force_structure_allignment[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.
SbuImageWidth
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 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 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

The following GBI commands are not supported by this microcode:

gSPLine3D, gSP1Triangle

Note

The sprite microcode does not directly support Z-Buffering. This is unnecessary as Z-Buffering can be accomplished outside of the sprite microcode by setting up the proper rendering mode and making use of the hardware primitive depth registers. Following is a code fragment that does Z-Buffering.

gDPSetRenderMode(glistp++, G_RM_AA_ZB_OPA_SURF, G_RM_AA_ZB_OPA_SURF2);
gDPSetDepthSource(glistp++, G_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

Images that have been non-unit scaled and flipped around the Y axis may not be smoothly converted in the vertical direction, depending on the quantity of sub-pixels. Jumping will occur at a certain quantity. The solution is to convert non-unit scaling to unit amounts in the vertical direction.

The Sprite Microcode was designed to be able to scale up images by any amount. Images can also be scaled down together with some attendant artifacts. Please note that, while the TextureScaleX and TextureScaleY parameters are s 5.10 fixed-point numbers, they are restricted to being positive. Consequently, the largest usable scale value is 32767, which corresponds to a texel to pixel ratio of 31.999.

Texture images that are either scaled in the Y axis or placed on a subpixel scanline boundary require filtering by the hardware texture filter unit. This filtering requires that at least one extra line in the screen image be loaded in the texture memory so that the filtering can occur. The texture memory is limited to 4K bytes, so there are some restrictions:

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.

See Also

gspLine3D, gspTurbo3D, gspFast3D, osSpTaskStart, gSPSprite2DBase, gSPSprite2DScaleFlip, gSPSprite2DDraw