metasprites.h (4287B)
1/** @file sms/metasprites.h 2 3 # Metasprite support 4 5 A metasprite is a larger sprite made up from a 6 collection of smaller individual hardware sprites. 7 Different frames of the same metasprites can share 8 tile data. 9 10 The api supports metasprites in both 11 @ref SPRITES_8x8 and @ref SPRITES_8x16 mode. If 12 8x16 mode is used then the height of the metasprite 13 must be a multiple of 16. 14 15 The origin (pivot) for the metasprite is not required 16 to be in the upper left-hand corner as with regular 17 hardware sprites. 18 19 Use the @ref utility_png2asset tool to convert single 20 or multiple frames of graphics into metasprite 21 structured data for use with the ...metasprite...() 22 functions. 23 24 # Metasprites composed of variable numbers of sprites 25 26 When using png2asset, it's common for the output of 27 different frames to be composed of different numbers 28 of hardware sprites (since it's trying to create each 29 frame as efficiently as possible). Due to that, it's 30 good practice to clear out (hide) unused sprites in the 31 shadow_OAM that have been set by previous frames. 32*/ 33 34#ifndef _METASPRITES_H_INCLUDE 35#define _METASPRITES_H_INCLUDE 36 37#include <msx/hardware.h> 38#include <types.h> 39#include <stdint.h> 40 41/** Metasprite sub-item structure 42 @param dy (int8_t) Y coordinate of the sprite relative to the metasprite origin (pivot) 43 @param dx (int8_t) X coordinate of the sprite relative to the metasprite origin (pivot) 44 @param dtile (uint8_t) Start tile relative to the metasprites own set of tiles 45 @param props (uint8_t) Property Flags 46 47 Metasprites are built from multiple metasprite_t items (one for each sub-sprite) 48 and a pool of tiles they reference. If a metasprite has multiple frames then each 49 frame will be built from some number of metasprite_t items (which may vary based 50 on how many sprites are required for that particular frame). 51 52 A metasprite frame is terminated with a {metasprite_end} entry. 53*/ 54typedef struct metasprite_t { 55 int8_t dy, dx; 56 uint8_t dtile; 57 uint8_t props; 58} metasprite_t; 59 60#define metasprite_end -128 61#define METASPR_ITEM(dy,dx,dt,a) {(dy),(dx),(dt),(a)} 62#define METASPR_TERM {metasprite_end} 63 64extern const void * __current_metasprite; 65extern uint8_t __current_base_tile; 66extern uint8_t __render_shadow_OAM; 67 68 69static uint8_t __move_metasprite(uint8_t id, uint8_t x, uint8_t y) Z88DK_CALLEE PRESERVES_REGS(iyh, iyl); 70static void __hide_metasprite(uint8_t id) Z88DK_FASTCALL PRESERVES_REGS(iyh, iyl); 71 72/** 73 * Hides all hardware sprites in range from <= X < to 74 * @param from start OAM index 75 * @param to finish OAM index 76 */ 77void hide_sprites_range(UINT8 from, UINT8 to) Z88DK_CALLEE PRESERVES_REGS(iyh, iyl); 78 79/** Moves metasprite to the absolute position x and y 80 81 @param metasprite Pointer to the first struct of the metasprite (for the desired frame) 82 @param base_tile Number of the first tile where the metasprite's tiles start 83 @param base_sprite Number of the first hardware sprite to be used by the metasprite 84 @param x Absolute x coordinate of the sprite 85 @param y Absolute y coordinate of the sprite 86 87 Moves __metasprite__ to the absolute position __x__ and __y__ 88 (with __no flip__ on the X or Y axis). Hardware sprites are 89 allocated starting from __base_sprite__, using tiles 90 starting from __base_tile__. 91 92 Sets: 93 \li __current_metasprite = metasprite; 94 \li __current_base_tile = base_tile; 95 96 @return Number of hardware sprites used to draw this metasprite 97 */ 98inline uint8_t move_metasprite(const metasprite_t * metasprite, uint8_t base_tile, uint8_t base_sprite, uint8_t x, uint8_t y) { 99 __current_metasprite = metasprite; 100 __current_base_tile = base_tile; 101 return __move_metasprite(base_sprite, x, y); 102} 103 104/** Hides a metasprite from the screen 105 106 @param metasprite Pointer to first struct of the desired metasprite frame 107 @param base_sprite Number of hardware sprite to start with 108 109 Sets: 110 \li __current_metasprite = metasprite; 111 112 **/ 113inline void hide_metasprite(const metasprite_t * metasprite, uint8_t base_sprite) { 114 __current_metasprite = metasprite; 115 __hide_metasprite(base_sprite); 116} 117 118#endif