sprite.h

Go to the documentation of this file.

 
#ifndef OPENSNES_SPRITE_H
#define OPENSNES_SPRITE_H
 
#include <snes/types.h>
 
/*============================================================================
 * Constants
 *============================================================================*/
 
#define MAX_SPRITES 128
 
#define OBJ_SIZE8_L16   0   
#define OBJ_SIZE8_L32   1   
#define OBJ_SIZE8_L64   2   
#define OBJ_SIZE16_L32  3   
#define OBJ_SIZE16_L64  4   
#define OBJ_SIZE32_L64  5   
#define OBJ_SIZE_TO_REG(size) ((size) << 5)
 
#define OBJ_BASE(vram_addr) (((vram_addr) >> 13) & 0x07)
 
#define OBJSEL(size, vram_addr) ((u8)(OBJ_SIZE_TO_REG(size) | OBJ_BASE(vram_addr)))
 
#define OBJ_CGRAM_BASE  128
 
#define OBJ_CGRAM_PAL(n)  (OBJ_CGRAM_BASE + (n) * 16)
 
#define PALETTE_16_SIZE  32
 
#define OAM_Y_OFFSCREEN  0xE0
 
#define OAM_EXT_OFFSET  512
 
#define OAM_EXT_SIZE    32
 
#define OAM_BUFFER_SIZE 544
 
#define OBJ_HIDE_Y  240
 
#define OBJ_SHOW    1   
#define OBJ_HIDE    0   
#define OBJ_SMALL   0   
#define OBJ_LARGE   1   
/*============================================================================
 * Dynamic Sprite Engine Constants
 *============================================================================*/
 
#define OBJ_SPRITE32    1   
#define OBJ_SPRITE16    2   
#define OBJ_SPRITE8     4   
#define OBJ_QUEUELIST_SIZE  128
 
#define MAXSPRTRF   (7 * 6)
 
/*============================================================================
 * Sprite Lookup Tables (for dynamic sprite management)
 *============================================================================*/
 
extern u16 lkup16oamS[];
 
extern u16 lkup16idT[];
 
extern u16 lkup16idT0[];
 
extern u16 lkup16idB[];
 
extern u16 lkup32oamS[];
 
extern u16 lkup32idT[];
 
extern u16 lkup32idB[];
 
extern u16 lkup8oamS[];
 
extern u16 lkup8idT[];
 
extern u16 lkup8idB[];
 
/*============================================================================
 * Dynamic Sprite Structure
 *============================================================================*/
 
typedef struct {
    s16 oamx;           
    s16 oamy;           
    u16 oamframeid;     
    u8 oamattribute;    
    u8 oamrefresh;      
    u16 oamgfxaddr;     
    u8 oamgfxbank;      
    u8 _pad;            
    u16 _reserved1;     
    u16 _reserved2;     
} t_sprites;
 
/*============================================================================
 * Compile-time struct layout assertions
 * Must match the oambuffer layout in sprite_dynamic.asm exactly.
 *============================================================================*/
 
_Static_assert(sizeof(t_sprites) == 16, "t_sprites must be 16 bytes");
_Static_assert(__builtin_offsetof(t_sprites, oamx) == 0, "oamx offset mismatch");
_Static_assert(__builtin_offsetof(t_sprites, oamy) == 2, "oamy offset mismatch");
_Static_assert(__builtin_offsetof(t_sprites, oamframeid) == 4, "oamframeid offset mismatch");
_Static_assert(__builtin_offsetof(t_sprites, oamattribute) == 6, "oamattribute offset mismatch");
_Static_assert(__builtin_offsetof(t_sprites, oamrefresh) == 7, "oamrefresh offset mismatch");
_Static_assert(__builtin_offsetof(t_sprites, oamgfxaddr) == 8, "oamgfxaddr offset mismatch");
_Static_assert(__builtin_offsetof(t_sprites, oamgfxbank) == 10, "oamgfxbank offset mismatch");
 
#define OAM_SET_GFX(id, gfx) do { \
    oambuffer[id].oamgfxaddr = (u16)(gfx); \
    oambuffer[id].oamgfxbank = 0; \
} while(0)
 
#define OAM_SET_GFX_BANK(id, gfx, bank) do { \
    oambuffer[id].oamgfxaddr = (u16)(gfx); \
    oambuffer[id].oamgfxbank = (u8)(bank); \
} while(0)
 
/* --- Bank $00 SLOT 1 (C-accessible, < $2000) --- */
 
extern t_sprites oambuffer[128];
 
/*============================================================================
 * Initialization
 *============================================================================*/
 
#define OAM_DEFAULT_SIZE        OBJ_SIZE8_L16
#define OAM_DEFAULT_TILE_BASE   0
 
void oamInit(u16 size, u16 tile_base);
 
void oamInitGfxSet(u8 *tileSource, u16 tileSize, u8 *tilePalette,
                   u16 paletteSize, u8 paletteEntry, u16 vramAddr, u8 oamSize);
 
/*============================================================================
 * Sprite Properties
 *============================================================================*/
 
void oamSet(u16 id, u16 x, u16 y, u16 tile, u16 palette, u16 priority, u16 flags);
 
void oamSetX(u8 id, u16 x);
 
void oamSetY(u8 id, u8 y);
 
void oamSetXY(u8 id, u16 x, u8 y);
 
void oamSetTile(u8 id, u16 tile);
 
void oamSetVisible(u8 id, u8 visible);
 
void oamHide(u8 id);
 
void oamSetSize(u16 id, u16 large);
 
/*============================================================================
 * OAM Update
 *============================================================================*/
 
void oamUpdate(void);
 
void oamClear(void);
 
/*============================================================================
 * Metasprites
 *============================================================================*/
 
typedef struct {
    s16 dx;         
    s16 dy;         
    u16 tile;       
    u8 attr;        
    u8 reserved;    
} MetaspriteItem;
 
typedef MetaspriteItem t_metasprite;
 
#define METASPR_ITEM(dx, dy, tile, attr) { (dx), (dy), (tile), (attr), 0 }
 
#define METASPR_TERM { -128, 0, 0, 0, 0 }
 
#define metasprite_end (-128)
 
#define OBJ_PAL(pal)    ((pal) << 1)
 
#define OBJ_PRIO(prio)  ((prio) << 4)
 
#define OBJ_FLIPX       0x40
 
#define OBJ_FLIPY       0x80
 
#define OBJ_NAMETABLE_HIGH  0x01
 
u8 oamDrawMeta(u8 startId, s16 x, s16 y, const MetaspriteItem *meta,
               u16 baseTile, u8 basePalette, u8 size);
 
u8 oamDrawMetaFlip(u8 startId, s16 x, s16 y, const MetaspriteItem *meta,
                   u16 baseTile, u8 basePalette, u8 size,
                   u8 flipX, u8 flipY, u8 width, u8 height);
 
u8 oamDrawMetasprite(u8 startId, u16 x, u8 y, const u8 *data, u8 palette);
 
/*============================================================================
 * Dynamic Sprite Engine
 *============================================================================*/
 
typedef struct {
    u16 vramLarge;      
    u16 vramSmall;      
    u16 slotLargeInit;  
    u16 slotSmallInit;  
    u8  sizeMode;       
} OamDynamicConfig;
 
void oamDynamicInit(const OamDynamicConfig *cfg);
 
void oamDynamicSetSize(u16 id, u8 size);
 
void oamDynamicDraw(u16 id);
 
void oamDynamicDrainQueue(void);
 
/*============================================================================
 * Dynamic Metasprite Engine
 *============================================================================*/
 
void oamMetaDrawDyn(u16 id, s16 x, s16 y,
                    const MetaspriteItem *meta, u8 *gfxptr, u8 size_class);
 
/*============================================================================
 * Fast Macro Sprite API
 *
 * Zero-overhead alternatives to oamSet/oamSetXY for performance-critical code.
 * These write directly to oamMemory[] without function call overhead.
 *
 * oamSet() has framesize=158 per call due to SSA temporaries. With >2-3
 * sprites/frame in the main loop, the stack manipulation causes visible
 * jitter. These macros eliminate that overhead entirely.
 *
 * Note: cc65816 does not truly inline 'static inline' functions — they
 * become separate SUPERFREE sections with global labels that conflict
 * across translation units. Macros are the only zero-overhead option.
 *
 * oamMemory[] and oam_update_flag are declared in <snes/system.h>
 * (included automatically via <snes.h>).
 *
 * Usage:
 *   // Pre-compute attribute byte once at init
 *   u8 attr = OAM_ATTR(tile, palette, priority, flags);
 *
 *   // Per-frame: fast full update
 *   oamSetFast(id, x, y, tile, palette, priority, flags);
 *
 *   // Per-frame: position-only update (most common)
 *   oamSetXYFast(id, x, y);
 *============================================================================*/
 
#define OAM_ATTR(_tile, _pal, _prio, _fl) \
    ((u8)(((_fl) & 0xC0) | \
          (((_prio) & 0x03) << 4) | \
          (((_pal) & 0x07) << 1) | \
          (((_tile) >> 8) & 0x01)))
 
#define OAM_XHI_MASK(_slot) \
    ((u8)((_slot) == 0 ? 0x01 : (_slot) == 1 ? 0x04 : \
          (_slot) == 2 ? 0x10 : 0x40))
 
#define oamSetFast(_id, _x, _y, _tile, _pal, _prio, _fl) do { \
    u16 _off = (u16)(_id) << 2; \
    oamMemory[_off + 0] = (u8)((_x) & 0xFF); \
    oamMemory[_off + 1] = (u8)(((_y) - 1) & 0xFF); /* compensate +1 PPU scanline quirk */ \
    oamMemory[_off + 2] = (u8)((_tile) & 0xFF); \
    oamMemory[_off + 3] = OAM_ATTR(_tile, _pal, _prio, _fl); \
    u16 _ext = 512 + ((u16)(_id) >> 2); \
    u16 _sl = (u16)(_id) & 0x03; \
    u8 _xhi = OAM_XHI_MASK(_sl); \
    if ((_x) & 0x100) \
        oamMemory[_ext] |= _xhi; \
    else \
        oamMemory[_ext] &= ~_xhi; \
    oam_update_flag = 1; \
} while(0)
 
#define oamSetXYFast(_id, _x, _y) do { \
    u16 _off = (u16)(_id) << 2; \
    oamMemory[_off + 0] = (u8)((_x) & 0xFF); \
    oamMemory[_off + 1] = (u8)(((_y) - 1) & 0xFF); /* compensate +1 PPU scanline quirk */ \
    u16 _ext = 512 + ((u16)(_id) >> 2); \
    u16 _sl = (u16)(_id) & 0x03; \
    u8 _xhi = OAM_XHI_MASK(_sl); \
    if ((_x) & 0x100) \
        oamMemory[_ext] |= _xhi; \
    else \
        oamMemory[_ext] &= ~_xhi; \
    oam_update_flag = 1; \
} while(0)
 
#endif /* OPENSNES_SPRITE_H */