|
GBDK 2020 Docs
4.3.0
API Documentation for GBDK 2020
|
As of version 4.2.0 GBDK includes support for other consoles in addition to the Game Boy.
While 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.
When compiling and building through lcc use the -m<port>:<plat> flag to select the desired console via its port and platform combination. See below for available settings.
When building directly with the sdcc toolchain, the following must be specified manually (when using lcc it will populate these automatically based on -m<port>:<plat>).
When compiling with sdcc:
-m<port>, -D__PORT_<port> and -D__TARGET_<plat>When assembling select the appropriate include path: -I<gbdk-path>lib/<plat>.
The assemblers used are:
When linking:
-k <gbdk-path>lib/<port>, -k <gbdk-path>lib/<plat>-l <port>.lib, -l <plat>.lib<gbdk-path>lib/<plat>/crt0.oThe linkers used are:
MSXDOS requires an additional build step with makecom after makebin to create the final binary:
makecom <image.bin> [<image.noi>] <output.com>Note: Starting with GBDK-2020 4.1.0 and SDCC 4.2, the Game Boy and related clones use sm83 for the port instead of gbz80
-msm83:gbsm83, plat:gb-msm83:apsm83, plat:ap-msm83:ducksm83, plat:duck-mz80:smsz80, plat:sms-mz80:ggz80, plat:gg-mmos6502:nesmos6502, plat:nes-mz80:msxdosz80, plat:msxdosThere are several constant #defines that can be used to help select console specific code during compile time (with #ifdef, #ifndef) .
<gb/gb.h> is included (either directly or through <gbdk/platform.h>)NINTENDO will be #definedGAMEBOY will be #definedNINTENDO will be #definedANALOGUEPOCKET will be #definedNINTENDO will be #definedMEGADUCK will be #defined<sms/sms.h> is included (either directly or through <gbdk/platform.h>)SEGA will be #definedMASTERSYSTEM will be #definedSEGA will be #definedGAMEGEAR will be #defined<nes/nes.h> is included (either directly or through <gbdk/platform.h>)NINTENDO_NES will be #defined<msx/msx.h> is included (either directly or through <gbdk/platform.h>)MSXDOS will be #definedConstants that describe properties of the console hardware are listed below. Their values will change to reflect the current console target that is being built.
Some 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).
For example, the following can be used
#include <gbdk/platform.h> #include <gbdk/metasprites.h>
Instead of
#include <gb/gb.h> #include <gb/metasprites.h>
and
#include <sms/sms.h> #include <sms/metasprites.h>
GBDK 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.
They 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.
The cross-platform Logo example project shows how assets can be managed for multiple different console targets together.
In the example 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 set_bkg_native_data() to load the assets tiles in native format to the tile memory used for background tiles on that platform.
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
SMS/GG
NES/Famicom
GB/AP
SMS/GG
NES/Famicom
These are some of the main hardware differences between the Regular Game Boy and the Game Boy Color.
These are some of the main GBDK API features for the CGB. Many of the items listed below link to additional information.
set_bkg/win/sprite_*())#include <gb/cgb.h>)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/metaspritesThe 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.
0xFF4E instead of 0xFF400x0104: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, 0x60In order for software to be easily ported to the Analogue Pocket, or to run on both, use the following practices.
Use API defined registers and register flags instead of hardwired ones.
As long as the target console is set during build time then the correct boot logo will be automatically selected.
-yo 4 for makebin (or -Wm-yo4 for LCC) can be used to set the size to 64K.Use the following api calls when assets are avaialble in the native format for each platform.
There are also bit-depth specific API calls:
The SMS/GG have 2 x 16 color palettes:
On the Game Gear
On the SMS
For setting palette data:
On the Game Boy Color, 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 set_bkg_tiles() and VBK_REG. It allows writing a 1-byte tile map separately from a 1-byte attributes map.
The NES graphics architecture is similar to the GB's. However, there are a number of design choices in the NES hardware that make the NES a particularly cumbersome platform to develop for, and that will require special attention.
Most notably:
To provide an easier experience, gbdk-nes attempts to hide most of these quirks so that in theory the programming experience for gbdk-nes should be as close as possible to that of the GB/GBC. However, to avoid surprises it is recommended to familiarize yourself with the NES-specific quirks and implementation choices mentioned here.
This entire section is written as a guide on porting GB projects to NES. If you are new to GBDK, you may wish to familiarize yourself with using GBDK for GB development first as the topics covered will make a lot more sense after gaining experience with GB development.
Currently the NES support in GBDK uses UNROM-512 (Mapper30) with single-screen mirroring.
On the GB, the vblank period serves as an optimal time to write data to PPU memory, and PPU memory can also be written efficiently with VRAM DMA.
On the NES, writing PPU memory during the vblank period is not optional. Whenever rendering is turned on the PPU is in a state where accessing PPU memory results in undefined behavior outside the short vblank period. The NES also has no VRAM DMA hardware to help with data writes. This makes the vblank period not only more precious, but important to never exceed to avoid glitched games.
To deal with this limitation, all functions in gbdk-nes that write to PPU memory can run in either Buffered or Direct mode.
The good news is that switching between buffered and direct mode in gbdk-nes is usually done behind-the-scenes and normally shouldn't affect your code too much, as long as you use the portable GBDK functions and macros to do this.
The following sections describe how the buffered / direct modes work in more detail. As buffered / direct mode is mostly hidden by the API calls, feel free to skip these sections if you wish.
To take maximum advantage of the short vblank period, gbdk-nes implements a popular optimization: An unrolled loop that pulls prepared data bytes from the stack.
PLA STA PPUDATA ... PLA STA PPUDATA RTS
The data structure to facilitate this is usually called a vram transfer buffer, often affectionately called a "popslide" buffer after Damian Yerrick's implementation. This buffer essentially forms a list of commands where each command sets up a new PPU address and then writes a sequence of bytes with an auto-increment of either +1 or +32. Each such command is often called a "stripe" in the nesdev community.
The transfer buffer starts at 0x100 and takes around half of the hardware stack page. You can think of the transfer buffer as a software-implemented DMA that allows writing bytes at the optimal rate of 8 cycles / byte. (ignoring the PPU address setup cost)
The buffer supports writing up to 32 continuous bytes at a time. This allows updating a full screen row / column, or two 8x8 tiles worth of tile data in one command / "stripe".
By doing writes to this buffer during game logic, your game will effectively keep writing data transfer commands for the vblank NMI handler to process in the next vblank period, without having to wait until the vblank.
Given that the transfer buffer only has space for around 100 data bytes, it is important to not overfill the buffer, as this will bring code execution to a screeching halt, until the NMI handler empties the old contents of the buffer to free up space and allow new commands to be written.
Buffered mode is typically used for scrolling updates or dynamically animated tiles, where only a small amount of bytes need updating per frame.
During direct mode, all graphics routines will write directly to the PPUADDR / PPUDATA ports and the transfer buffer limit is never a concern because the transfer buffer is effectively bypassed.
Direct mode is typically used for initializing large amounts of tile data at boot and/or level loading time. Unless you plan to have an animated loading screen and decompress a lot of data, it makes more sense to just fade the screen to black and allow direct mode to write data as fast as possible.
Because the switch to direct mode is instant and doesn't wait for the next invocation of the vblank, it is possible to create situations where there is still remaining data in the transfer buffer that would only get written once the system is switched back to buffered mode.
To avoid this situation, make sure to always "drain" the buffer by doing a call to vsync when you expect your code to finish.
The oddity that PPU palette values are accessed through the same mechanism as other PPU memory bytes comes with the side effect that the vblank NMI handler will only write the palette values in buffered mode.
The reason for this design choice is two-fold:
To work around this, you are advised to never fully turn the display off during a palette fade. If you don't follow this advice all your palette updates will get delayed until the screen is turned back on.
Like the SMS, the NES hardware is designed to only allow loading the full X/Y scroll on the very first scanline. i.e., under normal operation you are only allowed to change the Y-scroll once.
In contrast to the SMS, this limitation can be circumvented with a specific set of out-of-order writes to the PPUSCROLL/PPUADDR registers, taking advantage of the quirk that the PPUADDR and PPUSCROLL share register bits. But this write sequence is very timing-sensitive as the writes need to fall into (a smaller portion of) the hblank period in order to avoid race conditions when the CPU and PPU both try to update the same register during scanline rendering.
To simplify the programming interface, gbdk-nes functions like move_bkg / scroll_bkg only ever update shadow registers in RAM. The vblank NMI handler will later pick these values up and write them to the actual PPU registers registers.
GBDK provides an API for installing Interrupt Service Routines that execute on start of vblank (VBL handler), or on a specific scanline (LCD handler).
But the base NES system has no suitable scanline interrupts that can provide such functionality. So instead, gbdk-nes API allows fake handlers to be installed in the goal of keeping code compatible with other platforms.
Because the LCD "ISR" is actually implemented with a delay loop, it will burn a lot of CPU cycles in the frame - the further down the requested scanline is the larger the CPU cycle loss. In practice this makes this faked-LCD-ISR functionality mostly suitable for status bars at the top of the screen screen. Or for simple parallax cutscenes where the CPU has little else to do.
On the GB, the call to vsync is an optional call that serves two purposes:
On gbdk-nes the second point is no longer true, because writes need to be made to the shadow registers before vsync is called.
But the vsync call serves three other very important purposes:
A. It calls the optional VBL handler, where shadow registers can be written (and will later be picked up by the actual vblank NMI handler) B. It repeatedly calls the optional LCD handler up to MAX_LCD_ISR_CALLS times. After each call, PPU shadow registers are stored into a buffer that will later be used by timed code in the NMI to handle mid-frame changes for screen splits / sprite hiding / etc. C. It calls flush_shadow_attributes so that updates to background attributes actually get written to PPU memory
For these reasons you should always include a call to vsync if you expect to see any graphical updates on the screen.
The fake LCD ISR system is not bullet-proof. In particular, it has a problem where lag frames can cause the shadow register updates in LCD handlers not to be ready in time for when the timed code in the NMI handler would be called. This will effectively cause all those updates to be missing for one frame, and result in glitched scroll updates.
There is currently no complete work-around for this problem other than avoiding lag frames altogether. But the glitch can be made less distracting by making sure only the status bar glitches rather than the main background.
If you are using LCD handlers to achieve a top-screen stationary status bar, it is recommended that you follow the following guidelines to make sure the background itself has consistent scrolling:
In short: Ensuring that the last called LCD handler sets the scroll back to the original value means the PPU rendering keeps rendering the background from the same scrolling position even when the NMI handling was missed.
Use the following api calls when assets are available in the native format for each platform.
Bit-depth specific API calls:
Platform specific API calls:
On the Game Boy Color, 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 of setting VBK_REG to specify tile indices/attributes is not supported on the NES platform. Instead the dedicated functions for attribute setting should be used. These will work on other platforms as well and are the preferred way to set attributes.
To maintain API compatibility with other platforms that have attributes on an 8x8 grid specified with a whole byte per attribute, the NES platform supports the dedicated calls for setting attributes on an 8x8 grid:
This allows code to for attribute setting to remain unchanged between platforms. The effect of using these calls is that some attribute setting will be redundant due to the coarser attribute grid. i.e., setting the attribute at coordinates (4, 4), (4,5), (5, 4) and (5, 5) will all set the same attribute.
There is one more platform specific difference to note: While the set_bkg_attribute_xy() function takes coordinates on a 8x8 grid, the set_bkg_attributes() and set_bkg_submap_attributes() functions take a pointer to data in NES packed attribute format, where each byte contains data for 4 16x16 attribute. i.e. a 32x32 region.
While this implementation detail of how the attribute map is encoded is usually hidden by the API functions it does mean that code which manually tries to read the attribute data is NOT portable between NES/other platforms, and is not recommended.
The Mega Duck is (for practical purposes) functionally identical to the Original Game Boy though it has a couple changes listed below.
0x0000 (on Game Boy: 0x0100 )0x0001 (many Game Boy MBCs use 0x2000 - 0x3FFF)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 Sound Register Value Changes).
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 written for the Game Boy.
((uint8_t)(value << 4) | (uint8_t)(value >> 4))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%(((~(uint8_t)value) + (uint8_t)0x20u) & (uint8_t)0x60u)These changes are handled automatically when their GBDK definitions are used.
| LCDC_REG Flag | Game Boy | Mega Duck | Purpose | |
|---|---|---|---|---|
| LCDCF_B_ON | .7 | .7 | (same) | Bit for LCD On/Off Select |
| LCDCF_B_WIN9C00 | .6 | .3 | Bit for Window Tile Map Region Select | |
| LCDCF_B_WINON | .5 | .5 | (same) | Bit for Window Display On/Off Control |
| LCDCF_B_BG8000 | .4 | .4 | (same) | Bit for BG & Window Tile Data Region Select |
| LCDCF_B_BG9C00 | .3 | .2 | Bit for BG Tile Map Region Select | |
| LCDCF_B_OBJ16 | .2 | .1 | Bit for Sprites Size Select | |
| LCDCF_B_OBJON | .1 | .0 | Bit for Sprites Display Visible/Hidden Select | |
| LCDCF_B_BGON | .0 | .6 | Bit for Background Display Visible Hidden Select |
These changes are handled automatically when their GBDK definitions are used.
| Register | Game Boy | Mega Duck |
|---|---|---|
| LCDC_REG | 0xFF40 | 0xFF10 |
| STAT_REG | 0xFF41 | 0xFF11 |
| SCY_REG | 0xFF42 | 0xFF12 |
| SCX_REG | 0xFF43 | 0xFF13 |
| LY_REG | 0xFF44 | 0xFF18 |
| LYC_REG | 0xFF45 | 0xFF19 |
| DMA_REG | 0xFF46 | 0xFF1A |
| BGP_REG | 0xFF47 | 0xFF1B |
| OBP0_REG | 0xFF48 | 0xFF14 |
| OBP1_REG | 0xFF49 | 0xFF15 |
| WY_REG | 0xFF4A | 0xFF16 |
| WX_REG | 0xFF4B | 0xFF17 |
| - | - | - |
| NR10_REG | 0xFF10 | 0xFF20 |
| NR11_REG | 0xFF11 | 0xFF22 |
| NR12_REG | 0xFF12 | 0xFF21 |
| NR13_REG | 0xFF13 | 0xFF23 |
| NR14_REG | 0xFF14 | 0xFF24 |
| - | - | - |
| NR21_REG | 0xFF16 | 0xFF25 |
| NR22_REG | 0xFF17 | 0xFF27 |
| NR23_REG | 0xFF18 | 0xFF28 |
| NR24_REG | 0xFF19 | 0xFF29 |
| - | - | - |
| NR30_REG | 0xFF1A | 0xFF2A |
| NR31_REG | 0xFF1B | 0xFF2B |
| NR32_REG | 0xFF1C | 0xFF2C |
| NR33_REG | 0xFF1D | 0xFF2E |
| NR34_REG | 0xFF1E | 0xFF2D |
| - | - | - |
| NR41_REG | 0xFF20 | 0xFF40 |
| NR42_REG | 0xFF21 | 0xFF42 |
| NR43_REG | 0xFF22 | 0xFF41 |
| NR44_REG | 0xFF23 | 0xFF43 |
| - | - | - |
| NR50_REG | 0xFF24 | 0xFF44 |
| NR51_REG | 0xFF25 | 0xFF46 |
| NR52_REG | 0xFF26 | 0xFF45 |
| - | - | - |