gbdk-2020 | GameBoy Development Kit |
| download: https://git.y1.nz/archives/gbdk.tar.gz | |
| README | Files | Log | Refs | LICENSE |
commit 76c607a52fa44b78ae36620daef26538eb195f12 parent bc48e3e5696ce4de39164b9624d5d943ad779e89 Author: Toxa <56631470+untoxa@users.noreply.github.com> Date: Tue, 23 Mar 2021 12:40:55 +0300 Merge pull request #158 from bbbbbr/docs_metasprites Docs: metasprite Diffstat:
| M | docs/pages/10_release_notes.md | 11 | ++++++++--- |
| M | gbdk-lib/include/gb/metasprites.h | 133 | ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------- |
2 files changed, 123 insertions(+), 21 deletions(-)
diff --git a/docs/pages/10_release_notes.md b/docs/pages/10_release_notes.md @@ -22,12 +22,17 @@ https://github.com/Zal0/gbdk-2020/releases - Added large_map: showing how to use @ref set_bkg_submap() - Added scroller: showing use of @ref get_bkg_xy_addr(), @ref set_bkg_tile_xy() and @ref set_vram_byte - Added gbdecompress: de-compressing tile data into vram + - Added metasprites: show creating a large sprite with the new metasprite api - Added template projects - Fixed build issue with banks_autobank example - Improved sgb_border - - Added GBCompress utility - - Added png2metaspr utility and metasprites example - + - Toolchain / Utilities + - Added @ref gbcompress utility + - Added @ref png2metaspr metasprite utility + - Docs + - Added extensive documentation (some of which is imported and updated from the old gbdk docs) + - Added PDF version of docs + ## GBDK 2020 4.0.2 2021/01/17 diff --git a/gbdk-lib/include/gb/metasprites.h b/gbdk-lib/include/gb/metasprites.h @@ -1,14 +1,41 @@ /** @file gb/metasprites.h Metasprite support + + 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 + @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. + + The origin (pivot) for the metasprite is not required + to be in the upper left-hand corner as with regular + hardware sprites. + + Use the @ref png2mtspr utility to convert single + or multiple frames of graphics into metasprite + structured data for use with the ...metasprite...() + functions. */ #ifndef _METASPRITES_H_INCLUDE #define _METASPRITES_H_INCLUDE -/** - * metasprite item description - */ +/** Metasprite sub-item structure + @param dy (INT8) Y coordinate of the sprite relative to the metasprite origin (pivot) + @param dx (INT8) X coordinate of the sprite relative to the metasprite origin (pivot) + @param dtile (UINT8) Start tile relative to the metasprites own set of tiles + @param props (UINT8) Property Flags + + Metasprites are built from multiple metasprite_t items (one for each sub-sprite) + and a pool of tiles they reference. If a metasprite has multiple frames then each + frame will be built from some number of metasprite_t items (which may vary based + on how many sprites are required for that particular frame). +*/ typedef struct metasprite_t { INT8 dy, dx; UINT8 dtile; @@ -21,53 +48,124 @@ extern const void * __current_metasprite; extern UBYTE __current_base_tile; extern UBYTE __render_shadow_OAM; + static UBYTE __move_metasprite(UINT8 id, UINT8 x, UINT8 y); static UBYTE __move_metasprite_vflip(UINT8 id, UINT8 x, UINT8 y); static UBYTE __move_metasprite_hflip(UINT8 id, UINT8 x, UINT8 y); static UBYTE __move_metasprite_hvflip(UINT8 id, UINT8 x, UINT8 y); static void __hide_metasprite(UINT8 id); -/** - * Moves metasprite to the absolute position x and y, allocating hardware sprites from base_sprite using tiles from base_tile - * @param metasprite metasprite description - * @param base_tile start tile where tiles for that metasprite begin - * @param base_sprite start hardware sprite - * @param x absolute x coordinate of the sprite - * @param y absolute y coordinate of the sprite - * @return number of hardware sprites used to draw this metasprite - **/ + +/** 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 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 + starting from __base_tile__. + + Sets: + \li __current_metasprite = metasprite; + \li __current_base_tile = base_tile; + + @return Number of hardware sprites used to draw this metasprite + */ inline UBYTE move_metasprite(const metasprite_t * metasprite, UINT8 base_tile, UINT8 base_sprite, UINT8 x, UINT8 y) { __current_metasprite = metasprite; __current_base_tile = base_tile; 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 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_base_tile = base_tile; + + @return Number of hardware sprites used to draw this metasprite + + @see move_metasprite() +*/ inline UBYTE move_metasprite_vflip(const metasprite_t * metasprite, UINT8 base_tile, UINT8 base_sprite, UINT8 x, UINT8 y) { __current_metasprite = metasprite; __current_base_tile = base_tile; return __move_metasprite_vflip(base_sprite, x - 8, y); } + +/** Moves metasprite to the absolute position x and y, __flipped on the X 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 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_base_tile = base_tile; + + @return Number of hardware sprites used to draw this metasprite + + @see move_metasprite() +*/ inline UBYTE move_metasprite_hflip(const metasprite_t * metasprite, UINT8 base_tile, UINT8 base_sprite, UINT8 x, UINT8 y) { __current_metasprite = metasprite; __current_base_tile = base_tile; 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 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_base_tile = base_tile; + + @return Number of hardware sprites used to draw this metasprite + + @see move_metasprite() +*/ inline UBYTE move_metasprite_hvflip(const metasprite_t * metasprite, UINT8 base_tile, UINT8 base_sprite, UINT8 x, UINT8 y) { __current_metasprite = metasprite; __current_base_tile = base_tile; return __move_metasprite_hvflip(base_sprite, x - 8, y - ((LCDC_REG & 0x04U) ? 16 : 8)); } -/** - * Hides metasprite from screen - * @param metasprite metasprite description - * @param base_sprite start hardware sprite +/** 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 + + Sets: + \li __current_metasprite = metasprite; + **/ inline void hide_metasprite(const metasprite_t * metasprite, UINT8 base_sprite) { __current_metasprite = metasprite; __hide_metasprite(base_sprite); } -#endif - +#endif
This webpage is intended to be an accessible preview of this repository. To get a fuller picture, clone it and use the git CLI.