Documentation of TileMap Engine v0.3 (01/19/2004)

• Introduction
• How to use the TileMap Engine ?
• Description of the functions
• Data structures used by the functions
• High level functions
• Low level functions
• Credits
• Appendix
• History
• To-do
• Contact information

Introduction

The TileMap Engine is a graphical library which displays maps of tiles.
Its main features are:

• B/W and grayscale functions;
• 16x16 or 8x8 sprites, therefore arrays of char or short;
• Many different display modes, including two transparency modes (they enable multiple layers for the background);
• Automatically animated tiles;
• Vertical and horizontal shifts for each line independently.

• RPG
• Platformers / Sidescrollers (with or without multiple layers for the background).

• games like SimCity, in which the scrolling is performed tile by tile, instead of pixel by pixel (see the Tile... functions in ExtGraph in order to do that)
• Shoot'em up

• Copy the sprites in a virtual screen, larger than the real screen (32 additional pixels in each dimension). The size in bytes of this virtual screen is (240+32)*(128+32)/8 = 5440 bytes. The copy is quite fast, since the sprites are drawn aligned (no shifting necessary), and the loops are partly unrolled.
• Draw the big virtual screen on the real screen, shifting the sprites as necessary. Shifting allows drawing at any X coordinate, not just byte/word boundaries.

+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|00|00|00|01|01|01|00|00|00|00|00|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|00|01|01|01|01|01|01|00|00|00|00|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|01|01|01|01|01|01|01|01|01|01|00|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|01|01|01|01|00|00|01|01|01|01|01|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|01|01|01|01|00|00|00|01|01|01|01|00|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|01|01|01|01|01|01|00|01|01|01|00|00|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|01|01|01|01|01|01|01|01|01|01|01|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|00|00|00|01|01|01|01|01|01|01|01|01|01|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|00|00|00|01|01|01|01|01|01|01|01|01|01|01|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|00|00|00|00|01|01|01|01|01|01|01|01|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|00|00|00|00|00|00|01|01|01|01|00|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
|00|00|00|00|00|00|00|00|00|00|00|00|01|00|00|00|00|00|00|00|
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

              272
     <----------------->
   ^ +-----------------+
   | |    ######       |
   | |   ##########    |
   | |   ####  #####   |
   | |  ####   ####    |
160| |  ###### ###     |
   | |   ###########   |
   | |      ########## |
   | |      ###########|
   | |       ########  |
   | |         ####    |
   v +-----------------+

            16
    <---------------->
  ^ +----------------+----------------+----------------+---------------
  | |             |  |           ^ |  |             |  |             | 
  | |             |  |           | |  |             |  |             | 
  | |             |  |         11| |  |             |  |             | 
16| |      13     |  |           | |  |             |  |             | 
  | |<----------->|  |           v |  |             |  |             | 
  | |-------------+--|-------------+--|-------------+--|-------------+-
  | |             |  |             |  |             |  |             | 
  | |             |  |             |  |             |  |             | 
  v +----------------+----------------+----------------+---------------
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |-------------+--|-------------+--|-------------+--|-------------+-
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    +----------------+----------------+----------------+---------------
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |             |  |             |  |             |  |             | 
    |-------------+--|-------------+--|-------------+--|-------------+-
    |             |  |             |  |             |  |             | 

How to use the tilemap engine in your programs ?

Description of the functions

Data structures used by the functions

From begining, we mention matrix of tiles, sprite array, big virtual screen, or virtual screen. Here are their details:



Matrix of tiles

Matrix of char or short, with two dimensions. Its size must be at least 8 rows and 15 columns with 16x16 sprites, or 16 rows and 30 columns with 8x8 sprites.





Sprites

The sprites can be in grayscale or in B/W, and their size can be 16x16 or 8x8 pixels. There are specific functions for each type of sprite, so you must be careful when choosing.
Black and White sprites are classics : a simple array of 8 char for 8x8 sprites, or an array of 16 short for 16x16 sprites, containing each line of the sprite.
Grayscale sprites use a more complex format : an array of 16 char for 8x8 sprites, or 32 short for 16x16 sprites, it contains the first line of the sprite for the first plane, the first line for the second plane, the second line of the sprite for the first plane, the second line of the sprite for the second plane, etc... It's called an interlaced format.
The first plane can be the light or the dark plane, that doesn't matter, but respect the convention in your virtuals screens (see below).





Sprite array

The sprite array can be seen like an 1D array containing sprites, but it's actually a 2D array, because sprites are already an 1D array.





Matrix of animations

2D array of short : the number of rows is the number of animation steps, and the number of columns is the number of animations. Each cell contains the number of the sprite for a step for an animation.





Array of horizontal shifts

Array of char, with one dimension, of 128 elements. Each element is a horizontal shift to add to the current line when the big virtual screen is drawn on the screen. Correct values are between 0 and 16.





Array of vertical shifts

Array of short, with one dimension, of 128 elements. Each element is a value to add to the pointer on the source, at the end of each line drawed, when the big virtual screen is drawed on the screen. Any value is allowed, but be careful to not point outside of the big virtual screen.





Big virtual screen

Buffer of 5440 bytes in B/W, or 10880 bytes in grayscale (in this case, the 5440 first bytes are the first plane and the 5440 followed bytes are the second plane ; you can choose which plane is the light or the dark plane, but keep this convention in your sprites).





Virtual screen

Buffer of 3840 bytes in B/W, or 7680 bytes in grayscales (in this case, like the big virtual screen, the two planes will be followed).





High level functions


Note that prototypes and usage of the tilemap engine functions may/will change in ExtGraph 2.00 Beta 3.


• void DrawPlane(short x,short y,Plane *plane,void *dest,TM_Mode mode,TM_Type type);


This function draws the plane plane from x and y coordinates on the screen (virtual or not) dest.
It updates the big virtual screen automatically if needed.
Parameters plane, type and mode are not ordinary, here are their specifications :
plane is the address of a Plane structure, which is defined like this :


typedef struct
{
    void *matrix;  // Matrix of tiles
    unsigned short width;  // Map's width
    void *sprites; // Sprite array
    char *big_vscreen;  // Big virtual screen
    long mask;  // Contains the mask, when you want to use the BLIT mode
    long reserved1;  // Internal use (do not modify)
    short force_update; // To force updating the big virtual screen
}Plane;

type indicates the type of the plane : the size of the sprites (16x16 or 8x8), the type of the matrix of tiles and it indicates if the function works in B/W or in grayscales. Its type is TM_Type, this type is a bit complex, and you don't need to know exactly what it is to use the function, because I wrote macros in the header file which can be used directly like a TM_Type value. Read the appendix of this document to know all the allowed values.
mode indicates the draw mode : RPLC, OR, XOR, AND, TRANW, TRANB or BLIT. The type of this parameter is TM_Mode, this type is complicated too, if you really want to know what it is, look at the header file, but that's not needed to be able to use the functions because I wrote macros in the header file which can be used directly for a parameter TM_Mode. Read the appendix at the end of this document to know all the allowed values.

This function updates the big virtual screen only if it's needed, so to force the updating, put a nonzero value in the force_update field. The DrawBuffer function will clear this field after it updates the big virtual screen. You must do this in the initialization.

To use a BLIT mode, put the mask value in the field mask before calling the DrawBuffer function.

You can see an example using this function in the Example 1, provided with the library (demo13 for ExtGraph).

Note : It's strongly recommended to use macros defined in the header file for parameters type and mode.



• void DrawAnimatedPlane(short x,short y,AnimatedPlane *plane,void *dest,TM_Mode mode,TM_AnimType type);


Draw the animated plane plane form x and y coordinates to the screen (virtual or not) dest.
It updates the big virtual screen automatically if needed.
The plane parameter is the address of an AnimatedPlane structure, which is defined like this :


typedef struct
{
    Plane p;
    void *tabanim; // Animation's matrix
    short nb_anim; // Number of animations
    short nb_step; // Number of animation's step
    short step; // Current step number
    short step_length; // Length of a step (in frames)
    short frame; // Current frame number for the current step
}AnimatedPlane;

This structure contains a Plane followed by all the necessary informations to animate it.
The matrix of the Plane will not contain sprite numbers, but animation numbers, and the function will find the corresponding sprite number in the animation's matrix tabanim.
The parameter mode works exactly like in the previous function, please look at the appendix to know what are correct values.
The parameter type works like in the previous function, but its possible values are not the same, they're given in the apppendix.

This function is used in the Example 3, provided with the library (demo15 for ExtGraph).





Low level functions

There are several families of functions, which do a specific task in several modes. The library provides 64 different functions, with more than 380 combinations...


Note that prototypes and usage of the tilemap engine functions may/will change in ExtGraph 2.00 Beta 3.


• The RefreshBuffer family


RefreshBuffer functions update a big virtual screen.

Their prototypes look like :
void Refresh[Gray]BufferXY(short width,void *tile,void *dest,void *sprts);
Where : Gray is optional and specifies if the function works in grayscale or not.
X specifies sprite's size, and can only take these values : 16 (sprites of 16x16 pixels) or 8 (sprites of 8x8 pixels).
Y specifies the size of a tile in the matrix of tiles, and can only take these values : W (matrix of words [2 bytes]) and B (matrix of bytes).
For example, to use this function on a matrix of bytes, with 16x16 sprites, and in grayscales, you must use the function RefreshGrayBuffer16B.

And here is the description of the parameters passed to the function :
width : tile matrix width.
tile : address of the first tile to draw on the big virtual screen (the one on the left-up corner).
dest : address of the big virtual screen (its size must be 5440 bytes in black and white, or 10880 bytes in grayscale).
sprts : address of the sprite array.

You should look at the Example 2 to see an example of use of this function (demo14 for ExtGraph).



• The RefreshAnimatedBuffer Family


RefreshAnimatedBuffer functions update a big virtual screen and animate its tiles.

Their prototypes look like :
void Refresh[Gray]AnimatedBufferXY(short width,void *tile,void *dest,void *sprts,void *animarray);
Where : Gray is optional and specifies if the function works in grayscale or not.
X specifies sprite's size, and can only take these values : 16 (sprites of 16x16 pixels) or 8 (sprites of 8x8 pixels).
Y specifies the size of a tile in the matrix of tiles, and can only take these values : W (matrix of words [2 bytes]) and B (matrix of bytes).
For example, to use this function on a matrix of bytes, with 16x16 sprites, and in grayscales, you must use the function RefreshGrayBuffer16B.

And here is the description of the parameters passed to the function :
width : tile matrix width.
tile : address of the first tile to draw on the big virtual screen (the one on the left-up corner). This tile will not contain a sprite number, but an animation number.
dest : address of the big virtual screen (its size must be 5440 bytes in black and white, or 10880 bytes in grayscales).
sprts : address of the sprite array.
animarray : address of the sprites numbers array. It's an array of short. The element n of this array contains the sprite number of the current step for the animation n.


There is no example of this function for now, so here is one short example :


char matrix[MAP_WIDTH][MAP_HEIGHT]={...};  // Contains animation numbers
short anim[NB_STEPS][NB_ANIMS]={...}; // Contains sprite numbers
short sprts[NB_SPRITES][16]={...}; // Contains black and white sprites

void _main(void)
{
  char big_vscreen[BIG_VSCREEN_SIZE];
  short old_sr,n_frame,n_step;

  old_sr=OSSetSR(0x0200);

  n_frame=n_step=0;

  do
  {
    if(!n_frame) // If it's the first frame of a step, we update the big virtual screen
        RefreshAnimatedBuffer(MAP_WIDTH,matrix,big_vscreen,sprts,anim[n_step]);

    DrawBuffer_RPLC(big_vscreen,0,0,LCD_MEM);

    if(!(++n_frame % 16)) // Every 16 frames, the animation's step changes
      n_step = (n_step+1) % NB_STEPS;
  }while(!_keytest(RR_ESC));

  OSSetSR(old_sr);
}

We can first note that the library is not fully used, because coordinates passed to the DrawBuffer function are both 0. That's only to make the example shorter.
On each frame, we increment a frame count, when this count reaches the value 16, we change the number of the animation's step.
To each step, the number of the sprite corresponding to each animation is given in the matrix anim.
In most of cases, we don't want to animate all tiles. To have an unanimated tile, you can set each animation step of the tile the same index of sprite.
So, if only some tiles are animated, the matrix anim become redundant. In this case, you should use another way : use only one array of sprite's numbers (instead of NB_STEPS arrays like in the example), and update directly this array when you want.



• The DrawBuffer family


DrawBuffer functions draw a big virtual screen into a screen (virtual or not).

Their prototypes look like :
void Draw[Gray]Buffer[89]_MODE(void *src,short x,short y,void *dest);
Where : Gray is optional and indicates if the function works in grayscales or not.
89 is optional too, it allows to draw only what is seen on a TI-89 screen (that's faster).
MODE specifies the draw mode, it can take these values : RPLC, OR, XOR, AND, TRANW, TRANB ou BLIT. The draw modes are described in the appendix, at the end of this file.
For example, to draw a plane in RPLC mode, and in grayscales, you must use DrawGrayBuffer_RPLC function.

And here is the description of the parameters passed to the function :
src : address of the big virtual screen to draw.
x : horizontal shift to apply, in pixels (Warning : must be between 0 and 31).
y : vertical shift to apply, in pixels (Warning : must be 0 and 31).
dest : address of destination screen (its size must be 3840 bytes in black and white, and 7680 bytes in grayscales).

Actually, functions drawing in BLIT mode are a little bit different of others, they take another parameter : the mask. Their prototypes look like :
void Draw[Gray]Buffer[89]_BLIT(void *src, short x, short y, long mask, void *dest);
Where mask contains mask value. Warning : the mask is 32 bits, to provide more flexibility, but it can be source of problems if you don't pay attention.



• The DrawBufferWithShifts family


DrawBufferWithShifts functions draw a big virtual screen on a screen, but you can also specify the horizontal shift for each line, and add verticals shifts between lines.
It allows you to make many graphicals effects.

Their prototypes look like :
void Draw[Gray]BufferWithShifts[89]_MODE(void *src,short x,short y,void *dest,char *hshift,short *vshift);
Where : Gray is optional and indicates if the function works in grayscales or not.
89 is optional too, it allows to draw only what is seen on a TI-89 screen (that's faster).
MODE specifies the draw mode, it can take these values : RPLC, OR, XOR, AND, TRANW, TRANB ou BLIT. The draw modes are described in the appendix, at the end of this file.

Description of the parameters of these functions :
src : address of the big virtual screen to draw.
x : horizontal shift, in pixels (Warning : must be between 0 and 15).
y : vertical shift, in pixels (Warning : must be between 0 and 15).
dest : address of destination screen.
hshifts : address of the array of horizontal shifts. When the function draws the big virtual screen to the destination, for each line, the corresponding value will be added at the horizontal shift.
vshifts : address of the array of verticals shifts. When the function draw the big virtual screen into the destination, at the end of each line drawed, the value of the array will be added at the pointer to the source (the big virtual screen). So, to draw two times the same line, for example, you just need to put the value -34 somewhere in the array (and to skip a line, put 34).

Function drawing in BLIT mode, are a little bit different, they take another parameter : the mask. Their prototypes look like :
void Draw[Gray]BufferWithShifts[89]_BLIT(void *src,short x,short y,long mask,void *dest,char *hshifts,short *vshifts);
Where mask contains the mask value.

The way these functions work is not really easy to understand, that's why I strongly recommend that you look at Example 4 (demo16 for ExtGraph) to help you to understand how they work. When you understand, you'll see that possibilities provided by these functions are very powerful.

Credits

Appendix

Description of the various drawing modes :

RPLC

Completely RePLaCes the destination (clearing it before is useless). You should use this mode to display a background.

OR

Logical OR between the source and the destination.

XOR

Logical XOR (eXclusive OR) between the source and the destination.

AND

Logical AND between the source and the destination.

BLIT

This mode uses the field mask of the Plane structure, or the mask is passed to the low-level functions. A logical AND is performed between the mask and the destination, and then the plane is drawn with a logical OR between the source and the destination. This mode can be useful to create transition effects.

TRANW

The White color is TRANsparent, the other colors are opaque. This mode is very useful to draw planes over a background.

TRANB

The Black color is TRANsparent, the other colors are opaque. This mode is very useful to draw planes over a background.

Table summarizing the different plane types:

(elements have type TM_Type)

	2D char arrays		2D short arrays
	8x8 sprites	16x16 sprites	8x8 sprites	16x16 sprites
B/W	TM_8B	TM_16B	TM_8W	TM_16W
Grayscale	TM_G8B	TM_G16B	TM_G8W	TM_G16W

Table summarizing the different animated plane types:

(elements have type TM_AnimType)

	2D char arrays		2D short arrays
	8x8 sprites	16x16 sprites	8x8 sprites	16x16 sprites
B/W	TM_A8B	TM_A16B	TM_A8W	TM_A16W
Grayscale	TM_GA8B	TM_GA16B	TM_GA8W	TM_GA16W

Table summarizing the different drawing modes

(elements have type TM_Mode)

		RPLC	OR	XOR	AND	BLIT	TRANW	TRANB
B/W	TI92+/V200	TM_RPLC	TM_OR	TM_XOR	TM_AND	TM_BLIT
	TI89	TM_RPLC89	TM_OR89	TM_XOR89	TM_AND89	TM_BLIT89
Grayscale	TI92+/V200	TM_GRPLC	TM_GOR	TM_GXOR	TM_GAND	TM_GBLIT	TM_GTRANW	TM_GTRANB
	TI89	TM_GRPLC89	TM_GOR89	TM_GXOR89	TM_GAND89	TM_GBLIT89	TM_GTRANW89	TM_GTRANB89

History

v0.3 (01/19/2004)

English translation of the documentation

v0.2 (12/26/2003)

Added functions animating tiles automatically, and independent horizontal / vertical shifts for each line.
Several bugfixes on BLIT functions.

v0.1b (12/21/2003)

No function was added, but all functions were rewritten because the size of the large virtual screen was changed, so as to have better adaptability.
The use of high-level functions shouldn't have changed, but that of low-level functions changed.

v0.1 (12/19/2003)

First release.

Todo

Contact information