gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 2255240ec87cd67e273030082c5395b80567ccdd parent 97319281688058ac7eab494ed5f4e3190aa70d0f Author: Toxa <56631470+untoxa@users.noreply.github.com> Date: Tue, 16 Mar 2021 19:59:55 +0300 Merge pull request #150 from bbbbbr/docs_updates Docs updates Diffstat:
| M | Makefile | 6 | ++++++ |
| M | docs/pages/banking_mbcs.md | 5 | +++-- |
| M | docs/pages/docs_index.md | 1 | + |
| A | docs/pages/faq.md | 53 | +++++++++++++++++++++++++++++++++++++++++++++++++++++ |
| M | docs/pages/getting_started.md | 29 | ++++++++++++++++++++++++----- |
| M | docs/pages/links_and_tools.md | 7 | +++++++ |
| M | docs/pages/migrating_new_versions.md | 7 | ++++++- |
| M | docs/pages/sample_programs.md | 9 | ++++++++- |
| M | docs/pages/toolchain.md | 39 | +++++---------------------------------- |
| M | gbdk-lib/include/asm/gbz80/types.h | 1 | + |
| M | gbdk-lib/include/asm/types.h | 1 | + |
| M | gbdk-lib/include/gb/gb.h | 111 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------- |
12 files changed, 208 insertions(+), 61 deletions(-)
diff --git a/Makefile b/Makefile @@ -59,6 +59,8 @@ docs: doxygen-generate docsclean: doxygen-clean +docsreset: doxygen-reset + # Build rule for michaelh's machine to spin a release sapphire-full-build: native-build binary cross-clean cross-linux-mingw32-build @@ -253,3 +255,7 @@ endif doxygen-clean: rm -rf $(GBDKDOCSDIR)/api +doxygen-reset: + rm -rf $(GBDKDOCSDIR)/api + git checkout $(GBDKDOCSDIR)/api + diff --git a/docs/pages/banking_mbcs.md b/docs/pages/banking_mbcs.md @@ -122,8 +122,9 @@ You can manually switch banks using the @ref SWITCH_ROM_MBC1(), @ref SWITCH_RAM_ Note: You can only do a switch_rom_bank call from unbanked `_CODE` since otherwise you would switch out the code that was executing. Global routines that will be called without an expectation of bank switching should fit within the limited 16k of unbanked `_CODE`. -## Bank switching inside an Interrupt Service Routine (ISR) -If a function call is made inside an ISR which changes the bank *without* restoring it, then the @ref _current_bank variable should be saved and then restored. +## Restoring the current bank (after calling functions which change it without restoring) +@anchor banking_current_bank +If a function call is made (for example inside an ISR) which changes the bank *without* restoring it, then the @ref _current_bank variable should be saved and then restored. For example, __instead__ of this code: ``` diff --git a/docs/pages/docs_index.md b/docs/pages/docs_index.md @@ -8,6 +8,7 @@ - @subpage docs_rombanking_mbcs - @subpage docs_toolchain - @subpage docs_example_programs +- @subpage docs_faq - @subpage docs_migrating_versions - @subpage docs_releases diff --git a/docs/pages/faq.md b/docs/pages/faq.md @@ -0,0 +1,52 @@ +@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" + <!-- --> + diff --git a/docs/pages/getting_started.md b/docs/pages/getting_started.md @@ -40,16 +40,36 @@ Take a look at the @ref docs_coding_guidelines "coding guidelines", even if you If you haven't written programs in C before, check the @ref docs_c_tutorials "C tutorials section". -# 5. Try a GBDK Tutorial +# 5. Hardware and Resources +If you have a specific project in mind, consider what hardware want to target. It isn't something that has to be decided up front, but it can influence design and implementation. + +What size will your game or program be? + - 32K Cart (no-MBC required) + - Larger than 32K (MBC required) + - See more details about @ref docs_rombanking_mbcs "ROM Banking and MBCs". + +What hardware will it run on? + - Game Boy (& Game Boy Color) + - Game Boy Color only + - Game Boy & Super Game Boy + - See how to @ref faq_gb_type_header_setting "set the compatibility type in the cartridge header". Read more about hardware differences in the @ref Pandocs + + +# 6. Set up C Source debugging +Tracking down problems in code is easier with a debugger. Emulicious has a @ref Emulicious_debug "debug adapter" that provides C source debugging with GBDK-2020. + + +# 7. Try a GBDK Tutorial You might want to start off with a guided GBDK tutorial from the @ref links_gbdk_tutorials "GBDK Tutorials section". - __Note:__ Tutorials (or parts of them) may be based on the older GBDK from the 2000's before it was updated to be GBDK-2020. The general principals are all the same, but the setup and parts of the @ref docs_toolchain "toolchain" (compiler/etc) may be somewhat different and some links may be outdated (pointing to the old GBDK or old tools). -# 6. Read up! +# 8. Read up! - It is strongly encouraged to read more @ref docs_index "GBDK-2020 General Documentation". - Learn about the Game Boy hardware by reading through the @ref Pandocs technical reference. -# 7. Need help? -Check out the links for @ref links_help_and_community "online community and support". - +# 9. Need help? +Check out the links for @ref links_help_and_community "online community and support" and read the @ref docs_faq "FAQ". + diff --git a/docs/pages/links_and_tools.md b/docs/pages/links_and_tools.md @@ -41,6 +41,13 @@ This is a brief list of useful tools and information. It is not meant to be comp https://github.com/gingemonster/GamingMonstersGameBoySampleCode +@anchor link_examples +# Example code + - @anchor examples_gbdk_playground + __Simplified GBDK examples__ + https://github.com/mrombout/gbdk_playground/commits/master + + @anchor links_graphic # Graphics Tools - @anchor gbtd_gbmb diff --git a/docs/pages/migrating_new_versions.md b/docs/pages/migrating_new_versions.md @@ -4,8 +4,13 @@ This section contains information that may be useful to know or important when u # GBDK 2020 versions +## Porting to GBDK 2020 4.0.3 + - No significant changes required + ## Porting to GBDK 2020 4.0.2 - - The default font has been reduced from 256 to 96 characters. Code using special characters may need to be updated. + - The default font has been reduced from 256 to 96 characters. + - Code using special characters may need to be updated. + - The off-by-1 character index offset was removed for fonts. Old fonts with the offset need to be re-adjusted. ## Porting to GBDK 2020 4.0.1 - __Important!__ : The `WRAM` memory region is no longer automatically initialized to zeros during startup. diff --git a/docs/pages/sample_programs.md b/docs/pages/sample_programs.md @@ -1,4 +1,4 @@ -@page docs_example_programs GBDK Example Programs +@page docs_example_programs Example Programs GBDK includes several example programs both in C and in assembly. They are located in the examples directory, and in its subdirectories. They can be built by typing `make` in the correnponding directory. @@ -54,6 +54,10 @@ The gb-dtmf, written by Osamu Ohashi, is a Dual Tone Multi-Frequency (DTMF) gene Illustrates how to install interrupt handlers. +# large map +Shows how to scroll with maps larger than 32 x 32 tiles using set_bkg_submap(). It fills rows and columns at the edges of the visible viewport (of the hardware Background Map) as it scrolls from the desired sub-region of the large map. + + # lcd isr wobble An example of how to use the LCD ISR for visual special effects @@ -109,3 +113,6 @@ The space example is an assembly program that demonstrates the use of sprites, w SELECT : Basic fading effect +# templates +Two basic template examples are provided as a starting place for writing your GBDK programs. + diff --git a/docs/pages/toolchain.md b/docs/pages/toolchain.md @@ -14,40 +14,11 @@ GBDK 2020 uses the SDCC compiler along with some custom tools to build Game Boy To see individual arguments and options for a tool, run that tool from the command line with either no arguments or with `-h`. -@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. - <!-- --> - -- 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" + +# Data Types +For data types and special C keywords, see @ref file_asm_gbz80_types_h "asm/gbz80/types.h" and @ref file_asm_types_h "asm/types.h". + +Also see the SDCC manual (scroll down a little on the linked page): http://sdcc.sourceforge.net/doc/sdccman.pdf#section.1.1 @anchor toolchain_changing_important_addresses diff --git a/gbdk-lib/include/asm/gbz80/types.h b/gbdk-lib/include/asm/gbz80/types.h @@ -1,4 +1,5 @@ /** @file asm/gbz80/types.h + @anchor file_asm_gbz80_types_h Types definitions for the gb. */ #ifndef ASM_GBZ80_TYPES_INCLUDE diff --git a/gbdk-lib/include/asm/types.h b/gbdk-lib/include/asm/types.h @@ -26,6 +26,7 @@ #endif /** TRUE or FALSE. + @anchor file_asm_types_h */ typedef INT8 BOOLEAN; diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -685,18 +685,26 @@ void get_bkg_data(UINT8 first_tile, unsigned char *data) NONBANKED __preserves_regs(b, c); -/** Sets a rectangular region of Tile Map entries for the Background layer. +/** Sets a rectangular region of Background Tile Map. @param x X Start position in Background Map tile coordinates. Range 0 - 31 @param y Y Start position in Background Map tile coordinates. Range 0 - 31 - @param w Width of area to set in tiles. Range 0 - 31 - @param h Height of area to set in tiles. Range 0 - 31 - @param tiles Pointer to source Tile Map data + @param w Width of area to set in tiles. Range 1 - 32 + @param h Height of area to set in tiles. Range 1 - 32 + @param tiles Pointer to source tile map data - Entries are copied from __tiles__ to the Background Tile Map starting at + Entries are copied from map at __tiles__ to the Background Tile Map starting at __x__, __y__ writing across for __w__ tiles and down for __h__ tiles. - One byte per Tile map entry. + Use @ref set_bkg_submap() instead when: + \li Source map is wider than 32 tiles. + \li Writing a width that does not match the source map width __and__ more + than one row high at a time. + + One byte per source tile map entry. + + Writes that exceed coordinate 31 on the x or y axis will wrap around to + the Left and Top edges. Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table. @@ -727,7 +735,7 @@ void get_bkg_data(UINT8 first_tile, assigned. @see SHOW_BKG - @see set_bkg_data + @see set_bkg_data, set_bkg_submap */ void set_bkg_tiles(UINT8 x, UINT8 y, @@ -736,6 +744,34 @@ void set_bkg_tiles(UINT8 x, const unsigned char *tiles) NONBANKED __preserves_regs(b, c); +/** Sets a rectangular area of the Background Tile Map using a sub-region + from a source tile map. Useful for scrolling implementations of maps + larger than 32 x 32 tiles. + + @param x X Start position in Background Map tile coordinates. Range 0 - 31 + @param y Y Start position in Background Map tile coordinates. Range 0 - 31 + @param w Width of area to set in tiles. Range 1 - 255 + @param h Height of area to set in tiles. Range 1 - 255 + @param map Pointer to source tile map data + @param map_w Width of source tile map in tiles. Range 1 - 255 + + Entries are copied from __map__ to the Background Tile Map starting at + __x__, __y__ writing across for __w__ tiles and down for __h__ tiles, + using __map_w__ as the rowstride for the source tile map. + + Use this instead of @ref set_bkg_tiles when the source map is wider than + 32 tiles or when writing a width that does not match the source map width. + + One byte per source tile map entry. + + Writes that exceed coordinate 31 on the x or y axis will wrap around to + the Left and Top edges. + + See @ref set_bkg_tiles for setting CGB attribute maps with @ref VBK_REG. + + @see SHOW_BKG + @see set_bkg_data, set_bkg_tiles, set_win_submap +*/ void set_bkg_submap(UINT8 x, UINT8 y, UINT8 w, UINT8 h, const unsigned char *map, UINT8 map_w); @@ -861,18 +897,26 @@ void get_win_data(UINT8 first_tile, unsigned char *data) NONBANKED __preserves_regs(b, c); -/** Sets a rectangular region of Tile Map entries for the Window layer. +/** Sets a rectangular region of the Window Tile Map. @param x X Start position in Window Map tile coordinates. Range 0 - 31 @param y Y Start position in Window Map tile coordinates. Range 0 - 31 - @param w Width of area to set in tiles. Range 0 - 31 - @param h Height of area to set in tiles. Range 0 - 31 - @param tiles Pointer to source Tile Map data + @param w Width of area to set in tiles. Range 1 - 32 + @param h Height of area to set in tiles. Range 1 - 32 + @param tiles Pointer to source tile map data - Entries are copied from __tiles__ to the background Tile Map starting at + Entries are copied from map at __tiles__ to the Window Tile Map starting at __x__, __y__ writing across for __w__ tiles and down for __h__ tiles. - One byte per Tile Map entry. + Use @ref set_win_submap() instead when: + \li Source map is wider than 32 tiles. + \li Writing a width that does not match the source map width __and__ more + than one row high at a time. + + One byte per source tile map entry. + + Writes that exceed coordinate 31 on the x or y axis will wrap around to + the Left and Top edges. Note: Patterns 128-255 overlap with patterns 128-255 of the sprite Tile Pattern table. @@ -880,8 +924,9 @@ void get_win_data(UINT8 first_tile, \li VBK_REG=0 Tile Numbers are written \li VBK_REG=1 Tile Attributes are written - @see set_bkg_tiles For more details about GBC Tile Attributes - @see SHOW_WIN, HIDE_WIN + For more details about GBC Tile Attributes see @ref set_bkg_tiles. + + @see SHOW_WIN, HIDE_WIN, set_win_submap, set_bkg_tiles, set_bkg_data */ void set_win_tiles(UINT8 x, UINT8 y, @@ -890,6 +935,36 @@ void set_win_tiles(UINT8 x, const unsigned char *tiles) NONBANKED __preserves_regs(b, c); +/** Sets a rectangular area of the Window Tile Map using a sub-region + from a source tile map. + + @param x X Start position in Window Map tile coordinates. Range 0 - 31 + @param y Y Start position in Wimdpw Map tile coordinates. Range 0 - 31 + @param w Width of area to set in tiles. Range 1 - 255 + @param h Height of area to set in tiles. Range 1 - 255 + @param map Pointer to source tile map data + @param map_w Width of source tile map in tiles. Range 1 - 255 + + Entries are copied from __map__ to the Window Tile Map starting at + __x__, __y__ writing across for __w__ tiles and down for __h__ tiles, + using __map_w__ as the rowstride for the source tile map. + + Use this instead of @ref set_win_tiles when the source map is wider than + 32 tiles or when writing a width that does not match the source map width. + + One byte per source tile map entry. + + Writes that exceed coordinate 31 on the x or y axis will wrap around to + the Left and Top edges. + + GBC only: @ref VBK_REG determines whether Tile Numbers or Tile Attributes get set. + \li VBK_REG=0 Tile Numbers are written + \li VBK_REG=1 Tile Attributes are written + + See @ref set_bkg_tiles for details about CGB attribute maps with @ref VBK_REG. + + @see SHOW_WIN, HIDE_WIN, set_win_tiles, set_bkg_submap, set_bkg_tiles, set_bkg_data +**/ void set_win_submap(UINT8 x, UINT8 y, UINT8 w, UINT8 h, const unsigned char *map, UINT8 map_w); @@ -1209,15 +1284,15 @@ void get_data(unsigned char *data, @param x X Start position in Map tile coordinates. Range 0 - 31 @param y Y Start position in Map tile coordinates. Range 0 - 31 - @param w Width of area to set in tiles. Range 0 - 31 - @param h Height of area to set in tiles. Range 0 - 31 + @param w Width of area to set in tiles. Range 1 - 32 + @param h Height of area to set in tiles. Range 1 - 32 @param vram_addr Pointer to destination VRAM Address @param tiles Pointer to source Tile Map data Entries are copied from __tiles__ to Tile Map at address vram_addr starting at __x__, __y__ writing across for __w__ tiles and down for __h__ tiles. - One byte per Tile map entry. + One byte per source tile map entry. There are two 32x32 Tile Maps in VRAM at addresses 9800h-9BFFh and 9C00h-9FFFh.
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.