joeylib2/include/joey/sprite.h

// Sprites: rectangles of 8x8 tiles drawn at arbitrary pixel positions
// with color-0 transparency.
//
// A sprite's pixel data is `widthTiles * heightTiles * 32` bytes,
// 4bpp packed, laid out as a flat blob of 8x8 tiles. Tile order is
// row-major (tile (0,0), tile (1,0), ..., tile (widthTiles-1,0),
// tile (0,1), ...). Within each tile, rows are top-to-bottom and
// each row is 4 bytes (8 pixels at 4bpp packed; high nibble = left
// pixel).
//
// Color 0 is always transparent on draw (DESIGN.md contract). Use a
// tile-block draw if you need an opaque rectangle.
//
// Performance contract: jlSpriteDraw should be at least as fast as the
// IIgs reference (the DESIGN.md spec calls for runtime-compiled draw
// code per CPU). v1 ships with an interpreted fallback that gives
// correct output everywhere; codegen lands per platform after the
// API stabilizes. jlSpritePrewarm is a hint that the application is
// about to draw the sprite repeatedly -- a future codegen-enabled
// build will use it to compile shift variants ahead of the first
// draw. With the interpreter it is a no-op.

#ifndef JOEYLIB_SPRITE_H
#define JOEYLIB_SPRITE_H

#include "platform.h"
#include "surface.h"
#include "types.h"

// Sprite codegen emits per-shift variants. Chunky 4bpp ports (DOS,
// IIgs, Atari ST) only need 2 shifts -- pixel offset 0 (sprite/dest
// byte boundaries align) and offset 1 (every dest byte combines two
// sprite bytes' nibbles). Planar ports (Amiga -- 8 px per plane byte)
// need 8 shifts: one for each x % 8 alignment, so smooth horizontal
// motion at any pixel position uses pre-shifted source bytes without
// runtime bit-shifting. Allocate the max so routineOffsets[] has
// slots for every variant; chunky ports leave shifts 2..7 as
// SPRITE_NOT_COMPILED, planar ports use all 8.
#define JOEY_SPRITE_SHIFT_COUNT 8

typedef struct jlSpriteT jlSpriteT;

// jlSpriteBackupT holds the destination bytes that lived under a sprite
// before it was drawn, so the application can restore them after the
// sprite moves. Sized for the largest backup the app will need; a
// stack-allocated jlSpriteBackupT plus a caller-owned byte buffer keeps
// the runtime allocation-free.
typedef struct {
    jlSpriteT       *sprite;
    int16_t        x;
    int16_t        y;
    uint16_t       width;       // pixels
    uint16_t       height;      // pixels
    uint8_t       *bytes;       // caller-owned, capacity >= sizeBytes
    uint16_t       sizeBytes;
} jlSpriteBackupT;

// Load up to maxCels cels from a baked .spr file produced by
// tools/assetbake/assetbake.py. Each cel becomes a freshly-allocated
// jlSpriteT (release with jlSpriteDestroy); the file's cellCount is
// capped at maxCels.
//
// If outPalette is non-NULL and the file embeds a 16-entry $0RGB
// LE16 palette, it is copied in; otherwise outPalette is unchanged.
//
// Returns the number of cels actually written into outCels[]. Returns
// 0 if the file is missing, the magic / target byte is wrong, or no
// cel could be allocated.
uint16_t jlSpriteBankLoad(const char *path, jlSpriteT **outCels,
                          uint16_t maxCels, uint16_t *outPalette);

// Wrap a tile-data blob in a jlSpriteT. The tile data must outlive the
// jlSpriteT; we do not copy it. Returns NULL if widthTiles or
// heightTiles is 0, or if the codegen arena cannot fit a placeholder
// entry for this sprite.
jlSpriteT *jlSpriteCreate(const uint8_t *tileData, uint8_t widthTiles, uint8_t heightTiles);

// Release a jlSpriteT and any codegen entries cached for it. The tile
// data the sprite was constructed from is NOT freed -- the caller
// owns that buffer.
void jlSpriteDestroy(jlSpriteT *sp);

// Compile the sprite's draw routines into the codegen arena. After
// this returns true, jlSpriteDraw uses the compiled fast path on
// platforms where the emitter is wired (currently x86/DOS). Returns
// false if the arena is full (caller may run jlSpriteCompact and
// retry), the platform doesn't have a real emitter yet, or the
// sprite has no source tile data.
//
// Idempotent: calling on a sprite that's already compiled is a
// no-op and returns true.
bool jlSpriteCompile(jlSpriteT *sp);

// Returns the number of bytes this sprite occupies in the codegen
// arena (sum of all compiled draw/save/restore shift variants).
// Returns 0 if the sprite has never been compiled or has no slot.
// Diagnostic only -- useful for tuning jlConfigT.codegenBytes against
// the actual per-cel cost of the current platform's emitter.
uint32_t jlSpriteCompiledSize(const jlSpriteT *sp);

// Hint that this sprite will be drawn soon. Currently a wrapper
// around jlSpriteCompile that ignores the return value, kept for API
// symmetry with the rest of the library and for callers that don't
// care about compile success.
void jlSpritePrewarm(jlSpriteT *sp);

// Draw the sprite at pixel (x,y) on the destination surface. Pixels
// equal to color 0 in the sprite source are skipped (transparent).
// Off-surface portions are clipped.
void jlSpriteDraw(jlSurfaceT *s, jlSpriteT *sp, int16_t x, int16_t y);

// Capture the destination region a subsequent jlSpriteDraw at the same
// (x,y) would write to. backup->bytes must have at least
// (widthTiles*4) * (heightTiles*8) bytes of capacity for fully
// in-bounds draws; for clipped draws only the visible bytes are
// stored. The captured region's exact size is reported in
// backup->sizeBytes.
void jlSpriteSaveUnder(const jlSurfaceT *s, jlSpriteT *sp, int16_t x, int16_t y, jlSpriteBackupT *backup);

// Repaint the destination region from a jlSpriteBackupT captured by a
// prior jlSpriteSaveUnder. The backup must not have been invalidated
// by other writes that overlapped its captured region.
void jlSpriteRestoreUnder(jlSurfaceT *s, const jlSpriteBackupT *backup);

// Combined save-then-draw entry point. The common animation pattern
// captures the destination bytes about to be overwritten, then draws
// the sprite. Both ops share validation, the destination ptr is
// computed once, and a single dirty-rect mark covers both. Saves
// roughly one full dispatcher chain (~150 cyc on IIgs ORCA-C) per
// frame versus calling jlSpriteSaveUnder + jlSpriteDraw separately.
//
// Identical semantics to:
//     jlSpriteSaveUnder(s, sp, x, y, backup);
//     jlSpriteDraw(s, sp, x, y);
// modulo: the dirty rect is marked once for the union (which here is
// just the draw rect, since save doesn't write).
void jlSpriteSaveAndDraw(jlSurfaceT *s, jlSpriteT *sp, int16_t x, int16_t y, jlSpriteBackupT *backup);

// Snapshot an 8x8-aligned region of a jlSurfaceT into a new jlSpriteT.
// The captured pixel data is copied into a sprite-owned buffer so
// the source surface can be modified afterwards. Width and height
// are in TILES (each tile = 8x8 pixels). x and y are in pixels and
// must be aligned to a tile boundary (multiple of 8) on the source
// surface; misaligned coordinates return NULL.
jlSpriteT *jlSpriteCreateFromSurface(const jlSurfaceT *src, int16_t x, int16_t y,
                                 uint8_t widthTiles, uint8_t heightTiles);

// Defragment the codegen arena. Walks live sprite slots and
// memmoves them down to consolidate free space; any holes left by
// destroyed sprites are reclaimed. Costs O(arena_used_bytes); call
// between levels rather than per frame. jlSpriteT pointers held by
// the application are NOT invalidated -- internal indirection
// through the slot record means draw calls automatically pick up
// the new code address on the next call.
void jlSpriteCompact(void);

// Arena introspection. Used to gauge whether jlSpriteCompact is
// worth running, or whether the codegenBytes budget needs to grow.
// Free space is (Total - Used), but it may be fragmented across
// holes until jlSpriteCompact runs.
uint32_t jlSpriteCodegenBytesUsed(void);
uint32_t jlSpriteCodegenBytesTotal(void);

#endif