Minor cleanup.

README.md

@@ -97,8 +97,12 @@ uint16_t    joeyFrameHz      (void);     // 50 / 60 / 70 depending on port
 
 ### Surfaces (`joey/surface.h`)
 
-All surfaces are 320x200 4bpp packed (high nibble = left pixel) with
+All surfaces are 320x200 16-color images with a 200-entry SCB table
-a 200-entry SCB table and 16 palettes of 16 `$0RGB` colors.
+and 16 palettes of 16 `$0RGB` colors. In-memory storage is
+target-native: chunky 4bpp packed on IIgs and DOS, native planar
+(separate bitplanes on Amiga, word-interleaved planes on Atari ST)
+on the 68k ports. The public API speaks in color indices (0..15) and
+hides the storage format.
 
 ```c
 #define SURFACE_WIDTH               320
@@ -211,7 +215,6 @@ bytes, tile-major 4bpp packed. Sprites can be runtime-compiled
 into per-shift code variants for fast draws.
 
 ```c
-typedef enum { SPRITE_FLAGS_NONE = 0 } SpriteFlagsE;
 typedef struct SpriteT SpriteT;            // opaque
 
 typedef struct {
@@ -223,14 +226,11 @@ typedef struct {
 } SpriteBackupT;
 
 SpriteT *spriteCreate            (const uint8_t *tileData,
-                                  uint8_t widthTiles, uint8_t heightTiles,
+                                  uint8_t widthTiles, uint8_t heightTiles);
-                                  SpriteFlagsE flags);
 SpriteT *spriteCreateFromSurface (const SurfaceT *src, int16_t x, int16_t y,
-                                  uint8_t widthTiles, uint8_t heightTiles,
+                                  uint8_t widthTiles, uint8_t heightTiles);
-                                  SpriteFlagsE flags);
+SpriteT *spriteLoadFile          (const char *path);
-SpriteT *spriteLoadFile          (const char *path, SpriteFlagsE flags);
+SpriteT *spriteFromCompiledMem   (const uint8_t *data, uint32_t length);
-SpriteT *spriteFromCompiledMem   (const uint8_t *data, uint32_t length,
-                                  SpriteFlagsE flags);
 bool     spriteSaveFile          (SpriteT *sp, const char *path);
 void     spriteDestroy           (SpriteT *sp);
 

examples/sprite/sprite.c

@@ -125,7 +125,7 @@ int main(void) {
     }
 
     repackBallTiles();
-    ball = spriteCreate(gBallTiles, BALL_TILES_X, BALL_TILES_Y, SPRITE_FLAGS_NONE);
+    ball = spriteCreate(gBallTiles, BALL_TILES_X, BALL_TILES_Y);
     if (ball == NULL) {
         fprintf(stderr, "spriteCreate failed\n");
         joeyShutdown();

examples/uber/uber.c

@@ -338,7 +338,7 @@ int main(void) {
     stagePresent();
 
     buildBallSprite();
-    gSprite = spriteCreate(gBallTiles, BALL_TILES_X, BALL_TILES_Y, SPRITE_FLAGS_NONE);
+    gSprite = spriteCreate(gBallTiles, BALL_TILES_X, BALL_TILES_Y);
     if (gSprite == NULL) {
         joeyLog("UBER: spriteCreate failed");
         joeyShutdown();

include/joey/asset.h

@@ -1,9 +1,10 @@
 // Sprite-style asset loading.
 //
-// A JoeyLib asset is a small bitmap with the same 4bpp packed pixel
+// A JoeyLib asset is a small bitmap in 4bpp packed (chunky) form,
-// format as the rest of the library, plus an optional 16-entry $0RGB
+// plus an optional 16-entry $0RGB palette. The packed format is
-// palette. Assets blit onto SurfaceT via surfaceBlit / surfaceBlitMasked
+// universal across ports -- assets are interchangeable between
-// (defined in draw.h).
+// platforms. surfaceBlit / surfaceBlitMasked (defined in draw.h)
+// converts to the destination surface's native storage at blit time.
 //
 // Two production paths:
 //

include/joey/sprite.h

@@ -38,10 +38,6 @@
 // SPRITE_NOT_COMPILED, planar ports use all 8.
 #define JOEY_SPRITE_SHIFT_COUNT 8
 
-typedef enum {
-    SPRITE_FLAGS_NONE = 0
-} SpriteFlagsE;
-
 typedef struct SpriteT SpriteT;
 
 // SpriteBackupT holds the destination bytes that lived under a sprite
@@ -63,7 +59,7 @@ typedef struct {
 // SpriteT; 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.
-SpriteT *spriteCreate(const uint8_t *tileData, uint8_t widthTiles, uint8_t heightTiles, SpriteFlagsE flags);
+SpriteT *spriteCreate(const uint8_t *tileData, uint8_t widthTiles, uint8_t heightTiles);
 
 // Release a SpriteT and any codegen entries cached for it. The tile
 // data the sprite was constructed from is NOT freed -- the caller
@@ -127,7 +123,7 @@ void spriteSaveAndDraw(SurfaceT *s, SpriteT *sp, int16_t x, int16_t y, SpriteBac
 // must be aligned to a tile boundary (multiple of 8) on the source
 // surface; misaligned coordinates return NULL.
 SpriteT *spriteCreateFromSurface(const SurfaceT *src, int16_t x, int16_t y,
-                                 uint8_t widthTiles, uint8_t heightTiles, SpriteFlagsE flags);
+                                 uint8_t widthTiles, uint8_t heightTiles);
 
 // Load a sprite from a `.spr` file produced by the host-side
 // joeysprite tool or by spriteSaveFile. Format is target-native for
@@ -143,10 +139,10 @@ SpriteT *spriteCreateFromSurface(const SurfaceT *src, int16_t x, int16_t y,
 // The runtime keeps both the compiled bytes (fast-path draws) and
 // the tile data (interpreter clip path), so loaded sprites work for
 // partially-off-surface draws without crashing.
-SpriteT *spriteLoadFile(const char *path, SpriteFlagsE flags);
+SpriteT *spriteLoadFile(const char *path);
 
 // Same as spriteLoadFile but parses bytes already in memory.
-SpriteT *spriteFromCompiledMem(const uint8_t *data, uint32_t length, SpriteFlagsE flags);
+SpriteT *spriteFromCompiledMem(const uint8_t *data, uint32_t length);
 
 // Persist a sprite to disk in `.spr` format. Sprites created via
 // spriteCreate / spriteCreateFromSurface that have not been

include/joey/surface.h

@@ -1,9 +1,14 @@
 // Surface type and allocation.
 //
-// All surfaces are 320x200 pixels, 4 bits per pixel packed (two pixels
+// All surfaces are 320x200 16-color images. In-memory storage is
-// per byte, high nibble is the left pixel). Each surface carries its
+// target-native: chunky 4bpp packed (two pixels per byte, high nibble
-// own 200-entry SCB (scanline control byte) table and a 16-by-16 $0RGB
+// is the left pixel) on IIgs and DOS; native planar (4 separate
-// palette set. See docs/DESIGN.md section 6.
+// bitplanes on Amiga, word-interleaved planes on Atari ST) on the
+// 68k ports. Public API entry points speak in color indices (0..15)
+// regardless, so game code does not see the storage format.
+//
+// Each surface carries its own 200-entry SCB (scanline control byte)
+// table and a 16-by-16 $0RGB palette set. See docs/DESIGN.md section 6.
 
 #ifndef JOEYLIB_SURFACE_H
 #define JOEYLIB_SURFACE_H

src/core/sprite.c

@@ -185,7 +185,7 @@ static void spriteDrawInterpreted(SurfaceT *s, SpriteT *sp, int16_t x, int16_t y
 
 // ----- Public API (alphabetical) -----
 
-SpriteT *spriteCreate(const uint8_t *tileData, uint8_t widthTiles, uint8_t heightTiles, SpriteFlagsE flags) {
+SpriteT *spriteCreate(const uint8_t *tileData, uint8_t widthTiles, uint8_t heightTiles) {
     SpriteT *sp;
 
     if (tileData == NULL || widthTiles == 0 || heightTiles == 0) {
@@ -204,13 +204,12 @@ SpriteT *spriteCreate(const uint8_t *tileData, uint8_t widthTiles, uint8_t heigh
     memset(sp->cachedDstBank, 0xFF, sizeof(sp->cachedDstBank));
     memset(sp->cachedSrcBank, 0xFF, sizeof(sp->cachedSrcBank));
     memset(sp->cachedSizeBytes, 0, sizeof(sp->cachedSizeBytes));
-    sp->flags        = flags;
     return sp;
 }
 
 
 SpriteT *spriteCreateFromSurface(const SurfaceT *src, int16_t x, int16_t y,
-                                 uint8_t widthTiles, uint8_t heightTiles, SpriteFlagsE flags) {
+                                 uint8_t widthTiles, uint8_t heightTiles) {
     SpriteT       *sp;
     uint8_t       *buf;
     uint16_t       tx;
@@ -281,7 +280,6 @@ SpriteT *spriteCreateFromSurface(const SurfaceT *src, int16_t x, int16_t y,
     memset(sp->cachedDstBank, 0xFF, sizeof(sp->cachedDstBank));
     memset(sp->cachedSrcBank, 0xFF, sizeof(sp->cachedSrcBank));
     memset(sp->cachedSizeBytes, 0, sizeof(sp->cachedSizeBytes));
-    sp->flags        = flags;
     return sp;
 }
 
@@ -417,7 +415,7 @@ void spriteSaveAndDraw(SurfaceT *s, SpriteT *sp, int16_t x, int16_t y, SpriteBac
 #define SPR_OFFSETS_SIZE  (JOEY_SPRITE_SHIFT_COUNT * SPRITE_OP_COUNT * (uint32_t)sizeof(uint16_t))
 
 
-SpriteT *spriteFromCompiledMem(const uint8_t *data, uint32_t length, SpriteFlagsE flags) {
+SpriteT *spriteFromCompiledMem(const uint8_t *data, uint32_t length) {
     SpriteT       *sp;
     ArenaSlotT    *slot;
     uint8_t        widthTiles;
@@ -488,7 +486,6 @@ SpriteT *spriteFromCompiledMem(const uint8_t *data, uint32_t length, SpriteFlags
     sp->heightTiles  = heightTiles;
     sp->ownsTileData = true;
     sp->slot         = slot;
-    sp->flags        = flags;
     memset(sp->cachedDstBank, 0xFF, sizeof(sp->cachedDstBank));
     memset(sp->cachedSrcBank, 0xFF, sizeof(sp->cachedSrcBank));
     memset(sp->cachedSizeBytes, 0, sizeof(sp->cachedSizeBytes));
@@ -496,7 +493,7 @@ SpriteT *spriteFromCompiledMem(const uint8_t *data, uint32_t length, SpriteFlags
 }
 
 
-SpriteT *spriteLoadFile(const char *path, SpriteFlagsE flags) {
+SpriteT *spriteLoadFile(const char *path) {
     FILE     *fp;
     long      fileSize;
     uint8_t  *buf;
@@ -534,7 +531,7 @@ SpriteT *spriteLoadFile(const char *path, SpriteFlagsE flags) {
         free(buf);
         return NULL;
     }
-    sp = spriteFromCompiledMem(buf, (uint32_t)fileSize, flags);
+    sp = spriteFromCompiledMem(buf, (uint32_t)fileSize);
     free(buf);
     return sp;
 }

src/core/spriteInternal.h

@@ -50,8 +50,6 @@ struct SpriteT {
     ArenaSlotT    *slot;
     uint16_t       routineOffsets[JOEY_SPRITE_SHIFT_COUNT][SPRITE_OP_COUNT];
 
-    SpriteFlagsE   flags;
-
     // Per-shift, per-op MVN bank-patch cache for IIgs save/restore.
     // patchMvnBanks rewrites 16+ MVN bank operands every call, but the
     // banks themselves rarely change frame-to-frame (screen surface

tools/joeysprite/joeysprite.c

@@ -698,7 +698,6 @@ int main(int argc, char **argv) {
     sp.ownsTileData = false;
     sp.slot         = NULL;
     memset(sp.routineOffsets, 0, sizeof(sp.routineOffsets));
-    sp.flags        = SPRITE_FLAGS_NONE;
 
     rc = compileToSpr(&sp, target, outPath);
     free(tileBytes);