N64® Functions Menu

al - Audio Library Functions
gDP - DP GBI Macros
gdSP - General GBI Macros
gSP - SP GBI Macros
gt - Turbo Microcode RDP
gu - Graphics Utilities
Math - Math Functions
nuSys - NuSystem
os - N64 Operating System
sp - Sprite Library Functions
uh - Host to Target IO
64DD - N64 Disk Drive

Nintendo® Confidential

## gSPSprite2DScaleFlip

Format

    #include "gbi.h"

    gSPSprite2DScaleFlip(Gfx*gdl,
       short ScaleX, short ScaleY,
       char FlipTextureX,
       char FlipTextureY);
    gsSPSprite2DScaleFlip(short ScaleX,
       short ScaleY, char FlipTextureX,
       char FlipTextureY);

Arguments

- gdl is the pointer to the graphics display list
- 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 less than 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 less than 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

What This Macro Does
It gains access to the sprite microcode. The optimized, full-featured 2D sprite geometry microcode supports automatic subdivision and loads any size of all of the texture format sizes and types supported in the macro, and sends it directly to the RDP. Additionally, images can be scaled up or inverted in the X or Y directions.
You can gain access to the sprite microcode through a combination of four macros:

- guSprite2DInit initializes a specified sprite structure.
- gSPSprite2DBase sends the sprite microcode to the initialized sprite structure to start actual processing. It initialize the common sprite parameters but does not perform actual screen drawing.
- gSPSprite2DScaleFlip specifies the X/Y scaling and/or flipping parameters for a sprite but 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

Example
To display a sprite, use this code:

    #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;
    /* Make sure 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);

Notes
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. The following is a code fragment for doing 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 useable 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. Because the texture memory is limited to 4KB, the following restrictions are in effect:

- 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 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 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 have slightly different heights from 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
gspSprite2D
gSPSprite2DBase
gSPSprite2DDraw

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 June 1998