gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 0335430b43e00254ba7dfcef0395b6c56e4f9058 parent 3ef9587ee96ad787b033bbd7ce63616a06c644c7 Author: bbbbbr <reg+github@roughhousing.com> Date: Fri, 21 May 2021 21:32:12 -0700 Merge pull request #186 from bbbbbr/docs_updates2 Docs updates Diffstat:
| M | README.md | 3 | ++- |
| M | docs/pages/02_links_and_tools.md | 27 | ++++++++++----------------- |
| M | docs/pages/04_coding_guidelines.md | 10 | ++++++++++ |
| M | docs/pages/07_sample_programs.md | 1 | + |
| M | docs/pages/08_faq.md | 121 | ++++++++++++++++++++++++++++++++++++++++++------------------------------------- |
| M | docs/pages/09_migrating_new_versions.md | 4 | ++-- |
| M | gbdk-lib/examples/gb/gbdecompress/Makefile | 4 | ++-- |
| M | gbdk-lib/include/gb/gb.h | 5 | +++++ |
| M | gbdk-lib/include/gb/metasprites.h | 17 | +++++++++++++++++ |
9 files changed, 113 insertions(+), 79 deletions(-)
diff --git a/README.md b/README.md @@ -6,8 +6,9 @@ You don't need the sources, unless you wish to compile GBDK-2020 yourself. Downl # Docs Online documentation is avaliable [HERE](https://gbdk-2020.github.io/gbdk-2020/docs/api) -A good place to start is the [Getting Started Section](https://gbdk-2020.github.io/gbdk-2020/docs/api/docs_getting_started.html) +A good place to start is the [Getting Started Section](https://gbdk-2020.github.io/gbdk-2020/docs/api/docs_getting_started.html). +Check the [Links and Third-Party Tools Section](https://gbdk-2020.github.io/gbdk-2020/docs/api/docs_links_and_tools.html) for a list of recommended emulators, graphics tools, music drivers and more. # gbdk-2020 [GBDK](http://gbdk.sourceforge.net/) A C compiler, assembler, linker and set of libraries for the Z80 like Nintendo Gameboy. diff --git a/docs/pages/02_links_and_tools.md b/docs/pages/02_links_and_tools.md @@ -1,7 +1,7 @@ @page docs_links_and_tools Links and Third-Party Tools -This is a brief list of useful tools and information. It is not meant to be complete or exhaustive, for a larger list see @ref awesome_gb +This is a brief list of useful tools and information. It is not meant to be complete or exhaustive, for a larger list see the @ref awesome_gb "Awesome Game Boy Development" list. @anchor links_sdcc_docs # SDCC Compiler Suite User Manual @@ -27,7 +27,7 @@ This is a brief list of useful tools and information. It is not meant to be comp https://gbdev.io/pandocs/ - @anchor awesome_gb - __Awesome Game Boy List__ + __Awesome Game Boy Development list__ A list of Game Boy/Color development resources, tools, docs, related projects and homebrew. https://gbdev.io/list.html @@ -52,19 +52,17 @@ This is a brief list of useful tools and information. It is not meant to be comp # Graphics Tools - @anchor gbtd_gbmb @anchor gbmb - @anchor gbtd + @anchor gbtd + @anchor toxa_gbtd_gbmb __Game Boy Tile Designer and Map Builder (GBTD / GBMB)__ Sprite / Tile editor and Map Builder that can export to C that works with GBDK. + This is an updated version with const export fixed and other improvments. + https://github.com/gbdk-2020/GBTD_GBMB - - @anchor toxa_gbtd_gbmb - __Use this updated version:__ (has const export fixed and other improvments): - https://github.com/untoxa/GBTD_GBMB - - - This older version is __not recommended__: - http://www.devrs.com/gb/hmgd/intro.html (old, original tools) - - - A GIMP plugin for import/export: - https://github.com/bbbbbr/gimp-tilemap-gb (GIMP plugin to read/write GBR/GBM files) + - A GIMP plugin to read/write GBR/GBM files and do map conversion: + https://github.com/bbbbbr/gimp-tilemap-gb + - Command line version of the above tool that doesn't require GIMP (png2gbtiles): + https://github.com/bbbbbr/gimp-tilemap-gb/tree/master/console - @anchor Tilemap_Studio __Tilemap Studio__ @@ -115,11 +113,6 @@ 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 noi2sym - __noi2sym.py__ - Convert .noi files into a symbol format compatible with BGB. Allows BGB to recognize variables and functions based on address. - https://github.com/untoxa/hUGEBuild/blob/master/tools/noi2sym.py - - @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/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -51,6 +51,13 @@ If you wish to use the original tools, you must add the `const` keyword every ti - @anchor const_array_data `const` keyword: Use const for arrays, structs and variables with read-only (constant) data. It will reduce ROM, RAM and CPU usage significantly. Non-`const` values are loaded from ROM into RAM inefficiently, and there is no benefit in loading them into the limited available RAM if they aren't going to be changed. + - Here is how to delcare `const` pointers and variables: + - non-const pointer to a const variable: `const UINT8 * some_pointer;` + - const pointer to a non-const variable: `UINT8 * const some_pointer;` + - const pointer to a const variable: `const UINT8 * const some_pointer;` + - https://codeforwin.org/2017/11/constant-pointer-and-pointer-to-constant-in-c.html + - https://stackoverflow.com/questions/21476869/constant-pointer-vs-pointer-to-constant + - For calculated values that don't change, pre-compute results once and store the result. Using lookup-tables and the like can improve speed and reduce code size. Macros can sometimes help. It may be beneficial to do the calculations with an outside tool and then include the result as C code in a const array. - Use an advancing pointer (`someStruct->var = x; someStruct++`) to loop through arrays of structs instead of using indexing each time in the loop `someStruct[i].var = x`. @@ -66,6 +73,9 @@ If you wish to use the original tools, you must add the `const` keyword every ti ## Code structure + - Do not `#include` `.c` source files into other `.c` source files. Instead create `.h` header files for them and include those. + https://www.tutorialspoint.com/cprogramming/c_header_files.htm + - When procesing for a given frame is done and it is time to wait before starting the next frame, @ref wait_vbl_done() can be used. It uses HALT to put the CPU into a low power state until processing resumes. The CPU will wake up and resume processing at the end of the current frame when the Vertical Blanking interrupt is triggered. - Minimize use of multiplication, modulo with non-powers of 2, and division with non-powers of 2. These operations have no corresponding CPU instructions (software functions), and hence are time costly. diff --git a/docs/pages/07_sample_programs.md b/docs/pages/07_sample_programs.md @@ -102,6 +102,7 @@ Demonstration of playing a sound sample. A collection of examples showing how to use the Super Game Boy API features. +@anchor examples_sound_sample # sound The sound example is meant for experimenting with the soung generator of the GameBoy (to use on a real GameBoy). The four different sound modes of the GameBoy are available. It also demonstrates the use of bit fields in C (it's a quick hack, so don't expect too much from the code). The following keys are used: diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -1,60 +1,67 @@ @page docs_faq Frequently Asked Questions (FAQ) @anchor toolchain_faq -# Frequently Asked Questions -- How do I set the ROM's title? - - Use the @ref makebin `-yn` flag. For example with @ref lcc `-Wm-yn"MYTITLE"` or with @ref makebin directly `-yn "MYTITLE"`. The maximum length is up to 15 characters, but may be shorter. - - See "0134-0143 - Title" in @ref Pandocs for more details. - <!-- --> - -@anchor faq_gb_type_header_setting -- How do I set SGB, Color only and Color compatibility in the ROM header? - - Use the following @ref makebin flags. Prefix them with `-Wm` if using @ref lcc. - - `-yc` : GameBoy Color compatible - - `-yC` : GameBoy Color only - - `-ys` : Super GameBoy compatible - <!-- --> - -- How do I set the ROM @ref MBC type? - - See @ref setting_mbc_and_rom_ram_banks - <!-- --> - -@anchor faq_bank_overflow_errors -- What do these kinds of warnings / errors mean? - `WARNING: possibly wrote twice at addr 4000 (93->3E)` - `Warning: Write from one bank spans into the next. 7ff7 -> 8016 (bank 1 -> 2)` - - You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. The warnings are generated by @ref ihxcheck during conversion of an .ihx file into a ROM file. - - See the section @ref docs_rombanking_mbcs for more details about how banks work and what their size is. You may want to use a tool such as @ref romusage to calculate the amount of free and used space. - <!-- --> - -- Why is the compiler so slow, or why did it suddenly get much slower? - - This may happen if you have large initialized arrays declared without the `const` keyword. It's important to use the const keyword for read-only data. See @ref const_gbtd_gbmb and @ref const_array_data - <!-- --> - -- What flags should be enabled for debugging? - - You can use the @ref lcc_debug "lcc debug flag" - <!-- --> - -- 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. - <!-- --> - -- How can maps larger than 32x32 tiles be scrolled? & Why is the map wrapping around to the left side when setting a map wider than 32 tiles with set_bkg_data()? - - The hardware Background map is 32 x 32 tiles. The screen viewport that can be scrolled around that map is 20 x 18 tiles. In order to scroll around within a much larger map, new tiles must be loaded at the edges of the screen viewport in the direction that it is being scrolled. @ref set_bkg_submap can be used to load those rows and columns of tiles from the desired sub-region of the large map. - - See the "Large Map" example program and @ref set_bkg_submap() - - Writes that exceed coordinate 31 of the Background tile map on the x or y axis will wrap around to the Left and Top edges. - <!-- --> - -- When using gbt_player with music in banks, how can the current bank be restored after calling gbt_update()? (since it changes the currently active bank without restoring it). - - See @ref banking_current_bank "restoring the current bank" - <!-- --> - -- How can CGB palettes and other sprite properties be used with metasprites? - - See @ref metasprite_and_sprite_properties "Metasprites and sprite properties" - <!-- --> - -- Weird things are happening to my sprite colors when I use png2mtspr and metasprites. What's going on and how does it work? - - See @ref utility_png2mtspr for details of how the conversion process works. - <!-- --> + +# General + - How can sound effects be made? + - The simplest way is to use the Game Boy sound hardware directly. See the @ref examples_sound_sample "Sound Example" for a way to test out sounds on the hardware. + - Further discussion on using the Sound Example rom can be found in the ZGB wiki. Note that some example code there is ZGB specific and not part of the base GBDK API: https://github.com/Zal0/ZGB/wiki/Sounds <!-- --> + +# ROM Header Settings + - How do I set the ROM's title? + - Use the @ref makebin `-yn` flag. For example with @ref lcc `-Wm-yn"MYTITLE"` or with @ref makebin directly `-yn "MYTITLE"`. The maximum length is up to 15 characters, but may be shorter. + - See "0134-0143 - Title" in @ref Pandocs for more details. <!-- --> + + @anchor faq_gb_type_header_setting + - How do I set SGB, Color only and Color compatibility in the ROM header? + - Use the following @ref makebin flags. Prefix them with `-Wm` if using @ref lcc. + - `-yc` : GameBoy Color compatible + - `-yC` : GameBoy Color only + - `-ys` : Super GameBoy compatible <!-- --> + + - How do I set the ROM @ref MBC type? + - See @ref setting_mbc_and_rom_ram_banks <!-- --> + +# Errors / Compiling / Toolchain + @anchor faq_bank_overflow_errors + - What do these kinds of warnings / errors mean? + `WARNING: possibly wrote twice at addr 4000 (93->3E)` + `Warning: Write from one bank spans into the next. 7ff7 -> 8016 (bank 1 -> 2)` + - You may have a overflow in one of your ROM banks. If there is more data allocated to a bank than it can hold it then will spill over into the next bank. The warnings are generated by @ref ihxcheck during conversion of an .ihx file into a ROM file. + + See the section @ref docs_rombanking_mbcs for more details about how banks work and what their size is. You may want to use a tool such as @ref romusage to calculate the amount of free and used space. <!-- --> + + @anchor faq_error_mbc_size + - What does `error: size of the buffer is too small` mean? + - Your program is using more banks than you have configured in the toolchain. + Either the MBC type was not set, or the number of banks or MBC type should be changed to provide more banks. + + See the section @ref setting_mbc_and_rom_ram_banks for more details. <!-- --> + + - Why is the compiler so slow, or why did it suddenly get much slower? + - This may happen if you have large initialized arrays declared without the `const` keyword. It's important to use the const keyword for read-only data. See @ref const_gbtd_gbmb and @ref const_array_data <!-- --> + + - What flags should be enabled for debugging? + - You can use the @ref lcc_debug "lcc debug flag" <!-- --> + + - Is it possible to generate a debug symbol file (`.sym`) compatible with the @ref bgb emulator? + - Yes, turn on `.noi` output (LCC argument: `-Wl-j` or `-debug` and then use `-Wm-yS` with LCC (or `-yS` with makebin directly). <!-- --> + +# API / Utilities + - 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. <!-- --> + + - How can maps larger than 32x32 tiles be scrolled? & Why is the map wrapping around to the left side when setting a map wider than 32 tiles with set_bkg_data()? + - The hardware Background map is 32 x 32 tiles. The screen viewport that can be scrolled around that map is 20 x 18 tiles. In order to scroll around within a much larger map, new tiles must be loaded at the edges of the screen viewport in the direction that it is being scrolled. @ref set_bkg_submap can be used to load those rows and columns of tiles from the desired sub-region of the large map. + - See the "Large Map" example program and @ref set_bkg_submap() + - Writes that exceed coordinate 31 of the Background tile map on the x or y axis will wrap around to the Left and Top edges. <!-- --> + + - When using gbt_player with music in banks, how can the current bank be restored after calling gbt_update()? (since it changes the currently active bank without restoring it). + - See @ref banking_current_bank "restoring the current bank" <!-- --> + + - How can CGB palettes and other sprite properties be used with metasprites? + - See @ref metasprite_and_sprite_properties "Metasprites and sprite properties" <!-- --> + + - Weird things are happening to my sprite colors when I use png2mtspr and metasprites. What's going on and how does it work? + - See @ref utility_png2mtspr for details of how the conversion process works. + diff --git a/docs/pages/09_migrating_new_versions.md b/docs/pages/09_migrating_new_versions.md @@ -26,7 +26,7 @@ This section contains information that may be useful to know or important when u - The old linker `link-gbz80` has been REMOVED, the linker @ref sdldgb from SDCC is used. - Due to the linker change, there are no longer warnings about multiple writes to the same ROM address. - GBDK now generates .ihx files, those are converted to a ROM using @ref makebin (lcc can do this automatically in some use cases) - - Setting ROM bytes directly with `-Wl-yp0x<address>=0x<value>` is no longer supported. Instead use @ref makebin flags. For example, use `-Wm-yC` instead of `-Wl-yp0x143=0xC0`. + - Setting ROM bytes directly with `-Wl-yp0x<address>=0x<value>` is no longer supported. Instead use @ref makebin flags. For example, use `-Wm-yC` instead of `-Wl-yp0x143=0xC0`. See @ref faq_gb_type_header_setting. - OAM symbol has been renamed to _shadow_OAM, that allows accessing shadow OAM directly from C code @@ -41,7 +41,7 @@ This section contains information that may be useful to know or important when u ## Porting to GBDK 2020 3.0.1 - LCC was upgraded to use SDCC v4.0. Makefile changes may be required - - The symbol format changed. To get usable symbols turn on `.noi` output (LCC argument: `-Wl-j`)can be enabled and you can use @ref noi2sym + - The symbol format changed. To get bgb compatible symbols turn on `.noi` output (LCC argument: `-Wl-j` or `-debug`) and use `-Wm-yS` - ?? Suggested: With LCC argument: `-Wa-l` (sdasgb:`-a All user symbols made global`) - In SDCC 3.6.0, the default for char changed from signed to unsigned. - If you want the old behavior use `--fsigned-char`. diff --git a/gbdk-lib/examples/gb/gbdecompress/Makefile b/gbdk-lib/examples/gb/gbdecompress/Makefile @@ -25,8 +25,8 @@ make.bat: Makefile @make -sn | sed y/\\//\\\\/ | grep -v make >> make.bat # Compile and link all source files in a single call to LCC -$(BINS): $(CSOURCES) $(ADMSOURCES) - $(LCC) -o $@ $(CSOURCES) $(ADMSOURCES) +$(BINS): $(CSOURCES) $(ASMSOURCES) + $(LCC) -o $@ $(CSOURCES) $(ASMSOURCES) clean: rm -f *.o *.lst *.map *.gb *.ihx *.sym *.cdb *.adb *.asm *.noi diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -427,6 +427,11 @@ void delay(UINT16 d) NONBANKED; /** Reads and returns the current state of the joypad. Follows Nintendo's guidelines for reading the pad. Return value is an OR of J_* + + When testing for multiple different buttons, it's + best to read the joypad state *once* into a variable + and then test using that variable. + @see J_START, J_SELECT, J_A, J_B, J_UP, J_DOWN, J_LEFT, J_RIGHT */ UINT8 joypad(void) NONBANKED __preserves_regs(b, c, h, l); diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h @@ -21,6 +21,23 @@ structured data for use with the ...metasprite...() functions. + # Metasprites composed of variable numbers of sprites + + When using png2mtspr, it's common for the output of + different frames to be composed of different numbers + of hardware sprites (since it's trying to create each + frame as efficiently as possible). Due to that, it's + good practice to clear out (hide) unused sprites in the + shadow_OAM that have been set by previous frames. + + \code + // Example: + // Hide rest of the hardware sprites, because amount + // of sprites differ between animation frames. + // (where hiwater == last hardware sprite used + 1) + for (UBYTE i = hiwater; i < 40; i++) shadow_OAM[i].y = 0; + \endcode + @anchor metasprite_and_sprite_properties # Metasprites and sprite properties (including cgb palette)
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.