.TH gspSprite2D 3P local "Silicon Graphics, Inc."
.SH NAME
.upperok
gspSprite2D, gspSprite2D.dram, gspSprite2D.fifo
\- high-quality 2D sprite geometry RSP microcode.

.SH DESCRIPTION 

This is the optimized, full-featured 2D sprite geometry RSP microcode.
It supports automatic subdivision and loading of arbitrarily sized
dram resident images of all supported texture format sizes and types
into 
.IR gSPTextureRectangle (3P) 
commands sent directly to the
RDP. Additionally, images can be optionally scaled up or mirrored in
the X or Y directions.

.SH USAGE

The sprite microcode is accessed through a combination of 4 new commands.
The first command, 
.IR guSprite2DInit (3P)
is used to initialize a sprite structure with user specified values which
are then passed to the 
.IR gSPSprite2DBase (3P)
command for actual processing of the sprite structure by the microcode. The 
.IR guSprite2DInit (3P)
command is merely
a convenience function and can be avoided by having the application
initialize the sprite structure directly.

.IR gSPSprite2DBase (3P) 
is used to initialize the base or common sprite parameters. No actual 
drawing occurs.

.IR gSPSprite2DScaleFlip (3P)
is used to specify X/Y scaling or flipping parameters for a sprite. No
actual drawing occurs.

.IR gSPSprite2DDraw (3P)
specifies the screen coordinates for where the 
sprite should be drawn, and triggers the actual rendering of the sprite
using parameters previously specified with
.IR gSPSprite2DBase (3P)
and
.IR gSPSprite2DScaleFlip (3P)

A sample code fragment for specifying a sprite would be:

.nf
\f3#include "gu.h"
\f3#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); 


\fP
.fi

\f1
These parameters are explained below.


.SH C SPECIFICATION

.nf


\f3

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);

\f1
\fP
.fi
.SH PARAMETERS

.I SpritePointer
The address of the sprite structure into which the parameters will
be written.

.I SourceImagePointer
The address of the base of the texture image in memory out of which
a subrectangle is to be displayed.

.I TlutPointer
The address of an optional color index table for used with CI images.
Use Null for non-CI images.

.I Stride
The width in texels of the original base image in memory.

.I SubImageWidth
The width in texels of the subimage which is to be displayed.

.I SubImageHeight
The height in texels of the subimage which is to be displayed.

.I SourceImageType
The format of the texture image in memory. All supported hardware texture formats
are allowed, such as 
\f3 G_IM_FMT_RGBA \f1 or \f3 G_IM_FMT_CI\f1.

.I SourceImageBitSize
The number of bits per texel of the input image. All supported hardware texture
sizes are allowed, such as
\f3 G_IM_SIZ_32b \f1 or \f3 G_IM_SIZ_4b\f1.

.I ScaleX
The s5.10 fixed point X axis 
.I texture to pixel
scaling ratio
which is to be applied to the input
image. A value of 1024 specifies 1 to 1 scaling. A value of 512 specifies that
each input texel should be scaled up to 2 output screen pixels. Scale values
should be <= 1024 in order to prevent sampling artifacts from occuring. Scale
values must be positive, use the 
.I FlipTextureX
parameter to create negatively scaled images.

.I ScaleY
The s5.10 fixed point Y axis 
.I texture to pixel 
scaling ratio
which is to be applied to the input
image. A value of 1024 specifies 1 to 1 scaling. A value of 512 specifies that
each input row should be scaled up to 2 output screen rows. Scale values
should be <= 1024 in order to prevent sampling artifacts from occuring. Scale
values must be positive, use the 
.I FlipTextureY
parameter to create negatively scaled images.

.I FlipTextureX
Specifies whether the image should be mirrored in the X direction before display

.I FlipTextureY
Specifies whether the image should be mirrored in the Y direction before display

.I SourceImageOffsetS 
The offset in texel columns from the origin of the input base
image where the texture subrectangle which is to be displayed starts.

.I SourceImageOffsetT
The offset in texel rows from the origin of the input base
image where the texture subrectangle which is to be displayed starts.

.I PScreenX
Specifies the starting X location in screen coordinates of the output image.
The origin is in the upper left corner of the screen.

.I PScreenY
Specifies the starting Y location in screen coordinates of the output image.
The origin is in the upper left corner of the screen.

.SH GBI
The following GBI commands are
.I not
supported with this microcode:
.IR	gSPLine3D (3P)
.IR     gSP1Triangle (3P)

.SH NOTE

The sprite microcode has no direct support for ZBuffering. This is unecessary as
ZBuffering can be accomplished outside of the sprite microcode by setting up the
proper rendering mode and making use of the hardware primitive depth register. 
A code fragment for doing ZBuffered sprites is:

.nf
\f3

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);

\fP
.fi

\f1

.SH WARNINGS, LIMITATIONS, BUGS, WORKAROUNDS

Images which have been non-unit scaled and flipped in the Y axis will
not translate vertically by sub-pixel amounts smoothly, they will
exhibit a certain amount of jumping. The solution is to translate 
non-unit scaled Y
flipped images by unit amounts in the vertical direction.

The Sprite Microcode was designed to handle images which have been
optionally scaled up. Images can also be scaled down with some attendant
artifacts. Beware that the 
.I ScaleX
and
.I ScaleY
parameters are s5.10, however they are restricted to being positive,
thus the largest usuable scale value is 32767, which corresponds to
a texel to pixel ratio of 31.999. 

Texture images which 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 1 extra row of the
input image be loaded into the texture memory so that the filtering
can occur. Since the texture memory is limited to 4KB, this means that
the following restrictions are in effect:

	32 bit subrectangles which are scaled in the Y direction 
are clamped by the microcode to being a maximum of 512 texels wide.

additionally,

	32 bit subrectangles which are placed starting on 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.

Note that this filtering requirement also means that when displaying a
Y scaled image, you will need to offset your starting T value by 1 to
prevent artifacts resulting from filtering with out of bound texels.

Y flipped Images which have been scaled vertically by non power of 2
amounts will be slightly different heights than their non-flipped
versions. If doing an animation involving scaled flipped and
non-flipped textures, restrict the Y scale value to being a power of 2.

.SH SEE ALSO
.IR gspLine3D (3P),
.IR gspTurbo3D (3P)
.IR gspFast3D (3P)
.IR osSpTaskStart (3P)
.IR gSPSprite2DBase (3P)
.IR gSPSprite2DScaleFlip (3P)
.IR gSPSprite2DDraw (3P)