2000.08.17 (60 functions)

Table of content :

Video Functions
Palette Functions
Font Functions
Text output Functions
Tile Functions
Sprite Functions
Joypad Functions
Miscelaneous Functions

## VIDEO FUNCTIONS

disp_off();

Blank the display.

disp_on();

Enable display output.

cls();
cls(int val);

Clear all the screen.
Without parameters the screen is filled with a space character, else it's filled with the bat-value given as argument.

vsync();
vsync(char nb_frame);

Synchronize your program to the video vertical blanking signal (VBL), which is 1/60th of a second. Without parameters this function return as soon as a VBL signal has been received, else your program will be synchronized to the number of frame you requested. So for example to run your game at 20fps, just use vsync(3) at the end of your game loop.

vreg(char idx);
vreg(char idx, int val);

This function gives you direct access to the video processor (VDC) registers. The first form of this function is used to just select a VDC register (for custom accesses), and the second is used to set the value of a register (it also selects this register).

vram_addr(char x, char y);

Simple function to return the screen video memory address of the character located at position x/y.

set_screen_size(char size);

Change the virtual screen size. By default the startup code initialize a virtual screen of 64 characters wide and 32 character tall, but other values are possible, namely : 32x32, 128x32, 32x64, 64x64, or 128x64. More the virtual screen is big, less video memory you have for your graphics (font, tiles, sprites).

load_vram(int vaddr, int *data, int nb);

Generic function to load data (BAT, CG, sprites) in video memory, at address 'vaddr'. 'nb' is the number of 16-bit words to load.

load_bat(int vaddr, int *bat_data, char w, char h);

Load a rectangular character attribute table (BAT) of width 'w' and of height 'h' in video memory, at address 'vaddr'.

load_background(char *gfx, int *pal, int *bat, char width, char height);

This function is an all-in-one function, it is used to display a whole background image on the screen, like a game title image. It will load BG character data, it will load the palette, and finaly if will load the BAT. Use it with directives #incchr, #incpal and #incbat to manage the different type of data. The BG character data will be stored at address 0x1000 to 0x5000 in video memory.

## PALETTE FUNCTIONS

set_color(int num, int rgb);

Set the specified color (0-511) to the given rgb-value.

set_color_rgb(int num, char r, char g, char b);

Set the specified color to the given rgb component values. This function is easier to use than set_color(), but it is slower.

get_color(int num);

Retrieve the rgb-value of the specified color.

load_palette(char pal_num, int *pal, char nb_pal);

Load one or more 16-color palette-blocks at once. 'pal_num' is the index of the first block (0-31) to load, and 'nb_pal' the number of block. This function can be used to load palette defined using #defpal or included with #incpal directive.

set_sprpal(char pal_num, int *pal);
set_sprpal(char pal_num, int *pal, int nb_pal);

Exactly the same function has load_palette(), but this function offers direct access to sprite palette-blocks. Sprite palette-blocks are standard block number 16 to 31, but with this function you can simply access them with indexes 0 to 15. This function and set_bgpal() function make sprite and character palette-blocks manipulation easier; with them you don't have to know the real block indexes. Without the third arguments, the function loads only one block.

set_bgpal(char pal_num, int *pal);
set_bgpal(char pal_num, int *pal, int nb_pal);

Same function as set_sprpal() but for character palette-blocks.

## FONT FUNCTIONS

set_font_color(char fg, char bg);

Set the default font foreground and background colors (colors range from 0 to 15). Changes won't take effect immediately, you must re-load the font by calling load_default_font().

set_font_pal(char pal);

Set the font palette index (0-15).

set_font_addr(int vaddr);

Set the font address in video memory. Use this function to change the current font; to use several font on the same screen, or when you load yourself a font and need to tell the library where it is.

get_font_pal();

Return the current font palette index.

get_font_addr();

Return the current font address in video memory.

load_default_font();
load_default_font(char num);
load_default_font(char num, int vaddr);

Load a default font in video memory. Without parameters the first default font is loaded just above the BAT in video memory; usualy it's address 0x800. Otherwise you can select the font number, and eventualy the address in video memory. In its current implementation the library support only one default font, but in the future more fonts could be available.

load_font(char *font, char nb_char);
load_font(char *font, char nb_char, int vaddr);

Load a custom font in video memory. Used together with the #incchr directive it will allow you to load a font from a PCX file. Note that custom fonts are colored fonts, so they won't be affected by any previous call to set_font_color(). The number of character to load range from 0 to 224, ASCII characters 0 to 31 are never used, and can't be defined, you must start your font at the space character, which is ASCII code 32. If you don't implicitely give a video memory address, the function will load your font just above the BAT (usualy it's address 0x800).

## TEXT OUTPUT FUNCTIONS

All the text output functions have two forms, one where you directly specify the video memory address, and another one where you specify x/y coordinates (in character unit). The second form is a bit slower but more user-friendly.

put_digit(char digit, int vaddr);
put_digit(char digit, char x, char y);

Output a digit character '0'-'9' given its numeric value. Hexa digits ('A'-'F') are also supported, a value of 10 will output 'A', a value of 11 will output 'B', and so on...

put_char(char c, int vaddr);
put_char(char c, char x, char y);

Output an ASCII character.

put_raw(int bat_val, int vaddr);
put_raw(int bat_val, char x, char y);

Output a raw bat-value.

put_number(int number, char width, int vaddr);
put_number(int number, char width, char x, char y);

Output a signed number. The 'width' argument is used to format the number. As much as 'width' digit(s) will be displayed. If the number has less than 'width' digit(s), blank spaces will be added at its left. If the number is negative, a '-' sign is added.

put_hex(int number, char width, int vaddr);
put_hex(int number, char width, char x, char y);

Output an hexa number.

put_string(char *string, int vaddr);
put_string(char *string, char x, char y);

Output a null terminated ASCII string.

## TILE & MAP FUNCTIONS

set_tile_data(char *tile_data, int nb_tile, char *pal_ref);

Define an array of tile to be used by all the tile and map functions. 'tile_data' is the address of the tile graphics data in memory, 'nb_tile' is the number of tile (max. 256), and 'pal_ref' is the address of a palette-index array to use for tiles; each tile has its own palette index attached to it (note that palette indexes must be shifted to the left by four bits, ie. 0x40 for palette index 4).

load_tile(int vaddr);

Load tile graphics data in video memory, at address 'vaddr'. You must first have defined a tile array with set_tile_data() before using this function.

put_tile(int num, int vaddr);
put_tile(int num, char x, char y);

Put individual tiles on the screen, either directly at video memory location 'vaddr', or at screen coordinates 'x/y' (in tile unit). 'num' is a tile index in the tile array defined by the most recent call to set_tile_data().

set_map_data(char *map, char w, char h);

Define a tile-index map to be used by load_map(). 'map' is the address of a map of width 'w' (max. 256) and of height 'h' (max. 256).

load_map(char sx, char sy, int mx, int my, char w, char h);

Load a part of a map on the screen. 'sx' and 'sy' are screen coordinates (in tile unit; 16 pixels), 'mx' and 'my' are position in the map, and 'w' and 'h' are respectively the number of tile-index to load horizontaly and verticaly. This function doesn't do any screen clipping, so you must not pass incorrect or too big screen coordinates to it, that would corrupt the video memory.

scroll(char num, int x, int y, char top, char bottom, char disp);

Define screen window 'num'. Up to four window can be defined. 'top' and 'bottom' are the screen top and bottom limits of the window (limits are included in the window area). 'disp' controls the type of the window, if bit 7 is set background graphics will be displayed in this window, and if bit 6 is set sprites will also be displayed. If none of these bits are set the window will stay blank. 'x' and 'y' are the top-left coordinates of the area in the virtual screen that will be displayed in the window.

## SPRITE FUNCTIONS

load_sprites(int vaddr, int *spr_data, int nb_spr);

Load sprite graphics data in video memory, at address 'vaddr'. This function load sprites by chunk of 8 sprites of 16x16 pixels. 'nb_spr' is the number of chunk to load. If you need to load less 16x16 sprites than the eight contained in a chunk, use load_vram() function instead.

init_satb();

Initialize the internal sprite attribute table (SATB) used by the library to handle sprites. This function must be called before any other sprite function is called.

reset_satb();

Reset the internal SATB, this has the effect to disable and reset all the sprites.

satb_update();
satb_update(char nb);

Copy the internal sprite attribute table to the video ram. This will refresh sprites on the screen. Use this function regularly to update the sprite display. The best place to call satb_update() is after every vsync() call, but no need to call satb_update if you didn't change any sprite attribute. 'nb' specifys the number of sprite to refresh; starting from sprite 0. By default the library refreshes only the sprites you use, but if you need to implicitely refresh a certain number of sprites then you can use 'nb'.

spr_set(char num);

Select sprite 'num' (0-63) as the current sprite.

spr_x(int value);

Set the x coordinate of the current sprite. Negative values will make the sprite disappear under the left border, while values higher than the screen width will make it disappear under the right border.

spr_y(int value);

Set the y coordinate of the current sprite.

spr_pattern(int vaddr);

Set the pattern address in video memory of the current sprite.

spr_ctrl(char mask, char value);

Set different attributes of the current sprite. With this function you can change the sprite size (16x16, 32x32, ...) and the sprite orientation (horizontal/vertical flipping).

spr_pal(char pal);

Set the palette-block index (0-15) of the current sprite.

spr_pri(char pri);

Set the priority of the current sprite. '0' will make it appear behind the background (through color 0), '1' will make it appear in front of the background.

spr_get_x();

Return the x coordinate of the current sprite.

spr_get_y();

Return the y coordinate of the current sprite.

spr_get_pal();

Return the palette-block index (0-15) of the current sprite.

spr_get_pattern();

Return the pattern address in video memory of the current sprite.

spr_hide();
spr_hide(char num);

Without parameters this function will hide the current sprite. Use 'num' to hide a different sprite than the current one.

spr_show();
spr_show(char num);

Show a sprite that has been hidden using the spr_hide() function.

## JOYPAD FUNCTIONS

joy(char num);

Return the current status of joypad number 'num'.

joytrg(char num);

Return informations about newly pressed buttons and directions of joypad number 'num'. But beware of this function, these informations are refreshed every frame, so if your game loop is not fast enough you could miss some keypresses. In such a case use the joy_events() functions, they do keep trace of all the keypresses.

set_joy_callback(char num, char mask, char keys, void (*proc)());

You can program the library to call one of your function when a certain joypad key as been pressed. The best use of this function is to handle game pause mode when the player press the START button. 'num' is the numero of the callback to install, for now there's only one callback (0), but future versions of the library may have more. 'mask' indicates which joypad to scan (one bit for each joypad, with bit 0 for joypad 0, etc...), and 'keys' indicates which keypresses to look, usualy just JOY_STRT. 'proc' is the address of the function you want to be called by the library.

get_joy_events(char num);
get_joy_events(char num, char rst);

Return all the joypad keypresses for joypad 'num' that has happened since this function was last called. With this function you can't miss any keypress. 'rst' tells the function if the keypress events will be reset after having being read, by default they are reset after each read, but if 'rst' is equal to zero events won't be reset.

clear_joy_events(char mask);

Reset the joypad keypress event list(s). 'mask' indicates which joypad event list you want to reset. One bit for each joypad, bit 0 is joypad 0, bit 1 is joypad 1, etc... All the event lists can be reset by setting 'mask' to 0x1F.

## MISC FUNCTIONS

poke(int offset, char val);

Write 'val' value at memory location 'offset'. This function can be used to access the hardware I/O ports located at 0x0000 to 0x1FFF.

peek(int offset);

Read the content of memory location 'offset'.

rand();

Return a 16-bit random number.