ShuriZma
/
SameBoy
mirror of https://github.com/LIJI32/SameBoy.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Updated GB_get_direct_access (markdown)

Lior Halphon 2024-11-26 00:43:36 +02:00
parent 313d8bd5cc
commit 2d96d2e671
1 changed files with 33 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
GB_get_direct_access.md

@ -17,14 +17,45 @@ typedef enum {
} GB_direct_access_t;
```
<tt>void *GB_get_direct_access([[GB_gameboy_t]] *gb, [[GB_direct_access_t]] access, size_t *size, uint16_t *bank);</tt>
<tt>void *GB_get_direct_access([[GB_gameboy_t]] *gb, GB_direct_access_t access, size_t *size, uint16_t *bank);</tt>
In `gb.h`
## Description
TBD
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|GB_get_direct_access#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|GB_switch_model_and_reset]]. Make sure to not 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 needs 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]]