GBDK 2020 Docs
API Documentation for GBDK 2020
gb.h File Reference
#include <types.h>
#include <gb/hardware.h>
#include <gb/sgb.h>
#include <gb/cgb.h>

Go to the source code of this file.

Data Structures

struct  joypads_t
 
struct  OAM_item_t
 

Macros

#define __GBDK_VERSION   402
 
#define J_START   0x80U
 
#define J_SELECT   0x40U
 
#define J_B   0x20U
 
#define J_A   0x10U
 
#define J_DOWN   0x08U
 
#define J_UP   0x04U
 
#define J_LEFT   0x02U
 
#define J_RIGHT   0x01U
 
#define M_DRAWING   0x01U
 
#define M_TEXT_OUT   0x02U
 
#define M_TEXT_INOUT   0x03U
 
#define M_NO_SCROLL   0x04U
 
#define M_NO_INTERP   0x08U
 
#define S_PALETTE   0x10U
 
#define S_FLIPX   0x20U
 
#define S_FLIPY   0x40U
 
#define S_PRIORITY   0x80U
 
#define VBL_IFLAG   0x01U
 
#define LCD_IFLAG   0x02U
 
#define TIM_IFLAG   0x04U
 
#define SIO_IFLAG   0x08U
 
#define JOY_IFLAG   0x10U
 
#define SCREENWIDTH   0xA0U
 
#define SCREENHEIGHT   0x90U
 
#define MINWNDPOSX   0x07U
 
#define MINWNDPOSY   0x00U
 
#define MAXWNDPOSX   0xA6U
 
#define MAXWNDPOSY   0x8FU
 
#define DMG_TYPE   0x01
 
#define MGB_TYPE   0xFF
 
#define CGB_TYPE   0x11
 
#define IO_IDLE   0x00U
 
#define IO_SENDING   0x01U
 
#define IO_RECEIVING   0x02U
 
#define IO_ERROR   0x04U
 
#define SWITCH_ROM_MBC1(b)    _current_bank = (b), *(unsigned char *)0x2000 = (b)
 
#define SWITCH_RAM_MBC1(b)    *(unsigned char *)0x4000 = (b)
 
#define ENABLE_RAM_MBC1    *(unsigned char *)0x0000 = 0x0A
 
#define DISABLE_RAM_MBC1    *(unsigned char *)0x0000 = 0x00
 
#define SWITCH_16_8_MODE_MBC1    *(unsigned char *)0x6000 = 0x00
 
#define SWITCH_4_32_MODE_MBC1    *(unsigned char *)0x6000 = 0x01
 
#define SWITCH_ROM_MBC5(b)
 
#define SWITCH_ROM_MBC5_8M(b)
 
#define SWITCH_RAM_MBC5(b)    *(unsigned char *)0x4000 = (b)
 
#define ENABLE_RAM_MBC5    *(unsigned char *)0x0000 = 0x0A
 
#define DISABLE_RAM_MBC5    *(unsigned char *)0x0000 = 0x00
 
#define DISPLAY_ON    LCDC_REG|=0x80U
 
#define DISPLAY_OFF    display_off();
 
#define SHOW_BKG    LCDC_REG|=0x01U
 
#define HIDE_BKG    LCDC_REG&=0xFEU
 
#define SHOW_WIN    LCDC_REG|=0x20U
 
#define HIDE_WIN    LCDC_REG&=0xDFU
 
#define SHOW_SPRITES    LCDC_REG|=0x02U
 
#define HIDE_SPRITES    LCDC_REG&=0xFDU
 
#define SPRITES_8x16    LCDC_REG|=0x04U
 
#define SPRITES_8x8    LCDC_REG&=0xFBU
 
#define DISABLE_OAM_DMA    _shadow_OAM_base = 0
 
#define ENABLE_OAM_DMA    _shadow_OAM_base = (UBYTE)((UWORD)&shadow_OAM >> 8)
 

Typedefs

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

Functions

void remove_VBL (int_handler h) NONBANKED
 
void remove_LCD (int_handler h) NONBANKED
 
void remove_TIM (int_handler h) NONBANKED
 
void remove_SIO (int_handler h) NONBANKED
 
void remove_JOY (int_handler h) NONBANKED
 
void add_VBL (int_handler h) NONBANKED
 
void add_LCD (int_handler h) NONBANKED
 
void add_TIM (int_handler h) NONBANKED
 
void add_SIO (int_handler h) NONBANKED
 
void add_JOY (int_handler h) NONBANKED
 
void nowait_int_handler (void) NONBANKED
 
void wait_int_handler (void) NONBANKED
 
void mode (UINT8 m) NONBANKED
 
UINT8 get_mode (void) NONBANKED __preserves_regs(b
 
void send_byte (void)
 
void receive_byte (void)
 
void delay (UINT16 d) NONBANKED
 
UINT8 joypad (void) NONBANKED __preserves_regs(b
 
UINT8 waitpad (UINT8 mask) NONBANKED __preserves_regs(b
 
void waitpadup (void) NONBANKED __preserves_regs(a
 
UINT8 joypad_init (UINT8 npads, joypads_t *joypads)
 
void joypad_ex (joypads_t *joypads)
 
void enable_interrupts (void) NONBANKED __preserves_regs(a
 
void disable_interrupts (void) NONBANKED __preserves_regs(a
 
void set_interrupts (UINT8 flags) NONBANKED __preserves_regs(b
 
void reset (void) NONBANKED
 
void wait_vbl_done (void) NONBANKED __preserves_regs(b
 
void display_off (void) NONBANKED __preserves_regs(b
 
void hiramcpy (UINT8 dst, const void *src, UINT8 n) NONBANKED __preserves_regs(b
 
void set_bkg_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void set_bkg_1bit_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data, UINT8 color) NONBANKED __preserves_regs(b
 
void get_bkg_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void set_bkg_tiles (UINT8 x, UINT8 y, UINT8 w, UINT8 h, unsigned char *tiles) NONBANKED __preserves_regs(b
 
void get_bkg_tiles (UINT8 x, UINT8 y, UINT8 w, UINT8 h, unsigned char *tiles) NONBANKED __preserves_regs(b
 
void move_bkg (UINT8 x, UINT8 y)
 
void scroll_bkg (INT8 x, INT8 y)
 
void set_win_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void set_win_1bit_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void get_win_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void set_win_tiles (UINT8 x, UINT8 y, UINT8 w, UINT8 h, unsigned char *tiles) NONBANKED __preserves_regs(b
 
void get_win_tiles (UINT8 x, UINT8 y, UINT8 w, UINT8 h, unsigned char *tiles) NONBANKED __preserves_regs(b
 
void move_win (UINT8 x, UINT8 y)
 
void scroll_win (INT8 x, INT8 y)
 
void set_sprite_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void set_sprite_1bit_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void get_sprite_data (UINT8 first_tile, UINT8 nb_tiles, unsigned char *data) NONBANKED __preserves_regs(b
 
void SET_SHADOW_OAM_ADDRESS (void *address)
 
void set_sprite_tile (UINT8 nb, UINT8 tile)
 
UINT8 get_sprite_tile (UINT8 nb)
 
void set_sprite_prop (UINT8 nb, UINT8 prop)
 
UINT8 get_sprite_prop (UINT8 nb)
 
void move_sprite (UINT8 nb, UINT8 x, UINT8 y)
 
void scroll_sprite (UINT8 nb, INT8 x, INT8 y)
 
void hide_sprite (UINT8 nb)
 
void set_data (unsigned char *vram_addr, unsigned char *data, UINT16 len) NONBANKED __preserves_regs(b
 
void get_data (unsigned char *data, unsigned char *vram_addr, UINT16 len) NONBANKED __preserves_regs(b
 
void set_tiles (UINT8 x, UINT8 y, UINT8 w, UINT8 h, unsigned char *vram_addr, unsigned char *tiles) NONBANKED __preserves_regs(b
 
void get_tiles (UINT8 x, UINT8 y, UINT8 w, UINT8 h, unsigned char *tiles, unsigned char *vram_addr) NONBANKED __preserves_regs(b
 
void init_win (UINT8 c) NONBANKED __preserves_regs(b
 
void init_bkg (UINT8 c) NONBANKED __preserves_regs(b
 
void vmemset (void *s, UINT8 c, size_t n) NONBANKED __preserves_regs(b
 
void fill_bkg_rect (UINT8 x, UINT8 y, UINT8 w, UINT8 h, UINT8 tile) NONBANKED __preserves_regs(b
 
void fill_win_rect (UINT8 x, UINT8 y, UINT8 w, UINT8 h, UINT8 tile) NONBANKED __preserves_regs(b
 

Variables

UINT8 c
 
UINT8 _cpu
 
volatile UINT16 sys_time
 
volatile UINT8 _io_status
 
volatile UINT8 _io_in
 
volatile UINT8 _io_out
 
__REG _current_bank
 
UINT8 h
 
UINT8 l
 
void b
 
void d
 
void e
 
volatile struct OAM_item_t shadow_OAM []
 
__REG _shadow_OAM_base
 

Detailed Description

Gameboy specific functions.

Macro Definition Documentation

◆ __GBDK_VERSION

#define __GBDK_VERSION   402

◆ J_START

#define J_START   0x80U

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 keys; keys = joypad(); if (keys & J_B) { ... }

See also
joypad

◆ J_SELECT

#define J_SELECT   0x40U

◆ J_B

#define J_B   0x20U

◆ J_A

#define J_A   0x10U

◆ J_DOWN

#define J_DOWN   0x08U

◆ J_UP

#define J_UP   0x04U

◆ J_LEFT

#define J_LEFT   0x02U

◆ J_RIGHT

#define J_RIGHT   0x01U

◆ M_DRAWING

#define M_DRAWING   0x01U

Screen modes. Normally used by internal functions only.

See also
mode()

◆ M_TEXT_OUT

#define M_TEXT_OUT   0x02U

◆ 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_PALETTE

#define S_PALETTE   0x10U

If this is set, sprite colours come from OBJ1PAL. Else they come from OBJ0PAL

See also
set_sprite_prop().

◆ S_FLIPX

#define S_FLIPX   0x20U

If set the sprite will be flipped horizontally.

See also
set_sprite_prop()

◆ S_FLIPY

#define S_FLIPY   0x40U

If set the sprite will be flipped vertically.

See also
set_sprite_prop()

◆ S_PRIORITY

#define S_PRIORITY   0x80U

If this bit is clear, then the sprite will be displayed on top of the background and window.

See also
set_sprite_prop()

◆ 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

Timer Interrupt when the timer TIMA_REG overflows.

See also
set_interrupts(),
add_TIM

◆ SIO_IFLAG

#define SIO_IFLAG   0x08U

Serial Link Interrupt occurs when the serial transfer has completed.

See also
set_interrupts(),
add_SIO

◆ JOY_IFLAG

#define JOY_IFLAG   0x10U

Joypad Interrupt occurs on a transition of the keypad.

See also
set_interrupts(),
add_JOY

◆ SCREENWIDTH

#define SCREENWIDTH   0xA0U

Width of the visible screen in pixels.

◆ SCREENHEIGHT

#define SCREENHEIGHT   0x90U

Height of the visible screen in pixels.

◆ MINWNDPOSX

#define MINWNDPOSX   0x07U

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   0xA6U

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

See also
move_win()

◆ MAXWNDPOSY

#define MAXWNDPOSY   0x8FU

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

See also
move_win()

◆ DMG_TYPE

#define DMG_TYPE   0x01

Hardware Model: Original GB or Super GB.

See also
_cpu

◆ MGB_TYPE

#define MGB_TYPE   0xFF

Hardware Model: Pocket GB or Super GB 2.

See also
_cpu

◆ CGB_TYPE

#define CGB_TYPE   0x11

Hardware Model: Color GB.

See also
_cpu

◆ IO_IDLE

#define IO_IDLE   0x00U

Serial Link IO is completed

◆ IO_SENDING

#define IO_SENDING   0x01U

Serial Link Sending data

◆ IO_RECEIVING

#define IO_RECEIVING   0x02U

Serial Link Receiving data

◆ IO_ERROR

#define IO_ERROR   0x04U

Serial Link Error

◆ SWITCH_ROM_MBC1

#define SWITCH_ROM_MBC1 (   b)     _current_bank = (b), *(unsigned char *)0x2000 = (b)

Makes MBC1 and other compatible MBCs switch the active ROM bank

Parameters
bROM bank to switch to

◆ SWITCH_RAM_MBC1

#define SWITCH_RAM_MBC1 (   b)     *(unsigned char *)0x4000 = (b)

Switches SRAM bank on MBC1 and other compaticle MBCs

Parameters
bSRAM bank to switch to

◆ ENABLE_RAM_MBC1

#define ENABLE_RAM_MBC1    *(unsigned char *)0x0000 = 0x0A

Enables SRAM on MBC1

◆ DISABLE_RAM_MBC1

#define DISABLE_RAM_MBC1    *(unsigned char *)0x0000 = 0x00

Disables SRAM on MBC1

◆ SWITCH_16_8_MODE_MBC1

#define SWITCH_16_8_MODE_MBC1    *(unsigned char *)0x6000 = 0x00

◆ SWITCH_4_32_MODE_MBC1

#define SWITCH_4_32_MODE_MBC1    *(unsigned char *)0x6000 = 0x01

◆ SWITCH_ROM_MBC5

#define SWITCH_ROM_MBC5 (   b)
Value:
*(unsigned char *)0x3000 = 0, \
*(unsigned char *)0x2000 = (b)

Makes MBC5 switch to the active ROM bank; only 4M roms are supported,

See also
SWITCH_ROM_MBC5_8M()
Parameters
bROM bank to switch to

Note the order used here. Writing the other way around on a MBC1 always selects bank 1

◆ SWITCH_ROM_MBC5_8M

#define SWITCH_ROM_MBC5_8M (   b)
Value:
*(unsigned char *)0x3000 = ((UINT16)(b) >> 8), \
*(unsigned char *)0x2000 = (b)

Makes MBC5 to switch the active ROM bank; active bank number is not tracked by _current_bank if you use this macro

See also
_current_bank
Parameters
bROM bank to switch to

Note the order used here. Writing the other way around on a MBC1 always selects bank 1

◆ SWITCH_RAM_MBC5

#define SWITCH_RAM_MBC5 (   b)     *(unsigned char *)0x4000 = (b)

Switches SRAM bank on MBC5

Parameters
bSRAM bank to switch to

◆ ENABLE_RAM_MBC5

#define ENABLE_RAM_MBC5    *(unsigned char *)0x0000 = 0x0A

Enables SRAM on MBC5

◆ DISABLE_RAM_MBC5

#define DISABLE_RAM_MBC5    *(unsigned char *)0x0000 = 0x00

Disables SRAM on MBC5

◆ DISPLAY_ON

#define DISPLAY_ON    LCDC_REG|=0x80U

Turns the display back on.

See also
display_off, DISPLAY_OFF

◆ DISPLAY_OFF

#define DISPLAY_OFF    display_off();

Turns the display off immediatly.

See also
display_off, DISPLAY_ON

◆ SHOW_BKG

#define SHOW_BKG    LCDC_REG|=0x01U

Turns on the background layer. Sets bit 0 of the LCDC register to 1.

◆ HIDE_BKG

#define HIDE_BKG    LCDC_REG&=0xFEU

Turns off the background layer. Sets bit 0 of the LCDC register to 0.

◆ SHOW_WIN

#define SHOW_WIN    LCDC_REG|=0x20U

Turns on the window layer Sets bit 5 of the LCDC register to 1.

◆ HIDE_WIN

#define HIDE_WIN    LCDC_REG&=0xDFU

Turns off the window layer. Clears bit 5 of the LCDC register to 0.

◆ SHOW_SPRITES

#define SHOW_SPRITES    LCDC_REG|=0x02U

Turns on the sprites layer. Sets bit 1 of the LCDC register to 1.

◆ HIDE_SPRITES

#define HIDE_SPRITES    LCDC_REG&=0xFDU

Turns off the sprites layer. Clears bit 1 of the LCDC register to 0.

◆ SPRITES_8x16

#define SPRITES_8x16    LCDC_REG|=0x04U

Sets sprite size to 8x16 pixels, two tiles one above the other. Sets bit 2 of the LCDC register to 1.

◆ SPRITES_8x8

#define SPRITES_8x8    LCDC_REG&=0xFBU

Sets sprite size to 8x8 pixels, one tile. Clears bit 2 of the LCDC register to 0.

◆ DISABLE_OAM_DMA

#define DISABLE_OAM_DMA    _shadow_OAM_base = 0

Disable OAM DMA copy each VBlank

◆ ENABLE_OAM_DMA

#define ENABLE_OAM_DMA    _shadow_OAM_base = (UBYTE)((UWORD)&shadow_OAM >> 8)

Enable OAM DMA copy each VBlank and set it to transfer default shadow_OAM array

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

◆ remove_VBL()

void remove_VBL ( int_handler  h)

The remove functions will remove any interrupt handler.

A handler of NULL will cause bad things to happen if the given interrupt is enabled.

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)

Removes the TIM interrupt handler.

See also
add_TIM(), remove_VBL()

◆ remove_SIO()

void remove_SIO ( int_handler  h)

Removes the Serial Link / SIO interrupt handler.

See also
add_SIO(),
remove_VBL()

The default SIO ISR gets installed automatically if any of the standard SIO calls are used. These calls include add_SIO(), remove_SIO(), send_byte(), receive_byte().

The default SIO ISR cannot be removed once installed. Only secondary chained SIO ISRs (added with add_SIO() ) can be removed.

◆ remove_JOY()

void remove_JOY ( int_handler  h)

Removes the JOY interrupt handler.

See also
add_JOY(), remove_VBL()

◆ add_VBL()

void add_VBL ( int_handler  h)

Adds a V-blank interrupt handler.

Parameters
hThe handler to be called whenever a V-blank interrupt occurs.

Up to 4 handlers may be added, with the last added being called last. If the remove_VBL function is to be called, only three may be added.

Note: The default VBL is installed automatically.

◆ add_LCD()

void add_LCD ( int_handler  h)

Adds a LCD interrupt handler.

Called when the LCD interrupt occurs, which is normally when LY_REG == LYC_REG.

From pan/k0Pa: There are various reasons for this interrupt to occur as described by the STAT_REG register ($FF41). One very popular reason is to indicate to the user when the video hardware is about to redraw a given LCD line. This can be useful for dynamically controlling the SCX_REG / SCY_REG registers ($FF43/$FF42) to perform special video effects.

See also
add_VBL

◆ add_TIM()

void add_TIM ( int_handler  h)

Adds a timer interrupt handler.

From pan/k0Pa: This interrupt occurs when the TIMA_REG register ($FF05) changes from $FF to $00.

See also
add_VBL
set_interrupts() with TIM_IFLAG

◆ add_SIO()

void add_SIO ( int_handler  h)

Adds a Serial Link transmit complete interrupt handler.

From pan/k0Pa: This interrupt occurs when a serial transfer has completed on the game link port.

See also
send_byte, receive_byte(), add_VBL()
set_interrupts() with SIO_IFLAG

◆ add_JOY()

void add_JOY ( int_handler  h)

Adds a joypad button change interrupt handler.

From pan/k0Pa: This interrupt occurs on a transition of any of the keypad input lines from high to low. Due to the fact that keypad "bounce" is virtually always present, software should expect this interrupt to occur one or more times for every button press and one or more times for every button release.

See also
joypad()

◆ nowait_int_handler()

void nowait_int_handler ( void  )

Interrupt handler chain terminator that does not wait for .STAT

You must add this handler last in every interrupt handler chain if you want to change the default interrupt handler behaviour that waits for LCD controller mode to become 1 or 0 before return from the interrupt.

Example:

__critical {
add_SIO(nowait_int_handler); // Disable wait on VRAM state before returning from SIO interrupt
}
See also
wait_int_handler()

◆ wait_int_handler()

void wait_int_handler ( void  )

Default Interrupt handler chain terminator that waits for

See also
STAT_REG and only returns at the BEGINNING of either Mode 0 or Mode 1.

Used by default at the end of interrupt chains to help prevent graphical glitches. The glitches are caused when an ISR interrupts a graphics operation in one mode but returns in a different mode for which that graphics operation is not allowed.

See also
nowait_int_handler()

◆ mode()

void mode ( UINT8  m)

Set the current screen mode - one of M_* modes

Normally used by internal functions only.

See also
M_DRAWING, M_TEXT_OUT, M_TEXT_INOUT, M_NO_SCROLL, M_NO_INTERP

◆ get_mode()

UINT8 get_mode ( void  )

Returns the current mode

See also
M_DRAWING, M_TEXT_OUT, M_TEXT_INOUT, M_NO_SCROLL, M_NO_INTERP

◆ send_byte()

void send_byte ( void  )

Serial Link: Send the byte in _io_out out through the serial port

Make sure to enable interrupts for the Serial Link before trying to transfer data.

See also
add_SIO(), remove_SIO()
set_interrupts() with SIO_IFLAG

◆ receive_byte()

void receive_byte ( void  )

Serial Link: Receive a byte from the serial port into _io_in

Make sure to enable interrupts for the Serial Link before trying to transfer data.

See also
add_SIO(), remove_SIO()
set_interrupts() with SIO_IFLAG

◆ delay()

void delay ( UINT16  d)

Delays the given number of milliseconds. Uses no timers or interrupts, and can be called with interrupts disabled (why nobody knows :)

◆ joypad()

UINT8 joypad ( void  )

Reads and returns the current state of the joypad. Follows Nintendo's guidelines for reading the pad. Return value is an OR of J_*

See also
J_START, J_SELECT, J_A, J_B, J_UP, J_DOWN, J_LEFT, J_RIGHT

◆ waitpad()

UINT8 waitpad ( UINT8  mask)

Waits until all the buttons given in mask are pressed.

Parameters
maskBitmask indicating which buttons to wait for

Normally only used for checking one key, but it will support many, even J_LEFT at the same time as J_RIGHT. :)

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

See also
joypad
J_START, J_SELECT, J_A, J_B, J_UP, J_DOWN, J_LEFT, J_RIGHT

◆ 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 joypad_init ( UINT8  npads,
joypads_t joypads 
)

Initializes joypads_t structure for polling multiple joypads (for the GB and ones connected via SGB)

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 (for the GB and ones connected via SGB)

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  )

Enables unmasked interrupts

See also
disable_interrupts, set_interrupts

◆ disable_interrupts()

void disable_interrupts ( void  )

Disables interrupts.

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

◆ set_interrupts()

void set_interrupts ( UINT8  flags)

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

Parameters
flagsA logical OR of *_IFLAGS
See also
enable_interrupts(), disable_interrupts()
VBL_IFLAG, LCD_IFLAG, TIM_IFLAG, SIO_IFLAG, JOY_IFLAG

◆ reset()

void reset ( void  )

Performs a warm reset by reloading the CPU value then jumping to the start of crt0 (0x0150)

◆ wait_vbl_done()

void wait_vbl_done ( void  )

HALTs the CPU and waits for the vertical blank interrupt (VBL) to finish.

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 immediatly.

◆ display_off()

void display_off ( void  )

Turns the display off.

Waits until the VBL interrupt before turning the display off.

See also
DISPLAY_ON

◆ hiramcpy()

void hiramcpy ( UINT8  dst,
const void *  src,
UINT8  n 
)

Copies data from somewhere in the lower address space to part of hi-ram.

Parameters
dstOffset in high ram (0xFF00 and above) to copy to.
srcArea to copy from
nNumber of bytes to copy.

◆ set_bkg_data()

void set_bkg_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Sets VRAM Tile Pattern data for the Background / Window

Parameters
first_tileIndex of the first tile to write
nb_tilesNumber of tiles to write
dataPointer to (2 bpp) source tile data

Writes nb_tiles tiles to VRAM starting at first_tile, tile data is sourced from data. Each Tile is 16 bytes in size (8x8 pixels, 2 bits-per-pixel).

Note: Sprite Tiles 128-255 share the same memory region as Background Tiles 128-255.

GBC only: VBK_REG determines which bank of Background tile patterns are written to.

  • VBK_REG=0 indicates the first bank
  • VBK_REG=1 indicates the second

◆ set_bkg_1bit_data()

void set_bkg_1bit_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data,
UINT8  color 
)

Sets VRAM Tile Pattern data for the Background / Window using 1bpp source data

Parameters
first_tileIndex of the first Tile to write
nb_tilesNumber of Tiles to write
dataPointer to (1bpp) source Tile Pattern data
colorColor

Similar to set_bkg_data, except source data is 1 bit-per-pixel which gets expanded into 2 bits-per-pixel.

For a given bit that represent a pixel:

  • 0 will be expanded into color 0
  • 1 will be expanded into color 1, 2 or 3 depending on color argument
See also
SHOW_BKG, HIDE_BKG, set_bkg_tiles

◆ get_bkg_data()

void get_bkg_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Copies from Background / Window VRAM Tile Pattern data into a buffer

Parameters
first_tileIndex of the first Tile to read from
nb_tilesNumber of Tiles to read
dataPointer to destination buffer for Tile Pattern data

Copies nb_tiles tiles from VRAM starting at first_tile, Tile data is copied into data.

Each Tile is 16 bytes, so the buffer pointed to by data should be at least nb_tiles x 16 bytes in size.

See also
get_win_data

◆ set_bkg_tiles()

void set_bkg_tiles ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
unsigned char *  tiles 
)

Sets a rectangular region of Tile Map entries for the Background layer.

Parameters
xX Start position in Background Map tile coordinates. Range 0 - 31
yY Start position in Background Map tile coordinates. Range 0 - 31
wWidth of area to set in tiles. Range 0 - 31
hHeight of area to set in tiles. Range 0 - 31
tilesPointer to source Tile Map data

Entries are copied from tiles to the Background Tile Map starting at x, y writing across for w tiles and down for h tiles.

One byte per Tile map entry.

Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.

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

  • VBK_REG=0 Tile Numbers are written
  • VBK_REG=1 Tile Attributes are written

GBC Tile Attributes are defined as:

  • Bit 7 - Priority flag. When this is set, it puts the tile above the sprites with colour 0 being transparent.
    0: Below sprites
    1: Above sprites
    Note: SHOW_BKG needs to be set for these priorities to take place.
  • Bit 6 - Vertical flip. Dictates which way up the tile is drawn vertically.
    0: Normal
    1: Flipped Vertically
  • Bit 5 - Horizontal flip. Dictates which way up the tile is drawn horizontally.
    0: Normal
    1: Flipped Horizontally
  • Bit 4 - Not used
  • Bit 3 - Character Bank specification. Dictates from which bank of Background Tile Patterns the tile is taken.
    0: Bank 0
    1: Bank 1
  • Bit 2 - See bit 0.
  • Bit 1 - See bit 0.
  • Bit 0 - Bits 0-2 indicate which of the 7 BKG colour palettes the tile is assigned.
See also
SHOW_BKG
set_bkg_data

◆ get_bkg_tiles()

void get_bkg_tiles ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
unsigned char *  tiles 
)

Copies a rectangular region of Background Tile Map entries into a buffer.

Parameters
xX Start position in Background Map tile coordinates. Range 0 - 31
yY Start position in Background Map tile coordinates. Range 0 - 31
wWidth of area to copy in tiles. Range 0 - 31
hHeight of area to copy in tiles. Range 0 - 31
tilesPointer to destination buffer for Tile Map data

Entries are copied into tiles from the Background Tile Map starting at x, y reading across for w tiles and down for h tiles.

One byte per tile.

The buffer pointed to by tiles should be at least x x y bytes in size.

◆ move_bkg()

void move_bkg ( UINT8  x,
UINT8  y 
)
inline

Moves the Background Layer to the position specified in x and y in pixels.

Parameters
xX axis screen coordinate for Left edge of the Background
yY axis screen coordinate for Top edge of the Background

0,0 is the top left corner of the GB screen. The Background Layer wraps around the screen, so when part of it goes off the screen it appears on the opposite side (factoring in the larger size of the Background Layer versus the screen size).

The background layer is always under the Window Layer.

See also
SHOW_BKG, HIDE_BKG

◆ scroll_bkg()

void scroll_bkg ( INT8  x,
INT8  y 
)
inline

Moves the Background relative to it's current position.

Parameters
xNumber of pixels to move the Background on the X axis
Range: -128 - 127
yNumber of pixels to move the Background on the Y axis
Range: -128 - 127
See also
move_bkg

◆ set_win_data()

void set_win_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Sets VRAM Tile Pattern data for the Window / Background

Parameters
first_tileIndex of the first tile to write
nb_tilesNumber of tiles to write
dataPointer to (2 bpp) source Tile Pattern data.

This is the same as set_bkg_data, since the Window Layer and Background Layer share the same Tile pattern data.

See also
set_bkg_data
set_win_tiles
SHOW_WIN, HIDE_WIN

◆ set_win_1bit_data()

void set_win_1bit_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Sets VRAM Tile Pattern data for the Window / Background using 1bpp source data

Parameters
first_tileIndex of the first tile to write
nb_tilesNumber of tiles to write
dataPointer to (1bpp) source Tile Pattern data

This is the same as set_bkg_1bit_data, since the Window Layer and Background Layer share the same Tile pattern data.

See also
set_bkg_data, set_bkg_1bit_data, set_win_data

◆ get_win_data()

void get_win_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Copies from Window / Background VRAM Tile Pattern data into a buffer

Parameters
first_tileIndex of the first Tile to read from
nb_tilesNumber of Tiles to read
dataPointer to destination buffer for Tile Pattern Data

This is the same as get_bkg_data, since the Window Layer and Background Layer share the same Tile pattern data.

See also
get_bkg_data

◆ set_win_tiles()

void set_win_tiles ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
unsigned char *  tiles 
)

Sets a rectangular region of Tile Map entries for the Window layer.

Parameters
xX Start position in Window Map tile coordinates. Range 0 - 31
yY Start position in Window Map tile coordinates. Range 0 - 31
wWidth of area to set in tiles. Range 0 - 31
hHeight of area to set in tiles. Range 0 - 31
tilesPointer to source Tile Map data

Entries are copied from tiles to the background Tile Map starting at x, y writing across for w tiles and down for h tiles.

One byte per Tile Map entry.

Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table.

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

  • VBK_REG=0 Tile Numbers are written
  • VBK_REG=1 Tile Attributes are written
See also
set_bkg_tiles For more details about GBC Tile Attributes
SHOW_WIN, HIDE_WIN

◆ get_win_tiles()

void get_win_tiles ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
unsigned char *  tiles 
)

Copies a rectangular region of Window Tile Map entries into a buffer.

Parameters
xX Start position in Window Map tile coordinates. Range 0 - 31
yY Start position in Window Map tile coordinates. Range 0 - 31
wWidth of area to copy in tiles. Range 0 - 31
hHeight of area to copy in tiles. Range 0 - 31
tilesPointer to destination buffer for Tile Map data

Entries are copied into tiles from the Window Tile Map starting at x, y reading across for w tiles and down for h tiles.

One byte per tile.

The buffer pointed to by tiles should be at least x x y bytes in size.

◆ move_win()

void move_win ( UINT8  x,
UINT8  y 
)
inline

Moves the Window to the x, y position on the screen.

Parameters
xX coordinate for Left edge of the Window (actual displayed location will be X - 7)
yY coordinate for Top edge of the Window

7,0 is the top left corner of the screen in Window coordinates. The Window is locked to the bottom right corner.

The Window is always over the Background layer.

See also
SHOW_WIN, HIDE_WIN

◆ scroll_win()

void scroll_win ( INT8  x,
INT8  y 
)
inline

Move the Window relative to its current position.

Parameters
xNumber of pixels to move the window on the X axis
Range: -128 - 127
yNumber of pixels to move the window on the Y axis
Range: -128 - 127
See also
move_win

◆ set_sprite_data()

void set_sprite_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Sets VRAM Tile Pattern data for Sprites

Parameters
first_tileIndex of the first tile to write
nb_tilesNumber of tiles to write
dataPointer to (2 bpp) source Tile Pattern data

Writes nb_tiles tiles to VRAM starting at first_tile, tile data is sourced from data. Each Tile is 16 bytes in size (8x8 pixels, 2 bits-per-pixel).

Note: Sprite Tiles 128-255 share the same memory region as Background Tiles 128-255.

GBC only: VBK_REG determines which bank of Background tile patterns are written to.

  • VBK_REG=0 indicates the first bank
  • VBK_REG=1 indicates the second

◆ set_sprite_1bit_data()

void set_sprite_1bit_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Sets VRAM Tile Pattern data for Sprites using 1bpp source data

Parameters
first_tileIndex of the first tile to write
nb_tilesNumber of tiles to write
dataPointer to (1bpp) source Tile Pattern data

Similar to set_sprite_data, except source data is 1 bit-per-pixel which gets expanded into 2 bits-per-pixel.

For a given bit that represent a pixel:

  • 0 will be expanded into color 0
  • 1 will be expanded into color 3
See also
SHOW_SPRITES, HIDE_SPRITES, set_sprite_tile

◆ get_sprite_data()

void get_sprite_data ( UINT8  first_tile,
UINT8  nb_tiles,
unsigned char *  data 
)

Copies from Sprite VRAM Tile Pattern data into a buffer

Parameters
first_tileIndex of the first tile to read from
nb_tilesNumber of tiles to read
dataPointer to destination buffer for Tile Pattern data

Copies nb_tiles tiles from VRAM starting at first_tile, tile data is copied into data.

Each Tile is 16 bytes, so the buffer pointed to by data should be at least nb_tiles x 16 bytes in size.

◆ SET_SHADOW_OAM_ADDRESS()

void SET_SHADOW_OAM_ADDRESS ( void *  address)
inline

Enable OAM DMA copy each VBlank and set it to transfer any 256-byte aligned array

◆ set_sprite_tile()

void set_sprite_tile ( UINT8  nb,
UINT8  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 get_sprite_tile ( UINT8  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  nb,
UINT8  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 - 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.

◆ get_sprite_prop()

UINT8 get_sprite_prop ( UINT8  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  nb,
UINT8  x,
UINT8  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  nb,
INT8  x,
INT8  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  nb)
inline

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

Parameters
nbSprite number, range 0 - 39

◆ set_data()

void set_data ( unsigned char *  vram_addr,
unsigned char *  data,
UINT16  len 
)

Copies Tile Pattern data to an address in VRAM

Parameters
vram_addrPointer to destination VRAM Address
dataPointer to source buffer
lenNumber of bytes to copy

Copies len bytes from a buffer at data to VRAM starting at vram_addr.

GBC only: VBK_REG determines which bank of Background tile patterns are written to.

  • VBK_REG=0 indicates the first bank
  • VBK_REG=1 indicates the second

◆ get_data()

void get_data ( unsigned char *  data,
unsigned char *  vram_addr,
UINT16  len 
)

Copies Tile Pattern data from an address in VRAM into a buffer

Parameters
vram_addrPointer to source VRAM Address
dataPointer to destination buffer
lenNumber of bytes to copy

Copies len bytes from VRAM starting at vram_addr into a buffer at data.

GBC only: VBK_REG determines which bank of Background tile patterns are written to.

  • VBK_REG=0 indicates the first bank
  • VBK_REG=1 indicates the second

◆ set_tiles()

void set_tiles ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
unsigned char *  vram_addr,
unsigned char *  tiles 
)

Sets a rectangular region of Tile Map entries at a given VRAM Address.

Parameters
xX Start position in Map tile coordinates. Range 0 - 31
yY Start position in Map tile coordinates. Range 0 - 31
wWidth of area to set in tiles. Range 0 - 31
hHeight of area to set in tiles. Range 0 - 31
vram_addrPointer to destination VRAM Address
tilesPointer to source Tile Map data

Entries are copied from tiles to Tile Map at address vram_addr starting at x, y writing across for w tiles and down for h tiles.

One byte per Tile map entry.

There are two 32x32 Tile Maps in VRAM at addresses 9800h-9BFFh and 9C00h-9FFFh.

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

  • VBK_REG=0 Tile Numbers are written
  • VBK_REG=1 Tile Attributes are written

◆ get_tiles()

void get_tiles ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
unsigned char *  tiles,
unsigned char *  vram_addr 
)

Copies a rectangular region of Tile Map entries from a given VRAM Address into a buffer.

Parameters
xX Start position in Background Map tile coordinates. Range 0 - 31
yY Start position in Background Map tile coordinates. Range 0 - 31
wWidth of area to copy in tiles. Range 0 - 31
hHeight of area to copy in tiles. Range 0 - 31
tilesPointer to destination buffer for Tile Map data
vram_addrPointer to source VRAM Address

Entries are copied into tiles from the Background Tile Map starting at x, y reading across for w tiles and down for h tiles.

One byte per tile.

There are two 32x32 Tile Maps in VRAM at addresses 9800h - 9BFFh and 9C00h - 9FFFh.

The buffer pointed to by tiles should be at least x x y bytes in size.

◆ init_win()

void init_win ( UINT8  c)

Initializes the entire Window Tile Map with Tile Number c

Parameters
cTile number to fill with

Note: This function avoids writes during modes 2 & 3

◆ init_bkg()

void init_bkg ( UINT8  c)

Initializes the entire Background Tile Map with Tile Number c

Parameters
cTile number to fill with

Note: This function avoids writes during modes 2 & 3

◆ vmemset()

void vmemset ( void *  s,
UINT8  c,
size_t  n 
)

Fills the VRAM memory region s of size n with Tile Number c

Parameters
sStart address in VRAM
cTile number to fill with
nSize of memory region (in bytes) to fill

Note: This function avoids writes during modes 2 & 3

◆ fill_bkg_rect()

void fill_bkg_rect ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
UINT8  tile 
)

Fills a rectangular region of Tile Map entries for the Background layer with tile.

Parameters
xX Start position in Background Map tile coordinates. Range 0 - 31
yY Start position in Background Map tile coordinates. Range 0 - 31
wWidth of area to set in tiles. Range 0 - 31
hHeight of area to set in tiles. Range 0 - 31
tileFill value

◆ fill_win_rect()

void fill_win_rect ( UINT8  x,
UINT8  y,
UINT8  w,
UINT8  h,
UINT8  tile 
)

Fills a rectangular region of Tile Map entries for the Window layer with tile.

Parameters
xX Start position in Window Map tile coordinates. Range 0 - 31
yY Start position in Window Map tile coordinates. Range 0 - 31
wWidth of area to set in tiles. Range 0 - 31
hHeight of area to set in tiles. Range 0 - 31
tileFill value

Variable Documentation

◆ c

int c

◆ _cpu

UINT8 _cpu
extern

GB CPU type

See also
DMG_TYPE, MGB_TYPE, CGB_TYPE, cpu_fast(), cpu_slow()

◆ sys_time

volatile UINT16 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)

◆ _io_status

volatile UINT8 _io_status
extern

Serial Link: Current IO Status. An OR of IO_*

◆ _io_in

volatile UINT8 _io_in
extern

Serial Link: Byte just read after calling receive_byte()

◆ _io_out

volatile UINT8 _io_out
extern

Serial Link: Write byte to send here before calling send_byte()

◆ _current_bank

__REG _current_bank

Tracks current active ROM bank

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

◆ h

void h

◆ l

void l

◆ b

void b

◆ d

void d

◆ e

void e

◆ 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

__REG _shadow_OAM_base

MSB of shadow_OAM address is used by OAM DMA copying routine

_current_bank
__REG _current_bank
Definition: gb.h:351
UINT16
unsigned int UINT16
Definition: types.h:27
nowait_int_handler
void nowait_int_handler(void) NONBANKED
add_SIO
void add_SIO(int_handler h) NONBANKED
b
void b
Definition: gb.h:453