sprite.h

Go to the documentation of this file.

 
#ifndef OPENSNES_SPRITE_H
#define OPENSNES_SPRITE_H
 
#include <snes/types.h>
 
/* Removed on 2026-10-05 (1.0 plan, lot C): oamDrawMeta, oamDrawMetaFlip.
 * The replacements are in docs/UPGRADING.md; `make check-upgrade` names them. */
 
/*============================================================================
 * 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)
 
/*============================================================================
 * 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)(u32)(const void *)(gfx); \
    oambuffer[id].oamgfxbank = (u8)((u32)(const void *)(gfx) >> 16); \
} while(0)
 
/* OAM_SET_GFX_BANK(id, gfx, bank) was removed on 2026-10-05: OAM_SET_GFX() reads
 * the bank from its pointer (docs/UPGRADING.md). */
 
/* --- 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
 *============================================================================*/
 
/* Sprite ids are u16 in every function below. The setters other than oamSet()
 * took a u8 until 2026-09-21: an id of 256 was truncated to 0 BEFORE the
 * `id >= 128` check could refuse it, and silently overwrote sprite 0. Same
 * stack slot either way — no ABI change, and a u8 variable still converts. */

void oamSet(u16 id, u16 x, u16 y, u16 tile, u16 palette, u16 priority, u16 flags);

void oamSetX(u16 id, u16 x);

void oamSetY(u16 id, u16 y);

void oamSetXY(u16 id, u16 x, u16 y);

u16 oamGetX(u16 id);

u8 oamGetY(u16 id);

typedef struct {
    const s16 *x;        
    const s16 *y;        
    const u8  *tile;     
    const u8  *attr;     
    u8  *visible;        
    u8   first_id;       
    u8   count;          
    u8   size;           
    const u8 *order;     
} OamWorldBatch;
 
/* Not under the host's syntax check (clang, 8-byte pointers): the layout
 * that matters is cc65816's, 4 bytes a pointer. */
#ifndef __clang__
_Static_assert(__builtin_offsetof(OamWorldBatch, y) == 4, "OamWorldBatch.y offset (sprite_world.asm)");
_Static_assert(__builtin_offsetof(OamWorldBatch, tile) == 8, "OamWorldBatch.tile offset (sprite_world.asm)");
_Static_assert(__builtin_offsetof(OamWorldBatch, attr) == 12, "OamWorldBatch.attr offset (sprite_world.asm)");
_Static_assert(__builtin_offsetof(OamWorldBatch, visible) == 16, "OamWorldBatch.visible offset (sprite_world.asm)");
_Static_assert(__builtin_offsetof(OamWorldBatch, first_id) == 20, "OamWorldBatch.first_id offset (sprite_world.asm)");
_Static_assert(__builtin_offsetof(OamWorldBatch, count) == 21, "OamWorldBatch.count offset (sprite_world.asm)");
_Static_assert(__builtin_offsetof(OamWorldBatch, size) == 22, "OamWorldBatch.size offset (sprite_world.asm)");
_Static_assert(__builtin_offsetof(OamWorldBatch, order) == 24, "OamWorldBatch.order offset (sprite_world.asm)");
#endif

void oamPlaceWorld(const OamWorldBatch *batch, u16 cam_x, u16 cam_y);

void oamSetTile(u16 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(u16 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

typedef struct {
    u16 baseTile;     
    u8  basePalette;  
    u8  size;         
    u8  pieceSize;    
    u8  width;        
    u8  height;       
} MetaspriteStyle;

u16 oamDrawMetasprite(u16 startId, s16 x, s16 y, const MetaspriteItem *frame,
                      const MetaspriteStyle *style, u8 flip);
 
/*============================================================================
 * 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() is a call with seven arguments pushed and a stack frame; for a
 * handful of sprites updated every frame the macros below write the four
 * OAM bytes in place. (A byte count of an earlier oamSet's frame and a
 * "visible jitter" claim stood here until 2026-10-04; the cost is in
 * docs/PERF.md, measured, not here.)
 *
 * 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) & 0xFF); \
    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) & 0xFF); \
    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 */