gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 3eecf7e644f90331260461a678fc253da27ec662 parent 7835d8df9863906c576c23e8fff60ce0b2c9b982 Author: bbbbbr <reg+github@roughhousing.com> Date: Tue, 7 Sep 2021 00:12:42 -0700 Merge pull request #247 from bbbbbr/docs_4_0_5 Docs: continuing 4.0.5 updates Diffstat:
| M | README.md | 3 | +++ |
| M | docs/pages/02_links_and_tools.md | 10 | ++++++++++ |
| M | docs/pages/03_using_gbdk.md | 13 | +++++++++++-- |
| M | docs/pages/04_coding_guidelines.md | 17 | +++++++++++++++++ |
| M | docs/pages/06b_supported_consoles.md | 45 | ++++++++++++++++++++++++++++----------------- |
| M | docs/pages/08_faq.md | 2 | +- |
| M | docs/pages/10_release_notes.md | 12 | +++++++++++- |
| M | docs/pages/docs_index.md | 10 | ++++++++-- |
8 files changed, 89 insertions(+), 23 deletions(-)
diff --git a/README.md b/README.md @@ -3,6 +3,9 @@ ## Current release for Linux: [Linux Binaries](https://github.com/gbdk-2020/gbdk-2020/releases/latest/download/gbdk-linux64.tar.gz) You don't need the sources, unless you wish to compile GBDK-2020 yourself. Download the current release binaries using the links above. +Upgrading to a new version? Check the [Migration notes](https://gbdk-2020.github.io/gbdk-2020/docs/api/docs_migrating_versions.html). + + # Docs Online documentation is avaliable [HERE](https://gbdk-2020.github.io/gbdk-2020/docs/api) diff --git a/docs/pages/02_links_and_tools.md b/docs/pages/02_links_and_tools.md @@ -40,6 +40,10 @@ This is a brief list of useful tools and information. It is not meant to be comp https://www.youtube.com/playlist?list=PLeEj4c2zF7PaFv5MPYhNAkBGrkx4iPGJo https://github.com/gingemonster/GamingMonstersGameBoySampleCode + - @anchor tutorials_typorter + __Pocket Leage Tutortial__ + https://blog.ty-porter.dev/development/2021/04/04/writing-a-gameboy-game-in-2021-pt-0.html + @anchor link_examples # Example code @@ -113,6 +117,12 @@ This is a brief list of useful tools and information. It is not meant to be comp Calculate used and free space in banks (ROM/RAM) and warn about errors such as bank overflows. https://github.com/bbbbbr/romusage + - @anchor bgb_symbol_conversion + __noi file to sym conversion for bgb__ + Debug information in .noi files can be converted to a symbol format that @ref bgb "BGB" recognizes using: + - @ref lcc : `-Wm-yS` (with `--debug`, or `-Wl-j` to create the .noi) + - directly with @ref makebin : `-yS` (with `-j` passed to the linker) + - @anchor src2sym __src2sym.pl__ Add line-by-line C source code to the main symbol file in a BGB compatible format. This allows for C source-like debugging in BGB in a limited way. diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md @@ -49,6 +49,11 @@ Interrupt handlers are called in sequence. To install a new interrupt handler, d See the `irq` example project for additional details for a complete example. +## Using your own Interrupt Dispatcher +If you want to use your own Interrupt Dispatcher instead of the GBDK chained dispatcher (for improved performance), then don't call the `add_...()` function for the respective interrupt and it's dispatcher won't be installed. + - Exception: the VBL dispatcher will always be linked in at compile time. + - For the SIO interrupt, also do not make any standard SIO calls to avoid having it's dispatcher installed. + ## Returning from Interrupts and STAT mode By default when an Interrupt handler completes and is ready to exit it will check STAT_REG and only return at the BEGINNING of either LCD Mode 0 or Mode 1. This helps prevent graphical glitches caused when an ISR interrupts a graphics operation in one mode but returns in a different mode for which that graphics operation is not allowed. @@ -69,7 +74,6 @@ Including @ref stdio.h and using functions such as @ref printf() will use a larg # Copying Functions to RAM and HIRAM - The `ram_function` example project included with GBDK demonstrates copying functions to RAM and HIRAM. It is possible to copy functions to RAM and HIRAM (using the memcpy() and hiramcpy() functions), and execute them from C. The compiler automatically generates two symbols for the start and the end of each function, named start_X and end_X (where X is the name of the function). This enables to calculate the length of a function when copying it to RAM. Ensure you have enough free space in RAM or HIRAM for copying a function. @@ -83,7 +87,6 @@ The second approach is slightly more efficient. Both approaches are demonstrated # Mixing C and Assembly - You can mix C and assembly (ASM) in two ways as described below. For additional detail see the @ref links_sdcc_docs. ## Inline ASM within C source files @@ -152,6 +155,12 @@ Here is an example of how to mix assembly with C: RET ; Return result in DE +# Including binary files in C source with incbin +Data from binary files can be included in C source files as a const array using the @ref INCBIN() macro. + +See the `incbin` example project for a demo of how to use it. + + # Known Issues and Limitations ## SDCC diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -39,6 +39,11 @@ If you wish to use the original tools, you must add the `const` keyword every ti ## Variables + - Initialize all variables before reading from them (typically at declaration). + - In other standard C environments global variables will get initialized to zero. + - The GBDK-2020 runtime __does not__ do this for you (wram does not get initialized to zero). Your code must explicitly initialize them instead. + - It is recommended to turn on "non-initalized RAM" exceptions (and others) in emulators which support them to help find and avoid bugs related to this. + - Use 8-bit values as much as possible. They will be much more efficient and compact than 16 and 32 bit types. - Prefer unsigned variables to signed ones: The code generated will be generally more efficient, especially when comparing two values. @@ -70,6 +75,18 @@ If you wish to use the original tools, you must add the `const` keyword every ti - NOTE: In SDCC 3.6.0, the default for char changed from signed to unsigned. The manual says to use `--fsigned-char` for the old behavior, this option flag is included by default when compiling through @ref lcc. + @anchor fixed_point_type + - A fixed point type (`fixed`) is included with GBDK when precision greater than whole numbers is required for 8 bit range values (since floating point is not included in GBDK). For example: + + fixed player[2]; + ... + // Modify player position using it's 16 bit representation + player[0].w += player_speed_x; + player[1].w += player_speed_y; + ... + // Use only the upper 8 bits for setting the sprite position + move_sprite(0, player[0].h ,player[1].h); + ## Code structure diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md @@ -1,4 +1,4 @@ -@page docs_supported_consoles Supported Consoles +@page docs_supported_consoles Supported Consoles & Cross Compile @anchor docs_consoles_supproted_list # Consoles Supported by GBDK @@ -12,26 +12,25 @@ As of version `4.0.5` GBDK includes support for other consoles in addition to th 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 abilities, memory layouts, processor type (z80 vs gbz80/sm83) and speed. -@anchor docs_consoles_port_plat_settings -# Port and Platform settings - +@anchor docs_consoles_compiling +# Cross Compiling for Different Consoles ## lcc -When building through @ref lcc use the `-m<port>:<plat>` flag to select the desired console via it's port and platform combination. +When compiling and building through @ref lcc use the `-m<port>:<plat>` flag to select the desired console via it's port and platform combination. ## sdcc When compiling directly with @ref sdcc use: `-m<port>`, `-D__PORT_<port>` and `-D__TARGET_<plat> ` -## Console Settings +## Console Port and Platform Settings - Nintendo Game Boy / Game Boy Color - @ref lcc : `-mgbz80:gb` - port:`gbz80`, plat:`gb` - Analogue Pocket - @ref lcc : `-mgbz80:ap` - port:`gbz80`, plat:`ap` - - The Analogue Pocket is functionally identical to the Game Boy / Color, but has a couple different register flag / address definitions and a different boot logo. + - Note: The Analogue Pocket is functionally identical to the Game Boy / Color, but has a couple altered register flag / address definitions and a different boot logo. - Sega Master System - @ref lcc : `-mz80:sms` @@ -41,7 +40,27 @@ When compiling directly with @ref sdcc use: `-m<port>`, `-D__PORT_<port>` and `- - port:`z80`, plat:`gg` -## gbdk/ include path +# Platform constants +There are several constant \#defines that can be used to help select console specific code during compile time (with `#ifdef`, `#ifndef`) . + + - When `<gb/gb.h>` is included (either directly or through `<gbdk/platform.h>`) + - When building for Game Boy: + - `NINTENDO` will be \#defined + - `GAMEBOY` will be \#defined + - When building for Analogue Pocket + - `NINTENDO` will be \#defined + - `ANALOGUEPOCKET` will be \#defined + + - When `<sms/sms.h >` is included (either directly or through `<gbdk/platform.h>`) + - When building for Master System + - `SEGA` will be \#defined + - `MASTERSYSTEM` will be \#defined + - When building for Game Gear + - `SEGA` will be \#defined + - `GAMEGEAR` will be \#defined + + +# Using <gbdk/...> headers 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 @@ -60,16 +79,8 @@ and #include <sms/metasprites.h> -## NINTENDO and SEGA #defines - - When `<gb/gb.h>` is included (either directly or through <gbdk/platform.h>) - then `NINTENDO` will be `#defined` - - - When `<sms/sms.h >` is included (either directly or through <gbdk/platform.h>) - then `SEGA` will be `#defined` - - @anchor docs_consoles_cross_platform_examples # Cross Platform Example Projects 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. +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. diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -54,7 +54,7 @@ - Can I use the `float` type to do floating point math? - There is no support for 'float' in GBDK-2020. - - Instead consider various kinds of `fixed point` math (including the @ref fixed type included in GBDK) <!-- --> + - Instead consider some form of `fixed point` math (including the @ref fixed_point_type "fixed" type included in GBDK) <!-- --> - Why are 8 bit numbers not printing correctly with printf()? - To correctly pass chars/uint8s for printing, they must be explicitly re-cast as such when calling the function. See docs_chars_varargs for more details. <!-- --> diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -8,14 +8,24 @@ https://github.com/gbdk-2020/gbdk-2020/releases ## GBDK 2020 4.0.5 2021/09 + - Known Issues + - The `bgb_debug` example has a compile error on macOS. + - The compiler has a bug on macOS where long strings used with macros cause a crash. @ref bgb_emu.h can still be used with shorter strings. - Overall - Added support for new consoles - Analogue Pocket (`ap`) - Sega Master System (`sms`) and Game Gear (`gg`) - The windows make.bat files were renamed to compile.bat - Library + - Added new register flag constants and names. For example: + - @ref rLCDC is a new alias for @ref LCDC_REG + - @ref LCDCF_WINON, @ref LCDCF_WINOFF, @ref LCDCF_B_WINON + - Added @ref BANK(), @ref BANKREF(), @ref BANKREF_EXTERN() + - Added @ref INCBIN(), @ref BANK(), @ref INCBIN_SIZE(), @ref INCBIN_EXTERN() + - Updated bgb debug output. Added @ref BGB_printf() - Examples - - Added cross-platorm examples (build multiple targets: gb, ap, sms, gg) + - Added cross-platform examples (builds for multiple consoles: gb, ap, sms, gg) + - Improved `bgb_debug` example - Toolchain / Utilities - @ref utility_png2asset "png2asset" - @ref utility_png2asset "png2asset" is the new name for the `png2mtspr` utility diff --git a/docs/pages/docs_index.md b/docs/pages/docs_index.md @@ -29,13 +29,14 @@ The original GBDK sources, documentation and website are at: http://gbdk.sourcef # About GBDK -The GameBoy Developer's Kit (GBDK, GBDK-2020) is used to develop games and programs for the Nintendo Game Boy system in C and assembly. GBDK includes a set of libraries for the most common requirements and generates image files for use with a real GameBoy or with emulators. +The GameBoy Developer's Kit (GBDK, GBDK-2020) is used to develop games and programs for the Nintendo Game Boy (and some other consoles) in C and assembly. GBDK includes a set of libraries for the most common requirements and generates image files for use with a real GameBoy or emulators. GBDK features: - C and ASM toolchain based on SDCC with some support utilities - A set of libraries with source code - Example programs in ASM and in C - Support for multiple ROM bank images + - Support for multiple consoles: Game Boy, Analogue Pocket, Master System and Game Gear 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. @@ -43,7 +44,12 @@ GBDK is freeware. Most of the tooling code is under the GPL. The runtime librari # Historical Info and Links -The following is from the original GBDK documentation. +Original work on GBDK (pre-2020) was by: + +Pascal Felber, Lars Malmborg, Michael Hope (and others) + + +The following is from the original GBDK documentation: Thanks to quang for many of the comments to the gb functions. Some of the comments are ripped directly from the Linux Programmers
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.