GBDK 2020 Docs 4.4.0 API Documentation for GBDK 2020

Data Structures | Macros | Typedefs | Functions | Variables
nes.h File Reference
`#include <types.h>`
`#include <stdint.h>`
`#include <gbdk/version.h>`
`#include <nes/hardware.h>`
`#include <nes/rgb_to_nes_macro.h>`

Go to the source code of this file.

## Data Structures
struct | joypads_t
struct | OAM_item_t

## Macros
#define | NINTENDO_NES
#define | SYSTEM_BITS_NTSC 0x00
#define | SYSTEM_BITS_PAL 0x40
#define | SYSTEM_BITS_DENDY 0x80
#define | SYSTEM_60HZ 0x00
#define | SYSTEM_50HZ 0x01
#define | TIMER_VBLANK_PARITY_MODE_SYSTEM_60HZ 0x78
#define | TIMER_VBLANK_PARITY_MODE_SYSTEM_50HZ 0x5D
#define | RGB(r, g, b) RGB_TO_NES(((r) | ((g) << 2) | ((b) << 4)))
#define | RGB8(r, g, b) RGB_TO_NES((((r) >> 6) | (((g) >> 6) << 2) | (((b) >> 6) << 4)))
#define | RGBHTML(RGB24bit) RGB_TO_NES((((RGB24bit) >> 22) | ((((RGB24bit) & 0xFFFF) >> 14) << 2) | ((((RGB24bit) & 0xFF) >> 6) << 4)))
#define | RGB_RED 0x16
#define | RGB_DARKRED 0x06
#define | RGB_GREEN 0x2A
#define | RGB_DARKGREEN 0x1A
#define | RGB_BLUE 0x12
#define | RGB_DARKBLUE 0x02
#define | RGB_YELLOW 0x28
#define | RGB_DARKYELLOW 0x18
#define | RGB_CYAN 0x2C
#define | RGB_AQUA 0x1C
#define | RGB_PINK 0x24
#define | RGB_PURPLE 0x14
#define | RGB_BLACK 0x0F
#define | RGB_DARKGRAY 0x00
#define | RGB_LIGHTGRAY 0x10
#define | RGB_WHITE 0x30
#define | J_UP 0x08U
#define | J_DOWN 0x04U
#define | J_LEFT 0x02U
#define | J_RIGHT 0x01U
#define | J_A 0x80U
#define | J_B 0x40U
#define | J_SELECT 0x20U
#define | J_START 0x10U
#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 0x40U
#define | S_FLIPY 0x80U
#define | S_PRIORITY 0x20U
#define | S_PAL(n) n
#define | EMPTY_IFLAG 0x00U
#define | VBL_IFLAG 0x01U
#define | LCD_IFLAG 0x02U
#define | TIM_IFLAG 0x04U
#define | DMG_BLACK 0x03
#define | DMG_DARK_GRAY 0x02
#define | DMG_LITE_GRAY 0x01
#define | DMG_WHITE 0x00
#define | DMG_PALETTE(C0, C1, C2, C3) ((uint8_t)((((C3) & 0x03) << 6) | (((C2) & 0x03) << 4) | (((C1) & 0x03) << 2) | ((C0) & 0x03)))
#define | SCREENWIDTH DEVICE_SCREEN_PX_WIDTH
#define | SCREENHEIGHT DEVICE_SCREEN_PX_HEIGHT
#define | MAX_LCD_ISR_CALLS 4
#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_ROM_DUMMY(b)
#define | SWITCH_ROM_UNROM(b) _switch_prg0(b)
#define | SWITCH_ROM SWITCH_ROM_UNROM
#define | SWITCH_RAM(b) 0
#define | ENABLE_RAM
#define | DISABLE_RAM
#define | DISPLAY_ON display_on();
#define | DISPLAY_OFF display_off();
#define | HIDE_LEFT_COLUMN shadow_PPUMASK &= ~(PPUMASK_SHOW_BG_LC | PPUMASK_SHOW_SPR_LC); \
#define | SHOW_LEFT_COLUMN shadow_PPUMASK |= (PPUMASK_SHOW_BG_LC | PPUMASK_SHOW_SPR_LC);
#define | SET_BORDER_COLOR(C)
#define | SHOW_BKG shadow_PPUMASK |= PPUMASK_SHOW_BG;
#define | HIDE_BKG shadow_PPUMASK &= ~PPUMASK_SHOW_BG;
#define | SHOW_SPRITES shadow_PPUMASK |= PPUMASK_SHOW_SPR;
#define | HIDE_SPRITES shadow_PPUMASK &= ~PPUMASK_SHOW_SPR;
#define | SPRITES_8x16 shadow_PPUCTRL |= PPUCTRL_SPR_8X16;
#define | SPRITES_8x8 shadow_PPUCTRL &= ~PPUCTRL_SPR_8X16;
#define | COMPAT_PALETTE(C0, C1, C2, C3) ((uint8_t)(((C3) << 6) | ((C2) << 4) | ((C1) << 2) | (C0)))
#define | set_bkg_2bpp_data set_bkg_data
#define | set_tile_map set_bkg_tiles
#define | set_tile_submap set_bkg_submap
#define | set_tile_xy set_bkg_tile_xy
#define | set_attribute_xy set_bkg_attribute_xy
#define | set_sprite_2bpp_data set_sprite_data
#define | DISABLE_OAM_DMA _shadow_OAM_base = 0
#define | DISABLE_VBL_TRANSFER DISABLE_OAM_DMA
#define | ENABLE_OAM_DMA _shadow_OAM_base = (uint8_t)((uint16_t)&shadow_OAM >> 8)
#define | ENABLE_VBL_TRANSFER ENABLE_OAM_DMA
#define | MAX_HARDWARE_SPRITES 64
#define | HARDWARE_SPRITE_CAN_FLIP_X 1
#define | HARDWARE_SPRITE_CAN_FLIP_Y 1
#define | fill_rect fill_bkg_rect

## Typedefs
typedef uint8_t | palette_color_t
typedef void(* | int_handler) (void) NONBANKED
typedef struct OAM_item_t | OAM_item_t

## Functions
void | set_bkg_palette (uint8_t first_palette, uint8_t nb_palettes, const palette_color_t *rgb_data) NO_OVERLAY_LOCALS
void | set_sprite_palette (uint8_t first_palette, uint8_t nb_palettes, const palette_color_t *rgb_data) NO_OVERLAY_LOCALS
void | set_bkg_palette_entry (uint8_t palette, uint8_t entry, palette_color_t rgb_data) NO_OVERLAY_LOCALS
void | set_sprite_palette_entry (uint8_t palette, uint8_t entry, palette_color_t rgb_data) NO_OVERLAY_LOCALS
void | remove_VBL (int_handler h) NO_OVERLAY_LOCALS
void | remove_LCD (int_handler h) NO_OVERLAY_LOCALS
void | remove_TIM (int_handler h) NO_OVERLAY_LOCALS
void | add_VBL (int_handler h) NO_OVERLAY_LOCALS
void | add_LCD (int_handler h) NO_OVERLAY_LOCALS
void | add_TIM (int_handler h) NO_OVERLAY_LOCALS
void | mode (uint8_t m) NO_OVERLAY_LOCALS
uint8_t | get_mode (void) NO_OVERLAY_LOCALS
uint8_t | get_system (void)
void | delay (uint16_t d) NO_OVERLAY_LOCALS
uint8_t | joypad (void) NO_OVERLAY_LOCALS
uint8_t | waitpad (uint8_t mask) NO_OVERLAY_LOCALS
void | waitpadup (void) NO_OVERLAY_LOCALS
uint8_t | joypad_init (uint8_t npads, joypads_t *joypads) NO_OVERLAY_LOCALS
void | joypad_ex (joypads_t *joypads) NO_OVERLAY_LOCALS
void | enable_interrupts (void)
void | disable_interrupts (void)
void | set_interrupts (uint8_t flags) NO_OVERLAY_LOCALS
void | reset (void)
void | vsync (void) NO_OVERLAY_LOCALS
void | wait_vbl_done (void) NO_OVERLAY_LOCALS
void | display_on (void) NO_OVERLAY_LOCALS
void | display_off (void) NO_OVERLAY_LOCALS
void | refresh_OAM (void) NO_OVERLAY_LOCALS
void | set_vram_byte (uint8_t *addr, uint8_t v) NO_OVERLAY_LOCALS
uint8_t * | get_bkg_xy_addr (uint8_t x, uint8_t y) NO_OVERLAY_LOCALS
void | set_2bpp_palette (uint16_t palette)
void | set_1bpp_colors_ex (uint8_t fgcolor, uint8_t bgcolor, uint8_t mode) NO_OVERLAY_LOCALS
void | set_1bpp_colors (uint8_t fgcolor, uint8_t bgcolor)
void | set_bkg_data (uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) NO_OVERLAY_LOCALS
void | set_bkg_1bpp_data (uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) NO_OVERLAY_LOCALS
void | set_bkg_tiles (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *tiles) NO_OVERLAY_LOCALS
void | set_bkg_attributes_nes16x16 (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *attributes) NO_OVERLAY_LOCALS
void | set_bkg_attributes (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *attributes)
void | set_bkg_submap_attributes_nes16x16 (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w) NO_OVERLAY_LOCALS
void | set_bkg_submap_attributes (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *attributes, uint8_t map_w)
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_bkg_submap (uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w) NO_OVERLAY_LOCALS
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 | get_bkg_tiles (uint8_t x, uint8_t y, uint8_t w, uint8_t h, uint8_t *tiles) NO_OVERLAY_LOCALS
uint8_t * | set_bkg_tile_xy (uint8_t x, uint8_t y, uint8_t t) NO_OVERLAY_LOCALS
void | set_bkg_attribute_xy_nes16x16 (uint8_t x, uint8_t y, uint8_t a) NO_OVERLAY_LOCALS
void | set_bkg_attribute_xy (uint8_t x, uint8_t y, uint8_t a)
uint8_t | get_bkg_tile_xy (uint8_t x, uint8_t y) NO_OVERLAY_LOCALS
void | move_bkg (uint8_t x, uint8_t y)
void | scroll_bkg (int8_t x, int8_t y)
void | set_sprite_data (uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) NO_OVERLAY_LOCALS
void | set_sprite_1bpp_data (uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) NO_OVERLAY_LOCALS
void | SET_SHADOW_OAM_ADDRESS (void *address)
void | set_sprite_tile (uint8_t nb, uint8_t tile) NO_OVERLAY_LOCALS
uint8_t | get_sprite_tile (uint8_t nb) NO_OVERLAY_LOCALS
void | set_sprite_prop (uint8_t nb, uint8_t prop) NO_OVERLAY_LOCALS
uint8_t | get_sprite_prop (uint8_t nb) NO_OVERLAY_LOCALS
void | move_sprite (uint8_t nb, uint8_t x, uint8_t y) NO_OVERLAY_LOCALS
void | scroll_sprite (uint8_t nb, int8_t x, int8_t y) NO_OVERLAY_LOCALS
void | hide_sprite (uint8_t nb) NO_OVERLAY_LOCALS
void | set_data (uint8_t *vram_addr, const uint8_t *data, uint16_t len) NO_OVERLAY_LOCALS
void | set_tiles (uint8_t x, uint8_t y, uint8_t w, uint8_t h, uint8_t *vram_addr, const uint8_t *tiles) NO_OVERLAY_LOCALS
void | set_tile_data (uint16_t first_tile, uint8_t nb_tiles, const uint8_t *data)
void | set_bkg_native_data (uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) NO_OVERLAY_LOCALS
void | set_sprite_native_data (uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) NO_OVERLAY_LOCALS
void | set_native_tile_data (uint16_t first_tile, uint8_t nb_tiles, const uint8_t *data)
void | init_bkg (uint8_t c) NO_OVERLAY_LOCALS
void | vmemset (void *s, uint8_t c, size_t n) NO_OVERLAY_LOCALS
void | fill_bkg_rect (uint8_t x, uint8_t y, uint8_t w, uint8_t h, uint8_t tile) NO_OVERLAY_LOCALS
void | flush_shadow_attributes (void) NO_OVERLAY_LOCALS
uint8_t | _switch_prg0 (uint8_t bank) NO_OVERLAY_LOCALS

## Variables
const uint8_t | _SYSTEM
volatile uint16_t | sys_time
volatile uint8_t | _current_bank
uint16_t | _current_1bpp_colors
uint8_t | _map_tile_offset
uint8_t | _submap_tile_offset
volatile struct OAM_item_t | shadow_OAM []
uint8_t | _shadow_OAM_base

## Detailed Description

NES specific functions.

## Macro Definition Documentation

## ◆ NINTENDO_NES

#define NINTENDO_NES

## ◆ SYSTEM_BITS_NTSC

#define SYSTEM_BITS_NTSC 0x00

## ◆ SYSTEM_BITS_PAL

#define SYSTEM_BITS_PAL 0x40

## ◆ SYSTEM_BITS_DENDY

#define SYSTEM_BITS_DENDY 0x80

## ◆ SYSTEM_60HZ

#define SYSTEM_60HZ 0x00

## ◆ SYSTEM_50HZ

#define SYSTEM_50HZ 0x01

## ◆ TIMER_VBLANK_PARITY_MODE_SYSTEM_60HZ

#define TIMER_VBLANK_PARITY_MODE_SYSTEM_60HZ 0x78

## ◆ TIMER_VBLANK_PARITY_MODE_SYSTEM_50HZ

#define TIMER_VBLANK_PARITY_MODE_SYSTEM_50HZ 0x5D

## ◆ RGB

#define RGB | ( |  | r,
|  |  | g,
|  |  | b
| ) |  | RGB_TO_NES(((r) | ((g) << 2) | ((b) << 4)))

## ◆ RGB8

#define RGB8 | ( |  | r,
|  |  | g,
|  |  | b
| ) |  | RGB_TO_NES((((r) >> 6) | (((g) >> 6) << 2) | (((b) >> 6) << 4)))

## ◆ RGBHTML

#define RGBHTML | ( |  | RGB24bit | ) | RGB_TO_NES((((RGB24bit) >> 22) | ((((RGB24bit) & 0xFFFF) >> 14) << 2) | ((((RGB24bit) & 0xFF) >> 6) << 4)))

## ◆ RGB_RED

#define RGB_RED 0x16

Common colors based on the EGA default palette.

Manually entered from https://www.nesdev.org/wiki/PPU_palettes#RGBI

## ◆ RGB_DARKRED

#define RGB_DARKRED 0x06

## ◆ RGB_GREEN

#define RGB_GREEN 0x2A

## ◆ RGB_DARKGREEN

#define RGB_DARKGREEN 0x1A

## ◆ RGB_BLUE

#define RGB_BLUE 0x12

## ◆ RGB_DARKBLUE

#define RGB_DARKBLUE 0x02

## ◆ RGB_YELLOW

#define RGB_YELLOW 0x28

## ◆ RGB_DARKYELLOW

#define RGB_DARKYELLOW 0x18

## ◆ RGB_CYAN

#define RGB_CYAN 0x2C

## ◆ RGB_AQUA

#define RGB_AQUA 0x1C

## ◆ RGB_PINK

#define RGB_PINK 0x24

## ◆ RGB_PURPLE

#define RGB_PURPLE 0x14

## ◆ RGB_BLACK

#define RGB_BLACK 0x0F

## ◆ RGB_DARKGRAY

#define RGB_DARKGRAY 0x00

## ◆ RGB_LIGHTGRAY

#define RGB_LIGHTGRAY 0x10

## ◆ RGB_WHITE

#define RGB_WHITE 0x30

## ◆ J_UP

#define J_UP 0x08U

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

## ◆ J_LEFT

#define J_LEFT 0x02U

## ◆ J_RIGHT

#define J_RIGHT 0x01U

## ◆ J_A

#define J_A 0x80U

## ◆ J_B

#define J_B 0x40U

## ◆ J_SELECT

#define J_SELECT 0x20U

## ◆ J_START

#define J_START 0x10U

## ◆ 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 0x40U

If set the sprite will be flipped horizontally.

See also
  set_sprite_prop()

## ◆ S_FLIPY

#define S_FLIPY 0x80U

If set the sprite will be flipped vertically.

See also
  set_sprite_prop()

## ◆ S_PRIORITY

#define S_PRIORITY 0x20U

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

See also
  set_sprite_prop()

## ◆ S_PAL

#define S_PAL | ( |  | n | ) | n

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

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

Timer Interrupt when the timer TIMA_REG overflows.

See also
  set_interrupts(),
  add_TIM

## ◆ DMG_BLACK

#define DMG_BLACK 0x03

## ◆ DMG_DARK_GRAY

#define DMG_DARK_GRAY 0x02

## ◆ DMG_LITE_GRAY

#define DMG_LITE_GRAY 0x01

## ◆ DMG_WHITE

#define DMG_WHITE 0x00

## ◆ DMG_PALETTE

#define DMG_PALETTE | ( |  | C0,
|  |  | C1,
|  |  | C2,
|  |  | C3
| ) |  | ((uint8_t)((((C3) & 0x03) << 6) | (((C2) & 0x03) << 4) | (((C1) & 0x03) << 2) | ((C0) & 0x03)))

Macro to create a DMG palette from 4 colors

Parameters

  C0 | Color for Index 0
  C1 | Color for Index 1
  C2 | Color for Index 2
  C3 | Color for Index 3

The resulting format is four greyscale colors packed into a single unsigned byte.

Example:

REG_BGP = DMG_PALETTE(DMG_BLACK, DMG_DARK_GRAY, DMG_LITE_GRAY, DMG_WHITE);
DMG_WHITE
#define DMG_WHITE
Definition: gb.h:139
DMG_DARK_GRAY
#define DMG_DARK_GRAY
Definition: gb.h:137
DMG_LITE_GRAY
#define DMG_LITE_GRAY
Definition: gb.h:138
DMG_PALETTE
#define DMG_PALETTE(C0, C1, C2, C3)
Definition: gb.h:159
DMG_BLACK
#define DMG_BLACK
Definition: gb.h:136

See also
  OBP0_REG, OBP1_REG, BGP_REG
  DMG_BLACK, DMG_DARK_GRAY, DMG_LITE_GRAY, DMG_WHITE

## ◆ 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.

## ◆ MAX_LCD_ISR_CALLS

#define MAX_LCD_ISR_CALLS 4

The maximum number of times the LCD handler will be called per frame.

## ◆ CURRENT_BANK

#define CURRENT_BANK _current_bank

## ◆ BANK

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

Obtains the bank number of VARNAME

Parameters

  VARNAME | Name 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

  VARNAME | Variable 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

  VARNAME | Name 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_ROM_DUMMY

#define SWITCH_ROM_DUMMY | ( |  | b | ) |

Dummy macro for no-bank-switching WIP prototype

Parameters

  b | ROM bank to switch to

## ◆ SWITCH_ROM_UNROM

#define SWITCH_ROM_UNROM | ( |  | b | ) | _switch_prg0(b)

Macro for simple UNROM-like switching (write bank# to single 8-bit register)

Parameters

  b | ROM bank to switch to

## ◆ SWITCH_ROM

#define SWITCH_ROM SWITCH_ROM_UNROM

Makes default mapper switch the active ROM bank

Parameters

  b | ROM bank to switch to (max 255)

See also
  SWITCH_ROM_UNROM

## ◆ SWITCH_RAM

#define SWITCH_RAM | ( |  | b | ) | 0

No-op at the moment. Placeholder for future mappers / test compatibility.

Parameters

  b | SRAM bank to switch to

## ◆ ENABLE_RAM

#define ENABLE_RAM

No-op at the moment. Placeholder for future mappers / test compatibility.

## ◆ DISABLE_RAM

#define DISABLE_RAM

No-op at the moment. Placeholder for future mappers / test compatibility.

## ◆ DISPLAY_ON

#define DISPLAY_ON display_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 shadow_PPUMASK &= ~(PPUMASK_SHOW_BG_LC | PPUMASK_SHOW_SPR_LC); \

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 shadow_PPUMASK |= (PPUMASK_SHOW_BG_LC | PPUMASK_SHOW_SPR_LC);

Shows leftmost column

See also
  HIDE_LEFT_COLUMN

## ◆ SET_BORDER_COLOR

#define SET_BORDER_COLOR | ( |  | C | ) |

Does nothing for NES not implemented yet

## ◆ SHOW_BKG

#define SHOW_BKG shadow_PPUMASK |= PPUMASK_SHOW_BG;

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

## ◆ HIDE_BKG

#define HIDE_BKG shadow_PPUMASK &= ~PPUMASK_SHOW_BG;

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

## ◆ SHOW_SPRITES

#define SHOW_SPRITES shadow_PPUMASK |= PPUMASK_SHOW_SPR;

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

## ◆ HIDE_SPRITES

#define HIDE_SPRITES shadow_PPUMASK &= ~PPUMASK_SHOW_SPR;

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

## ◆ SPRITES_8x16

#define SPRITES_8x16 shadow_PPUCTRL |= PPUCTRL_SPR_8X16;

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 shadow_PPUCTRL &= ~PPUCTRL_SPR_8X16;

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

## ◆ COMPAT_PALETTE

#define COMPAT_PALETTE | ( |  | C0,
|  |  | C1,
|  |  | C2,
|  |  | C3
| ) |  | ((uint8_t)(((C3) << 6) | ((C2) << 4) | ((C1) << 2) | (C0)))

## ◆ set_bkg_2bpp_data

#define set_bkg_2bpp_data set_bkg_data

## ◆ set_tile_map

#define set_tile_map set_bkg_tiles

## ◆ set_tile_submap

#define set_tile_submap set_bkg_submap

## ◆ set_tile_xy

#define set_tile_xy set_bkg_tile_xy

## ◆ set_attribute_xy

#define set_attribute_xy set_bkg_attribute_xy

## ◆ set_sprite_2bpp_data

#define set_sprite_2bpp_data set_sprite_data

## ◆ DISABLE_OAM_DMA

#define DISABLE_OAM_DMA _shadow_OAM_base = 0

## ◆ DISABLE_VBL_TRANSFER

#define DISABLE_VBL_TRANSFER DISABLE_OAM_DMA

Disable OAM DMA copy each VBlank

## ◆ ENABLE_OAM_DMA

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

## ◆ ENABLE_VBL_TRANSFER

#define ENABLE_VBL_TRANSFER ENABLE_OAM_DMA

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

## ◆ MAX_HARDWARE_SPRITES

#define MAX_HARDWARE_SPRITES 64

Amount of hardware sprites in OAM

## ◆ HARDWARE_SPRITE_CAN_FLIP_X

#define HARDWARE_SPRITE_CAN_FLIP_X 1

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

## ◆ HARDWARE_SPRITE_CAN_FLIP_Y

#define HARDWARE_SPRITE_CAN_FLIP_Y 1

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

## ◆ fill_rect

#define fill_rect fill_bkg_rect

## Typedef Documentation

## ◆ palette_color_t

typedef uint8_t palette_color_t

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

  x | X Coordinate of the sprite on screen
  y | Y Coordinate of the sprite on screen - 1
  tile | Sprite tile number (see set_sprite_tile)
  prop | OAM Property Flags (see set_sprite_prop)

## Function Documentation

## ◆ set_bkg_palette()

void set_bkg_palette | ( | uint8_t | first_palette,
|  | uint8_t | nb_palettes,
|  | const palette_color_t * | rgb_data
| ) |  |

## ◆ set_sprite_palette()

void set_sprite_palette | ( | uint8_t | first_palette,
|  | uint8_t | nb_palettes,
|  | const palette_color_t * | rgb_data
| ) |  |

## ◆ set_bkg_palette_entry()

void set_bkg_palette_entry | ( | uint8_t | palette,
|  | uint8_t | entry,
|  | palette_color_t | rgb_data
| ) |  |

## ◆ set_sprite_palette_entry()

void set_sprite_palette_entry | ( | uint8_t | palette,
|  | uint8_t | entry,
|  | palette_color_t | rgb_data
| ) |  |

## ◆ 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()

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()

## ◆ add_VBL()

void add_VBL | ( | int_handler | h | ) |

Adds a Vertical Blanking interrupt handler.

Parameters

  h | The handler to be called whenever a V-blank interrupt occurs.

Only a single handler is currently supported for NES.

Do not use the function definition attributes CRITICAL and INTERRUPT when declaring ISR functions added via add_VBL() (or LCD, etc). Those attributes are only required when constructing a bare jump from the interrupt vector itself (such as with ISR_VECTOR()).

ISR handlers added using add_VBL()/etc are instead called via the GBDK ISR dispatcher which makes the extra function attributes unecessary.

Note
  The default GBDK VBL is installed automatically.
  On the current NES implementation, this handler is actually faked, and called before vblank occurs, by vsync(). Writes to PPU registers should be done to the shadow_ versions, so they are updated by the default VBL handler only when vblank actually occurs.

See also
  ISR_VECTOR()

Adds a V-blank interrupt handler.

## ◆ add_LCD()

void add_LCD | ( | int_handler | h | ) |

Adds a LCD interrupt handler.

Called when the scanline matches the _lcd_scanline variables.

Only a single handler is currently supported for NES.

The use-case 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 scrolling registers to perform special video effects.

Do not use the function definition attributes CRITICAL and INTERRUPT when declaring ISR functions added via add_VBL() (or LCD, etc). Those attributes are only required when constructing a bare jump from the interrupt vector itself (such as with ISR_VECTOR()).

ISR handlers added using add_VBL()/etc are instead called via the GBDK ISR dispatcher which makes the extra function attributes unecessary.

Note
  On the current NES implementation, this handler is actually faked, and called by the default VBL handler after a manual delay loop. Only one such faked "interrupt" is possible per frame. This means the CPU cycles wasted in the delay loop increase with higher values of _lcd_scanline. In practice, it makes this functionality mostly suited for a top status bar.

See also
  add_VBL, nowait_int_handler, ISR_VECTOR()

Adds a LCD interrupt handler.

## ◆ add_TIM()

void add_TIM | ( | int_handler | h | ) |

Adds a timer interrupt handler.

Can not be used together with add_low_priority_TIM

This interrupt handler is invoked at the end of the NMI handler for gbdk-nes, after first processing the registers writes done by the VBL and and LCD handlers. It is therefore currently limited to 60Hz / 50Hz (depending on system).

Note
  Make sure to wrap TIM interrupt handlers with a nooverlay pragma. For more details see docs_nes_tim_overlay

See also
  add_VBL
  set_interrupts() with TIM_IFLAG, ISR_VECTOR()

## ◆ mode()

void mode | ( | uint8_t | 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_t get_mode | ( | void |  | ) |

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.

## ◆ 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. Return value is an OR of J_*

When testing for multiple different buttons, it's best to read the joypad state once into a variable and then test using that variable.

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

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

When testing for multiple different buttons, it's best to read the joypad state once into a variable and then test using that variable.

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

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.

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

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

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

Parameters

  mask | Bitmask 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

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.

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.

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

  npads | number of joypads requested (1, 2 or 4)
  joypads | pointer 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

See also
  joypad_init(), joypads_t

Polls all avaliable joypads (for the GB and ones connected via SGB)

Parameters

  joypads | pointer to joypads_t structure to be filled with joypad statuses, must be previously initialized with joypad_init()

See also
  joypad_init(), joypads_t

Polls all avaliable joypads

Parameters

  joypads | pointer 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_interrupts()

void set_interrupts | ( | uint8_t | flags | ) |

Sets the interrupt mask to flags.

Parameters

  flags | A logical OR of *_IFLAGS

See also
  VBL_IFLAG, LCD_IFLAG, TIM_IFLAG

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

Parameters

  flags | A 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

## ◆ reset()

void reset | ( | void |  | ) |
| inline

Performs a soft reset.

For the Game Boy and related it does this by jumping to address 0x0150 which is in crt0.s (the c-runtime that executes before main() is called).

This performs various startup steps such as resetting the stack, clearing WRAM and OAM, resetting initialized variables and some display registers (scroll, window, LCDC), etc.

This is not the same a hard power reset.

## ◆ vsync()

void vsync | ( | void |  | ) |

Waits for the vertical blank interrupt.

This is often used in main loops to idle the CPU 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.

HALTs the CPU and waits for the vertical blank interrupt and then returns when all registered VBL ISRs have completed.

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.

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_on()

void display_on | ( | void |  | ) |

Turns the display on.

See also
  DISPLAY_ON

## ◆ display_off()

void display_off | ( | void |  | ) |
| inline

Turns the display off immediately.

See also
  DISPLAY_ON

Turns the display off.

Waits until the VBL before turning the display off.

See also
  DISPLAY_ON

Turns the display off.

See also
  DISPLAY_ON

## ◆ refresh_OAM()

void refresh_OAM | ( | void |  | ) |

Copies data from shadow OAM to OAM

## ◆ set_vram_byte()

void set_vram_byte | ( | uint8_t * | addr,
|  | uint8_t | v
| ) |  |

Set byte in vram at given memory location

Parameters

  addr | address to write to
  v | value

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

## ◆ set_2bpp_palette()

void set_2bpp_palette | ( | uint16_t | palette | ) |
| inline

Sets palette for 2bpp color translation for GG/SMS, does nothing on GB

## ◆ set_1bpp_colors_ex()

void set_1bpp_colors_ex | ( | uint8_t | fgcolor,
|  | uint8_t | bgcolor,
|  | uint8_t | mode
| ) |  |

## ◆ set_1bpp_colors()

void set_1bpp_colors | ( | uint8_t | fgcolor,
|  | uint8_t | bgcolor
| ) |  |
| inline

## ◆ set_bkg_data()

void set_bkg_data | ( | uint8_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |

Sets VRAM Tile Pattern data for the Background

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.

See also
  set_tile_data

Sets VRAM Tile Pattern data for the Background / Window

Parameters

  first_tile | Index of the first tile to write
  nb_tiles | Number of tiles to write
  data | Pointer 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 tile patterns are written to.

- VBK_REG = VBK_BANK_0 indicates the first bank
- VBK_REG = VBK_BANK_1 indicates the second

See also
  set_win_data, set_tile_data

## ◆ set_bkg_1bpp_data()

void set_bkg_1bpp_data | ( | uint8_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |

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

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

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

Parameters

  first_tile | Index of the first Tile to write
  nb_tiles | Number of Tiles to write
  data | Pointer to (1bpp) source Tile Pattern data

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 the Background color
- 1 will be expanded into the Foreground color

See set_1bpp_colors for details about setting the Foreground and Background colors.

See also
  SHOW_BKG, HIDE_BKG, set_bkg_tiles
  set_win_1bpp_data, set_sprite_1bpp_data

## ◆ set_bkg_tiles()

void set_bkg_tiles | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | const uint8_t * | tiles
| ) |  |

Sets a rectangular region of Background Tile Map.

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

Use set_bkg_submap() instead when:

- Source map is wider than 32 tiles.
- Writing a width that does not match the source map width and more than one row high at a time.

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 also
  SHOW_BKG
  set_bkg_data, set_bkg_submap, set_win_tiles, set_tiles

Sets a rectangular region of Background Tile Map.

Parameters

  x | X Start position in Background Map tile coordinates. Range 0 - 31
  y | Y Start position in Background Map tile coordinates. Range 0 - 31
  w | Width of area to set in tiles. Range 1 - 32
  h | Height of area to set in tiles. Range 1 - 32
  tiles | Pointer to source tile map data

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

Use set_bkg_submap() instead when:

- Source map is wider than 32 tiles.
- Writing a width that does not match the source map width and more than one row high at a time.

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.

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 = VBK_TILES Tile Numbers are written
- VBK_REG = VBK_ATTRIBUTES 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, set_bkg_submap, set_win_tiles, set_tiles

## ◆ set_bkg_attributes_nes16x16()

void set_bkg_attributes_nes16x16 | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | const uint8_t * | attributes
| ) |  |

Sets a rectangular region of Background Tile Map Attributes.

Parameters

  x | X Start position in Background Map tile coordinates. Range 0 - 15
  y | Y Start position in Background Map tile coordinates. Range 0 - 14
  w | Width of area to set in tiles. Range 1 - 16
  h | Height of area to set in tiles. Range 1 - 15
  attributes | Pointer to source tile map attribute data

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

NES 16x16 Tile Attributes are tightly packed into 4 attributes per byte, with each 16x16 area of a 32x32 pixel block using the bits as follows: D1-D0: Top-left 16x16 pixels D3-D2: Top-right 16x16 pixels D5-D4: Bottom-left 16x16 pixels D7-D6: Bottom-right 16x16 pixels

https://www.nesdev.org/wiki/PPU_attribute_tables

See also
  SHOW_BKG
  set_bkg_data, set_bkg_submap_attributes, set_win_tiles, set_tiles

## ◆ set_bkg_attributes()

void set_bkg_attributes | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | const uint8_t * | attributes
| ) |  |
| inline

Sets a rectangular region of Background Tile Map Attributes.

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

Use set_bkg_submap_attributes() instead when:

- Source map is wider than 32 tiles.
- Writing a width that does not match the source map width and more than one row high at a time.

One byte per source tile map attribute entry.

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

Please note that this is just a wrapper function for set_bkg_attributes_nes16x16() and divides the coordinates and dimensions by 2 to achieve this. It is intended to make code more portable by using the same coordinate system that systems with the much more common 8x8 attribute resolution would use.

See also
  SHOW_BKG
  set_bkg_data, set_bkg_submap_attributes, set_win_tiles, set_tiles

## ◆ set_bkg_submap_attributes_nes16x16()

void set_bkg_submap_attributes_nes16x16 | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | const uint8_t * | map,
|  | uint8_t | map_w
| ) |  |

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 30 tiles / 16x15 attributes.

Parameters

  x | X Start position in both the Source Attribute Map and hardware Background Map attribute coordinates. Range 0 - 255
  y | Y Start position in both the Source Attribute Map and hardware Background Map attribute coordinates. Range 0 - 255
  w | Width of area to set in Attributes. Range 1 - 127
  h | Height of area to set in Attributes. Range 1 - 127
  map | Pointer to source tile map data
  map_w | Width of source tile map in tiles. Range 1 - 127

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

The x and y parameters are in Source Attribute Map Attribute 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-15 (they are bit-masked: `x & 0xF` and `y & 0xF`). 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 Attribute 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 attribute map entry.

Writes that exceed coordinate 15/14 on the x / 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_bkg_submap_attributes()

void set_bkg_submap_attributes | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | const uint8_t * | attributes,
|  | uint8_t | map_w
| ) |  |
| inline

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

Please note that this is just a wrapper function for set_bkg_submap_attributes_nes16x16() and divides the coordinates and dimensions by 2 to achieve this. It is intended to make code more portable by using the same coordinate system that systems with the much more common 8x8 attribute resolution would use.

See also
  SHOW_BKG
  set_bkg_data, set_bkg_tiles, set_win_submap, set_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

Sets a rectangular region of Background Tile Map. The offset value in base_tile is added to the tile ID for each map entry.

Parameters

  x | X Start position in Background Map tile coordinates. Range 0 - 31
  y | Y Start position in Background Map tile coordinates. Range 0 - 31
  w | Width of area to set in tiles. Range 1 - 32
  h | Height of area to set in tiles. Range 1 - 32
  tiles | Pointer to source tile map data
  base_tile | Offset each tile ID entry of the source map by this value. Range 1 - 255

This is identical to set_bkg_tiles() except that it adds the base_tile parameter for when a tile map's tiles don't start at index zero. (For example, the tiles used by the map range from 100 -> 120 in VRAM instead of 0 -> 20).

See also
  set_bkg_tiles for more details

## ◆ 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.

@ param x X Start position in Background Map tile coordinates. Range 0 - 31 @ param y Y Start position in Background Map tile coordinates. Range 0 - 31 @ param w Width of area to set in tiles. Range 1 - 255 @ param h Height of area to set in tiles. Range 1 - 255 @ param map Pointer to source tile map data @ param map_w Width 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.

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

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

  x | X Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255
  y | Y Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255
  w | Width of area to set in tiles. Range 1 - 255
  h | Height of area to set in tiles. Range 1 - 255
  map | Pointer to source tile map data
  map_w | Width 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_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

Sets a rectangular area of the Background Tile Map using a sub-region from a source tile map. The offset value in base_tile is added to the tile ID for each map entry.

Parameters

  x | X Start position in Background Map tile coordinates. Range 0 - 31
  y | Y Start position in Background Map tile coordinates. Range 0 - 31
  w | Width of area to set in tiles. Range 1 - 255
  h | Height of area to set in tiles. Range 1 - 255
  map | Pointer to source tile map data
  map_w | Width of source tile map in tiles. Range 1 - 255
  base_tile | Offset each tile ID entry of the source map by this value. Range 1 - 255

This is identical to set_bkg_submap() except that it adds the base_tile parameter for when a tile map's tiles don't start at index zero. (For example, the tiles used by the map range from 100 -> 120 in VRAM instead of 0 -> 20).

See also
  set_bkg_submap for more details

## ◆ get_bkg_tiles()

void get_bkg_tiles | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | uint8_t * | tiles
| ) |  |

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

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.

See also
  get_bkg_tile_xy, get_tiles

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

Parameters

  x | X Start position in Background Map tile coordinates. Range 0 - 31
  y | Y Start position in Background Map tile coordinates. Range 0 - 31
  w | Width of area to copy in tiles. Range 0 - 31
  h | Height of area to copy in tiles. Range 0 - 31
  tiles | Pointer to destination buffer for Tile Map data

Note
  In general avoid reading from VRAM since that memory is not accessible at all times. It is also not supported by GBDK on the NES platform. See coding guidelines for more details.

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.

See also
  get_win_tiles, get_bkg_tile_xy, get_tiles, get_vram_byte

## ◆ set_bkg_tile_xy()

uint8_t* set_bkg_tile_xy | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | t
| ) |  |

Set single tile t on background layer at x,y

Parameters

  x | X-coordinate
  y | Y-coordinate
  t | tile index

Returns
  returns the address of tile, so you may use faster set_vram_byte() later

## ◆ set_bkg_attribute_xy_nes16x16()

void set_bkg_attribute_xy_nes16x16 | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | a
| ) |  |

Set single attribute data a on background layer at x,y

Parameters

  x | X-coordinate
  y | Y-coordinate
  a | tile attributes

## ◆ set_bkg_attribute_xy()

void set_bkg_attribute_xy | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | a
| ) |  |
| inline

Set single attribute data a on background layer at x,y

Please note that this is just a wrapper function for set_bkg_submap_attributes_nes16x16() and divides the coordinates and dimensions by 2 to achieve this. It is intended to make code more portable by using the same coordinate system that systems with the much more common 8x8 attribute resolution would use.

Parameters

  x | X-coordinate
  y | Y-coordinate
  a | tile attributes

## ◆ get_bkg_tile_xy()

uint8_t get_bkg_tile_xy | ( | uint8_t | x,
|  | uint8_t | y
| ) |  |

Get single tile t on background layer at x,y

Parameters

  x | X-coordinate
  y | Y-coordinate

Returns
  returns tile index

Get single tile t on background layer at x,y

Parameters

  x | X-coordinate
  y | Y-coordinate

Returns
  returns tile index

Note
  In general avoid reading from VRAM since that memory is not accessible at all times. It is also not supported by GBDK on the NES platform. See coding guidelines for more details.

## ◆ move_bkg()

void move_bkg | ( | uint8_t | x,
|  | uint8_t | y
| ) |  |
| inline

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

Parameters

  x | X axis screen coordinate for Left edge of the Background
  y | Y 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_t | x,
|  | int8_t | y
| ) |  |
| inline

Moves the Background relative to it's current position.

Parameters

  x | Number of pixels to move the Background on the X axis Range: -128 - 127
  y | Number of pixels to move the Background on the Y axis Range: -128 - 127

See also
  move_bkg

## ◆ set_sprite_data()

void set_sprite_data | ( | uint8_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |

Sets VRAM Tile Pattern data for Sprites

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 tile patterns are written to.

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

Sets VRAM Tile Pattern data for Sprites

Parameters

  first_tile | Index of the first tile to write
  nb_tiles | Number of tiles to write
  data | Pointer 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 tile patterns are written to.

- VBK_REG = VBK_BANK_0 indicates the first bank
- VBK_REG = VBK_BANK_1 indicates the second

## ◆ set_sprite_1bpp_data()

void set_sprite_1bpp_data | ( | uint8_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |

Sets VRAM Tile Pattern data for Sprites using 1bpp source 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

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

Parameters

  first_tile | Index of the first tile to write
  nb_tiles | Number of tiles to write
  data | Pointer 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 the Background color
- 1 will be expanded into the Foreground color

See set_1bpp_colors for details about setting the Foreground and Background colors.

See also
  SHOW_SPRITES, HIDE_SPRITES, set_sprite_tile
  set_bkg_1bpp_data, set_win_1bpp_data

## ◆ 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_t | nb,
|  | uint8_t | tile
| ) |  |
| inline

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

Parameters

  nb | Sprite number, range 0 - 63
  tile | Selects a tile (0 - 255) from PPU memory at 0000h - 0FFFh / 1000h - 1FFFh

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

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

Parameters

  nb | Sprite number, range 0 - 39
  tile | Selects 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

  nb | Sprite number, range 0 - 63

See also
  set_sprite_tile for more details

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

Parameters

  nb | Sprite 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

  nb | Sprite number, range 0 - 39
  prop | Property 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.
set_sprite_prop(0, S_FLIPY | S_FLIPX);
S_FLIPY
#define S_FLIPY
Definition: gb.h:96
set_sprite_prop
void set_sprite_prop(uint8_t nb, uint8_t prop)
Definition: gb.h:1945
S_FLIPX
#define S_FLIPX
Definition: gb.h:92
set_sprite_palette
#define set_sprite_palette(first_palette, nb_palettes, rgb_data)
Definition: msx.h:558

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

  nb | Sprite number, range 0 - 39
  prop | Property 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.
set_sprite_prop(0, S_FLIPY | S_FLIPX);

See also
  S_PALETTE, S_FLIPX, S_FLIPY, S_PRIORITY

Function has no affect on sms.

This function is only here to enable game portability

## ◆ get_sprite_prop()

uint8_t get_sprite_prop | ( | uint8_t | nb | ) |
| inline

Returns the OAM Property Flags of sprite number nb.

Parameters

  nb | Sprite 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

  nb | Sprite number, range 0 - 63
  x | X Position. Specifies the sprites horizontal position on the screen (minus 8).
  y | Y Position. Specifies the sprites vertical position on the screen (minus 16). An offscreen value (Y>=240) hides the sprite.

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

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

Parameters

  nb | Sprite number, range 0 - 39
  x | X 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.
  y | Y 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

  nb | Sprite number, range 0 - 63
  x | Number of pixels to move the sprite on the X axis Range: -128 - 127
  y | Number 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

Moves sprite number nb relative to its current position.

Parameters

  nb | Sprite number, range 0 - 39
  x | Number of pixels to move the sprite on the X axis Range: -128 - 127
  y | Number 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 Y position 240.

Parameters

  nb | Sprite number, range 0 - 63

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

Parameters

  nb | Sprite number, range 0 - 39

See also
  hide_sprites_range, HIDE_SPRITES

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

Parameters

  nb | Sprite number, range 0 - 39

## ◆ set_data()

void set_data | ( | uint8_t * | vram_addr,
|  | const uint8_t * | data,
|  | uint16_t | len
| ) |  |

Copies arbitrary data to an address in VRAM without taking into account the state of LCDC bits 3 or 4.

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

See also
  set_bkg_data, set_win_data, set_bkg_tiles, set_win_tiles, set_tile_data, set_tiles

## ◆ set_tiles()

void set_tiles | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | uint8_t * | vram_addr,
|  | const uint8_t * | tiles
| ) |  |

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

Parameters

  x | X Start position in Map tile coordinates. Range 0 - 31
  y | Y Start position in Map tile coordinates. Range 0 - 31
  w | Width of area to set in tiles. Range 1 - 32
  h | Height of area to set in tiles. Range 1 - 32
  vram_addr | Pointer to destination VRAM Address
  tiles | Pointer 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 source tile map entry.

There are two 32x30 Tile Maps in VRAM at addresses 2000h-23FFh and 2400h-27FFh.

See also
  set_bkg_tiles

## ◆ set_tile_data()

void set_tile_data | ( | uint16_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |
| inline

Sets VRAM Tile Pattern data starting from given base address without taking into account the state of PPUMASK.

See also
  set_bkg_data, set_data

## ◆ set_bkg_native_data()

void set_bkg_native_data | ( | uint8_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |
| inline

Sets VRAM Tile Pattern data for the Background in the native format

Parameters

  first_tile | Index of the first tile to write
  nb_tiles | Number of tiles to write
  data | Pointer to source tile data

Writes nb_tiles tiles to VRAM starting at first_tile, tile data is sourced from data.

See also
  set_tile_data

Sets VRAM Tile Pattern data for the Background / Window in the native format

Parameters

  first_tile | Index of the first tile to write
  nb_tiles | Number of tiles to write
  data | Pointer to source tile data

Writes nb_tiles tiles to VRAM starting at first_tile, tile data is sourced from data.

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

- VBK_REG = VBK_BANK_0 indicates the first bank
- VBK_REG = VBK_BANK_1 indicates the second

See also
  set_win_data, set_tile_data

## ◆ set_sprite_native_data()

void set_sprite_native_data | ( | uint8_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |
| inline

Sets VRAM Tile Pattern data for Sprites in the native format

Parameters

  first_tile | Index of the first tile to write
  nb_tiles | Number of tiles to write
  data | Pointer to source tile data

Writes nb_tiles tiles to VRAM starting at first_tile, tile data is sourced from data.

Sets VRAM Tile Pattern data for Sprites in the native format

Parameters

  first_tile | Index of the first tile to write
  nb_tiles | Number of tiles to write
  data | Pointer to source tile data

Writes nb_tiles tiles to VRAM starting at first_tile, tile data is sourced from data.

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

- VBK_REG = VBK_BANK_0 indicates the first bank
- VBK_REG = VBK_BANK_1 indicates the second

## ◆ set_native_tile_data()

void set_native_tile_data | ( | uint16_t | first_tile,
|  | uint8_t | nb_tiles,
|  | const uint8_t * | data
| ) |  |
| inline

Sets VRAM Tile Pattern data in the native format

Parameters

  first_tile | Index of the first tile to write (0 - 511)
  nb_tiles | Number of tiles to write
  data | Pointer to source Tile Pattern data.

When `first_tile` is larger than 256 on the GB/AP, it will write to sprite data instead of background data.

The bit depth of the source Tile Pattern data depends on which console is being used:

- NES: loads 2bpp tiles data

## ◆ init_bkg()

void init_bkg | ( | uint8_t | c | ) |

Initializes the entire Background Tile Map with Tile Number c

Parameters

  c | Tile number to fill with

Note: This function avoids writes during modes 2 & 3

Initializes the entire Background Tile Map with Tile Number c

Parameters

  c | Tile number to fill with

Note
  This function avoids writes during modes 2 & 3

## ◆ vmemset()

void vmemset | ( | void * | s,
|  | uint8_t | c,
|  | size_t | n
| ) |  |

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

Parameters

  s | Start address in VRAM
  c | Tile number to fill with
  n | Size of memory region (in bytes) to fill

Note: This function avoids writes during modes 2 & 3

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

Parameters

  s | Start address in VRAM
  c | Tile number to fill with
  n | Size of memory region (in bytes) to fill

Note
  This function avoids writes during modes 2 & 3

## ◆ fill_bkg_rect()

void fill_bkg_rect | ( | uint8_t | x,
|  | uint8_t | y,
|  | uint8_t | w,
|  | uint8_t | h,
|  | uint8_t | tile
| ) |  |

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

Parameters

  x | X Start position in Background Map tile coordinates. Range 0 - 31
  y | Y Start position in Background Map tile coordinates. Range 0 - 31
  w | Width of area to set in tiles. Range 0 - 31
  h | Height of area to set in tiles. Range 0 - 31
  tile | Fill value

## ◆ flush_shadow_attributes()

void flush_shadow_attributes | ( | void |  | ) |

"Flushes" the updates to the shadow attributes so they are written to the transfer buffer, and then written to PPU memory on next vblank.

This function must be called to see visible changes to attributes on the NES target. But it will automatically be called by vsync(), so the use-cases for calling it manually are rare in practice.

## ◆ _switch_prg0()

uint8_t _switch_prg0 | ( | uint8_t | bank | ) |

## Variable Documentation

## ◆ _SYSTEM

const uint8_t _SYSTEM
| extern

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

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()

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()

## ◆ _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

uint8_t _shadow_OAM_base
| extern

MSB of shadow_OAM address is used by OAM DMA copying routine