Low level functions
There are several families of functions, which do a specific task in several modes. The library provides 84 different functions, with more than 400 combinations...
- 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.
- 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 DrawTiles
family
DrawTiles
functions draw directly the tiles (without scrolling them) into a buffer of 240x128 pixels (not a big_vscreen).
Actually, these functions do exactly the same work as the RefreshBuffer
functions, but the destination is a screen which has a normal size.
The drawing mode is RPLC
, so there is no need to erase the destination buffer calling these functions.
Their prototypes look like :
void Draw[Gray]TilesXY[89](short width,void *tile,void *dest,void *sprts);
Where Gray
is optionnal 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).
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 draw a plane in black and white, using a matrix of bytes, with 8x8 sprites, and drawing only the part of the screen seen on a TI-89, we'll use the DrawTiles8B89
function.
Here's the description of the parameters passed to the function :
width
: tile matrix width.
tile
: adress of the first tile to draw on the destination (the one on the left-up corner).
dest
: adress of the destination buffer.
sprts
: adress of the sprite array.
The example 6 shows a way to use one of these functions.
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 to help you to understand how they work. When you understand, you'll see that possibilities provided by these functions are very powerful.