gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit d74c664bbbfd73a00ce8c2702ccb3079397acfe9 parent 629647e0fd152ed8ae9a1d344459fec73c4eac0d Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Mon, 14 Nov 2022 17:41:36 -0800 Merge pull request #451 from bbbbbr/docs_4_1_1 Docs: Mega Duck vs Game Boy Hardware differences Diffstat:
| M | docs/pages/06b_supported_consoles.md | 223 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------- |
1 file changed, 154 insertions(+), 69 deletions(-)
diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md @@ -2,7 +2,7 @@ @anchor docs_consoles_supported_list # Consoles Supported by GBDK -As of version `4.0.5` GBDK includes support for other consoles in addition to the Game Boy. +As of version `4.1.0` GBDK includes support for other consoles in addition to the Game Boy. - Game Boy and related clones - Nintendo Game Boy / Game Boy Color (GB/GBC) @@ -147,10 +147,62 @@ The cross-platform `Logo` example project shows how assets can be managed for mu In the example @ref utility_png2asset is used to generate assets in the native format for each console at compile-time from separate source PNG images. The Makefile is set to use the source PNG folder which matches the current console being compiled, and the source code uses @ref set_native_tile_data() to load the assets tiles in native format. -# Porting From Game Boy to Analogue Pocket +# Hardware Summaries +The specs below reflect the typical configuration of hardware when used with GBDK and is not meant as a complete list of their capabilities. + +GB/AP/DUCK +- Sprites: + - 256 tiles (upper 128 are shared with background) (amount is doubled in CGB mode) + - tile flipping/mirroring: yes + - 40 total, max 10 per line + - 2 x 4 color palette (color 0 transparent). 8 x 4 color palettes in CGB mode +- Background: 256 tiles (typical setup: upper 128 are shared with sprites) (amount is doubled in CGB mode) + - tile flipping/mirroring: no (yes in CGB mode) + - 1 x 4 color palette. 8 x 4 color palettes in CGB mode +- Window "layer": available +- Screen: 160 x 144 +- Hardware Map: 256 x 256 + + +SMS/GG +- Sprites: + - 256 tiles (a bit less in the default setup) + - tile flipping/mirroring: no + - 64 total, max 8 per line + - 1 x 16 color palette (color 0 transparent) +- Background: 512 tiles (upper 256 are shared with sprites) + - tile flipping/mirroring: yes + - 2 x 16 color palettes +- Window "layer": not available +- SMS + - Screen: 256 x 192 + - Hardware Map: 256 x 224 +- GG + - Screen: 160 x 144 + - Hardware Map: 256 x 224 + + +@anchor docs_consoles_safe_display_controller_access +## Safe VRAM / Display Controller Access + +GB/AP +- VRAM / Display Controller (PPU) + - VRAM and some other display data / registers should only be written to when the @ref STATF_B_BUSY bit of @ref STAT_REG is off. Most GBDK API calls manage this automatically. + +SMS/GG +- Display Controller (VDP) + - Writing to the VDP should not be interrupted while an operation is already in progress (since that will interfere with the internal data pointer causing data to be written to the wrong location). + - Recommended approach: Avoid writing to the VDP (tiles, map, scrolling, colors, etc) during an interrupt routine (ISR). + - Alternative (requires careful implementation): Make sure writes to the VDP during an ISR are only performed when the @ref _shadow_OAM_OFF flag indicates it is safe to do so. + + + +# Porting Between Supported Consoles + +## From Game Boy to Analogue Pocket The Analogue Pocket operating in `.pocket` mode is (for practical purposes) functionally identical to the Game Boy / Color though it has a couple changes listed below. These are handled automatically in GBDK as long as the practices outlined below are followed. -Official differences: +### Official differences: - Altered register flag and address definitions - @ref STAT_REG "STAT" & @ref LCDC_REG "LCDC": Order of register bits is reversed - Example: @ref LCDCF_B_ON "LCD on/off" is LCDC.0 instead of .7 @@ -160,45 +212,34 @@ Official differences: - `0x01, 0x10, 0xCE, 0xEF, 0x00, 0x00, 0x44, 0xAA, 0x00, 0x74, 0x00, 0x18, 0x11, 0x95, 0x00, 0x34, 0x00, 0x1A, 0x00, 0xD5, 0x00, 0x22, 0x00, 0x69, 0x6F, 0xF6, 0xF7, 0x73, 0x09, 0x90, 0xE1, 0x10, 0x44, 0x40, 0x9A, 0x90, 0xD5, 0xD0, 0x44, 0x30, 0xA9, 0x21, 0x5D, 0x48, 0x22, 0xE0, 0xF8, 0x60` -Observed differences: +### Observed differences: - MBC1 and MBC5 are supported, MBC3 won't save, the HuC3 isn't supported at all (via JoseJX) - The Serial Link port does not work - The IR port in CGB mode does not work as reliably as the Game Boy Color In order for software to be easily ported to the Analogue Pocket, or to run on both, use the following practices. -## Registers and Flags +### Registers and Flags Use API defined registers and register flags instead of hardwired ones. - LCDC register: @ref LCDC_REG or @ref rLCDC - STAT register: @ref STAT_REG or @ref rSTAT - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON) - STAT flags: -> STATF_... (example: @ref STATF_LYC) -## Boot logo +### Boot logo As long as the target console is @ref docs_consoles_compiling "set during build time" then the correct boot logo will be automatically selected. -# Porting From Game Boy to Mega Duck / Cougar Boy -The Mega Duck is fairly similar to the classic Game Boy. It has a couple altered register flag and address definitions, no boot logo and a different startup/entry-point address. In order for software to be easily ported to the Mega Duck, or to run on both, use the following practices. - -## Registers and Flags -Use API defined registers and register flags instead of hardwired ones - - LCDC register: @ref LCDC_REG or @ref rLCDC - - STAT register: @ref STAT_REG or @ref rSTAT - - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON) - - STAT flags: -> STATF_... (example: @ref STATF_LYC) - +## From Game Boy to SMS/GG -# Porting From Game Boy to SMS/GG +### Tile Data and Tile Map loading -## Tile Data and Tile Map loading - -### Tile and Map Data in 2bpp Game Boy Format +#### Tile and Map Data in 2bpp Game Boy Format - @ref set_bkg_data() and @ref set_sprite_data() will load 2bpp tile data in "game boy" format on both GB and SMS/GG. - On the SMS/GG @ref set_2bpp_palette() sets 4 colors that will be used when loading 2bpp assets with set_bkg_data(). This allows GB assets to be easily colorized without changing the asset format. There is some performance penalty for using the conversion. - @ref set_bkg_tiles() loads 1-byte-per-tile tilemaps both for the GB and SMS/GG. -### Tile and Map Data in Native Format +#### Tile and Map Data in Native Format Use the following api calls when assets are avaialble in the native format for each platform. @ref set_native_tile_data() @@ -214,59 +255,103 @@ There are also bit-depth specific API calls: - 2bpp: @ref set_2bpp_palette, @ref set_bkg_2bpp_data, @ref set_sprite_2bpp_data, @ref set_tile_2bpp_data (sms/gg only) - 2bpp: @ref set_bkg_4bpp_data (sms/gg only), @ref set_sprite_4bpp_data (sms/gg only) -### Emulated Game Boy Color map attributes on the SMS/Game Gear +#### Emulated Game Boy Color map attributes on the SMS/Game Gear On the Game Boy Color, @ref VBK_REG is used to select between the regular background tile map and the background attribute tile map (for setting tile color palette and other properties). This behavior is emulated for the SMS/GG when using @ref set_bkg_tiles() and @ref VBK_REG. It allows writing a 1-byte tile map separately from a 1-byte attributes map. @note Tile map attributes on SMS/Game Gear use different control bits than the Game Boy Color, so a modified attribute map must be used. -# Hardware Comparison -The specs below reflect the typical configuration of hardware when used with GBDK and is not meant as a complete list of their capabilities. - -GB/AP -- Sprites: - - 256 tiles (upper 128 are shared with background) (amount is doubled in CGB mode) - - tile flipping/mirroring: yes - - 40 total, max 10 per line - - 2 x 4 color palette (color 0 transparent). 8 x 4 color palettes in CGB mode -- Background: 256 tiles (typical setup: upper 128 are shared with sprites) (amount is doubled in CGB mode) - - tile flipping/mirroring: no (yes in CGB mode) - - 1 x 4 color palette. 8 x 4 color palettes in CGB mode -- Window "layer": available -- Screen: 160 x 144 -- Hardware Map: 256 x 256 - - -SMS/GG -- Sprites: - - 256 tiles (a bit less in the default setup) - - tile flipping/mirroring: no - - 64 total, max 8 per line - - 1 x 16 color palette (color 0 transparent) -- Background: 512 tiles (upper 256 are shared with sprites) - - tile flipping/mirroring: yes - - 2 x 16 color palettes -- Window "layer": not available -- SMS - - Screen: 256 x 192 - - Hardware Map: 256 x 224 -- GG - - Screen: 160 x 144 - - Hardware Map: 256 x 224 - - -@anchor docs_consoles_safe_display_controller_access -## Safe VRAM / Display Controller Access - -GB/AP -- VRAM / Display Controller (PPU) - - VRAM and some other display data / registers should only be written to when the @ref STATF_B_BUSY bit of @ref STAT_REG is off. Most GBDK API calls manage this automatically. - -SMS/GG -- Display Controller (VDP) - - Writing to the VDP should not be interrupted while an operation is already in progress (since that will interfere with the internal data pointer causing data to be written to the wrong location). - - Recommended approach: Avoid writing to the VDP (tiles, map, scrolling, colors, etc) during an interrupt routine (ISR). - - Alternative (requires careful implementation): Make sure writes to the VDP during an ISR are only performed when the @ref _shadow_OAM_OFF flag indicates it is safe to do so. +## 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: + - Cartridge Boot Logo: not present on Mega Duck + - Cartridge Header data: not present on Mega Duck + - Program Entry Point: `0x0000` (on Game Boy: `0x0100` ) + - Display registers and flag definitions: Some changed + - Audio registers and flag definitions: Some changed + - MBC ROM bank switching register address: `0x0001` (many Game Boy MBCs use `0x2000 - 0x3FFF`) + +### Best Practices +In order for software to be easily ported to the Mega Duck, or to run on both, use these practices. That will allow GBDK to automatically handle _most_ of the differences (for the exceptions see @ref megaduck_sound_register_value_changes "Sound Register Value Changes"). + - @ref docs_consoles_compiling "Set the target console during build time" + - Use the GBDK definitions and macros for: + - Video Registers and Flags (examples: @ref LCDC_REG, @ref LCDCF_BG8000, etc) + - Audio Registers and Flags (examples: @ref NR12_REG, @ref NR43_REG, etc) + - Use the default @ref SWITCH_ROM macro for changing ROM banks + +@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. + +These changes may be required when using existing Sound Effects and Music Drivers. + +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)` + +### Graphics Register Bit Changes +These changes are handled automatically when their GBDK definitions are used. + +| @ref LCDC_REG Flag | Game Boy | Mega Duck | | Purpose | +| -------------------- | -------- | --------- | ------ | ------------------------------------------------ | +| @ref LCDCF_B_ON | .7 | .7 | (same) | Bit for LCD On/Off Select | +| @ref LCDCF_B_WIN9C00 | .6 | .3 | | Bit for Window Tile Map Region Select | +| @ref LCDCF_B_WINON | .5 | .5 | (same) | Bit for Window Display On/Off Control | +| @ref LCDCF_B_BG8000 | .4 | .4 | (same) | Bit for BG & Window Tile Data Region Select | +| @ref LCDCF_B_BG9C00 | .3 | .2 | | Bit for BG Tile Map Region Select | +| @ref LCDCF_B_OBJ16 | .2 | .1 | | Bit for Sprites Size Select | +| @ref LCDCF_B_OBJON | .1 | .0 | | Bit for Sprites Display Visible/Hidden Select | +| @ref LCDCF_B_BGON | .0 | .6 | | Bit for Background Display Visible Hidden Select | + + +### Detailed Register Address Changes +These changes are handled automatically when their GBDK definitions are used. + +| Register | Game Boy | Mega Duck | +| ------------- | -------- | --------- | +| @ref LCDC_REG | 0xFF40 | 0xFF10 | +| @ref STAT_REG | 0xFF41 | 0xFF11 | +| @ref SCY_REG | 0xFF42 | 0xFF12 | +| @ref SCX_REG | 0xFF43 | 0xFF13 | +| @ref LY_REG | 0xFF44 | 0xFF18 | +| @ref LYC_REG | 0xFF45 | 0xFF19 | +| @ref DMA_REG | 0xFF46 | 0xFF1A | +| @ref BGP_REG | 0xFF47 | 0xFF1B | +| @ref OBP0_REG | 0xFF48 | 0xFF14 | +| @ref OBP1_REG | 0xFF49 | 0xFF15 | +| @ref WY_REG | 0xFF4A | 0xFF16 | +| @ref WX_REG | 0xFF4B | 0xFF17 | +| - | - | - | +| @ref NR10_REG | 0xFF10 | 0xFF20 | +| @ref NR11_REG | 0xFF11 | 0xFF22 | +| @ref NR12_REG | 0xFF12 | 0xFF21 | +| @ref NR13_REG | 0xFF13 | 0xFF23 | +| @ref NR14_REG | 0xFF14 | 0xFF24 | +| - | - | - | +| @ref NR21_REG | 0xFF16 | 0xFF25 | +| @ref NR22_REG | 0xFF17 | 0xFF27 | +| @ref NR23_REG | 0xFF18 | 0xFF28 | +| @ref NR24_REG | 0xFF19 | 0xFF29 | +| - | - | - | +| @ref NR30_REG | 0xFF1A | 0xFF2A | +| @ref NR31_REG | 0xFF1B | 0xFF2B | +| @ref NR32_REG | 0xFF1C | 0xFF2C | +| @ref NR33_REG | 0xFF1D | 0xFF2E | +| @ref NR34_REG | 0xFF1E | 0xFF2D | +| - | - | - | +| @ref NR41_REG | 0xFF20 | 0xFF40 | +| @ref NR42_REG | 0xFF21 | 0xFF42 | +| @ref NR43_REG | 0xFF22 | 0xFF41 | +| @ref NR44_REG | 0xFF23 | 0xFF43 | +| - | - | - | +| @ref NR50_REG | 0xFF24 | 0xFF44 | +| @ref NR51_REG | 0xFF25 | 0xFF46 | +| @ref NR52_REG | 0xFF26 | 0xFF45 | +| - | - | - |
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.