gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 414519ef5ac2eea7d281777e9348b3a2ccd95345 parent fd4e12732c4d2fd38e08ded5037524d6033602ad Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Sat, 1 Jul 2023 01:18:34 -0700 Merge pull request #531 from bbbbbr/docs_4_2_0 Docs 4 2 0 Diffstat:
| M | Makefile | 2 | +- |
| M | docs/pages/03_using_gbdk.md | 21 | +++++++++++++++++++++ |
| M | docs/pages/04_coding_guidelines.md | 2 | +- |
| M | docs/pages/05_banking_mbcs.md | 3 | ++- |
| M | docs/pages/06_toolchain.md | 9 | +++++++-- |
| M | docs/pages/10_release_notes.md | 3 | ++- |
| M | gbdk-lib/include/gb/gb.h | 31 | ++++++++++++++++++++++++------- |
| M | gbdk-lib/include/msx/msx.h | 2 | +- |
8 files changed, 59 insertions(+), 14 deletions(-)
diff --git a/Makefile b/Makefile @@ -309,7 +309,7 @@ sdcc-install: check-SDCCDIR @for i in $(SDCC_BINS); do \ cp $(SDCCDIR)/bin/$$i $(BUILDDIR)/bin/ && echo "-> $$i" ; \ done - cp -r $(SDCCDIR)/libexec $(BUILDDIR) && echo "-> cc1" + @cp -r $(SDCCDIR)/libexec $(BUILDDIR) && echo "-> cc1" # Final binary binary: diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md @@ -68,6 +68,13 @@ You can change this behavior using @ref nowait_int_handler() which does not chec ## OAM (VRAM Sprite Attribute Table) GBDK sets up a Shadow OAM which gets copied automatically to the hardware OAM by the default V-Blank ISR. The Shadow OAM allows updating sprites without worrying about whether it is safe to write to them or not based on the hardware LCD mode. +## Graphics Tile Maps and Data on Startup +By default for the Game Boy GBDK assigns: +- Background and Window Tile data starting at `0x8800` +- Background Tile Map starting at `0x9800` +- Window Tile Map starting at `0x9C00` +- Sprites to `8x8` mode + ## Font tiles when using stdio.h Including @ref stdio.h and using functions such as @ref printf() will use a large number of the background tiles for font characters. If stdio.h is not included then that space will be available for use with other tiles instead. @@ -85,6 +92,20 @@ The ISR return behavior @ref isr_nowait_info "can be turned off" using the @ref For more details see the related Pandocs section: https://gbdev.io/pandocs/Accessing_VRAM_and_OAM.html +@anchor using_compression +# Compression +For programs that would benefit from compression GBDK includes the @ref utility_gbcompress "gbcompress" utility and companion API functions. + +In addition to the built-in compression unapack is another option: +- UnaPACK aPack decompression by Toxa: https://github.com/untoxa +- apultra aPack compression: https://github.com/emmanuel-marty/apultra + +Another way to save space is using 1 bit-per-pixel (bpp) tile pattern data instead of 2-bpp or 4-bpp data. This can reduce the ROM size for groups of tiles which only require two shades of color. +- See: set_1bpp_colors(), set_bkg_1bpp_data(), set_win_1bpp_data(), set_sprite_1bpp_data() + +Use of 1-bpp tile pattern data may be combined with the compression described above to save even more space, however that approach requires using an intermediary RAM buffer before the tile pattern data can be written to VRAM with the set_*_1bpp_data() functions. + + # Copying Functions to RAM and HIRAM See the `ram_function` example project included with GBDK which demonstrates copying functions to RAM and HIRAM. diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -40,7 +40,7 @@ If you wish to use the original tools, you must add the `const` keyword every ti @anchor best_practice_dont_read_vram ## Avoid Reading from VRAM -In general avoid reading from VRAM since that memory is not accessible at all times. If GBDK a API function which reads from VRAM (such as @ref get_bkg_tile_xy()) is called during a video mode when VRAM is not accessible, then that function call will delay until VRAM becomes accessible again. This can cause unnecessary slowdowns when running programs on the Game Boy. +In general avoid reading from VRAM since that memory is not accessible at all times. If GBDK a API function which reads from VRAM (such as @ref get_bkg_tile_xy()) is called during a video mode when VRAM is not accessible, then that function call will delay until VRAM becomes accessible again. This can cause unnecessary slowdowns when running programs on the Game Boy. It is also not supported by GBDK on the NES platform. Instead it is better to store things such as map data in general purpose RAM which does not have video mode access limitations. diff --git a/docs/pages/05_banking_mbcs.md b/docs/pages/05_banking_mbcs.md @@ -29,7 +29,7 @@ For most projects we recommend __MBC5__. - __MBC1 is not recommended__. Some banks in it's range are unavailable. See pandocs for more details. https://gbdev.io/pandocs/MBC1 -### Bank 0 Size Limit and Overlows When Using MBCs +### Bank 0 Size Limit and Overflows When Using MBCs When using MBCs and bank switching the space used in the lower fixed Bank `0` **must be <= 16K bytes**. Otherwise it's data will overflow into Bank `1` and may be overwriten or overwrite other data, and can get switched out when banks are changed. See the @ref faq_bank_overflow_errors "FAQ entry about bank overflow errors". @@ -190,6 +190,7 @@ Banked functions (located in a switchable ROM bank) - May use data in any bank: __NO__ - May only use data from fixed Bank 0 and the currently active bank. - A @ref wrapped_function_for_banked_data "NONBANKED wrapper function" may be used to access data in other banks. + - Banks cannot be switched manually from inside a BANKED function (otherwise it will switch out it's own function code as it is executing it, likely leading to a crash). Limitations: - SDCC banked calls and far_pointers in GBDK only save one byte for the ROM bank. So, for example, they are limited to __bank 31__ max for MBC1 and __bank 255__ max for MBC5. This is due to the bank switching for those MBCs requiring a second, additional write to select the upper bits for more banks (banks 32+ in MBC1 and banks 256+ in MBC5). diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md @@ -215,9 +215,14 @@ Compression utility. For detailed settings see @ref gbcompress-settings -Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK, see @ref gb_decompress(). +Compresses (and decompresses) binary file data with the gbcompress algorithm (also used in GBTD/GBMB). Decompression support is available in GBDK: +- gb_decompress(), gb_decompress_bkg_data(), gb_decompress_win_data(), gb_decompress_sprite_data() +- The `cross-platform/gbdecompress` example demonstrates how to use this compression -Can also compress (and decompress) using block style RLE encoding with the `--alg=rle` flag. Decompression support is available in GBDK, see @ref rle_decompress(). + +The utility can also compress (and decompress) using block style RLE encoding with the `--alg=rle` flag. Decompression support is available in GBDK: +- rle_init(), rle_decompress() +- The `cross-platform/rle_map` example demonstrates how to use this compression @anchor utility_png2asset diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -8,7 +8,7 @@ https://github.com/gbdk-2020/gbdk-2020/releases ## GBDK-2020 4.2 2023/x - - Includes SDCC version 14...TODO... with GBDK-2020 patches for Z80 and NES + - Includes SDCC version ~4.3 with GBDK-2020 patches for Z80 and NES - ([Patched SDCC Builds](https://github.com/gbdk-2020/gbdk-2020-sdcc/releases) with support for Sega GG/SMS and the Nintendo NES are used. See the [github workflow](https://github.com/gbdk-2020/gbdk-2020-sdcc/tree/main/.github/workflows) for details - Library - Added: set_bkg_attributes(), set_bkg_submap_attributes() @@ -52,6 +52,7 @@ https://github.com/gbdk-2020/gbdk-2020/releases - Metasprites: Added sub-palette switching for GBC and NES, software metasprite flipping for sms/gg - Large Map: Added color for supported platforms - LCD ISR Wobble: Improved interrupt flag settings + - Added GB-Type example: - Docs: - Added @ref using_cgb_features "Using Game Boy Color Features" - Added SDAS assembler manual (asmlnk_manual.txt) diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -538,6 +538,13 @@ __endasm; \ */ #define SWITCH_ROM(b) (_current_bank = (b), rROMB0 = (b)) +/** Switches SRAM bank on MBC1 and other compatible MBCs + @param b SRAM bank to switch to + + Before switching SRAM banks enable it using @ref ENABLE_RAM + + @see SWITCH_RAM_MBC1, SWITCH_RAM_MBC5 +*/ #define SWITCH_RAM(b) (rRAMB = (b)) #define ENABLE_RAM (rRAMG = 0x0A) @@ -559,16 +566,14 @@ __endasm; \ */ #define SWITCH_ROM_MBC1(b) SWITCH_ROM(b) -/** Switches SRAM bank on MBC1 and other compaticle MBCs +/** Switches SRAM bank on MBC1 and other compatible MBCs @param b SRAM bank to switch to -*/ -#define SWITCH_RAM_MBC1(b) SWITCH_RAM(b) -/** Switches SRAM bank on MBC1 and other compaticle MBCs - @param b SRAM bank to switch to + Before switching SRAM banks enable it using @ref ENABLE_RAM - @see SWITCH_RAM_MBC1, SWITCH_RAM_MBC5 + @see SWITCH_RAM, SWITCH_RAM_MBC5 */ +#define SWITCH_RAM_MBC1(b) SWITCH_RAM(b) /** Enables SRAM on MBC1 */ @@ -613,6 +618,8 @@ __endasm; \ /** Switches SRAM bank on MBC5 @param b SRAM bank to switch to + + Before switching SRAM banks enable it using @ref ENABLE_RAM */ #define SWITCH_RAM_MBC5(b) SWITCH_RAM(b) @@ -879,6 +886,7 @@ void set_vram_byte(uint8_t * addr, uint8_t v) OLDCALL PRESERVES_REGS(b, c); @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. */ @@ -980,6 +988,7 @@ void set_bkg_1bpp_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *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 @ref best_practice_dont_read_vram "coding guidelines" for more details. @@ -1271,6 +1280,7 @@ inline void set_bkg_submap_attributes(uint8_t x, uint8_t y, uint8_t w, uint8_t h @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. @@ -1305,6 +1315,7 @@ uint8_t * set_bkg_tile_xy(uint8_t x, uint8_t y, uint8_t t) OLDCALL PRESERVES_REG @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. @@ -1381,7 +1392,7 @@ void set_win_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) OLD See @ref set_1bpp_colors for details about setting the Foreground and Background colors. - @see set_bkg_data, set_bkg_1bpp_data, set_win_data, set_1bpp_colors + @see set_bkg_data, set_win_data, set_1bpp_colors @see set_bkg_1bpp_data, set_sprite_1bpp_data */ void set_win_1bpp_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data) OLDCALL PRESERVES_REGS(b, c); @@ -1395,6 +1406,7 @@ void set_win_1bpp_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *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 @ref best_practice_dont_read_vram "coding guidelines" for more details. @@ -1550,6 +1562,7 @@ inline void set_win_based_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, con @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. @@ -1583,6 +1596,7 @@ uint8_t * set_win_tile_xy(uint8_t x, uint8_t y, uint8_t t) OLDCALL PRESERVES_REG @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. */ @@ -1666,6 +1680,7 @@ void set_sprite_1bpp_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *d @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. @@ -1881,6 +1896,7 @@ void set_data(uint8_t *vram_addr, const uint8_t *data, uint16_t len); @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. @@ -1959,6 +1975,7 @@ void set_tile_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data, ui @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 @ref best_practice_dont_read_vram "coding guidelines" for more details. diff --git a/gbdk-lib/include/msx/msx.h b/gbdk-lib/include/msx/msx.h @@ -358,7 +358,7 @@ __endasm; \ /** Makes switch the active ROM bank in frame 1 - @param b ROM bank to switch to + @param bank ROM bank to switch to */ void SWITCH_ROM(uint8_t bank) Z88DK_FASTCALL PRESERVES_REGS(b, c, d, e, iyh, iyl);
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.