GB_get_direct_access

Definition

typedef enum {
    GB_DIRECT_ACCESS_ROM,
    GB_DIRECT_ACCESS_RAM,
    GB_DIRECT_ACCESS_CART_RAM,
    GB_DIRECT_ACCESS_VRAM,
    GB_DIRECT_ACCESS_HRAM,
    GB_DIRECT_ACCESS_IO,
    GB_DIRECT_ACCESS_BOOTROM,
    GB_DIRECT_ACCESS_OAM,
    GB_DIRECT_ACCESS_BGP,
    GB_DIRECT_ACCESS_OBP,
    GB_DIRECT_ACCESS_IE,
    GB_DIRECT_ACCESS_ROM0,
} GB_direct_access_t;

void *GB_get_direct_access(GB_gameboy_t *gb, GB_direct_access_t access, size_t *size, uint16_t *bank);

In gb.h

Description

Returns a pointer to various memory regions of the emulated instance that can be freely read and modified. It will also return the size of that memory region via the size output argument, and on applicable regions, the currently mapped bank as well via the bank output argument. You may set bank and/or size to NULL if you don't require them.

The regions supported by this function are:

• GB_DIRECT_ACCESS_ROM: Returns a pointer to the ROM and its size. Will return the ROM bank number mapped at $4000-$7fff.
• GB_DIRECT_ACCESS_ROM0: Similar to GB_DIRECT_ACCESS_ROM, but will return the ROM bank number mapped at $0000-$3fff instead. (Useful when emulating MBCs that can bank-switch within this region, such as MMM01)
• GB_DIRECT_ACCESS_RAM: Returns a pointer to the RAM and its size (either 0x8000 bytes for CGB and newer, or 0x2000 for older models). Will return the RAM bank number mapped at $d000-$dfff.
• GB_DIRECT_ACCESS_CART_RAM: Returns a pointer to the cartridge RAM and its size. Will return the number of the currently mapped cartridge RAM bank.
• GB_DIRECT_ACCESS_VRAM: Returns a pointer to VRAM and its size (either 0x4000 bytes for CGB and newer, or 0x2000 for older models). Will return the currently mapped VRAM bank.
• GB_DIRECT_ACCESS_HRAM: Returns a pointer to HRAM and its size (always 0x7f).
• GB_DIRECT_ACCESS_IO: Returns a pointer to MMIO (see Notes) and its size (always 0x80).
• GB_DIRECT_ACCESS_BOOTROM: Returns a pointer to the boot ROM and its size (either 0x900 bytes for CGB and newer, or 0x100 for older models). Bytes 0x100 to 0x1ff are not used in this buffer.
• GB_DIRECT_ACCESS_OAM: Returns a pointer to OAM and its size (always 0xa0).
• GB_DIRECT_ACCESS_BGP: Returns a pointer to background palette RAM, and its size (always 0x40).
• GB_DIRECT_ACCESS_OBP: Returns a pointer to object palette RAM, and its size (always 0x40).
• GB_DIRECT_ACCESS_IE: Returns a pointer to IE register, and its size (always 1).

Thread Safety

GB_get_direct_access is thread-safe and can be called from any thread and context.

Notes

The pointers returned by this function may become invalid upon calling a function that loads a different ROM (e.g. GB_load_rom) or by switching the emulated model. Make sure not to retain pointers to these buffers after they stop being valid.

Some MMIO registers will not appear in the GB_DIRECT_ACCESS_IO region in the same way they actually appear in the emulator instance's memory, and writes to this region might not always have the desired effect. It is recommended to use GB_read_memory and GB_write_memory to access this region when possible.

Writes to GB_DIRECT_ACCESS_IE can have unexpected results and need to be avoided.

Writes to the GB_DIRECT_ACCESS_BGP and GB_DIRECT_ACCESS_OBP regions might not have an immediate visual effect.

See Also

• GB_read_memory
• GB_safe_read_memory
• GB_write_memory