gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit c9b5e777ff8a0ee69f6f55b57d64c0d69a1d3a7e parent 2a5f330f1610ff476d1129f26bf5f625bb04cbf1 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Fri, 17 Feb 2023 00:26:15 -0800 Merge pull request #480 from bbbbbr/docs_411_next Docs 4.2 Diffstat:
| M | docs/pages/03_using_gbdk.md | 12 | ++++++++++++ |
| M | docs/pages/04_coding_guidelines.md | 6 | ++---- |
| M | docs/pages/06_toolchain.md | 3 | +++ |
| M | docs/pages/06b_supported_consoles.md | 50 | +++++++++++++++++++++++++++++++++++++++++++++----- |
| M | docs/pages/09_migrating_new_versions.md | 8 | ++++++++ |
| M | docs/pages/10_release_notes.md | 8 | ++++++++ |
| M | docs/pages/docs_index.md | 2 | +- |
| M | gbdk-lib/include/gb/cgb.h | 4 | ++-- |
| M | gbdk-lib/include/gb/gb.h | 10 | ++++++---- |
| M | gbdk-lib/include/gb/hardware.h | 6 | +++--- |
| M | gbdk-lib/include/msx/msx.h | 2 | +- |
| M | gbdk-lib/include/nes/nes.h | 6 | +++--- |
| M | gbdk-lib/include/sms/sms.h | 2 | +- |
13 files changed, 95 insertions(+), 24 deletions(-)
diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md @@ -181,3 +181,15 @@ See the `incbin` example project for a demo of how to use it. - Const arrays declared with `somevar[n] = {x}` will __NOT__ get initialized with value `x`. This may change when the SDCC RLE initializer is fixed. Use memset for now if you need it. - SDCC banked calls and @ref far_pointers in GBDK only save one byte for the ROM bank, so for example they are limited to __bank 15__ max for MBC1 and __bank 255__ max for MBC5. See @ref banked_calls for more details. + - In SDCC __pre-initializing a variable__ assigned to SRAM with `-Wf-ba*` will force that variable to be in WRAM instead. + - The following is a workaround for initializing a variable in SRAM. It assignes value `0xA5` to a variable in `bank 0` and assigned to address `0xA000` using the AT() directive: + + + // Workaround for initializing variable in SRAM + // (MBC RAM and Bank needs to get enabled during GSINIT loading) + static uint8_t AT(0x0000) __rRAMG = 0x0a; // Enable SRAM + static uint8_t AT(0x4000) __rRAMB = 0x00; // Set SRAM bank 0 + // Now SRAM is enabled so the variable can get initialized + uint8_t AT(0xA000) initialized_sram_var = 0xA5u; + + diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -191,15 +191,13 @@ Parameters (chars, ints, etc) to @ref printf / @ref sprintf should always be exp For example, below will result in the likely unintended output: ```{.c} -sprintf(str_temp, "%u, %d, %x\n", UINT16_MAX, INT16_MIN, UINT16_MAX); -printf("%s",str_temp); +printf(str_temp, "%u, %d, %x\n", UINT16_MAX, INT16_MIN, UINT16_MAX); // Will output: "65535, 0, 8000" ``` Instead this will give the intended output: ```{.c} -sprintf(str_temp, "%u, %d, %x\n", (uint16_t)UINT16_MAX, (int16_t)INT16_MIN, (uint16_t)UINT16_MAX); -printf("%s",str_temp); +printf(str_temp, "%u, %d, %x\n", (uint16_t)UINT16_MAX, (int16_t)INT16_MIN, (uint16_t)UINT16_MAX); // Will output: "65535, -32768, FFFF" ``` diff --git a/docs/pages/06_toolchain.md b/docs/pages/06_toolchain.md @@ -257,6 +257,9 @@ It is also posible to pass a indexed 8-bit png with the palette properly sorted - Each tile can only have colors from one of these palettes per tile. - The maximum number of colors is 32. +For indexed color images, sometimes RGB paint programs mix up indexed colors in tiles if the same color exists in multiple palettes. + - `-repair_indexed_pal` can be used to fix this problem, though tiles must still follow the rule of using only one palette per tile. + Using this image a tileset will be created - Duplicated tiles will be removed. - Tiles will be matched without mirror, using vertical mirror, horizontal mirror or both (use `-noflip` to turn off matching mirrored tiles). diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md @@ -197,6 +197,46 @@ SMS/GG +@anchor using_cgb_features +# Using Game Boy Color (CGB) Features + +## Differences Versus the Regular Game Boy (DMG/GBP/SGB) +These are some of the main hardware differences between the Regular Game Boy and the Game Boy Color. + + - CPU: Optional 2x Speed mode + - Serial Link: Additional Speeds 2KB/s, 32KB/s, 64KB/s + - IR Port + - Sprites: + - 2 x 256 banks of tile patterns (2x as many) (typically upper 256 shared with background) + - 8 x 4 color palettes in CGB mode (BGR-555 per color, 32768 color choices) + - Background: + - 2 x 256 banks of tile patterns (2x as many) (typically upper 256 shared with sprites) + - Second map bank for tile attributes (color, flipping/mirroring, priority, bank) + - 8 x 4 color palettes in CGB mode (BGR-555 per color, 32768 color choices)) + - BG and Window master priority + - WRAM: 8 x 4K WRAM banks in the 0xD000 - 0xDFFF region + - LCD VRAM DMA + +## CGB features in GBDK +These are some of the main GBDK API features for the CGB. +Many of the items listed below link to additional information. + + - Tile and Pattern data: + - Select VRAM Banks: @ref VBK_REG (used with `set_bkg/win/sprite_*()`) + - set_bkg_attributes(), set_bkg_submap_attributes() + - Color: + - set_bkg_palette(), set_bkg_palette_entry() + - set_sprite_palette(), set_sprite_palette_entry() + - set_default_palette() + - RGB(), RGB8(), RGBHTML() + - Detect and change CPU speed: if (@ref _cpu == @ref CGB_TYPE), cpu_fast() + - More details in @ref cgb.h (`#include <gb/cgb.h>`) + +## CGB Examples +Several examples in GBDK show how to use CGB features, including the following: + - `gb/colorbar`, `gb/dscan`, `cross-platform/large_map`, `cross-platform/logo`, `cross-platform/metasprites` + + # Porting Between Supported Consoles ## From Game Boy to Analogue Pocket @@ -213,7 +253,7 @@ The Analogue Pocket operating in `.pocket` mode is (for practical purposes) func ### Observed differences: - - MBC1 and MBC5 are supported, MBC3 won't save, the HuC3 isn't supported at all (via JoseJX) + - MBC1 and MBC5 are supported, MBC3 won't save and RTC doesn't progress when game is not running, the HuC3 isn't supported at all (via JoseJX and sg). - The Serial Link port does not work - The IR port in CGB mode does not work as reliably as the Game Boy Color @@ -267,7 +307,7 @@ This behavior is emulated for the SMS/GG when using @ref set_bkg_tiles() and @re ## From Game Boy to Mega Duck / Cougar Boy The Mega Duck is (for practical purposes) functionally identical to the Original Game Boy though it has a couple changes listed below. -### Summary of changes: +### Summary of Hardware changes: - Cartridge Boot Logo: not present on Mega Duck - Cartridge Header data: not present on Mega Duck - Program Entry Point: `0x0000` (on Game Boy: `0x0100` ) @@ -285,16 +325,16 @@ In order for software to be easily ported to the Mega Duck, or to run on both, u @anchor megaduck_sound_register_value_changes ### Sound Register Value Changes -The only changes which will not be handled automatically with the practices mentioned above these two cases. +There are two hardware changes which will not be handled automatically when following the practices mentioned above. -These changes may be required when using existing Sound Effects and Music Drivers. +These changes may be required when using existing Sound Effects and Music Drivers written for the Game Boy. 1. Registers @ref NR12_REG, @ref NR22_REG, @ref NR42_REG, and @ref NR43_REG have their contents nybble swapped. - To maintain compatibility the value to write (or the value read) can be converted this way: `((uint8_t)(value << 4) | (uint8_t)(value >> 4))` 2. Register @ref NR32_REG has the volume bit values changed. - `Game Boy: Bits:6..5 : 00 = mute, 01 = 100%, 10 = 50%, 11 = 25%` - `Mega Duck: Bits:6..5 : 00 = mute, 01 = 25%, 10 = 50%, 11 = 100%` - - To maintain compatibility the value to write (or the value read) can be converted this way: `(((~(uint8_t)value) + 1u) & (uint8_t)0x60u)` + - To maintain compatibility the value to write (or the value read) can be converted this way: `(((~(uint8_t)value) + (uint8_t)0x20u) & (uint8_t)0x60u)` ### Graphics Register Bit Changes These changes are handled automatically when their GBDK definitions are used. diff --git a/docs/pages/09_migrating_new_versions.md b/docs/pages/09_migrating_new_versions.md @@ -4,6 +4,10 @@ This section contains information that may be useful to know or important when u # GBDK-2020 versions +## Porting to GBDK-2020 4.2 + - GBDK now requires SDCC 4.3 or higher with GBDK-2020 patches for the the z80 linker + - wait_vbl_done() has been renamed to vsync(). The old name will continue to work for the time being, but migration to the new name is strongly encouraged. + ## Porting to GBDK-2020 4.1.1 - No significant changes required @@ -14,6 +18,10 @@ This section contains information that may be useful to know or important when u - If you are linking to libraries compiled with an older version of SDCC / GBDK then you may have to recompile them. - If there are existing functions written in ASM which __receive parameters__ they should also be reviewed to make sure they work with the new `__sdcccall(1)` calling convention, or have their header declaration changed to use `OLDCALL`. - If there are existing functions written in ASM which __call other functions written in C__ the callee C function should be declared OLDCALL. + - Function pointer declarations should be checked to see if they need OLDCALL added to the declaration. + - Example (add OLDCALL at the end) + - FROM: `typedef void (*someFunc)(uint8_t, uint8_t);` + - TO: `typedef void (*someFunc)(uint8_t, uint8_t) OLDCALL;` - If you are using tools such as `rgb2sdas` (from hUGETracker/Driver) you may need to edit the resulting .o file and replace `-mgbz80` with `-msm83` in addition to using `OLDCALL` - The SDCC `PORT` name for the Game Boy and related clones changed from `gbz80` to `sm83`. - Additional details in the @ref console_port_plat_settings "Console Port and Platform Settings" section and @ref faq_gbz80_sm83_old_port_name_error "FAQ entry". @ref lcc will error out if the old `PORT` name is passed in. diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -6,6 +6,14 @@ https://github.com/gbdk-2020/gbdk-2020/releases # GBDK-2020 Release Notes +## GBDK-2020 4.2 + 2023/x + - Library + - wait_vbl_done() has been renamed to vsync(). The old name will continue to work for the time being, but migration to the new name is strongly encouraged. + - Added: set_bkg_attributes(), set_bkg_submap_attributes() + - Docs: + - Expanded @ref megaduck_sound_register_value_changes "MegaDuck hardware documentation" + ## GBDK-2020 4.1.1 2022/11 - Library diff --git a/docs/pages/docs_index.md b/docs/pages/docs_index.md @@ -38,7 +38,7 @@ GBDK features: - A set of libraries with source code - Example programs in ASM and in C - Support for multiple ROM bank images and auto-banking - - Support for multiple consoles: Game Boy, Analogue Pocket, Mega Duck, Master System and Game Gear + - Support for multiple consoles: Game Boy, Analogue Pocket, Mega Duck, Master System and Game Gear, expirimental NES support GBDK is freeware. Most of the tooling code is under the GPL. The runtime libraries should be under the LGPL. Please consider mentioning GBDK in the credits of projects made with it. diff --git a/gbdk-lib/include/gb/cgb.h b/gbdk-lib/include/gb/cgb.h @@ -173,7 +173,7 @@ void cpu_slow(void); */ void cpu_fast(void); -/** Set palette, compatible with the DMG/GBP. +/** Sets CGB palette 0 to be compatible with the DMG/GBP. The default/first CGB palettes for sprites and backgrounds are set to a similar default appearance as on the DMG/Pocket/SGB models. @@ -183,7 +183,7 @@ void cpu_fast(void); */ void set_default_palette(void); -/** This function is obsolete +/** This function has been replaced by set_default_palette(), which has identical behavior. */ void cgb_compatibility(void); diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -745,7 +745,8 @@ void set_interrupts(uint8_t flags) PRESERVES_REGS(b, c, d, e, h, l); */ void reset(void); -/** HALTs the CPU and waits for the vertical blank interrupt. +/** 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 @@ -757,7 +758,8 @@ void reset(void); */ void vsync(void) PRESERVES_REGS(b, c, d, e, h, l); -/** Obsolete +/** This function has been replaced by vsync(), which has identical behavior. + */ void wait_vbl_done(void) PRESERVES_REGS(b, c, d, e, h, l); @@ -1069,7 +1071,7 @@ inline void set_bkg_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, cons @param y Y Start position in Background Map tile coordinates. Range 0 - 31 @param w Width of area to set in tiles. Range 1 - 32 @param h Height of area to set in tiles. Range 1 - 32 - @param tiles Pointer to source tile map data + @param tiles 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. @@ -1202,7 +1204,7 @@ inline void set_bkg_based_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, con @param y Y Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255 @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 Pointer to source tile map attribute 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 diff --git a/gbdk-lib/include/gb/hardware.h b/gbdk-lib/include/gb/hardware.h @@ -292,11 +292,11 @@ __REG LYC_REG; /**< LY compare */ #define rLYC LYC_REG __REG DMA_REG; /**< DMA transfer */ #define rDMA DMA_REG -__REG BGP_REG; /**< BG palette data */ +__REG BGP_REG; /**< Background palette data @see OBP0_REG, OBP1_REG, DMG_PALETTE, DMG_BLACK, DMG_DARK_GRAY, DMG_LITE_GRAY, DMG_WHITE */ #define rBGP BGP_REG -__REG OBP0_REG; /**< OBJ palette 0 data */ +__REG OBP0_REG; /**< OBJ (Sprite) palette 0 data @see OBP1_REG, BGP_REG, DMG_PALETTE, DMG_BLACK, DMG_DARK_GRAY, DMG_LITE_GRAY, DMG_WHITE */ #define rOBP0 OBP0_REG -__REG OBP1_REG; /**< OBJ palette 1 data */ +__REG OBP1_REG; /**< OBJ (Sprite) palette 1 data @see OBP0_REG, BGP_REG, DMG_PALETTE, DMG_BLACK, DMG_DARK_GRAY, DMG_LITE_GRAY, DMG_WHITE */ #define rOBP1 OBP1_REG __REG WY_REG; /**< Window Y coordinate */ #define rWY WY_REG diff --git a/gbdk-lib/include/msx/msx.h b/gbdk-lib/include/msx/msx.h @@ -214,7 +214,7 @@ inline void scroll_bkg(int8_t x, int8_t y) { */ void vsync(void) PRESERVES_REGS(b, c, d, e, h, l, iyh, iyl); -/** Obsolete +/** This function has been replaced by vsync(), which has identical behavior. */ void wait_vbl_done(void) PRESERVES_REGS(b, c, d, e, h, l, iyh, iyl); diff --git a/gbdk-lib/include/nes/nes.h b/gbdk-lib/include/nes/nes.h @@ -337,7 +337,7 @@ inline void disable_interrupts(void) { */ void vsync(void); -/** Obsolete +/** This function has been replaced by vsync(), which has identical behavior. */ void wait_vbl_done(void); @@ -493,7 +493,7 @@ void set_bkg_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *ti @param y Y Start position in Background Map tile coordinates. Range 0 - 14 @param w Width of area to set in tiles. Range 1 - 16 @param h Height of area to set in tiles. Range 1 - 15 - @param tiles Pointer to source tile map data + @param tiles 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. @@ -522,7 +522,7 @@ void set_bkg_attributes_nes16x16(uint8_t x, uint8_t y, uint8_t w, uint8_t h, con \li 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. + 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. diff --git a/gbdk-lib/include/sms/sms.h b/gbdk-lib/include/sms/sms.h @@ -218,7 +218,7 @@ inline void scroll_bkg(int8_t x, int8_t y) { */ void vsync(void) PRESERVES_REGS(b, c, d, e, h, l, iyh, iyl); -/** Obsolete +/** This function has been replaced by vsync(), which has identical behavior. */ void wait_vbl_done(void) PRESERVES_REGS(b, c, d, e, h, l, 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.