gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 29a5a39add6aba4f701c031b55a76aa02085e995 parent e0c90a2bcc84fdd2e017974ed039f5443a0aab7f Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Wed, 26 Jan 2022 21:44:03 -0800 Merge pull request #306 from bbbbbr/docs_4_0_6 Docs & Examples: Updates for 4.0.6, SGB & Autobanking Diffstat:
| M | docs/pages/08_faq.md | 9 | ++++++++- |
| M | gbdk-lib/examples/ap/sgb_border/border.c | 7 | ++++++- |
| M | gbdk-lib/examples/ap/sgb_border/sgb_border.h | 11 | ++++++++++- |
| M | gbdk-lib/examples/cross-platform/banks_autobank/src/banks.c | 59 | +++++++++++++++++++++++++---------------------------------- |
| A | gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_1.h | 16 | ++++++++++++++++ |
| A | gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_2.h | 16 | ++++++++++++++++ |
| A | gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_3.h | 16 | ++++++++++++++++ |
| M | gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_4_not-autobanked.c | 4 | ++-- |
| A | gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_4_not-autobanked.h | 16 | ++++++++++++++++ |
| M | gbdk-lib/examples/gb/sgb_border/border.c | 7 | ++++++- |
| M | gbdk-lib/examples/gb/sgb_border/sgb_border.h | 11 | ++++++++++- |
| M | gbdk-lib/include/gb/gb.h | 94 | +++++++++++++++++++++++++++++++++++++++++++++++-------------------------------- |
| M | gbdk-lib/include/gb/sgb.h | 9 | +++++++++ |
13 files changed, 196 insertions(+), 79 deletions(-)
diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -5,7 +5,14 @@ # 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 <!-- --> + - 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 <!-- --> + +# Graphics and Resources + - How do I use a tile map when it's tiles don't start at index zero? + - The two main options are: + - Use @ref set_bkg_based_tiles(), @ref set_bkg_based_submap(), @ref set_win_based_tiles(), @ref set_win_based_submap() and provide a tile origin offset. + - Use @ref utility_png2asset with `-tile_origin` to create a map with the tile index offsets built in. + <!-- --> # ROM Header Settings - How do I set the ROM's title? diff --git a/gbdk-lib/examples/ap/sgb_border/border.c b/gbdk-lib/examples/ap/sgb_border/border.c @@ -5,7 +5,12 @@ #include "border_data.h" void main(void) { - DISPLAY_ON; + + // Wait 4 frames + // For SGB on PAL SNES this delay is required on startup, otherwise borders don't show up + for (uint8_t i = 4; i != 0; i--) wait_vbl_done(); + + DISPLAY_ON; set_sgb_border(border_chr, border_chr_size, border_map, border_map_size, border_pal, border_pal_size); while(1) { wait_vbl_done(); diff --git a/gbdk-lib/examples/ap/sgb_border/sgb_border.h b/gbdk-lib/examples/ap/sgb_border/sgb_border.h @@ -6,8 +6,17 @@ #define SNES_RGB(R,G,B) (uint16_t)((B) << 10 | (G) << 5 | (R)) -/** sets SGB border */ +/** sets SGB border + When using the SGB with a PAL SNES, a delay should be added + just after program startup such as: + + \code{.c} + // Wait 4 frames + // For PAL SNES this delay is required on startup + for (uint8_t i = 4; i != 0; i--) wait_vbl_done(); + \endcode +*/ void set_sgb_border(unsigned char * tiledata, size_t tiledata_size, unsigned char * tilemap, size_t tilemap_size, unsigned char * palette, size_t palette_size); diff --git a/gbdk-lib/examples/cross-platform/banks_autobank/src/banks.c b/gbdk-lib/examples/cross-platform/banks_autobank/src/banks.c @@ -2,38 +2,13 @@ #include <stdint.h> #include <stdio.h> -// Banked const vars from the other source files -// -// "BANKREF_EXTERN()" makes a "BANKREF()" reference -// from another source file accessible for use with "BANK()" -// -// The entries below could also be in separate, matching -// ".h" header files for each banked ".c" source file, -// instead of here at the start of "banks.c". -extern const uint8_t some_const_var_1; -BANKREF_EXTERN(some_const_var_1) +// The header files below include provide bank references for the +// banked const vars and functions in the other source files +#include "srcfile_1.h" +#include "srcfile_2.h" +#include "srcfile_3.h" +#include "srcfile_4_not-autobanked.h" -extern const uint8_t some_const_var_2; -BANKREF_EXTERN(some_const_var_2) - -extern const uint8_t some_const_var_3; -BANKREF_EXTERN(some_const_var_3) - -extern const uint8_t some_const_var_4; -BANKREF_EXTERN(some_const_var_4) - -// Banked functions from the other source files -void func_1() BANKED; -BANKREF_EXTERN(func_1) - -void func_2() BANKED; -BANKREF_EXTERN(func_2) - -void func_3() BANKED; -BANKREF_EXTERN(func_3) - -void some_4() BANKED; -BANKREF_EXTERN(some_4) // Non-banked const const uint8_t some_const_var_0 = 0; @@ -46,20 +21,22 @@ void bank_fixed(void) NONBANKED void main(void) { + uint8_t _saved_bank; + set_default_palette(); printf("Program Start...\n\n"); // Call the functions, unbanked first then the banked ones bank_fixed(); - func_1(); func_2(); func_3(); - some_4(); + func_4(); printf("\n"); + // Print the const vars, unbanked first then the banked ones printf("Const0= %u nonbanked\n", some_const_var_0); @@ -69,14 +46,28 @@ void main(void) printf("Const2= %u in bank %hu\n", some_const_var_2, BANK(some_const_var_2)); SWITCH_ROM(BANK(some_const_var_3)); printf("Const3= %u in bank %hu\n", some_const_var_3, BANK(some_const_var_3)); + + // If you want to temporarily save and then restore the previous active bank: + // + + // Save the currently active bank + _saved_bank = _current_bank; + + // Switch to the desired one SWITCH_ROM(BANK(some_const_var_4)); printf("Const4= %u in bank %hu\n", some_const_var_4, BANK(some_const_var_4)); + // Then restore the previous bank + SWITCH_ROM(_saved_bank); + + + printf("\n"); puts("The End..."); - // Loop endlesslu + // Loop forever while(1) { + // Yield CPU till the end of each frame wait_vbl_done(); } diff --git a/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_1.h b/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_1.h @@ -0,0 +1,15 @@ +#include <gbdk/platform.h> + +#ifndef _srcfile_1_h +#define _srcfile_1_h + +// "BANKREF_EXTERN()" makes a "BANKREF()" reference +// from another source file accessible for use with "BANK()" +extern const uint8_t some_const_var_1; +BANKREF_EXTERN(some_const_var_1) + +// Reference for a banked function +void func_1() BANKED; +BANKREF_EXTERN(func_1) + +#endif + diff --git a/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_2.h b/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_2.h @@ -0,0 +1,15 @@ +#include <gbdk/platform.h> + +#ifndef _srcfile_2_h +#define _srcfile_2_h + +// "BANKREF_EXTERN()" makes a "BANKREF()" reference +// from another source file accessible for use with "BANK()" +extern const uint8_t some_const_var_2; +BANKREF_EXTERN(some_const_var_2) + +// Reference for a banked function +void func_2() BANKED; +BANKREF_EXTERN(func_2) + +#endif + diff --git a/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_3.h b/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_3.h @@ -0,0 +1,15 @@ +#include <gbdk/platform.h> + +#ifndef _srcfile_3_h +#define _srcfile_3_h + +// "BANKREF_EXTERN()" makes a "BANKREF()" reference +// from another source file accessible for use with "BANK()" +extern const uint8_t some_const_var_3; +BANKREF_EXTERN(some_const_var_3) + +// Reference for a banked function +void func_3() BANKED; +BANKREF_EXTERN(func_3) + +#endif + diff --git a/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_4_not-autobanked.c b/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_4_not-autobanked.c @@ -9,12 +9,12 @@ const uint8_t some_const_var_4 = 4; BANKREF(some_const_var_4) -void some_4() BANKED +void func_4() BANKED { printf("Func4 not autobank\n" " is in ROM bank %u\n", _current_bank); } -BANKREF(some_4) +BANKREF(func_4) // A big constant array to take up space static const unsigned char local_const_4[] = { diff --git a/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_4_not-autobanked.h b/gbdk-lib/examples/cross-platform/banks_autobank/src/srcfile_4_not-autobanked.h @@ -0,0 +1,15 @@ +#include <gbdk/platform.h> + +#ifndef _srcfile_4_h +#define _srcfile_4_h + +// "BANKREF_EXTERN()" makes a "BANKREF()" reference +// from another source file accessible for use with "BANK()" +extern const uint8_t some_const_var_4; +BANKREF_EXTERN(some_const_var_4) + +// Reference for a banked function +void func_4() BANKED; +BANKREF_EXTERN(func_4) + +#endif + diff --git a/gbdk-lib/examples/gb/sgb_border/border.c b/gbdk-lib/examples/gb/sgb_border/border.c @@ -5,7 +5,12 @@ #include "border_data.h" void main(void) { - DISPLAY_ON; + + // Wait 4 frames + // For SGB on PAL SNES this delay is required on startup, otherwise borders don't show up + for (uint8_t i = 4; i != 0; i--) wait_vbl_done(); + + DISPLAY_ON; set_sgb_border(border_data_tiles, sizeof(border_data_tiles), border_data_map, sizeof(border_data_map), border_data_palettes, sizeof(border_data_palettes)); while(1) { wait_vbl_done(); diff --git a/gbdk-lib/examples/gb/sgb_border/sgb_border.h b/gbdk-lib/examples/gb/sgb_border/sgb_border.h @@ -6,8 +6,17 @@ #define SNES_RGB(R,G,B) (uint16_t)((B) << 10 | (G) << 5 | (R)) -/** sets SGB border */ +/** sets SGB border + When using the SGB with a PAL SNES, a delay should be added + just after program startup such as: + + \code{.c} + // Wait 4 frames + // For PAL SNES this delay is required on startup + for (uint8_t i = 4; i != 0; i--) wait_vbl_done(); + \endcode +*/ void set_sgb_border(unsigned char * tiledata, size_t tiledata_size, unsigned char * tilemap, size_t tilemap_size, unsigned char * palette, size_t palette_size); diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -674,6 +674,10 @@ inline void disable_interrupts() PRESERVES_REGS(a, b, c, d, e, h, l) { /** Clears any pending interrupts and sets the interrupt mask register IO to flags. @param flags A logical OR of *_IFLAGS + + @note: This disables and then re-enables interrupts so it + must be used outside of a critical section. + @see enable_interrupts(), disable_interrupts() @see VBL_IFLAG, LCD_IFLAG, TIM_IFLAG, SIO_IFLAG, JOY_IFLAG */ @@ -934,6 +938,24 @@ void set_bkg_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *ti extern uint8_t _map_tile_offset; +/** Sets a rectangular region of Background Tile Map. + The offset value in __base_tile__ is added to + the tile ID for each map entry. + + @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 - 32 + @param h Height of area to set in tiles. Range 1 - 32 + @param tiles Pointer to source tile map data + @param base_tile Offset each tile ID entry of the source map by this value. Range 1 - 255 + + This is identical to @ref set_bkg_tiles() except that it + adds the __base_tile__ parameter for when a tile map's tiles don't + start at index zero. (For example, the tiles used by the map + range from 100 -> 120 in VRAM instead of 0 -> 20). + + @see set_bkg_tiles for more details +*/ inline void set_bkg_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *tiles, uint8_t base_tile) { _map_tile_offset = base_tile; set_bkg_tiles(x, y, w, h, tiles); @@ -976,8 +998,8 @@ void set_bkg_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *m extern uint8_t _submap_tile_offset; /** Sets a rectangular area of the Background Tile Map using a sub-region - from a source tile map and base_tile tile ID offset. Useful for scrolling - implementations of maps larger than 32 x 32 tiles. + from a source tile map. The offset value in __base_tile__ is added to + the tile ID for each map entry. @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 @@ -985,24 +1007,14 @@ extern uint8_t _submap_tile_offset; @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 - @param base_tile Offset each tile ID of submap by this value - - 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. + @param base_tile Offset each tile ID entry of the source map by this value. Range 1 - 255 - 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. + This is identical to @ref set_bkg_based_submap() except that it + adds the __base_tile__ parameter for when a tile map's tiles don't + start at index zero. (For example, the tiles used by the map + range from 100 -> 120 in VRAM instead of 0 -> 20). - @see SHOW_BKG - @see set_bkg_data, set_bkg_tiles, set_win_submap, set_tiles + @see set_bkg_based_submap for more details */ inline void set_bkg_based_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w, uint8_t base_tile) { _submap_tile_offset = base_tile; @@ -1167,6 +1179,24 @@ void get_win_data(uint8_t first_tile, uint8_t nb_tiles, uint8_t *data) OLDCALL P void set_win_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *tiles) OLDCALL PRESERVES_REGS(b, c); +/** Sets a rectangular region of the Window Tile Map. + The offset value in __base_tile__ is added to + the tile ID for each map entry. + + @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 1 - 32 + @param h Height of area to set in tiles. Range 1 - 32 + @param tiles Pointer to source tile map data + @param base_tile Offset each tile ID entry of the source map by this value. Range 1 - 255 + + This is identical to @ref set_win_tiles() except that it + adds the __base_tile__ parameter for when a tile map's tiles don't + start at index zero. (For example, the tiles used by the map + range from 100 -> 120 in VRAM instead of 0 -> 20). + + @see set_win_tiles for more details +*/ inline void set_win_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *tiles, uint8_t base_tile) { _map_tile_offset = base_tile; set_win_tiles(x, y, w, h, tiles); @@ -1207,7 +1237,8 @@ void set_win_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *m /** Sets a rectangular area of the Window Tile Map using a sub-region - from a source tile map and base_tile tile ID offset + from a source tile map. The offset value in __base_tile__ is added + to the tile ID for each map entry. @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 @@ -1215,27 +1246,14 @@ void set_win_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *m @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 - @param base_tile Offset each tile ID of submap by this value + @param base_tile Offset each tile ID entry of the source map by this value. 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. + This is identical to @ref set_win_submap() except that it + adds the __base_tile__ parameter for when a tile map's tiles don't + start at index zero. (For example, the tiles used by the map + range from 100 -> 120 in VRAM instead of 0 -> 20). - 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, set_tiles + @see set_win_submap for more details **/ inline void set_win_based_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *map, uint8_t map_w, uint8_t base_tile) { _submap_tile_offset = base_tile; diff --git a/gbdk-lib/include/gb/sgb.h b/gbdk-lib/include/gb/sgb.h @@ -49,6 +49,15 @@ uint8_t sgb_check() OLDCALL PRESERVES_REGS(b, c); See the `sgb_border` GBDK example project for a demo of how to use these the sgb functions. + When using the SGB with a PAL SNES, a delay should be added + just after program startup such as: + + \code{.c} + // Wait 4 frames + // For PAL SNES this delay is required on startup + for (uint8_t i = 4; i != 0; i--) wait_vbl_done(); + \endcode + @see sgb_check() */ void sgb_transfer(uint8_t * packet) OLDCALL PRESERVES_REGS(b, c);
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.