Engine API

General definitions

The MSX header contains several useful definitions used by other modules.

#include "msx.h".

sys_irq_disable(): Disable interrupts

sys_irq_enable(): Enable interrupts

sys_wait_vsync(): Wait for VSYNC

unused(x): Declare an unused argument to avoid compiler warnings

EOK: Error codes

Sprite Module

The Sprite module provides a software abstraction to handle composite hardware sprites consisting of several layers (colors) and multiple animation states.

It supports dynamic VRAM allocation and automatic calculation of the frames to be displayed based on the current animation state of the sprite.

Up to 48 sprite pattern set definitions can be stored in RAM with 8 states per sprite. The maximum allowed number of planes per frame depends on the sprite size, due to the VDP limit of 4 sprites per row. This value varies from 1 (for 32x32 sprites) to 3 (for 16x16 sprites).

The maximum number of animation steps per state is not defined, but the VDP sets a hard limit of 2KB on the amount of individual patterns that can be allocated at any give time. This amounts to a total 64 frames for 16x16 sprites.

#include "sprite.h".

type SpriteSize

Size of a Sprite

SPR_SIZE_8x8: 8x8 pixel sprite, each frame is a superposition of 8x8 hardware sprites

SPR_SIZE_16x16: 16x16 pixel sprite, each frame is a superposition of 16x16 hardware sprites.

SPR_SIZE_16x32: 16x32 pixel sprite, composed by two 16x16 sprites.

SPR_SIZE_32x16: 32x16 pixel sprite, composed by two 16x16 sprites.

SPR_SIZE_32x32: 32x32 pixel sprite, composed by four 16x16 sprites.

SPR_PATRN_MAX: Max number of patterns that are held in RAM

SPR_STATES_MAX: Max number of states per sprites

SPR_PATRN_COLORS: Number of color lines per sprite in MODE 2

enum spr_state

Set of predefined sprite states that can be used with spr_animate()

SPR_STATE_LEFT: Moving left

SPR_STATE_RIGHT: Moving right

SPR_STATE_UP: Moving up

SPR_STATE_DOWN: Moving down

type SpritePattern: Defines a sprite pattern

struct SpritePattern

Contains a software sprite pattern composed of many individual hardware sprite patterns, along with metadata to describe the structure.

int allocated: Indicates if the pattern has been allocated in VRAM

uint8_t size: Size, see SpriteSize

uint8_t planes: Number of planes (colors)

uint8_t states: Number of states

uint8_t [10] state_steps: Animation steps per state

uint8_t steps: Total number of animation steps

uint8_t *patterns: Raw hardware sprite pattern data

uint8_t *colors: Raw hardware sprite color data

type SpriteDef: Contains a software sprite definition

struct SpriteDef

Contains sprite attributes like position and color, along with the current animation state.

uint8_t state: current sprite state

uint8_t frame: current animation frame

SPR_DEFINE_PATTERN_SET(INDEX, SIZE, PLANES, STATES, STEPS, PATTERNS)

Helper macro for filling in a SpritePattern structure using resource data

Parameters

INDEX – Pattern index (value between 0 and 47)
SIZE – a SpriteSize
PLANES – number of planes
STATES – number of states
STEPS – array containing the number of animation steps per state
PATTERNS – patterns binary data

void spr_init()

Initialize Sprite module: Calling this function clears all defined patters and frees allocations.

void spr_init2(VdpSpriteSize size, VdpSpriteZoom zoom): Initialize Sprite module with non default hardware sprite settings

void spr_refresh()

Apply changes made to SpriteDefs into VRAM

This function should be called after running sys_wait_vsync() and is required for changes due to spr_update() to be visible on screen.

This fuction does 5th sprite detection and interleaving

The first 3 attributes are reserved for the main character sprite and won’t be interleaved to avoid flickering on that sprite. The rest of the sprite attributes are sent in reverse order to ensure the 5th sprite is visible. This works well for 5th sprites in a row, but not for more which requires a more expensive algorithm.

void spr_clear(): Clear all sprites from VRAM and frees all allocations. Preserves defined patterns.

void spr_init_sprite(SpriteDef *sp, uint8_t patrn_idx)

Initializes a SpriteDef structure

Parameters

sp – a SpriteDef object
patrn_idx – sprite pattern set index (0-47)

int spr_valloc_pattern_set()

Allocates VRAM and transfers a SpritePattern making the Sprite ready for visualization.

Parameters

patrn_idx – sprite pattern set index (0-47)

Returns

true if sucess, false is the pattern could not be allocated

void spr_vfree_pattern_set(uint8_t patrn_idx)

Frees the VRAM used by the specified SpritePattern

Parameters

patrn_idx – sprite pattern set index (0-47)

void spr_update(SpriteDef *sp)

Updates a SpriteDef: This function must be called after It is necessary to call spr_refresh() for the changes to be transferred to VRAM and be visible on screen.

Parameters

sp – a SpriteDef object

int spr_show()

Allocates a SpriteDef in VRAM: this function

Parameters

sp – a SpriteDef object

Returns

true on sucess, false if the Sprite could not be allocated

void spr_hide(SpriteDef *sp)

Frees a SpriteDef from VRAM

calling this function removes the Sprite from screen.

It is necessary to call spr_refresh() for the changes to be transferred to VRAM and be visible on screen.

Parameters

sp – SpriteDef object

void spr_set_pos(SpriteDef *sp, int16_t xp, int16_t yp)

Set a Sprite position on screen taking into account off-screen coordinates

It is necessary to call spr_refresh() for the changes to be transferred to VRAM and be visible on screen.

Parameters

sp – a SpriteDef object
xp – x screen coordinate (-32 to 256)
yp – y screen coordinate (-32 to 192)

void spr_animate(SpriteDef *sp, int8_t dx, int8_t dy)

Updates a SpriteDef state and animation frame based on the direction of movement, for a simple case of 2 or 4 states.

Parameters

sp – a SpriteDef object
dx – delta X
dy – delta Y

Tile Module

The Tile module provides a software abstraction to handle a set of tiles defined either as a TileSet or a TileObject.

A TileSet can be defined as a static set of tiles and behave as a container for tile pattern and color definitions. But alternatively can also be defined as dynamic and contain structural information for animation in a similar way as Sprites do (states and frames).

A dynamic TileSet can be used as a pattern into a TileObject to display animated tiles on screen.

#include "tile.h".

type TileBank

Name Table Bank in MODE_GRP2

BANK0: Top Bank

BANK1: Middle Bank

BANK2: Bottom Bank

ALLBANKS: All Banks

type TileSet: Defines a TileSet

struct TileSet

Contents of a TileSet

uint8_t w: TileSet width in pixels

uint8_t h: TileSet height in pixels

uint8_t *pattern: Pointer to the TileSet pattern data

uint8_t *color: Pointer to the TileSet color data

uint8_t pidx: Offset of the TileSet once allocated into VRAM (0 to 255)

int allocated: True if the tileset is allocated in VRAM

int raw: True if the TileSet data is not compressed

uint8_t frame_w: Animation frame width in number tiles

uint8_t frame_h: Animation frame height in number of tiles

uint8_t frames: Number of animation frames within the set

uint8_t states: Number of animation states within the set

type TileMap: Defines a TileMap

struct TileMap: Contents of a TileMap

type TileObject: Defines a TileObject

struct TileObject

Contens of a TileObject

uint8_t x: Screen X position in pixel coordinates

uint8_t y: Screen Y position in pixel coordinates

uint8_t state: Current animation state

uint8_t frame: Current animation frame

TileSet *tileset: Tileset data

INIT_TILE_SET(TS, DATA)

Initialize a Static TileSet

Parameters

TS – a TileSet object
DATA – name of data asset

INIT_RAW_TILE_SET(TS, DATA)

Initialize an uncompressed Static TileSet

Parameters

TS – a TileSet object
DATA – name of data asset

INIT_DYNAMIC_TILE_SET(TS, DATA, W, H, F, S)

Initialize a Dynamic TileSet

Parameters

TS – a TileSet object
DATA – name of data asset
W – frame width of the tileset in tile units
H – frame heigth of the tileset in tile units
F – number of frames per state
S – number of states

INIT_RAW_DYNAMIC_TILE_SET(TS, DATA, W, H, F, S)

Initialize a Dynamic TileSet

Parameters

TS – a TileSet object
DATA – name of data asset
W – frame width of the tileset in tile units
H – frame heigth of the tileset in tile units
F – number of frames
S – number of states

void tile_init(): This function clears all TileSet allocations.

void tile_set_to_vram_bank(TileSet *tileset, TileBank bank, uint8_t offset)

Transfer a compressed Tileset to VRAM into a fixed position and into a specific bank.

This function is useful when a TileMap requires tile defintions to be at a specific offset.

Warning

this function overrides previous TileSet allocations.

Parameters

tileset – TileSet to be transferred
bank – target bank see TileBank
offset – start position inside the target bank to transder the TileSet

void tile_set_to_vram_bank_raw(TileSet *tileset, TileBank bank, uint8_t offset)

Transfer an uncompressed Tileset to VRAM into a fixed position and a specific bank.

This function is useful when a TileMap requires tile defintions to be at a specific offset.

Warning

this function overrides previous TileSet allocations.

Parameters

tileset – TileSet to be transferred
bank – target bank see TileBank
offset – start position inside the target bank to transder the tileset

int tile_set_valloc_bank(TileSet *tileset, TileBank bank)

Allocates and transfers a TileSet to VRAM in a specific tile bank

This function transders uncompressed TileSets to the first available gap in VRAM in the specified bank.

Parameters

tileset – the TileSet to be allocated and transferred

Returns

either EOK or error code

int tile_set_valloc(TileSet *tileset)

Allocates and transfers a TileSet to VRAM.

This function detects compression and transfers the TileSet to the first available gap in VRAM.

Parameters

tileset – the TileSet to be allocated and transferred

Returns

either EOK or error code

void tile_set_to_vram(TileSet *tileset, uint8_t offset)

Transfer a Tileset to VRAM into a fixed position in ALL_BANKS

This function is useful when a TileMap requires tile defintions to be at a specific offset.

Warning

this function overrides previous TileSet allocations.

Parameters

tileset – TileSet to be transferred
offset – start position inside the target bank to transder the tileset

void tile_set_vfree(TileSet *tileset)

Free a previously allocated TileSet

Parameters

tileset – the TileSet to be freed.

void tile_object_show(TileObject *tileobject, uint8_t *scrbuf, int refresh_vram)

Transfers a TileObject into a Buffer and/or VRAM

Parameters

tileobject – the TileObject to be displayed
scrbuf – a screen buffer in RAM
refresh_vram – true for the TileObject to be transferred to VRAM after transferring into the RAM buffer.

allow for shift using idx: this will only work for single frame one direction objects *

void tile_object_hide(TileObject *tileobject, uint8_t *scrbuf, int refresh_vram)

Hide a TileObject by replacing it with zero-tiles

Parameters

to – the TileObject to be hidden
scrbuf – a screen buffer in RAM
refresh_vram – true for the TileObject to be transferred to VRAM after transferring into the RAM buffer.

Font Module

type FontSet

A font set may contain four fonths each providing different types of glyphs: symbols: ascii range 33 to 47 numeric: ascii range 48 to 57 upper: ascii range 65 to 90 lower: ascii range 97 to 122

void font_to_vram(Font *f, uint8_t pos)

void font_to_vram_bank(Font *f, uint8_t bank, uint8_t pos): Uploads a font to vram

void font_color_mask(Font *f, uint8_t color): Applies a color mask to a font already allocated in vram

void font_set_color_mask(FontSet *fs, uint8_t color): Apply color mask to a font set already allocated in vram

void font_printf(FontSet *fs, uint8_t x, uint8_t y, uint8_t *buffer, char *text): print a complex string to a buffer using a font_set

void font_vprintf(FontSet *fs, uint8_t x, uint8_t y, char *text): prints a complex string directly to vram

Display Object Module

type DisplayObject: An object to be displayed as part of a display list.

struct DisplayObject

contents of a DisplayObject

uint8_t type: DisplayObject type, see :c:enum:DisplayObjectType

uint8_t max: Maximum coordinate used for animation

uint8_t min: Minimum coordinate used in animation

uint8_t speed: Speed of movement, used in animation

uint8_t color: Color override, used to in animation

int visible: Indicates if the object should be visible in screen

int check_collision: Indicates if collision detection should be carried out for this object

uint8_t state: Animation state

uint8_t aux: Auxiliary animation data

uint8_t aux2: Auxiliary animation data

int16_t xpos: Current screen position

int16_t ypos: Current screen position

uint8_t collision_state: Current collision state

SpriteDef *spr: Sprite definition

TileObject *tob: TileObject definition

DisplayObject *parent: Parent object, used for animation

type Animator: Contains an animator

dpo_define_animator(ANIMIDX, SYMBOL)

Defines the animator with the given index

Parameters

anim_idx – index of the animator
anim – animator function

void dpo_init(): Initializes the display list

DisplayObject *dpo_new(): Allocates a new DisplayObject

void dpo_clear(): Does garbage collection of DisplayObjects part of the display list

void dpo_display_list_add(DisplayObject *dpo)

Adds a DisplayObject to the display list

Parameters

dpo – DisplayObject to be added

void dpo_init_animators(uint8_t n_animators)

Allocates memory for animators

@param n_animators

void dpo_add_animator(DisplayObject *dpo, uint8_t animidx)

Adds an animator to a Display Object

Parameters

dpo – the DisplayObject
animidx – the animator index

void dpo_show_all(uint8_t *scr_buffer): Shows on a screen buffer all DisplayObjects in the display list

void dpo_animate_all(): Run animations for all DisplayObjects in the display list

Animation Module

Physics Module

The Physics Module provides an abstraction to define what objects in a scene generate collisions and to allow for detecting and handling those collisions during animation.

TileObjects, TileSets and individual tiles can be used to configure collision events that can then be detected during the animation of a DisplayObject.

#include "phys.h".

is_colliding_left(x): Check if a DisplayObject is colliding on the left side

is_colliding_right(x): Check if a DisplayObject is colliding on the right side

is_colliding_down(x): Check if a DisplayObject is colliding on the bottom side

is_colliding_down_ft(x): Check if a DisplayObject is colliding on the bottom side with fallthrough tiles

is_colliding_up(x): Check if a DisplayObject is colliding on the top side

is_colliding_x(x): Check if a DisplayObject is colliding on the x-axis

is_colliding_y(x): Check if a DisplayObject is colliding on the y-axis

is_colliding(x): Check if a DisplayObject is colliding in any direction

type TileCollisionType

Defines the type of tile collision

TILE_COLLISION_FULL: Collision in all directions

TILE_COLLISION_DOWN: Collision only when moving down (falling)

TILE_COLLISION_TRIGGER: Collision that triggers a callback but does not impair movement

TILE_COLLISION_MULTIPLE: Collision from multiple instances of the same objects but potentially with different callbacks

type TileCollisionHandler: Defines a TileCollisionHandler

struct TileCollisionHandler

Contains a TileCollisionHandler

uint8_t page: ascii8 ROM page where the handler is locatted

void (*)(DisplayObject *, uint8_t) handler: handler function pointer

type TileCollisionDef: Defines a set of tiles that generate collision events

struct TileCollisionDef

Contains TileCollisionDef data

uint8_t start: Starting tile index that defines the collision range

uint8_t end: Ending tile index that defines the collision range

uint8_t data: Data to be passed to the handler on collision event

TileCollisionType type: Type of collision

DisplayObject *dpo: DisplayObject to be passed to the handler on collision

TileCollisionHandler callback: Handler to be called on collision event

uint8_t page: page switching

void phys_init()

Initializes the Physics Module

This function clears all types of colliding tiles.

void phys_set_sprite_collision_handler(void (*)() handler)

Sets the Sprite collision handler

Parameters

handler – function to be called when a collision occur

Warning

The collision handler will be called from interrupt context, therefore it should not perform long running operations and must be defined as a __nonbanked function.

void phys_clear_sprite_collision_handler(): Clears the currently configured Sprite collision handler

void phys_set_colliding_tile_object(DisplayObject *dpo, TileCollisionType type, TileCollisionHandler *callback, uint8_t data)

Create a new TileCollisionDef for a DisplayObject

Parameters

dpo – the DisplayObject target for collision detection
type – collision type, see TileCollisionType
handler – a tile collision handler
data – data to be passed to the handler on the event of collision

void phys_set_masked_colliding_tile_object(DisplayObject *dpo, TileCollisionType type, uint8_t x, uint8_t y, uint8_t w, uint8_t h, TileCollisionHandler *callback, uint8_t data)

Create a new TileCollisionDef for a DisplayObject with a Mask

This function narrows down the collision box a DisplayObject before defining the collision.

Parameters

dpo – the DisplayObject target for collision detection
type – collision type, see TileCollisionType
x – left position of the mask in tile coordinates
y – top position of the mask in tile coordinates
w – width of the mask in tile coordinates
h – heigth of the mask in tile coordinates
handler – a tile collision handler
data – data to be passed to the handler on the event of collision

void phys_clear_colliding_tile_object(DisplayObject *dpo)

Clear TileCollisionDefs related to a DisplayObject

Parameters

dpo – DisplayObject to clear collisions for

void phys_set_colliding_tile_set(TileSet *ts): Set /

void phys_set_colliding_tile(uint8_t tile)

Set all collision flags for a specific tile

Parameters

tile – index of the tile to enable collisions for

void phys_set_down_colliding_tile(uint8_t tile)

Set down collision flag for a specific tile

Parameters

tile – index of the tile to enable collisions for

void phys_set_trigger_colliding_tile(uint8_t tile)

Set trigger collision flag for a specific tile

Parameters

tile – index of the tile to enable collisions for

void phys_clear_colliding_tile(uint8_t tile)

Clear all collision flags for a specific tile

Parameters

tile – index of the tile to clear collisions for

void phys_detect_tile_collisions(DisplayObject *dpo, uint8_t *map, int8_t dx, int8_t dy, int duck, int notify)

Detect projected collisions for a DisplayObject

This function updates collision status of the provided DisplayObject and notifies collision handlers if specified in the arguments.

Warning

Only DisplayObjects of type SPRITE and sizes 16x16 and 16x32 are supported.

Parameters

dpo – DisplayObject to check collisions for
map – RAM buffer containing the current map on display
dx – delta x, applied to the DisplayObject current position before checking for collisions
dy – delta y, applied to the DisplayObject current position before checking for collisions
notify – true if listeners should be notified on collision event

Vdp Module

The Vdp module provides functions to configure the Vdp and transfer data from RAM to VRAM.

#include "vdp.h"

type VdpMode

VDP Mode

MODE_TXT: Text Mode (Screen 0)

MODE_GRP1: Graphic Mode 1 (Screen 1)

MODE_GRP2: Graphic Mode 2 (Screen 2)

MODE_MULT: Multicolor Mode (Screen 3)

MODE_GRP3: Graphics Mode 3 (Screen 4, MSX2)

MODE_GRP4: Graphics Mode 4 (Screen 5, MSX2)

MODE_GRP5: Graphics Mode 5 (Screen 6, MSX2)

MODE_GRP6: Graphics Mode 6 (Screen 7, MSX2)

type VdpSpriteSize

Sprite Size

SPR_SIZE_8: Use 8x8 Hardware Sprites

SPR_SIZE_16: Use 16x16 Hardware Sprites

type VdpSpriteZoom

Sprite zoom

SPR_ZOOM_OFF: Disable sprites zoom

SPR_ZOOM_ON: Enable sprite zoom

type VdpColor

Vdp Palette

COLOR_TRANSPARENT

COLOR_BLACK

COLOR_GREEN

COLOR_LIGHTGREEN

COLOR_DIMBLUE

COLOR_BLUE

COLOR_DIMRED

COLOR_LIGHTBLUE

COLOR_RED

COLOR_LIGHTRED

COLOR_YELLOW

COLOR_LIGHTYELLOW

COLOR_DIMGREEN

COLOR_MAGENTA

COLOR_GREY

COLOR_WHITE

type VdpRGBColor: Defines an 9-bit RGB color

struct VdpRGBColor

Contains an 9-bit RGB color

uint8_t r: red component (0 to 7)

uint8_t g: green component (0 to 7)

uint8_t b: blue component (0 to 7)

type VdpCommandType: Vdp Blit Command Types

type VdpCommandLogicType: Vdp Logical modifiers for Logical operations

type VdpCommand: Defines an vdp command

struct VdpCommand

Contains a vdp command definition

uint16_t sx: Source screen coordinate x

uint16_t sy: Source screen coordinate y

uint16_t dx: Destination screen coordinate x

uint16_t dy: Destination screen coordinate y

uint16_t nx: Number of pixels in x axis

uint16_t ny: Number of pixels in y axis

uint8_t color: Color

uint8_t destdir: Transfer destination and direction

uint8_t command: Actual command to be executed

void vdp_screen_disable(): Disable Screen

void vdp_screen_enable(): Enable Screen

void vdp_set_mode(VdpMode mode)

Set VDP mode

Parameters

mode – see VdpMode

VdpMode vdp_get_mode()

Gets currently set mode

Returns: mode see VdpMode

uint8_t vdp_5th_sprite()

Checks 5th sprite collision flag

Warning

This function must be called right after sys_wait_vsync()

Returns: index of the 5th sprite attribute, or zero

void vdp_set_color(VdpColor ink, VdpColor border)

Sets foreground and border screen color

Parameters

ink – see VdpColor
border – see VdpColor

Sets a complete palette and saves it to VRAM (MSX2)

param palette: a RGB color array with 16 elements

Sets a palette color and saves it to VRAM (MSX2)

param index: palette index to set (0 to 15)
param color: RGB color definition

Sets current VRAM 16Kb page to access up to 128Kb

param page: vram page to be selected (0 to 7)

Execute a VDP command

param cmd: see :c:typedef:`VdpCommand`

void vdp_write(uint16_t address, uint8_t value)

Write a single byte to VRAM

Parameters

address – VRAM address (0 to 16384)
value – byte to be written

void vdp_memset(uint16_t vaddress, uint16_t size, uint8_t value)

Writes value into an VRAM range

Parameters

vaddress – VRAM target address (0 to 16384)
size – number of bytes to write
value – byte to be written

void vdp_memcpy(uint16_t vaddress, uint8_t *buffer, uint16_t size)

Copy block from RAM to VRAM

Parameters

vaddress – VRAM target address (0 to 16384)
buffer – pointer to RAM source
size – number of bytes to copy

void vdp_memcpy_vda(uint8_t *buffer)

Copy buffer with built-in address information to VRAM

This function is equivalent to BLOAD””,S in Basic

Parameters

buffer – pointer to RAM source

void vdp_init_hw_sprites(VdpSpriteSize spritesize, VdpSpriteZoom zoom)

Initialize VDP sprites

Parameters

spritesize – see VdpSpriteSize
zoom – see VdpSpriteZoom

void vdp_fastcopy_nametable(uint8_t *buffer)

Fast copy of a RAM buffer of 768 bytes to VRAM, on the name table.

This function provides a faster way to refresh tiles on the screen.

Parameters

buffer – pointer to RAM buffer of 768 bytes

Decompress and Copy a RAM buffer into VRAM

This function performs Run-Length-Encoding decompression, and can be used to tranfer big compressed assets (pattern definitions) to VRAM

param vaddress: VRAM target address
param buffer: pointer to source RAM buffer
param size: size of decompressed buffer

void vdp_clear(VdpColor color): Clears screen by filling the name table with zeros and defining a tile with index zero and the provided color.

void vdp_puts(char x, char y, char *msg)

Writes a String to VRAM on mode MODE_GRP1

Parameters

x – x coordinate (0-32)
y – y coordinate (0-24)
msg – String to be written

System Module

void sys_reboot(): Reboot the machine.

void sys_disable_kbd_click(): Disable keyboard click sound using BIOS

void sys_set_turbo(): Sets CPU Mode to R800 DRAM

uint8_t sys_get_keyrow(uint8_t line): Read Keyboard Matrix status using BIOS

uint16_t sys_get_mouse(uint8_t port)

Read Mouse Offset

Parameters

port – device port (12 for port A, 16 for port B)

Returns

16bits containing signed offset for X (MSB) and Y (LSB) relative to last mouse position.

uint8_t sys_get_char(): Gets character from keyboard buffer without wait

uint8_t sys_get_trigger(uint8_t port): Get trigger status using BIOS

uint8_t sys_get_stick(uint8_t port): Get Joystick status using BIOS

void sys_memcpy(uint8_t *dst, uint8_t *src, uint16_t size): Copy memory

void sys_irq_register(void (*)() func)

sys_irq_register:: register a function to be run from the interrupt handler any registered caller must run with _interrupts disabled_

void sys_irq_unregister(void (*)() func): Unregister secondary

void sys_irq_init()

Initialize the engine IRQ handler.

Calling this function is necessary for

void sys_sleep_ms(uint16_t msecs)

Blocks main thread for an amount of miliseconds.

Parameters

msecs – amount of miliseconds to sleep

void sys_sleep(uint16_t secs)

Blocks main thread for an amount of seconds. During this time only the IRQ handler is run.

Parameters

secs – number of seconds to sleep

uint16_t sys_gettime_secs(): Returns elapsed time since call to sys_irq_init

uint16_t sys_gettime_msec(): Returns elapsed time miliseconds

uint16_t sys_get_ticks()

Returns current system ticks count

Returns: system ticks (50/60Hz)

void sys_rand_init(uint8_t *seed)

Initialized seed of random number generator

Parameters

seed – pointer to a 64bit seed

uint8_t sys_rand()

Generates a random number using LFSR

Returns: random byte

int sys_is60Hz(): Returns true if running on a 60Hz MSX machine

Sound Effects Module

void sfx_setup(uint8_t *bank)

Setup SFX bank

Parameters

bank – binary data containing a bank of sound effects

void sfx_play_effect(uint8_t effect, uint8_t priority)

Play a sound effect: set up a sound effect from the current bank with specific priority to be played

Parameters

effect – index for effect to be played inside the current bank
priority – value from 0 (higher) to 255 (lower) priority

void sfx_play()

Play next note of the currently selected sound effect: this function should be called after sfx_play_effect

Vortex Tracker Module

void pt3_mute(): Silence the PSG

void pt3_init(uint8_t *song, uint8_t loop)

Initialize the PT3 Module

Parameters

song – a PT3 song in binary format
loop – indicates whether the song should loop (0:no, 1: yes)

void pt3_init_notes(uint8_t *note_table)

Initialize PT3 note table: there are 4 available note tables in files pt3_nt0.h, pt3_nt1.h pt3_nt2.h and pt3_nt3.h. One of those files should be included to load the definition on a note table in the global variable NT. After that this function can be called passing NT as parameter.

Parameters

note_table – a PT3 note table in binary format.

void pt3_play()

Play a current set of notes.: This function should be called after pt3_decode

void pt3_decode()

Decode the following note of the song: this function should be called before pt3_play

SCC Module

The SCC module provides low level access to Konami Sound Custom Chips.

int scc_init()

Initializes an SCC by attempting detection

Returns: true if the SCC was detected and initialized successfully, false otherwise

void scc_enable(uint8_t chan)

Enables a set of SCC channels

Parameters

chan – masked list of channels to be enabled (bits 0-5)

void scc_mute(uint8_t chan)

Mutes a set of SCC channels

Parameters

chan – maked list of channels to be muted (0-5)

void scc_set_wave(uint8_t chan, uint8_t *data)

Set the the 32-byte wave table for specific channel

Warning

wave data must be placed in an address other than 2 (0x8000-0xBFFF) as that page is switched to the ROM slot containing the SCC when calling this function

Parameters

chan – channel (1-5)
data – 32-byte buffer containing the wave table

void scc_set_vol(uint8_t chan, uint8_t vol)

Set volume for a specific SCC channel

Parameters

chan – channel (1-5)
vol – Volume (0-15)

void scc_set_freq(uint8_t chan, uint16_t freq)

Set the frequency for a specific SCC channel

Parameters

chan – channel (1-5)
freq – frequency

Map Module

void map_inflate(const uint8_t *dict, uint8_t *in, uint8_t *out, uint16_t data_size, uint8_t w)

read a buffer an expand it using a 4x4 tile dictionary: this provides a fixed ratio of 1/4 and decompression buffer size is fixed.

width of the map is needed out buffer needs to be 4 times data_size

void __map_inflate_screen(const uint8_t *dict, uint16_t *in, uint8_t *out, uint8_t w, uint8_t vpx, uint8_t vpy): Inflate only a 32x24 window of the map to a buffer, useful if the map is too big to be decompressed entirely.

Utility Modules

ROM Mapper

ascii8_get_page(SYMBOL): Gets the ASCII8 ROM page from a symbol and stores it in ascii8_page

void ascii8_set_data(uint8_t page): Set ASCII8 mapper DATA bank to the specified page (0xA000-0xBFFF)

ascii8_set_code(page): Set ASCII8 mapper CODE bank to the specified page (0x8000-0x9FFF)

ascii8_restore_code(page): Restore ASCII8 mapper code bank to the last used page

Timers

void timer_init(): Initialize the timer module.

void timer_define(Timer * timer, void (*)(uint8_t) func, uint16_t expires, int repeat)

Define a Timer

Parameters

timer – Timer object
func – Callback function to be called on expiration
expires – Time to expiration in tics (50/60Hz)
repeat – True to repeat after expiration

void timer_add(Timer *timer, uint8_t data)

Activate a Timer

Parameters

timer – reference to the Timer to activate
data – byte to be passed on to the timer callback

void timer_del(Timer *timer)

Deactivate a Timer

Parameters

timer – reference to the timer to deactivate

uint16_t timer_msecs_to_tics(uint16_t msecs)

Convert time to tics taking into account interrupt rate on the machine running the Timer.

Parameters

msecs – miliseconds

Returns uint16_t

tics

Bitmaps

bitmap_find_gap:: find a sequence of n 1s in the bitmap

Lists

type List: Defines a List Object

struct List

Contents of a List

List *next: pointer to the next element

List *prev: pointer to the previous element

list_entry(ptr, type, member)

Get the current object pointed to by a list entry

Parameters

ptr – the List entry pointer.
type – the type of object embedded in.
member – the name of the List within the struct.

list_for_each(pos, head)

Iterate over a list

Parameters

pos – the &List to use as a loop cursor.
head – the head for your list.

void INIT_LIST_HEAD(List *list)

Initialize a List object

Parameters

list – pointer to the List object

void list_add(List *new, List *head)

Add a new entry to a List after the specified head.

Parameters

new – new entry to be added
head – List head to add it after

void list_del(List *entry)

Deletes entry from a list

Parameters

entry – the element to delete from the list.

Dynamic Memory Allocator

Simple dynamic memory allocator that allows to use the available RAM between the end of the DATA segment and the bottom of the Stack.

Note that this allocator is a minimal implementation that doesn’t optimize for best block fit or do coalescence of unallocated blocks. Repeated calls to free and alloc will fragment the heap and result in a very inefficient use of memory.

This allocator is best used by only allocating blocks, and not calling free.

HEAP_MAX: Defines the bottom of the Stack

void mem_init(): Initializes the memory allocator by finding the amount of RAM available between the end of the DATA segment and the bottom of the Stack.

void *mem_alloc(int size)

Attemps to allocate a block of the requested size.

Parameters

size – Size of the block to be allocated

Returns

void* pointer to the allocated block or NULL

void mem_free(void *block)

Free a previously allocated block.

Parameters

block – Memory block to be freed.

void *mem_calloc(int num, int nsize)

Allocates an array of elements and sets to zero.

Parameters

num – Number of elements
nsize – Size of each element

Returns

void* pointer to the allocated block or NULL

Debug

void putchar(char c): send a char to the debug port

void log(int level, char *fmt, ...)

log: debug log trough printer port, useful when running in openmsx