16.1 Application Programmers Interface (API)

Sprites are usually used to draw images onto the screen. For these simple cases, a few scripts are provided to automatically take a specified image and generate an appropriate sprite data structure. The generated sprite may then be edited manually or modified at run time to create dynamic behavior.

mksprite name imgfile.rgb tileX tileY overlap > sp_name.h

This program takes a Silicon Graphics image file and generates a sprite. This sprite consists of a number of individual bitmaps (tiles) that are tileX apart in the x direction and tileY apart in the y direction. If overlap is "0", then these bitmaps are exactly tileX by tileY in size and should not be scaled (see spScale()). If overlap is "1", then the tiles are (tileX+1) by (tileY+1) in size. These sprites may be scaled and the textures will be properly interpolated. This extra pixel of overlap, or "border", provides the required data to create smooth transitions between tiles. The generated file may be included in an application and the sprite may be manipulated with the name "name".

mkisprite name imgfile.rgb tileX tileY overlap > sp_name.h

This mkisprite command is just like mksprite, except that it converts the image to an 8-bit Color Index format, computes the TLUT, and generates the sprite with all the appropriate changes to support this format.

void spInit(Gfx **glistp)

This routine is called at the beginning of sprite drawing. Some GBI display list commands are added to the specified glistp to get the RCP into the correct mode for sprite rendering. This sets default texturing modes.

void spFinish(Gfx **glistp)

This routine is called at the end of sprite drawing. Some GBI display list commands are added to the specified glistp to get the RCP to complete all pending drawing operations and reset the RCP to its regular state. It also tacks on a gEndDisplayList( ).

void spMove(Sprite *sp, s32 x, s32 y)

This routine sets the screen position of the upper left-hand corner of the sprite.

void spScale(Sprite *sp, f32 sx, f32 sy)

This routine sets the resizing amount for this sprite. Scales may be less than 1.0 to produce a smaller image, or greater than 1 to create an expanded image.

void spColor(Sprite *sp, u8 red, u8 green, u8 blue, u8 alpha)

This routine sets the color of the sprite. Based on how the sprite is to be drawn, this could be either the PRIMITIVE_COLOR or the FILL_COLOR.

void spSetAttribute(Sprite *sp, s32 attr)

This routine sets the indicated attribute. "attr" can be the bit-wise OR of many attributes.

void spClearAttribute(Sprite *sp, s32 attr)

This routine clears the indicated attributes. "attr" can be the bit-wise OR of many attributes.

void spScissor(s32 xmin, s32 xmax, s32 ymin, s32 ymax)

This routine specifies the bounding region in which sprites will be drawn. By default, this region is initialized with xmin=0, xmax=319, ymin=0, and ymax=239.

Gfx *spDraw(Sprite *sp)

This routine constructs a display list starting at sp->rsp_dl_next that draws the sprite into the framebuffer in the indicated way. This display list is terminated with an gEndDisplayList( ) entry, and the sp->rsp_dl_next entry is updated to point to the next entry. The pointer to the start of this display list is returned when it completes to construct a display list..