gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 49bd4a2a1c257ab581418e2391eb33f759a85a66 parent 17732372dbb6809693fbf5d61bb082e0b8ae2480 Author: bbbbbr <reg+github@roughhousing.com> Date: Wed, 15 Dec 2021 23:27:25 -0800 Merge pull request #290 from bbbbbr/docs_work_2 Docs work 2 Diffstat:
| M | docs/pages/03_using_gbdk.md | 6 | ++++-- |
| M | docs/pages/06b_supported_consoles.md | 13 | ++++++++----- |
| M | docs/pages/08_faq.md | 8 | ++++++++ |
| M | gbdk-lib/include/gb/gb.h | 14 | +++++++------- |
| M | gbdk-lib/include/gb/metasprites.h | 65 | +++++++++++++++++++++++++++++++++++++++-------------------------- |
5 files changed, 66 insertions(+), 40 deletions(-)
diff --git a/docs/pages/03_using_gbdk.md b/docs/pages/03_using_gbdk.md @@ -76,9 +76,11 @@ 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. +See 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. +`Warning!` Copying of functions is generally not safe since they may contain jumps to absolute addresses that will not be converted to match the new location. + +It is possible to copy functions to RAM and HIRAM (using the memcpy() and hiramcpy() functions), and execute them from C. Ensure you have enough free space in RAM or HIRAM for copying a function. There are basically two ways for calling a function located in RAM, HIRAM, or ROM: diff --git a/docs/pages/06b_supported_consoles.md b/docs/pages/06b_supported_consoles.md @@ -4,11 +4,14 @@ # Consoles Supported by GBDK As of version `4.0.5` GBDK includes support for other consoles in addition to the Game Boy. - - Nintendo Game Boy / Game Boy Color (GB/GBC) - - Analogue Pocket (AP) - - Sega Master System (SMS) - - Sega Game Gear (GG) - - Mega Duck / Cougar Boy (DUCK) + - Game Boy and related clones + - Nintendo Game Boy / Game Boy Color (GB/GBC) + - Analogue Pocket (AP) + - Mega Duck / Cougar Boy (DUCK) + + - Sega Consoles + - Sega Master System (SMS) + - Sega Game Gear (GG) 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. diff --git a/docs/pages/08_faq.md b/docs/pages/08_faq.md @@ -51,6 +51,14 @@ - 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). <!-- --> + - How do I move the start of the `DATA` section and the `Shadow OAM` location? + - The default locations are: `_shadow_OAM=0xC000` and 240 bytes after it `_DATA=0xC0A0` + - So, for example, if you wanted to move them both to start 256(0x100) bytes later, use these command line arguments for LCC: + - To change the Shadow OAM address: `-Wl-g_shadow_OAM=0xC100` + - To change the DATA address (again, 240 bytes after the Shadow OAM): `-Wl-b_DATA=0xc1a0` + <!-- --> + + # API / Utilities - Is there a list of all functions in the API? - [Functions](globals_func.html) diff --git a/gbdk-lib/include/gb/gb.h b/gbdk-lib/include/gb/gb.h @@ -129,7 +129,7 @@ REG_BGP = DMG_PALETTE(DMG_BLACK, DMG_DARK_GRAY, DMG_LITE_GRAY, DMG_WHITE); \endcode - @see REG_OBP0, REG_OBP1, REG_BGP + @see OBP0_REG, OBP1_REG, BGP_REG @see DMG_BLACK, DMG_DARK_GRAY, DMG_LITE_GRAY, DMG_WHITE */ @@ -1428,7 +1428,7 @@ inline void hide_sprite(uint8_t nb) { /** Copies arbitrary data to an address in VRAM - without taking into account the state of LCDC bit 4. + without taking into account the state of LCDC bits 3 or 4. @param vram_addr Pointer to destination VRAM Address @param data Pointer to source buffer @@ -1440,13 +1440,13 @@ inline void hide_sprite(uint8_t nb) { \li VBK_REG=0 indicates the first bank \li VBK_REG=1 indicates the second - @see set_bkg_data, set_win_data, set_tile_data + @see set_bkg_data, set_win_data, set_bkg_tiles, set_win_tiles, set_tile_data, set_tiles */ void set_data(uint8_t *vram_addr, const uint8_t *data, uint16_t len) OLDCALL PRESERVES_REGS(b, c); /** Copies arbitrary data from an address in VRAM into a buffer - without taking into account the state of LCDC bit 4. + without taking into account the state of LCDC bits 3 or 4. @param vram_addr Pointer to source VRAM Address @param data Pointer to destination buffer @@ -1458,7 +1458,7 @@ void set_data(uint8_t *vram_addr, const uint8_t *data, uint16_t len) OLDCALL PRE \li VBK_REG=0 indicates the first bank \li VBK_REG=1 indicates the second - @see get_bkg_data, get_win_data + @see get_bkg_data, get_win_data, get_bkg_tiles, get_win_tiles, get_tiles */ void get_data(uint8_t *data, uint8_t *vram_addr, uint16_t len) OLDCALL PRESERVES_REGS(b, c); @@ -1479,7 +1479,7 @@ void vmemcpy(uint8_t *dest, uint8_t *sour, uint16_t len) OLDCALL PRESERVES_REGS( /** Sets a rectangular region of Tile Map entries at a given VRAM Address - without taking into account the state of LCDC bit 4. + without taking into account the state of LCDC bit 3. @param x X Start position in Map tile coordinates. Range 0 - 31 @param y Y Start position in Map tile coordinates. Range 0 - 31 @@ -1516,7 +1516,7 @@ void set_tiles(uint8_t x, uint8_t y, uint8_t w, uint8_t h, uint8_t *vram_addr, c void set_tile_data(uint8_t first_tile, uint8_t nb_tiles, const uint8_t *data, uint8_t base) OLDCALL PRESERVES_REGS(b, c); /** Copies a rectangular region of Tile Map entries from a given VRAM Address into a buffer - without taking into account the state of LCDC bit 4. + without taking into account the state of LCDC bit 3. @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 diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h @@ -1,13 +1,13 @@ /** @file gb/metasprites.h - + # Metasprite support - A metasprite is a larger sprite made up from a + A metasprite is a larger sprite made up from a collection of smaller individual hardware sprites. Different frames of the same metasprites can share tile data. - The api supports metasprites in both + The api supports metasprites in both @ref SPRITES_8x8 and @ref SPRITES_8x16 mode. If 8x16 mode is used then the height of the metasprite must be a multiple of 16. @@ -47,7 +47,7 @@ for a sprite (CGB palette, BG/WIN priority, Tile VRAM Bank) will get overwritten. - How to use sprite property flags with metasprites: + How to use sprite property flags with metasprites: - Metsaprite structures can be copied into RAM so their property flags can be modified at runtime. - The metasprite structures can have the property flags @@ -55,6 +55,13 @@ in the @ref utility_png2asset "png2asset" tool). - Update properties for the affected sprites after calling a move_metasprite_*() function. + + The following functions are only available for Game Boy and + related clone consoles due to lack of hardware support for + sprite flipping in other consoles. See @ref docs_consoles_supported_list + - @ref move_metasprite_vflip() + - @ref move_metasprite_hflip() + - @ref move_metasprite_hvflip() */ #ifndef _METASPRITES_H_INCLUDE @@ -83,7 +90,7 @@ typedef struct metasprite_t { uint8_t props; } metasprite_t; -#define metasprite_end -128 +#define metasprite_end -128 #define METASPR_ITEM(dy,dx,dt,a) {(dy),(dx),(dt),(a)} #define METASPR_TERM {metasprite_end} @@ -102,24 +109,24 @@ 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 - */ + */ void hide_sprites_range(UINT8 from, UINT8 to) OLDCALL PRESERVES_REGS(b, c); /** Moves metasprite to the absolute position x and y @param metasprite Pointer to the first struct of the metasprite (for the desired frame) @param base_tile Number of the first tile where the metasprite's tiles start - @param base_sprite Number of the first hardware sprite to be used by the metasprite + @param base_sprite Number of the first hardware sprite to be used by the metasprite @param x Absolute x coordinate of the sprite @param y Absolute y coordinate of the sprite Moves __metasprite__ to the absolute position __x__ and __y__ - (with __no flip__ on the X or Y axis). Hardware sprites are - allocated starting from __base_sprite__, using tiles + (with __no flip__ on the X or Y axis). Hardware sprites are + allocated starting from __base_sprite__, using tiles starting from __base_tile__. Sets: - \li __current_metasprite = metasprite; + \li __current_metasprite = metasprite; \li __current_base_tile = base_tile; Note: Overwrites OAM sprite properties (such as CGB Palette), see @@ -128,36 +135,38 @@ void hide_sprites_range(UINT8 from, UINT8 to) OLDCALL PRESERVES_REGS(b, c); @return Number of hardware sprites used to draw this metasprite */ inline uint8_t move_metasprite(const metasprite_t * metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y) { - __current_metasprite = metasprite; + __current_metasprite = metasprite; __current_base_tile = base_tile; - return __move_metasprite(base_sprite, x, y); + return __move_metasprite(base_sprite, x, y); } /** Moves metasprite to the absolute position x and y, __flipped on the Y axis__ @param metasprite Pointer to the first struct of the metasprite (for the desired frame) @param base_tile Number of the first tile where the metasprite's tiles start - @param base_sprite Number of the first hardware sprite to be used by the metasprite + @param base_sprite Number of the first hardware sprite to be used by the metasprite @param x Absolute x coordinate of the sprite @param y Absolute y coordinate of the sprite Same as @ref move_metasprite(), but with the metasprite flipped on the Y axis only. Sets: - \li __current_metasprite = metasprite; + \li __current_metasprite = metasprite; \li __current_base_tile = base_tile; Note: Overwrites OAM sprite properties (such as CGB palette), see @ref metasprite_and_sprite_properties "Metasprites and sprite properties". + This function is only available on Game Boy and related clone consoles. + @return Number of hardware sprites used to draw this metasprite @see move_metasprite() */ inline uint8_t move_metasprite_vflip(const metasprite_t * metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y) { - __current_metasprite = metasprite; + __current_metasprite = metasprite; __current_base_tile = base_tile; - return __move_metasprite_vflip(base_sprite, x - 8, y); + return __move_metasprite_vflip(base_sprite, x - 8, y); } @@ -165,58 +174,62 @@ inline uint8_t move_metasprite_vflip(const metasprite_t * metasprite, uint8_t ba @param metasprite Pointer to the first struct of the metasprite (for the desired frame) @param base_tile Number of the first tile where the metasprite's tiles start - @param base_sprite Number of the first hardware sprite to be used by the metasprite + @param base_sprite Number of the first hardware sprite to be used by the metasprite @param x Absolute x coordinate of the sprite @param y Absolute y coordinate of the sprite Same as @ref move_metasprite(), but with the metasprite flipped on the X axis only. Sets: - \li __current_metasprite = metasprite; + \li __current_metasprite = metasprite; \li __current_base_tile = base_tile; Note: Overwrites OAM sprite properties (such as CGB palette), see @ref metasprite_and_sprite_properties "Metasprites and sprite properties". + This function is only available on Game Boy and related clone consoles. + @return Number of hardware sprites used to draw this metasprite @see move_metasprite() */ inline uint8_t move_metasprite_hflip(const metasprite_t * metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y) { - __current_metasprite = metasprite; + __current_metasprite = metasprite; __current_base_tile = base_tile; - return __move_metasprite_hflip(base_sprite, x, y - ((LCDC_REG & 0x04U) ? 16 : 8) ); + return __move_metasprite_hflip(base_sprite, x, y - ((LCDC_REG & 0x04U) ? 16 : 8) ); } /** Moves metasprite to the absolute position x and y, __flipped on the X and Y axis__ @param metasprite Pointer to the first struct of the metasprite (for the desired frame) @param base_tile Number of the first tile where the metasprite's tiles start - @param base_sprite Number of the first hardware sprite to be used by the metasprite + @param base_sprite Number of the first hardware sprite to be used by the metasprite @param x Absolute x coordinate of the sprite @param y Absolute y coordinate of the sprite Same as @ref move_metasprite(), but with the metasprite flipped on both the X and Y axis. Sets: - \li __current_metasprite = metasprite; + \li __current_metasprite = metasprite; \li __current_base_tile = base_tile; Note: Overwrites OAM sprite properties (such as CGB palette), see @ref metasprite_and_sprite_properties "Metasprites and sprite properties". + This function is only available on Game Boy and related clone consoles. + @return Number of hardware sprites used to draw this metasprite @see move_metasprite() */ inline uint8_t move_metasprite_hvflip(const metasprite_t * metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y) { - __current_metasprite = metasprite; + __current_metasprite = metasprite; __current_base_tile = base_tile; - return __move_metasprite_hvflip(base_sprite, x - 8, y - ((LCDC_REG & 0x04U) ? 16 : 8)); + return __move_metasprite_hvflip(base_sprite, x - 8, y - ((LCDC_REG & 0x04U) ? 16 : 8)); } /** Hides a metasprite from the screen - + @param metasprite Pointer to first struct of the desired metasprite frame @param base_sprite Number of hardware sprite to start with @@ -225,7 +238,7 @@ inline uint8_t move_metasprite_hvflip(const metasprite_t * metasprite, uint8_t b **/ inline void hide_metasprite(const metasprite_t * metasprite, uint8_t base_sprite) { - __current_metasprite = metasprite; + __current_metasprite = metasprite; __hide_metasprite(base_sprite); }
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.