GBDK 2020 Docs  4.3.0
API Documentation for GBDK 2020
msx.h File Reference
#include <types.h>
#include <stdint.h>
#include <gbdk/version.h>
#include <msx/hardware.h>

Go to the source code of this file.

Data Structures

struct  joypads_t
 
struct  OAM_item_t
 

Macros

#define MSX
 
#define SYSTEM_60HZ   0x00
 
#define SYSTEM_50HZ   0x01
 
#define VBK_REG   VDP_ATTR_SHIFT
 
#define J_UP   0b00100000
 
#define J_DOWN   0b01000000
 
#define J_LEFT   0b00010000
 
#define J_RIGHT   0b10000000
 
#define J_A   0b00000001
 
#define J_B   0b00000100
 
#define J_SELECT   0b00001000
 
#define J_START   0b00000010
 
#define M_TEXT_OUT   0x02U
 
#define M_TEXT_INOUT   0x03U
 
#define M_NO_SCROLL   0x04U
 
#define M_NO_INTERP   0x08U
 
#define S_BANK   0x01U
 
#define S_FLIPX   0x02U
 
#define S_FLIPY   0x04U
 
#define S_PALETTE   0x08U
 
#define S_PRIORITY   0x10U
 
#define S_PAL(n)   (((n) & 0x01U) << 3)
 
#define __WRITE_VDP_REG_UNSAFE(REG, v)   shadow_##REG=(v),VDP_CMD=(shadow_##REG),VDP_CMD=REG
 
#define __WRITE_VDP_REG(REG, v)   shadow_##REG=(v);__asm__("di");VDP_CMD=(shadow_##REG);VDP_CMD=REG;__asm__("ei")
 
#define __READ_VDP_REG(REG)   shadow_##REG
 
#define EMPTY_IFLAG   0x00U
 
#define VBL_IFLAG   0x01U
 
#define LCD_IFLAG   0x02U
 
#define TIM_IFLAG   0x04U
 
#define SIO_IFLAG   0x08U
 
#define JOY_IFLAG   0x10U
 
#define SCREENWIDTH   DEVICE_SCREEN_PX_WIDTH
 
#define SCREENHEIGHT   DEVICE_SCREEN_PX_HEIGHT
 
#define MINWNDPOSX   0x00U
 
#define MINWNDPOSY   0x00U
 
#define MAXWNDPOSX   0x00U
 
#define MAXWNDPOSY   0x00U
 
#define DISPLAY_ON    __WRITE_VDP_REG(VDP_R1, __READ_VDP_REG(VDP_R1) |= R1_DISP_ON)
 
#define DISPLAY_OFF    display_off();
 
#define HIDE_LEFT_COLUMN    __WRITE_VDP_REG(VDP_R0, __READ_VDP_REG(VDP_R0) |= R0_LCB)
 
#define SHOW_LEFT_COLUMN    __WRITE_VDP_REG(VDP_R0, __READ_VDP_REG(VDP_R0) &= (~R0_LCB))
 
#define SET_BORDER_COLOR(C)   __WRITE_VDP_REG(VDP_R7, ((C) | 0xf0u))
 
#define SHOW_BKG
 
#define HIDE_BKG
 
#define SHOW_WIN
 
#define HIDE_WIN
 
#define SHOW_SPRITES
 
#define HIDE_SPRITES
 
#define SPRITES_16x16    __WRITE_VDP_REG(VDP_R1, __READ_VDP_REG(VDP_R1) |= R1_SPR_16X16)
 
#define SPRITES_8x8    __WRITE_VDP_REG(VDP_R1, __READ_VDP_REG(VDP_R1) &= (~R1_SPR_16X16))
 
#define DEVICE_SUPPORTS_COLOR   (TRUE)
 
#define DIV_REG   get_r_reg()
 
#define CURRENT_BANK   _current_bank
 
#define BANK(VARNAME)   ( (uint8_t) & __bank_ ## VARNAME )
 
#define BANKREF(VARNAME)
 
#define BANKREF_EXTERN(VARNAME)   extern const void __bank_ ## VARNAME;
 
#define SWITCH_ROM1   SWITCH_ROM
 
#define SWITCH_ROM2(b)   MAP_FRAME2=(b)
 
#define SWITCH_RAM(b)   RAM_CONTROL=((b)&1)?RAM_CONTROL|RAMCTL_BANK:RAM_CONTROL&(~RAMCTL_BANK)
 
#define ENABLE_RAM   RAM_CONTROL|=RAMCTL_RAM
 
#define DISABLE_RAM   RAM_CONTROL&=(~RAMCTL_RAM)
 
#define set_bkg_palette_entry   set_palette_entry
 
#define set_sprite_palette_entry(palette, entry, rgb_data)   set_palette_entry(1,entry,rgb_data)
 
#define set_bkg_palette   set_palette
 
#define set_sprite_palette(first_palette, nb_palettes, rgb_data)   set_palette(1,1,rgb_data)
 
#define COMPAT_PALETTE(C0, C1, C2, C3)   (((uint16_t)(C3) << 12) | ((uint16_t)(C2) << 8) | ((uint16_t)(C1) << 4) | (uint16_t)(C0))
 
#define set_bkg_tiles   set_tile_map
 
#define set_win_tiles   set_tile_map
 
#define fill_bkg_rect   fill_rect
 
#define fill_win_rect   fill_rect
 
#define DISABLE_VBL_TRANSFER    _shadow_OAM_base = 0
 
#define ENABLE_VBL_TRANSFER    _shadow_OAM_base = (uint8_t)((uint16_t)&shadow_OAM >> 8)
 
#define MAX_HARDWARE_SPRITES   32
 
#define HARDWARE_SPRITE_CAN_FLIP_X   0
 
#define HARDWARE_SPRITE_CAN_FLIP_Y   0
 
#define set_bkg_tile_xy   set_tile_xy
 
#define set_win_tile_xy   set_tile_xy
 
#define get_win_xy_addr   get_bkg_xy_addr
 

Typedefs

typedef void(* int_handler) (void) NONBANKED
 
typedef struct OAM_item_t OAM_item_t
 

Functions

void WRITE_VDP_CMD (uint16_t cmd) Z88DK_FASTCALL PRESERVES_REGS(b
 
void WRITE_VDP_DATA (uint16_t data) Z88DK_FASTCALL PRESERVES_REGS(b
 
void mode (uint8_t m) OLDCALL
 
uint8_t get_mode (void) OLDCALL
 
uint8_t get_system (void)
 
void set_interrupts (uint8_t flags) Z88DK_FASTCALL
 
void remove_VBL (int_handler h) Z88DK_FASTCALL PRESERVES_REGS(iyh
 
void remove_LCD (int_handler h) Z88DK_FASTCALL PRESERVES_REGS(b
 
void remove_TIM (int_handler h) Z88DK_FASTCALL
 
void remove_SIO (int_handler h) Z88DK_FASTCALL
 
void remove_JOY (int_handler h) Z88DK_FASTCALL
 
void add_VBL (int_handler h) Z88DK_FASTCALL PRESERVES_REGS(d
 
void add_LCD (int_handler h) Z88DK_FASTCALL PRESERVES_REGS(b
 
void add_TIM (int_handler h) Z88DK_FASTCALL
 
void add_SIO (int_handler h) Z88DK_FASTCALL
 
void add_JOY (int_handler h) Z88DK_FASTCALL
 
uint8_t cancel_pending_interrupts (void)
 
void move_bkg (uint8_t x, uint8_t y)
 
void scroll_bkg (int8_t x, int8_t y)
 
void vsync (void) PRESERVES_REGS(b
 
void wait_vbl_done (void) PRESERVES_REGS(b
 
void display_off (void)
 
void refresh_OAM (void)
 
uint8_t get_r_reg (void) PRESERVES_REGS(b
 
void SWITCH_ROM (uint8_t bank) Z88DK_FASTCALL PRESERVES_REGS(b
 
void delay (uint16_t d) Z88DK_FASTCALL
 
uint8_t joypad (void) OLDCALL PRESERVES_REGS(b
 
uint8_t waitpad (uint8_t mask) Z88DK_FASTCALL PRESERVES_REGS(b
 
void waitpadup (void) PRESERVES_REGS(b
 
uint8_t joypad_init (uint8_t npads, joypads_t *joypads) Z88DK_CALLEE
 
void joypad_ex (joypads_t *joypads) Z88DK_FASTCALL PRESERVES_REGS(iyh
 
void enable_interrupts (void) PRESERVES_REGS(a
 
void disable_interrupts (void) PRESERVES_REGS(a
 
void set_default_palette (void)
 
void cpu_fast (void)
 
void set_palette_entry (uint8_t palette, uint8_t entry, uint16_t rgb_data) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void set_palette (uint8_t first_palette, uint8_t nb_palettes, const palette_color_t *rgb_data) Z88DK_CALLEE
 
void set_native_tile_data (uint16_t start, uint16_t ntiles, const void *src) Z88DK_CALLEE
 
void set_bkg_4bpp_data (uint16_t start, uint16_t ntiles, const void *src)
 
void set_sprite_1bpp_data (uint16_t start, uint16_t ntiles, const void *src) Z88DK_CALLEE
 
void set_native_sprite_data (uint16_t start, uint16_t ntiles, const void *src)
 
void set_2bpp_palette (uint16_t palette)
 
void set_bkg_data (uint16_t start, uint16_t ntiles, const void *src)
 
void set_sprite_data (uint16_t start, uint16_t ntiles, const void *src)
 
void set_1bpp_colors (uint8_t fgcolor, uint8_t bgcolor)
 
void set_tile_1bpp_data (uint16_t start, uint16_t ntiles, const void *src, uint16_t colors) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void set_bkg_1bpp_data (uint16_t start, uint16_t ntiles, const void *src)
 
void set_data (uint16_t dst, const void *src, uint16_t size) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void vmemcpy (uint16_t dst, const void *src, uint16_t size) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void set_tile_map (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *tiles) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void set_bkg_based_tiles (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *tiles, uint8_t base_tile)
 
void set_win_based_tiles (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *tiles, uint8_t base_tile)
 
void set_tile_submap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, uint8_t map_w, const uint8_t *map) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void set_tile_submap_compat (uint8_t x, uint8_t y, uint8_t w, uint8_t h, uint8_t map_w, const uint8_t *map) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void set_bkg_submap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w)
 
void set_win_submap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w)
 
void set_bkg_based_submap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w, uint8_t base_tile)
 
void set_win_based_submap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w, uint8_t base_tile)
 
void fill_rect (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint16_t tile) Z88DK_CALLEE PRESERVES_REGS(iyh
 
void SET_SHADOW_OAM_ADDRESS (void *address)
 
void set_sprite_tile (uint8_t nb, uint8_t tile)
 
uint8_t get_sprite_tile (uint8_t nb)
 
void set_sprite_prop (uint8_t nb, uint8_t prop)
 
uint8_t get_sprite_prop (uint8_t nb)
 
void move_sprite (uint8_t nb, uint8_t x, uint8_t y)
 
void scroll_sprite (uint8_t nb, int8_t x, int8_t y)
 
void hide_sprite (uint8_t nb)
 
void set_vram_byte (uint8_t *addr, uint8_t v) Z88DK_CALLEE PRESERVES_REGS(iyh
 
uint8_tset_attributed_tile_xy (uint8_t x, uint8_t y, uint16_t t) Z88DK_CALLEE PRESERVES_REGS(iyh
 
uint8_tset_tile_xy (uint8_t x, uint8_t y, uint8_t t) Z88DK_CALLEE PRESERVES_REGS(iyh
 
uint8_tget_bkg_xy_addr (uint8_t x, uint8_t y) Z88DK_CALLEE PRESERVES_REGS(iyh
 

Variables

const uint8_t _SYSTEM
 
void c
 
void d
 
void e
 
void iyh
 
void iyl
 
void h
 
void l
 
volatile uint16_t sys_time
 
volatile uint8_t _current_bank
 
void b
 
uint16_t _current_2bpp_palette
 
uint16_t _current_1bpp_colors
 
uint8_t _map_tile_offset
 
uint8_t _submap_tile_offset
 
volatile struct OAM_item_t shadow_OAM []
 
volatile uint8_t _shadow_OAM_base
 
volatile uint8_t _shadow_OAM_OFF
 

Detailed Description

MSX specific functions.

Macro Definition Documentation

◆ MSX

#define MSX

◆ SYSTEM_60HZ

#define SYSTEM_60HZ   0x00

◆ SYSTEM_50HZ

#define SYSTEM_50HZ   0x01

◆ VBK_REG

#define VBK_REG   VDP_ATTR_SHIFT

◆ J_UP

#define J_UP   0b00100000

Joypad bits. A logical OR of these is used in the wait_pad and joypad functions. For example, to see if the B button is pressed try

uint8_t keys; keys = joypad(); if (keys & J_B) { ... }

See also
joypad

◆ J_DOWN

#define J_DOWN   0b01000000

◆ J_LEFT

#define J_LEFT   0b00010000

◆ J_RIGHT

#define J_RIGHT   0b10000000

◆ J_A

#define J_A   0b00000001

◆ J_B

#define J_B   0b00000100

◆ J_SELECT

#define J_SELECT   0b00001000

◆ J_START

#define J_START   0b00000010

◆ M_TEXT_OUT

#define M_TEXT_OUT   0x02U

Screen modes. Normally used by internal functions only.

See also
mode()

◆ M_TEXT_INOUT

#define M_TEXT_INOUT   0x03U

◆ M_NO_SCROLL

#define M_NO_SCROLL   0x04U

Set this in addition to the others to disable scrolling

If scrolling is disabled, the cursor returns to (0,0)

See also
mode()

◆ M_NO_INTERP

#define M_NO_INTERP   0x08U

Set this to disable interpretation

See also
mode()

◆ S_BANK

#define S_BANK   0x01U

The nineth bit of the tile id

◆ S_FLIPX

#define S_FLIPX   0x02U

If set the background tile will be flipped horizontally.

◆ S_FLIPY

#define S_FLIPY   0x04U

If set the background tile will be flipped vertically.

◆ S_PALETTE

#define S_PALETTE   0x08U

If set the background tile palette.

◆ S_PRIORITY

#define S_PRIORITY   0x10U

If set the background tile priority.

◆ S_PAL

#define S_PAL (   n)    (((n) & 0x01U) << 3)

Defines how palette number is encoded in OAM. Required for the png2asset tool's metasprite output.

◆ __WRITE_VDP_REG_UNSAFE

#define __WRITE_VDP_REG_UNSAFE (   REG,
 
)    shadow_##REG=(v),VDP_CMD=(shadow_##REG),VDP_CMD=REG

◆ __WRITE_VDP_REG

#define __WRITE_VDP_REG (   REG,
 
)    shadow_##REG=(v);__asm__("di");VDP_CMD=(shadow_##REG);VDP_CMD=REG;__asm__("ei")

◆ __READ_VDP_REG

#define __READ_VDP_REG (   REG)    shadow_##REG

◆ EMPTY_IFLAG

#define EMPTY_IFLAG   0x00U

Disable calling of interrupt service routines

◆ VBL_IFLAG

#define VBL_IFLAG   0x01U

VBlank Interrupt occurs at the start of the vertical blank.

During this period the video ram may be freely accessed.

See also
set_interrupts(),
add_VBL

◆ LCD_IFLAG

#define LCD_IFLAG   0x02U

LCD Interrupt when triggered by the STAT register.

See also
set_interrupts(),
add_LCD

◆ TIM_IFLAG

#define TIM_IFLAG   0x04U

Does nothing on MSX

◆ SIO_IFLAG

#define SIO_IFLAG   0x08U

Does nothing on MSX

◆ JOY_IFLAG

#define JOY_IFLAG   0x10U

Does nothing on MSX

◆ SCREENWIDTH

#define SCREENWIDTH   DEVICE_SCREEN_PX_WIDTH

Width of the visible screen in pixels.

◆ SCREENHEIGHT

#define SCREENHEIGHT   DEVICE_SCREEN_PX_HEIGHT

Height of the visible screen in pixels.

◆ MINWNDPOSX

#define MINWNDPOSX   0x00U

The Minimum X position of the Window Layer (Left edge of screen)

See also
move_win()

◆ MINWNDPOSY

#define MINWNDPOSY   0x00U

The Minimum Y position of the Window Layer (Top edge of screen)

See also
move_win()

◆ MAXWNDPOSX

#define MAXWNDPOSX   0x00U

The Maximum X position of the Window Layer (Right edge of screen)

See also
move_win()

◆ MAXWNDPOSY

#define MAXWNDPOSY   0x00U

The Maximum Y position of the Window Layer (Bottom edge of screen)

See also
move_win()

◆ DISPLAY_ON

#define DISPLAY_ON    __WRITE_VDP_REG(VDP_R1, __READ_VDP_REG(VDP_R1) |= R1_DISP_ON)

Turns the display back on.

See also
display_off, DISPLAY_OFF

◆ DISPLAY_OFF

#define DISPLAY_OFF    display_off();

Turns the display off immediately.

See also
display_off, DISPLAY_ON

◆ HIDE_LEFT_COLUMN

#define HIDE_LEFT_COLUMN    __WRITE_VDP_REG(VDP_R0, __READ_VDP_REG(VDP_R0) |= R0_LCB)

Blanks leftmost column, so it is not garbaged when you use horizontal scroll

See also
SHOW_LEFT_COLUMN

◆ SHOW_LEFT_COLUMN

#define SHOW_LEFT_COLUMN    __WRITE_VDP_REG(VDP_R0, __READ_VDP_REG(VDP_R0) &= (~R0_LCB))

Shows leftmost column

See also
HIDE_LEFT_COLUMN

◆ SET_BORDER_COLOR

#define SET_BORDER_COLOR (   C)    __WRITE_VDP_REG(VDP_R7, ((C) | 0xf0u))

Sets border color

◆ SHOW_BKG

#define SHOW_BKG

Turns on the background layer. Not yet implemented

◆ HIDE_BKG

#define HIDE_BKG

Turns off the background layer. Not yet implemented

◆ SHOW_WIN

#define SHOW_WIN

Turns on the window layer Not yet implemented

◆ HIDE_WIN

#define HIDE_WIN

Turns off the window layer. Not yet implemented

◆ SHOW_SPRITES

#define SHOW_SPRITES

Turns on the sprites layer. Not yet implemented

◆ HIDE_SPRITES

#define HIDE_SPRITES

Turns off the sprites layer. Not yet implemented

◆ SPRITES_16x16

#define SPRITES_16x16    __WRITE_VDP_REG(VDP_R1, __READ_VDP_REG(VDP_R1) |= R1_SPR_16X16)

Sets sprite size to 8x16 pixels, two tiles one above the other.

◆ SPRITES_8x8

#define SPRITES_8x8    __WRITE_VDP_REG(VDP_R1, __READ_VDP_REG(VDP_R1) &= (~R1_SPR_16X16))

Sets sprite size to 8x8 pixels, one tile.

◆ DEVICE_SUPPORTS_COLOR

#define DEVICE_SUPPORTS_COLOR   (TRUE)

Macro returns TRUE if device supports color (it always does on MSX)

◆ DIV_REG

#define DIV_REG   get_r_reg()

◆ CURRENT_BANK

#define CURRENT_BANK   _current_bank

◆ BANK

#define BANK (   VARNAME)    ( (uint8_t) & __bank_ ## VARNAME )

Obtains the bank number of VARNAME

Parameters
VARNAMEName of the variable which has a __bank_VARNAME companion symbol which is adjusted by bankpack

Use this to obtain the bank number from a bank reference created with BANKREF().

See also
BANKREF_EXTERN(), BANKREF()

◆ BANKREF

#define BANKREF (   VARNAME)
Value:
void __func_ ## VARNAME(void) __banked __naked { \
__asm \
.local b___func_ ## VARNAME \
___bank_ ## VARNAME = b___func_ ## VARNAME \
.globl ___bank_ ## VARNAME \
__endasm; \
}

Creates a reference for retrieving the bank number of a variable or function

Parameters
VARNAMEVariable name to use, which may be an existing identifier
See also
BANK() for obtaining the bank number of the included data.

More than one BANKREF() may be created per file, but each call should always use a unique VARNAME.

Use BANKREF_EXTERN() within another source file to make the variable and it's data accesible there.

◆ BANKREF_EXTERN

#define BANKREF_EXTERN (   VARNAME)    extern const void __bank_ ## VARNAME;

Creates extern references for accessing a BANKREF() generated variable.

Parameters
VARNAMEName of the variable used with BANKREF()

This makes a BANKREF() reference in another source file accessible in the current file for use with BANK().

See also
BANKREF(), BANK()

◆ SWITCH_ROM1

#define SWITCH_ROM1   SWITCH_ROM

◆ SWITCH_ROM2

#define SWITCH_ROM2 (   b)    MAP_FRAME2=(b)

Makes switch the active ROM bank in frame 2

Parameters
bROM bank to switch to

◆ SWITCH_RAM

#define SWITCH_RAM (   b)    RAM_CONTROL=((b)&1)?RAM_CONTROL|RAMCTL_BANK:RAM_CONTROL&(~RAMCTL_BANK)

Switches RAM bank

Parameters
bSRAM bank to switch to

◆ ENABLE_RAM

#define ENABLE_RAM   RAM_CONTROL|=RAMCTL_RAM

Enables RAM

◆ DISABLE_RAM

#define DISABLE_RAM   RAM_CONTROL&=(~RAMCTL_RAM)

Disables RAM

◆ set_bkg_palette_entry

#define set_bkg_palette_entry   set_palette_entry

◆ set_sprite_palette_entry

#define set_sprite_palette_entry (   palette,
  entry,
  rgb_data 
)    set_palette_entry(1,entry,rgb_data)

◆ set_bkg_palette

#define set_bkg_palette   set_palette

◆ set_sprite_palette

#define set_sprite_palette (   first_palette,
  nb_palettes,
  rgb_data 
)    set_palette(1,1,rgb_data)

◆ COMPAT_PALETTE

#define COMPAT_PALETTE (   C0,
  C1,
  C2,
  C3 
)    (((uint16_t)(C3) << 12) | ((uint16_t)(C2) << 8) | ((uint16_t)(C1) << 4) | (uint16_t)(C0))

◆ set_bkg_tiles

#define set_bkg_tiles   set_tile_map

◆ set_win_tiles

#define set_win_tiles   set_tile_map

◆ fill_bkg_rect

#define fill_bkg_rect   fill_rect

◆ fill_win_rect

#define fill_win_rect   fill_rect

◆ DISABLE_VBL_TRANSFER

#define DISABLE_VBL_TRANSFER    _shadow_OAM_base = 0

Disable shadow OAM to VRAM copy on each VBlank

◆ ENABLE_VBL_TRANSFER

#define ENABLE_VBL_TRANSFER    _shadow_OAM_base = (uint8_t)((uint16_t)&shadow_OAM >> 8)

Enable shadow OAM to VRAM copy on each VBlank

◆ MAX_HARDWARE_SPRITES

#define MAX_HARDWARE_SPRITES   32

Amount of hardware sprites in OAM

◆ HARDWARE_SPRITE_CAN_FLIP_X

#define HARDWARE_SPRITE_CAN_FLIP_X   0

True if sprite hardware can flip sprites by X (horizontally)

◆ HARDWARE_SPRITE_CAN_FLIP_Y

#define HARDWARE_SPRITE_CAN_FLIP_Y   0

True if sprite hardware can flip sprites by Y (vertically)

◆ set_bkg_tile_xy

#define set_bkg_tile_xy   set_tile_xy

◆ set_win_tile_xy

#define set_win_tile_xy   set_tile_xy

◆ get_win_xy_addr

#define get_win_xy_addr   get_bkg_xy_addr

Typedef Documentation

◆ int_handler

typedef void(* int_handler) (void) NONBANKED

Interrupt handlers

◆ OAM_item_t

typedef struct OAM_item_t OAM_item_t

Sprite Attributes structure

Parameters
xX Coordinate of the sprite on screen
yY Coordinate of the sprite on screen
tileSprite tile number (see set_sprite_tile)
propOAM Property Flags (see set_sprite_prop)

Function Documentation

◆ WRITE_VDP_CMD()

void WRITE_VDP_CMD ( uint16_t  cmd)

◆ WRITE_VDP_DATA()

void WRITE_VDP_DATA ( uint16_t  data)

◆ mode()

void mode ( uint8_t  m)

Set the current screen mode - one of M_* modes

Normally used by internal functions only.

See also
M_TEXT_OUT, M_TEXT_INOUT, M_NO_SCROLL, M_NO_INTERP

◆ get_mode()

uint8_t get_mode ( void  )

Returns the current mode

See also
M_TEXT_OUT, M_TEXT_INOUT, M_NO_SCROLL, M_NO_INTERP

Returns the current mode

See also
M_DRAWING, M_TEXT_OUT, M_TEXT_INOUT, M_NO_SCROLL, M_NO_INTERP

◆ get_system()

uint8_t get_system ( void  )
inline

Returns the system gbdk is running on.

◆ set_interrupts()

void set_interrupts ( uint8_t  flags)

Clears any pending interrupts and sets the interrupt mask register IO to flags.

Parameters
flagsA logical OR of *_IFLAGS
Note
This disables and then re-enables interrupts so it must be used outside of a critical section.
See also
enable_interrupts(), disable_interrupts()
VBL_IFLAG, LCD_IFLAG, TIM_IFLAG, SIO_IFLAG, JOY_IFLAG

◆ remove_VBL()

void remove_VBL ( int_handler  h)

Removes the VBL interrupt handler.

See also
add_VBL()

◆ remove_LCD()

void remove_LCD ( int_handler  h)

Removes the LCD interrupt handler.

See also
add_LCD(), remove_VBL()

◆ remove_TIM()

void remove_TIM ( int_handler  h)

◆ remove_SIO()

void remove_SIO ( int_handler  h)

◆ remove_JOY()

void remove_JOY ( int_handler  h)

◆ add_VBL()

void add_VBL ( int_handler  h)

Adds a V-blank interrupt handler.

◆ add_LCD()

void add_LCD ( int_handler  h)

Adds a LCD interrupt handler.

◆ add_TIM()

void add_TIM ( int_handler  h)

Does nothing on MSX

◆ add_SIO()

void add_SIO ( int_handler  h)

Does nothing on MSX

◆ add_JOY()

void add_JOY ( int_handler  h)

Does nothing on MSX

◆ cancel_pending_interrupts()

uint8_t cancel_pending_interrupts ( void  )
inline

Cancel pending interrupts

◆ move_bkg()

void move_bkg ( uint8_t  x,
uint8_t  y 
)
inline

◆ scroll_bkg()

void scroll_bkg ( int8_t  x,
int8_t  y 
)
inline

◆ vsync()

void vsync ( void  )

HALTs the CPU and waits for the vertical blank interrupt.

This is often used in main loops to idle the CPU at low power until it's time to start the next frame. It's also useful for syncing animation with the screen re-draw.

Warning: If the VBL interrupt is disabled, this function will never return. If the screen is off this function returns immediately.

◆ wait_vbl_done()

void wait_vbl_done ( void  )

Obsolete. This function has been replaced by vsync(), which has identical behavior.

◆ display_off()

void display_off ( void  )
inline

Turns the display off.

See also
DISPLAY_ON

◆ refresh_OAM()

void refresh_OAM ( void  )

Copies data from shadow OAM to OAM

◆ get_r_reg()

uint8_t get_r_reg ( void  )

Return R register for the DIV_REG emulation

Increments once per CPU instruction (fetches the Z80 CPU R register)

◆ SWITCH_ROM()

void SWITCH_ROM ( uint8_t  bank)

Makes switch the active ROM bank in frame 1

Parameters
bankROM bank to switch to

◆ delay()

void delay ( uint16_t  d)

Delays the given number of milliseconds. Uses no timers or interrupts, and can be called with interrupts disabled

◆ joypad()

uint8_t joypad ( void  )

Reads and returns the current state of the joypad.

◆ waitpad()

uint8_t waitpad ( uint8_t  mask)

Waits until at least one of the buttons given in mask are pressed.

◆ waitpadup()

void waitpadup ( void  )

Waits for the directional pad and all buttons to be released.

Note: Checks in a loop that doesn't HALT at all, so the CPU will be maxed out until this call returns.

◆ joypad_init()

uint8_t joypad_init ( uint8_t  npads,
joypads_t joypads 
)

Initializes joypads_t structure for polling multiple joypads

Parameters
npadsnumber of joypads requested (1, 2 or 4)
joypadspointer to joypads_t structure to be initialized

Only required for joypad_ex, not required for calls to regular joypad()

Returns
number of joypads avaliable
See also
joypad_ex(), joypads_t

◆ joypad_ex()

void joypad_ex ( joypads_t joypads)

Polls all avaliable joypads

Parameters
joypadspointer to joypads_t structure to be filled with joypad statuses, must be previously initialized with joypad_init()
See also
joypad_init(), joypads_t

◆ enable_interrupts()

void enable_interrupts ( void  )
inline

Enables unmasked interrupts

Note
Use CRITICAL {...} instead for creating a block of of code which should execute with interrupts temporarily turned off.
See also
disable_interrupts, set_interrupts, CRITICAL

◆ disable_interrupts()

void disable_interrupts ( void  )
inline

Disables interrupts

Note
Use CRITICAL {...} instead for creating a block of of code which should execute with interrupts temporarily turned off.

This function may be called as many times as you like; however the first call to enable_interrupts will re-enable them.

See also
enable_interrupts, set_interrupts, CRITICAL

◆ set_default_palette()

void set_default_palette ( void  )

◆ cpu_fast()

void cpu_fast ( void  )
inline

Set CPU speed to fast (CGB Double Speed) operation.

On startup the CGB operates in Normal Speed Mode and can be switched into Double speed mode (faster processing but also higher power consumption). See the Pan Docs for more information about which hardware features operate faster and which remain at Normal Speed.

  • Interrupts are temporarily disabled and then re-enabled during this call.
  • You can check to see if _cpu == CGB_TYPE before using this function.
See also
cpu_slow(), _cpu

◆ set_palette_entry()

void set_palette_entry ( uint8_t  palette,
uint8_t  entry,
uint16_t  rgb_data 
)

◆ set_palette()

void set_palette ( uint8_t  first_palette,
uint8_t  nb_palettes,
const palette_color_t rgb_data 
)

◆ set_native_tile_data()

void set_native_tile_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src 
)

◆ set_bkg_4bpp_data()

void set_bkg_4bpp_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src 
)
inline

◆ set_sprite_1bpp_data()

void set_sprite_1bpp_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src 
)
inline

◆ set_native_sprite_data()

void set_native_sprite_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src 
)
inline

◆ set_2bpp_palette()

void set_2bpp_palette ( uint16_t  palette)
inline

◆ set_bkg_data()

void set_bkg_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src 
)
inline

◆ set_sprite_data()

void set_sprite_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src 
)
inline

◆ set_1bpp_colors()

void set_1bpp_colors ( uint8_t  fgcolor,
uint8_t  bgcolor 
)
inline

◆ set_tile_1bpp_data()

void set_tile_1bpp_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src,
uint16_t  colors 
)

◆ set_bkg_1bpp_data()

void set_bkg_1bpp_data ( uint16_t  start,
uint16_t  ntiles,
const void *  src 
)
inline

◆ set_data()

void set_data ( uint16_t  dst,
const void *  src,
uint16_t  size 
)

Copies arbitrary data to an address in VRAM

Parameters
dstdestination VRAM Address
srcPointer to source buffer
sizeNumber of bytes to copy

Copies size bytes from a buffer at _src__ to VRAM starting at dst.

◆ vmemcpy()

void vmemcpy ( uint16_t  dst,
const void *  src,
uint16_t  size 
)

◆ set_tile_map()

void set_tile_map ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t tiles 
)

◆ set_bkg_based_tiles()

void set_bkg_based_tiles ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t tiles,
uint8_t  base_tile 
)
inline

◆ set_win_based_tiles()

void set_win_based_tiles ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t tiles,
uint8_t  base_tile 
)
inline

◆ set_tile_submap()

void set_tile_submap ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  map_w,
const uint8_t map 
)

◆ set_tile_submap_compat()

void set_tile_submap_compat ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
uint8_t  map_w,
const uint8_t map 
)

◆ set_bkg_submap()

void set_bkg_submap ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t map,
uint8_t  map_w 
)
inline

Sets a rectangular area of the Background Tile Map using a sub-region from a source tile map. Useful for scrolling implementations of maps larger than 32 x 32 tiles.

Parameters
xX Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255
yY Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255
wWidth of area to set in tiles. Range 1 - 255
hHeight of area to set in tiles. Range 1 - 255
mapPointer to source tile map data
map_wWidth of source tile map in tiles. Range 1 - 255

Entries are copied from map to the Background Tile Map starting at x, y writing across for w tiles and down for h tiles, using map_w as the rowstride for the source tile map.

The x and y parameters are in Source Tile Map tile coordinates. The location tiles will be written to on the hardware Background Map is derived from those, but only uses the lower 5 bits of each axis, for range of 0-31 (they are bit-masked: x & 0x1F and y & 0x1F). As a result the two coordinate systems are aligned together.

In order to transfer tile map data in a way where the coordinate systems are not aligned, an offset from the Source Tile Map pointer can be passed in: (map_ptr + x + (y * map_width)).

For example, if you want the tile id at 1,2 from the source map to show up at 0,0 on the hardware Background Map (instead of at 1,2) then modify the pointer address that is passed in: map_ptr + 1 + (2 * map_width)

Use this instead of set_bkg_tiles when the source map is wider than 32 tiles or when writing a width that does not match the source map width.

One byte per source tile map entry.

Writes that exceed coordinate 31 on the x or y axis will wrap around to the Left and Top edges.

See set_bkg_tiles for setting CGB attribute maps with VBK_REG.

See also
SHOW_BKG
set_bkg_data, set_bkg_tiles, set_win_submap, set_tiles

◆ set_win_submap()

void set_win_submap ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t map,
uint8_t  map_w 
)
inline

Sets a rectangular area of the Window Tile Map using a sub-region from a source tile map.

Parameters
xX Start position in both the Source Tile Map and hardware Window Map tile coordinates. Range 0 - 255
yY Start position in both the Source Tile Map and hardware Window Map tile coordinates. Range 0 - 255
wWidth of area to set in tiles. Range 1 - 255
hHeight of area to set in tiles. Range 1 - 255
mapPointer to source tile map data
map_wWidth of source tile map in tiles. Range 1 - 255

Entries are copied from map to the Window Tile Map starting at x, y writing across for w tiles and down for h tiles, using map_w as the rowstride for the source tile map.

The x and y parameters are in Source Tile Map tile coordinates. The location tiles will be written to on the hardware Background Map is derived from those, but only uses the lower 5 bits of each axis, for range of 0-31 (they are bit-masked: x & 0x1F and y & 0x1F). As a result the two coordinate systems are aligned together.

In order to transfer tile map data in a way where the coordinate systems are not aligned, an offset from the Source Tile Map pointer can be passed in: (map_ptr + x + (y * map_width)).

For example, if you want the tile id at 1,2 from the source map to show up at 0,0 on the hardware Background Map (instead of at 1,2) then modify the pointer address that is passed in: map_ptr + 1 + (2 * map_width)

Use this instead of set_win_tiles when the source map is wider than 32 tiles or when writing a width that does not match the source map width.

One byte per source tile map entry.

Writes that exceed coordinate 31 on the x or y axis will wrap around to the Left and Top edges.

GBC only: VBK_REG determines whether Tile Numbers or Tile Attributes get set.

See set_bkg_tiles for details about CGB attribute maps with VBK_REG.

See also
SHOW_WIN, HIDE_WIN, set_win_tiles, set_bkg_submap, set_bkg_tiles, set_bkg_data, set_tiles

◆ set_bkg_based_submap()

void set_bkg_based_submap ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t map,
uint8_t  map_w,
uint8_t  base_tile 
)
inline

◆ set_win_based_submap()

void set_win_based_submap ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint8_t map,
uint8_t  map_w,
uint8_t  base_tile 
)
inline

◆ fill_rect()

void fill_rect ( uint8_t  x,
uint8_t  y,
uint8_t  w,
uint8_t  h,
const uint16_t  tile 
)

◆ SET_SHADOW_OAM_ADDRESS()

void SET_SHADOW_OAM_ADDRESS ( void *  address)
inline

Sets address of 256-byte aligned array of shadow OAM to be transferred on each VBlank

◆ set_sprite_tile()

void set_sprite_tile ( uint8_t  nb,
uint8_t  tile 
)
inline

Sets sprite number nb__in the OAM to display tile number __tile.

Parameters
nbSprite number, range 0 - 39
tileSelects a tile (0 - 255) from memory at 8000h - 8FFFh
In CGB Mode this could be either in VRAM Bank
0 or 1, depending on Bit 3 of the OAM Attribute Flag
(see set_sprite_prop)

In 8x16 mode:

  • The sprite will also display the next tile (tile + 1) directly below (y + 8) the first tile.
  • The lower bit of the tile number is ignored: the upper 8x8 tile is (tile & 0xFE), and the lower 8x8 tile is (tile | 0x01).
  • See: SPRITES_8x16

◆ get_sprite_tile()

uint8_t get_sprite_tile ( uint8_t  nb)
inline

Returns the tile number of sprite number nb in the OAM.

Parameters
nbSprite number, range 0 - 39
See also
set_sprite_tile for more details

◆ set_sprite_prop()

void set_sprite_prop ( uint8_t  nb,
uint8_t  prop 
)
inline

Sets the OAM Property Flags of sprite number nb to those defined in prop.

Parameters
nbSprite number, range 0 - 39
propProperty setting (see bitfield description)

The bits in prop represent:

  • Bit 7 - Vertical flip. Dictates which way up the sprite is drawn vertically.
    0: normal
    1: upside down
  • Bit 6 - Horizontal flip. Dictates which way up the sprite is drawn horizontally.
    0: normal
    1: back to front
  • Bit 5 - Priority flag. When this is set, the sprites appear behind the background and window layer.
    0: infront
    1: behind
  • Bit 4 - Unimplemented
  • Bit 3 - Unimplemented
  • Bit 2 - Unimplemented
  • Bit 1 - See bit 0.
  • Bit 0 - Bits 0-1 indicate which color palette the sprite should use. Note: only palettes 4 to 7 will be available for NES sprites.

It's recommended to use GBDK constants (eg: S_FLIPY) to configure sprite properties as these are crossplatform.

// Load palette data into the first palette
set_sprite_palette(4, 1, exampleSprite_palettes)
// Set the OAM value for the sprite
// These flags tell the sprite to use the first sprite palette (palette 4) and to flip the sprite both vertically and horizontally.
#define S_FLIPY
Definition: gb.h:96
void set_sprite_prop(uint8_t nb, uint8_t prop)
Definition: gb.h:1933
#define S_FLIPX
Definition: gb.h:92
#define set_sprite_palette(first_palette, nb_palettes, rgb_data)
Definition: msx.h:550
See also
S_PALETTE, S_FLIPX, S_FLIPY, S_PRIORITY

Sets the OAM Property Flags of sprite number nb to those defined in prop.

Parameters
nbSprite number, range 0 - 39
propProperty setting (see bitfield description)

The bits in prop represent:

  • Bit 7 - Priority flag. When this is set the sprites appear behind the background and window layer.
    0: infront
    1: behind
  • Bit 6 - Vertical flip. Dictates which way up the sprite is drawn vertically.
    0: normal
    1:upside down
  • Bit 5 - Horizontal flip. Dictates which way up the sprite is drawn horizontally.
    0: normal
    1:back to front
  • Bit 4 - DMG/Non-CGB Mode Only. Assigns either one of the two b/w palettes to the sprite.
    0: OBJ palette 0
    1: OBJ palette 1
  • Bit 3 - GBC only. Dictates from which bank of Sprite Tile Patterns the tile is taken.
    0: Bank 0
    1: Bank 1
  • Bit 2 - See bit 0.
  • Bit 1 - See bit 0.
  • Bit 0 - GBC only. Bits 0-2 indicate which of the 7 OBJ colour palettes the sprite is assigned.

It's recommended to use GBDK constants (eg: S_FLIPY) to configure sprite properties as these are crossplatform.

// Load palette data into the first palette
set_sprite_palette(4, 1, exampleSprite_palettes)
// Set the OAM value for the sprite
// These flags tell the sprite to flip both vertically and horizontally.
See also
S_PALETTE, S_FLIPX, S_FLIPY, S_PRIORITY

◆ get_sprite_prop()

uint8_t get_sprite_prop ( uint8_t  nb)
inline

Returns the OAM Property Flags of sprite number nb.

Parameters
nbSprite number, range 0 - 39
See also
set_sprite_prop for property bitfield settings

◆ move_sprite()

void move_sprite ( uint8_t  nb,
uint8_t  x,
uint8_t  y 
)
inline

Moves sprite number nb to the x, y position on the screen.

Parameters
nbSprite number, range 0 - 39
xX Position. Specifies the sprites horizontal position on the screen (minus 8).
An offscreen value (X=0 or X>=168) hides the sprite, but the sprite still affects the priority ordering - a better way to hide a sprite is to set its Y-coordinate offscreen.
yY Position. Specifies the sprites vertical position on the screen (minus 16).
An offscreen value (for example, Y=0 or Y>=160) hides the sprite.

Moving the sprite to 0,0 (or similar off-screen location) will hide it.

◆ scroll_sprite()

void scroll_sprite ( uint8_t  nb,
int8_t  x,
int8_t  y 
)
inline

Moves sprite number nb relative to its current position.

Parameters
nbSprite number, range 0 - 39
xNumber of pixels to move the sprite on the X axis
Range: -128 - 127
yNumber of pixels to move the sprite on the Y axis
Range: -128 - 127
See also
move_sprite for more details about the X and Y position

◆ hide_sprite()

void hide_sprite ( uint8_t  nb)
inline

Hides sprite number nb by moving it to zero position by Y.

Parameters
nbSprite number, range 0 - 39

◆ set_vram_byte()

void set_vram_byte ( uint8_t addr,
uint8_t  v 
)

Set byte in vram at given memory location

Parameters
addraddress to write to
vvalue

◆ set_attributed_tile_xy()

uint8_t* set_attributed_tile_xy ( uint8_t  x,
uint8_t  y,
uint16_t  t 
)

Set single tile t with attributes on background layer at x,y

Parameters
xX-coordinate
yY-coordinate
ttile index
Returns
returns the address of tile, so you may use faster set_vram_byte() later

◆ set_tile_xy()

uint8_t* set_tile_xy ( uint8_t  x,
uint8_t  y,
uint8_t  t 
)

Set single tile t on background layer at x,y

Parameters
xX-coordinate
yY-coordinate
ttile index
Returns
returns the address of tile, so you may use faster set_vram_byte() later

◆ get_bkg_xy_addr()

uint8_t* get_bkg_xy_addr ( uint8_t  x,
uint8_t  y 
)

Get address of X,Y tile of background map

Variable Documentation

◆ _SYSTEM

const uint8_t _SYSTEM
extern

◆ c

void c

◆ d

void d

◆ e

void e

◆ iyh

void iyh

◆ iyl

uint8_t iyl
Initial value:
{
__asm__("ei")

◆ h

void h

◆ l

void l

◆ sys_time

volatile uint16_t sys_time
extern

Global Time Counter in VBL periods (60Hz)

Increments once per Frame

Will wrap around every ~18 minutes (unsigned 16 bits = 65535 / 60 / 60 = 18.2)

◆ _current_bank

volatile uint8_t _current_bank
extern

Tracks current active ROM bank in frame 1

Tracks current active ROM bank

In most cases the CURRENT_BANK macro for this variable is recommended for use instead of the variable itself.

The active bank number is not tracked by _current_bank when SWITCH_ROM_MBC5_8M is used.

This variable is updated automatically when you call SWITCH_ROM_MBC1 or SWITCH_ROM_MBC5, SWITCH_ROM(), or call a BANKED function.

See also
SWITCH_ROM_MBC1(), SWITCH_ROM_MBC5(), SWITCH_ROM()

◆ b

void b

◆ _current_2bpp_palette

uint16_t _current_2bpp_palette
extern

◆ _current_1bpp_colors

uint16_t _current_1bpp_colors
extern

◆ _map_tile_offset

uint8_t _map_tile_offset
extern

◆ _submap_tile_offset

uint8_t _submap_tile_offset
extern

◆ shadow_OAM

volatile struct OAM_item_t shadow_OAM[]
extern

Shadow OAM array in WRAM, that is DMA-transferred into the real OAM each VBlank

◆ _shadow_OAM_base

volatile uint8_t _shadow_OAM_base
extern

MSB of shadow_OAM address is used by OAM copying routine

MSB of shadow_OAM address is used by OAM DMA copying routine

◆ _shadow_OAM_OFF

volatile uint8_t _shadow_OAM_OFF
extern

Flag for disabling of OAM copying routine

Values:

  • 1: OAM copy routine is disabled (non-isr VDP operation may be in progress)
  • 0: OAM copy routine is enabled

This flag is modified by all MSX GBDK API calls that write to the VDP. It is set to DISABLED when they start and ENABLED when they complete.

Note
It is recommended to avoid writing to the Video Display Processor (VDP) during an interrupt service routine (ISR) since it can corrupt the VDP pointer of an VDP operation already in progress.

If it is necessary, this flag can be used during an ISR to determine whether a VDP operation is already in progress. If the value is 1 then avoid writing to the VDP (tiles, map, scrolling, colors, etc).

// at the beginning of and ISR that would write to the VDP
if (_shadow_OAM_OFF) return;
volatile uint8_t _shadow_OAM_OFF
See also
docs_consoles_safe_display_controller_access