The <sprites.h> Header File

Simple sprite routines

Functions

Sprite8
Draws a sprite with a width of 8 pixels or less on the screen.
Sprite16
Draws a sprite with a width of 16 pixels or less on the screen.
Sprite32
Draws a sprite with a width of 32 pixels or less on the screen.

Predefined Types

SprtModes
An enumeration to describe possible modes of sprite drawing.

For a lot of advanced drawing routines, we recommend you to download the ExtGraph library by the TI-Chess Team.

See also: graph.h, gray.h


Sprite8

void Sprite8 (short x, short y, short height, const unsigned char *sprite, void *vm_addr, short mode);

Draws a sprite with a width of 8 pixels or less on the screen.

Sprite8 draws a sprite with a width of 8 pixels or less on the screen. Use Sprite16 or Sprite32 for wider sprites. This routine is many times faster than TIOS routines like DrawIcon, BitmapPut, etc. x and y are the coordinates of the upper left corner of the sprite. height is the height of the sprite. sprite is a pointer to the array of unsigned characters which define the shape of the sprite (line by line). vm_addr is the pointer to the video plane; it should be LCD_MEM if you are not using grayscale or the PortSet function. mode is the drawing mode, and it may have one of the following values (these constants are defined in the enum SprtModes):

SPRT_XOR XOR the sprite into a background. This is used only for non-masked sprites. XOR mode switches every pixel with a corresponding '1' bit in the sprite array from white to black and verse vica.
SPRT_OR OR the sprite into a background. This is mainly used for masked sprites together with SPRT_AND. OR means that every pixel with a corresponding '1' bit in the sprite array will be set to black, but all other pixels stay the same. If you want to turn all other pixels to white instead, one way to achieve this would be to AND the sprite as well.
SPRT_AND AND the sprite into a background. This is used for masked sprites together with SPRT_OR. AND turns off every pixel with a corresponding '0' bit in the sprite array, but all other pixels remain untouched.

In fact, you can use one of two techniques to draw sprites:

Here is a simple example (called "Masked Sprite"), which first draws a simple "background", then draws a "masked" sprite (which is a simple 8x8 square with solid edges and blank interior) at (30,30):

// Display a masked sprite over an arbitrary background

#define USE_TI89              // Compile for TI-89
#define USE_TI92PLUS          // Compile for TI-92 Plus
#define USE_V200              // Compile for V200

#define OPTIMIZE_ROM_CALLS    // Use ROM Call Optimization
#define MIN_AMS 100           // Compile for AMS 1.00 or higher
#define SAVE_SCREEN           // Save/Restore LCD Contents

#include <tigcclib.h>         // Include All Header Files

// Main Function
void _main(void)
{
  static const unsigned char sprite[] = {0xFF,0x81,0x81,0x81,0x81,0x81,0x81,0xFF};
  static const unsigned char imask[] = {(unsigned char)~0xFF,(unsigned char)~0xFF,
    (unsigned char)~0xFF,(unsigned char)~0xFF,(unsigned char)~0xFF,
    (unsigned char)~0xFF,(unsigned char)~0xFF,(unsigned char)~0xFF};
  int i;
  ClrScr ();
  for (i = 0; i <= LCD_WIDTH; i++)
    DrawLine (i, 0, i, LCD_HEIGHT, A_SHADE_NS);  // A simple background
  Sprite8 (30, 30, 8, imask, LCD_MEM, SPRT_AND);
  Sprite8 (30, 30, 8, sprite, LCD_MEM, SPRT_OR);
  ngetchx ();
}

Here the sprite mask is {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF}, but it needs to be inverted before passing it to the Sprite8 function. For this purpose, the operator '~' may be very useful. Note that '~' is "bitwise NOT". Of course, ~0xFF is the same as 0x00, but this notation makes the program more clear (and it does not increase the code size, because the inverting will be performed at compilation time). And if you want to use Sprite16 or Sprite32, the notation ~0xFF will still be valid in a short int array, or in a long int array if you add the 'L' suffix (see the respective info about Sprite32). Without this notation, you must use 0x00 in Sprite8, but 0xFF00 in Sprite16, and 0xFFFFFF00 in Sprite32. This is why a notation like ~0xFF is more universal.

Starting from TIGCC v0.91, you can use binary numbers to define your sprites. On the one hand, it makes the program incompatible with other C dialects as well as previous (ancient) versions of TIGCC. On the other hand, it makes designing a sprite much easier and also allows for editing the sprite at a later time without having to reconvert it. The binary representation of the sprite presented above would look like this:

static const unsigned char sprite[]={
0b11111111,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b10000001,
0b11111111};

Sprite16

void Sprite16 (short x, short y, short height, const unsigned short *sprite, void *vm_addr, short mode);

Draws a sprite with a width of 16 pixels or less on the screen.

Sprite16 works exactly like Sprite8, but it takes sprites with a width of 16 pixels. sprite is now a pointer to the array of unsigned short integers which defines the sprite. So, to define a sprite (or sprite mask), use something like

static const unsigned short sprite[] = {...};

See Sprite8 for more info about sprites.


Sprite32

void Sprite32 (short x, short y, short height, const unsigned long *sprite, void *vm_addr, short mode);

Draws a sprite with a width of 32 pixels or less on the screen.

Sprite32 works exactly like Sprite8, but it takes sprites with a width of 32 pixels. sprite is now a pointer to the array of unsigned long integers which defines the sprite. So, to define a sprite (or sprite mask), use something like

static const unsigned long sprite[] = {...};

Note: If you define a sprite mask and invert it with the '~' operator, you need to take care of the possibility of the first two bytes being zero in one constant. In this case, the constant will be assumed to be a 16 bit value, so only 16 bits will be inverted. Then the constant is promoted to an unsigned long integer, and the first 16 bits are still zero as if they actually belonged to the mask. To take care of this problem, add the 'L' (long) suffix to the end of the value.

If you want to use sprites wider than 32 pixels (which is not very likely), one solution is to use DoorsOS and its "put_sprite" function (see Frequently Asked Questions for more info about how to do it). If you don't want to use DoorsOS, the proposed method depends on what the use of the sprite will be. If you don't need too fast action, the built-in TIOS function BitmapPut may be good enough. If you need a very fast sprite routine for very large sprites, then you must write it yourself.

See Sprite8 for more info about sprites.


SprtModes

enum SprtModes {SPRT_XOR, SPRT_OR, SPRT_AND};

An enumeration to describe possible modes of sprite drawing.

This type is used by all sprite functions.


Return to the main index