gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 16fb151c328ed2c6b4c1871a25c98324a0d37062 parent 933737214ca122f2a32e46127a956f7ada344a74 Author: bbbbbr <bbbbbr@users.noreply.github.com> Date: Sun, 12 Jun 2022 00:54:13 -0700 Merge pull request #378 from bbbbbr/docs_4_1_0_headers Docs 4 1 0 headers Diffstat:
| M | Makefile | 2 | +- |
| M | docs/pages/04_coding_guidelines.md | 42 | +++++++++++++++++++++++++++++++----------- |
| M | docs/pages/09_migrating_new_versions.md | 1 | + |
| M | gbdk-lib/examples/gb/apa_image/src/main.c | 5 | +++-- |
| M | gbdk-lib/include/gb/gb.h | 42 | ++++++++++++++++++++++++++++++------------ |
| M | gbdk-lib/include/gb/hardware.h | 2 | +- |
| M | gbdk-lib/include/gb/metasprites.h | 8 | +++++--- |
| M | gbdk-lib/include/stdio.h | 10 | ++++++++-- |
8 files changed, 80 insertions(+), 32 deletions(-)
diff --git a/Makefile b/Makefile @@ -8,7 +8,7 @@ TOPDIR = $(shell pwd) # Package name, used for tarballs PKG = gbdk # Version, used for tarballs & docs -VER = 4.0.6 +VER = 4.1.0 PORTS=sm83 z80 mos6502 PLATFORMS=gb ap duck gg sms msxdos nes diff --git a/docs/pages/04_coding_guidelines.md b/docs/pages/04_coding_guidelines.md @@ -185,6 +185,24 @@ There are a some scenarios where the compiler will warn about overflows with con @anchor docs_chars_varargs ## Chars and vararg functions +Parameters (chars, ints, etc) to @ref printf / @ref sprintf should always be explicitly cast to avoid type related parameter passing issues. + +For example, below will result in the likely unintended output: +```{.c} +sprintf(str_temp, "%u, %d, %x\n", UINT16_MAX, INT16_MIN, UINT16_MAX); +printf("%s",str_temp); + +// Will output: "65535, 0, 8000" +``` +Instead this will give the intended output: +```{.c} +sprintf(str_temp, "%u, %d, %x\n", (uint16_t)UINT16_MAX, (int16_t)INT16_MIN, (uint16_t)UINT16_MAX); +printf("%s",str_temp); + +// Will output: "65535, -32768, FFFF" +``` + +### Chars In standard C when `chars` are passed to a function with variadic arguments (varargs, those declared with `...` as a parameter), such as @ref printf(), those `chars` get automatically promoted to `ints`. For an 8 bit CPU such as the Game Boy's, this is not as efficient or desirable in most cases. So the default SDCC behavior, which GBDK-2020 expects, is that chars will remain chars and _not_ get promoted to ints when **explicitly cast as chars while calling a varargs function**. - They must be explicitly re-cast when passing them to a varargs function, even though they are already declared as chars. @@ -197,17 +215,19 @@ In standard C when `chars` are passed to a function with variadic arguments (var For example: - unsigned char i = 0x5A; - - // NO: - // The char will get promoted to an int, producing incorrect printf output - // The output will be: 5A 00 - printf("%hx %hx", i, i); - - // YES: - // The char will remain a char and printf output will be as expected - // The output will be: 5A 5A - printf("%hx %hx", (unsigned char)i, (unsigned char)i); +```{.c} +unsigned char i = 0x5A; + +// NO: +// The char will get promoted to an int, producing incorrect printf output +// The output will be: 5A 00 +printf("%hx %hx", i, i); + +// YES: +// The char will remain a char and printf output will be as expected +// The output will be: 5A 5A +printf("%hx %hx", (unsigned char)i, (unsigned char)i); +``` Some functions that accept varargs: - @ref EMU_printf, @ref gprintf(), @ref printf(), @ref sprintf() diff --git a/docs/pages/09_migrating_new_versions.md b/docs/pages/09_migrating_new_versions.md @@ -19,6 +19,7 @@ This section contains information that may be useful to know or important when u ## Porting to GBDK-2020 4.0.5 - GBDK now requires SDCC 12259 or higher with GBDK-2020 patches + - Variables in static storage are now initialized to zero per C standard (but remaining WRAM is not cleared) - @ref utility_png2asset "png2asset" is the new name for the `png2mtspr` utility - @ref lcc : Changed default output format when not specified from `.ihx` to `.gb` (or other active rom extension) - The `_BSS` area is deprecated (use `_DATA` instead) diff --git a/gbdk-lib/examples/gb/apa_image/src/main.c b/gbdk-lib/examples/gb/apa_image/src/main.c @@ -5,7 +5,8 @@ #include <res/scenery.h> -#define CGB_ONE_PAL 1u +#define CGB_BKG_PAL_0 0u +#define CGB_ONE_PAL 1u const palette_color_t cgb_pal_black[] = {RGB_BLACK, RGB_BLACK, RGB_BLACK, RGB_BLACK}; @@ -13,7 +14,7 @@ void main(void) { // Set the screen to black via the palettes to hide the image draw if (_cpu == CGB_TYPE) { - set_bkg_palette(OAMF_CGB_PAL0, CGB_ONE_PAL, cgb_pal_black); + set_bkg_palette(CGB_BKG_PAL_0, CGB_ONE_PAL, cgb_pal_black); } else { BGP_REG = DMG_PALETTE(DMG_BLACK, DMG_BLACK, DMG_BLACK, DMG_BLACK); } diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -772,6 +772,8 @@ void hiramcpy(uint8_t dst, const void *src, uint8_t n) OLDCALL PRESERVES_REGS(b, /** Turns off the sprites layer. Clears bit 1 of the LCDC register to 0. + + @see hide_sprite, hide_sprites_range */ #define HIDE_SPRITES \ LCDC_REG&=~LCDCF_OBJON @@ -998,8 +1000,8 @@ inline void set_bkg_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, cons 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 x X Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255 + @param y Y Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255 @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 @@ -1009,6 +1011,13 @@ inline void set_bkg_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, cons __x__, __y__ writing across for __w__ tiles and down for __h__ tiles, using __map_w__ as the rowstride for the source tile map. + The __x__ and __y__ parameters are linked in lockstep between + the Source Tile Map and the hardware Background Map. + The hardware Background Map tile coordinates will be masked + to the lowest 5 bits (`value & 0x1F`). In order to use them + out of lockstep an offset from the Source Tile Map pointer + can be passed in `map + x + (y * map_width)`. + 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. @@ -1032,12 +1041,12 @@ extern uint8_t _submap_tile_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 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 + @param x X Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255 + @param y Y Start position in both the Source Tile Map and hardware Background Map tile coordinates. Range 0 - 255 + @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 @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_based_submap() except that it @@ -1244,8 +1253,8 @@ inline void set_win_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, cons /** 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 x X Start position in both the Source Tile Map and hardware Window Map tile coordinates. Range 0 - 255 + @param y Y Start position in both the Source Tile Map and hardware Window Map tile coordinates. Range 0 - 255 @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 @@ -1255,6 +1264,13 @@ inline void set_win_based_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, cons __x__, __y__ writing across for __w__ tiles and down for __h__ tiles, using __map_w__ as the rowstride for the source tile map. + The __x__ and __y__ parameters are linked in lockstep between + the Source Tile Map and the hardware Window Map. + The hardware Window Map tile coordinates will be masked + to the lowest 5 bits (`value & 0x1F`). In order to use them + out of lockstep an offset from the Source Tile Map pointer + can be passed in `map + x + (y * map_width)`. + 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. @@ -1278,8 +1294,8 @@ void set_win_submap(uint8_t x, uint8_t y, uint8_t w, uint8_t h, const uint8_t *m 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 + @param x X Start position in both the Source Tile Map and hardware Window Map tile coordinates. Range 0 - 255 + @param y Y Start position in both the Source Tile Map and hardware Window Map tile coordinates. Range 0 - 255 @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 @@ -1582,6 +1598,8 @@ inline void scroll_sprite(uint8_t nb, int8_t x, int8_t y) { /** Hides sprite number __nb__ by moving it to zero position by Y. @param nb Sprite number, range 0 - 39 + + @see hide_sprites_range, HIDE_SPRITES */ inline void hide_sprite(uint8_t nb) { shadow_OAM[nb].y = 0; diff --git a/gbdk-lib/include/gb/hardware.h b/gbdk-lib/include/gb/hardware.h @@ -309,7 +309,7 @@ __REG KEY1_REG; /**< CPU speed */ #define KEY1F_DBLSPEED 0b10000000 #define KEY1F_PREPARE 0b00000001 -__REG VBK_REG; /**< VRAM bank select */ +__REG VBK_REG; /**< VRAM bank select (CGB only)*/ #define rVBK VBK_REG __REG HDMA1_REG; /**< DMA control 1 */ #define rHDMA1 HDMA1_REG diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h @@ -106,9 +106,11 @@ static uint8_t __move_metasprite_hvflip(uint8_t id, uint8_t x, uint8_t y) OLDCAL static void __hide_metasprite(uint8_t id) OLDCALL; /** - * Hides all hardware sprites in range from <= X < to - * @param from start OAM index - * @param to finish OAM index + Hides all hardware sprites in range from <= X < to + @param from start OAM index + @param to finish OAM index + + @see hide_sprite */ void hide_sprites_range(UINT8 from, UINT8 to) OLDCALL PRESERVES_REGS(b, c); diff --git a/gbdk-lib/include/stdio.h b/gbdk-lib/include/stdio.h @@ -33,8 +33,9 @@ void putchar(char c) OLDCALL; \li \%x (unsigned int as hex) \li \%s (string) - Warning: to correctly pass chars for printing as chars, they *must* - be explicitly re-cast as such when calling the function. + Warning: to correctly pass parameters (such as chars, ints, etc) + __all of them should always be explicitly cast__ as when calling + the function. See @ref docs_chars_varargs for more details. */ void printf(const char *format, ...) OLDCALL REENTRANT; @@ -45,6 +46,11 @@ void printf(const char *format, ...) OLDCALL REENTRANT; @param format The format string as per @ref printf Does not return the number of characters printed. + + Warning: to correctly pass parameters (such as chars, ints, etc) + __all of them should always be explicitly cast__ as when calling + the function. + See @ref docs_chars_varargs for more details. */ void sprintf(char *str, const char *format, ...) OLDCALL REENTRANT;
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.