06b_supported_consoles.md (10936B)
1@page docs_supported_consoles Supported Consoles & Cross Compiling 2 3@anchor docs_consoles_supported_list 4# Consoles Supported by GBDK 5As of version `4.0.5` GBDK includes support for other consoles in addition to the Game Boy. 6 7 - Game Boy and related clones 8 - Nintendo Game Boy / Game Boy Color (GB/GBC) 9 - Analogue Pocket (AP) 10 - Mega Duck / Cougar Boy (DUCK) 11 12 - Sega Consoles 13 - Sega Master System (SMS) 14 - Sega Game Gear (GG) 15 16 - MSX DOS (MSXDOS) 17 18While the GBDK API has many convenience functions that work the same or similar across different consoles, it's important to keep their different capabilities in mind when writing code intended to run on more than one. Some (but not all) of the differences are screen sizes, color capabilities, memory layouts, processor type (z80 vs gbz80/sm83) and speed. 19 20 21@anchor docs_consoles_compiling 22# Cross Compiling for Different Consoles 23 24## lcc 25When compiling and building through @ref lcc use the `-m<port>:<plat>` flag to select the desired console via its port and platform combination. 26 27 28## sdcc 29When building directly with the sdcc toolchain, the following must be specified manually 30(when using @ref lcc it will populate these automatically based on `-m<port>:<plat>`). 31 32When compiling with @ref sdcc-settings "sdcc": 33 - `-m<port>`, `-D__PORT_<port>` and `-D__TARGET_<plat> ` 34 35When assembling with @ref sdasgb-settings "sdasgb" (for GB/AP) and @ref sdasz80-settings "sdasz80" (for SMS/GG): 36 - Select the appropriate include path: `-I<gbdk-path>lib/small/asxxxx/<plat>` 37 38When linking with @ref sdldgb-settings "sdldgb" (for GB/AP) and @ref sdldz80-settings "sdldz80" (for SMS/GG or MSXDOS): 39 - Select the appropriate include paths: `-k <gbdk-path>lib/small/asxxxx/<port>`, `-k <gbdk-path>lib/small/asxxxx/<plat>` 40 - Include the appropriate library files `-l <port>.lib`, `-l <plat>.lib` 41 - The crt will be under ` <gbdk-path>lib/small/asxxxx/<plat>/crt0.o` 42 43MSXDOS requires an additional build step after makebin to create the final binary: 44 - `makecom <image.bin> [<image.noi>] <output.com>` 45 46 47## Console Port and Platform Settings 48 - Nintendo Game Boy / Game Boy Color 49 - @ref lcc : `-mgbz80:gb` 50 - port:`gbz80`, plat:`gb` 51 - Analogue Pocket 52 - @ref lcc : `-mgbz80:ap` 53 - port:`gbz80`, plat:`ap` 54 - Mega Duck / Cougar Boy 55 - @ref lcc : `-mgbz80:duck` 56 - port:`gbz80`, plat:`duck` 57 58 - Sega Master System 59 - @ref lcc : `-mz80:sms` 60 - port:`z80`, plat:`sms` 61 - Sega Game Gear 62 - @ref lcc : `-mz80:gg` 63 - port:`z80`, plat:`gg` 64 65 - MSX DOS 66 - @ref lcc : `-mz80:msxdos` 67 - port:`z80`, plat:`msxdos` 68 69 70# Cross-Platform Constants 71There are several constant \#defines that can be used to help select console specific code during compile time (with `#ifdef`, `#ifndef`) . 72 73## Console Identifiers 74 - When `<gb/gb.h>` is included (either directly or through `<gbdk/platform.h>`) 75 - When building for Game Boy: 76 - `NINTENDO` will be \#defined 77 - `GAMEBOY` will be \#defined 78 - When building for Analogue Pocket 79 - `NINTENDO` will be \#defined 80 - `ANALOGUEPOCKET` will be \#defined 81 - When building for Mega Duck / Cougar Boy 82 - `NINTENDO` will be \#defined 83 - `MEGADUCK` will be \#defined 84 85 86 - When `<sms/sms.h>` is included (either directly or through `<gbdk/platform.h>`) 87 - When building for Master System 88 - `SEGA` will be \#defined 89 - `MASTERSYSTEM` will be \#defined 90 - When building for Game Gear 91 - `SEGA` will be \#defined 92 - `GAMEGEAR` will be \#defined 93 94 - When `<msx/msx.h>` is included (either directly or through `<gbdk/platform.h>`) 95 - `MSXDOS` will be \#defined 96 97## Console Hardware Properties 98Constants that describe properties of the console hardware are listed below. Their values will change to reflect the current console target that is being built. 99 100 - @ref DEVICE_SCREEN_X_OFFSET, @ref DEVICE_SCREEN_Y_OFFSET 101 - @ref DEVICE_SCREEN_WIDTH, @ref DEVICE_SCREEN_HEIGHT 102 - @ref DEVICE_SCREEN_BUFFER_WIDTH, @ref DEVICE_SCREEN_BUFFER_HEIGHT 103 - @ref DEVICE_SCREEN_MAP_ENTRY_SIZE 104 - @ref DEVICE_SPRITE_PX_OFFSET_X, @ref DEVICE_SPRITE_PX_OFFSET_Y 105 - @ref DEVICE_SCREEN_PX_WIDTH, @ref DEVICE_SCREEN_PX_HEIGHT 106 107 108# Using <gbdk/...> headers 109Some include files under `<gbdk/..>` are cross platform and others allow the build process to auto-select the correct include file for the current target port and platform (console). 110 111For example, the following can be used 112 113 #include <gbdk/platform.h> 114 #include <gbdk/metasprites.h> 115 116Instead of 117 118 #include <gb/gb.h> 119 #include <gb/metasprites.h> 120 121and 122 123 #include <sms/sms.h> 124 #include <sms/metasprites.h> 125 126 127@anchor docs_consoles_cross_platform_examples 128# Cross Platform Example Projects 129GBDK includes an number of cross platform example projects. These projects show how to write code that can be compiled and run on multiple different consoles (for example Game Boy and Game Gear) with, in some cases, minimal differences. 130 131They also show how to build for multiple target consoles with a single build command and `Makefile`. The `Makefile.targets` allows selecting different `port` and `plat` settings when calling the build stages. 132 133## Cross Platform Asset Example 134The cross-platform `Logo` example project shows how assets can be managed for multiple different console targets together. 135 136In 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. 137 138 139# Porting From Game Boy to Analogue Pocket 140The Analogue Pocket is (for practical purposes) functionally identical to the Game Boy / Color, but has a couple altered register flag and address definitions and a different boot logo. In order for software to be easily ported to the Analogue Pocket, or to run on both, use the following practices. 141 142## Registers and Flags 143Use API defined registers and register flags instead of hardwired ones. 144 - LCDC register: @ref LCDC_REG or @ref rLCDC 145 - STAT register: @ref STAT_REG or @ref rSTAT 146 - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON) 147 - STAT flags: -> STATF_... (example: @ref STATF_LYC) 148 149## Boot logo 150As long as the target console is @ref docs_consoles_compiling "set during build time" then the correct boot logo will be automatically selected. 151 152 153# Porting From Game Boy to Mega Duck / Cougar Boy 154The 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. 155 156## Registers and Flags 157Use API defined registers and register flags instead of hardwired ones 158 - LCDC register: @ref LCDC_REG or @ref rLCDC 159 - STAT register: @ref STAT_REG or @ref rSTAT 160 - LCDC flags: -> LCDCF_... (example: @ref LCDCF_ON) 161 - STAT flags: -> STATF_... (example: @ref STATF_LYC) 162 163 164# Porting From Game Boy to SMS/GG 165 166## Tile Data and Tile Map loading 167 168### Tile and Map Data in 2bpp Game Boy Format 169- @ref set_bkg_data() and @ref set_sprite_data() will load 2bpp tile data in "game boy" format on both GB and SMS/GG. 170- 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. 171- @ref set_bkg_tiles() loads 1-byte-per-tile tilemaps both for the GB and SMS/GG. 172 173### Tile and Map Data in Native Format 174Use the following api calls when assets are avaialble in the native format for each platform. 175 176@ref set_native_tile_data() 177 - GB/AP: loads 2bpp tiles data 178 - SMS/GG: loads 4bpp tile data 179 180@ref set_tile_map() 181 - GB/AP: loads 1-byte-per-tile tilemaps 182 - SMS/GG: loads 2-byte-per-tile tilemaps 183 184There are also bit-depth specific API calls: 185- 1bpp: @ref set_1bpp_colors, @ref set_bkg_1bpp_data, @ref set_sprite_1bpp_data 186- 2bpp: @ref set_2bpp_palette, @ref set_bkg_2bpp_data, @ref set_sprite_2bpp_data, @ref set_tile_2bpp_data (sms/gg only) 187- 2bpp: @ref set_bkg_4bpp_data (sms/gg only), @ref set_sprite_4bpp_data (sms/gg only) 188 189### Emulated Game Boy Color map attributes on the SMS/Game Gear 190On 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). 191 192This 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. 193 194@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. 195 196# Hardware Comparison 197The specs below reflect the typical configuration of hardware when used with GBDK and is not meant as a complete list of their capabilities. 198 199GB/AP 200- Sprites: 201 - 256 tiles (upper 128 are shared with background) (amount is doubled in CGB mode) 202 - tile flipping/mirroring: yes 203 - 40 total, max 10 per line 204 - 2 x 4 color palette (color 0 transparent). 8 x 4 color palettes in CGB mode 205- Background: 256 tiles (typical setup: upper 128 are shared with sprites) (amount is doubled in CGB mode) 206 - tile flipping/mirroring: no (yes in CGB mode) 207 - 1 x 4 color palette. 8 x 4 color palettes in CGB mode 208- Window "layer": available 209- Screen: 160 x 144 210- Hardware Map: 256 x 256 211 212 213SMS/GG 214- Sprites: 215 - 256 tiles (a bit less in the default setup) 216 - tile flipping/mirroring: no 217 - 64 total, max 8 per line 218 - 1 x 16 color palette (color 0 transparent) 219- Background: 512 tiles (upper 256 are shared with sprites) 220 - tile flipping/mirroring: yes 221 - 2 x 16 color palettes 222- Window "layer": not available 223- SMS 224 - Screen: 256 x 192 225 - Hardware Map: 256 x 224 226- GG 227 - Screen: 160 x 144 228 - Hardware Map: 256 x 224 229 230 231@anchor docs_consoles_safe_display_controller_access 232## Safe VRAM / Display Controller Access 233 234GB/AP 235- VRAM / Display Controller (PPU) 236 - 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. 237 238SMS/GG 239- Display Controller (VDP) 240 - 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). 241 - Recommended approach: Avoid writing to the VDP (tiles, map, scrolling, colors, etc) during an interrupt routine (ISR). 242 - 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. 243 244