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_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 name_base);

#define OBJ_NAME_BASE(vram_word_addr) (((vram_word_addr) >> 13) & 0x07)

void oamInitGfxSet(const u8 *tileSource, u16 tileSize, const 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);
 
/* Note: there is deliberately no oamSetVisible(id, show) — SNES sprite
 * visibility is Y-position-based, so a "show" call can't know which Y to
 * restore and could only be a silent no-op (which the removed v0.x
 * function was). Use oamHide() to hide and oamSetY()/oamSet() with a
 * valid Y to show. */

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);
 
/*============================================================================
 * 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, const 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 */