StaticTilemapLayerCache
ClassSource: StaticTilemapLayerCache.h
Description
Centralized framebuffer snapshot for static 4bpp tilemap layers.
On drivers that expose a direct logical 8bpp sprite buffer (e.g. TFT_eSPI), this avoids redrawing “static” layers every frame when the sampled camera position is unchanged and the cache has not been invalidated.
Override points:
- Compile-time: set PIXELROOT32_ENABLE_STATIC_TILEMAP_FB_CACHE to 0 in build flags.
- Run-time: setFramebufferCacheEnabled(false) per scene or platform init.
- No sprite buffer or failed allocation: automatically falls back to full draw.
Allocate during scene init() via allocateForLogicalSize() or allocateForRenderer() so the game loop does not hit the heap (see ARCH_MEMORY_SYSTEM.md).
Projected layers
A layer whose TileMap4bppDrawSpec::projection is non-null is cached exactly like an axis-aligned one, because the cache stores framebuffer bytes: it never re-derives cell placement, so the basis a layer was drawn through is irrelevant to the snapshot and to its restore.
What that does NOT buy is a cheap scrolling isometric background. draw() rebuilds whenever the sampled camera moved (camMoved), so a layer drawn through a projection under a camera that scrolls every frame is redrawn every frame and the snapshot is pure overhead. The win is on frames where the camera is stationary or clamped — a paused or menu frame, a room whose map fits the screen, a camera pinned at a level edge. Isometric maps often scroll on both axes at once, which makes the stationary case rarer here than it is for a side-scroller; measure before enabling the cache on a projected layer.
Methods
void clear()
bool allocateForLogicalSize(int width, int height)
Description:
Pre-allocate the snapshot for a logical framebuffer of width * height bytes.
Returns: false if dimensions are invalid or allocation failed.
bool allocateForRenderer(const Renderer& renderer)
Description:
Same as allocateForLogicalSize(renderer.getLogicalWidth/Height()).
void invalidate()
void draw(Renderer& renderer, int cameraSampleX, int cameraSampleY, const TileMap4bppDrawSpec* staticLayers, std::size_t staticLayerCount, const TileMap4bppDrawSpec* dynamicLayers, std::size_t dynamicLayerCount)
Parameters:
cameraSampleX: TypicallycameraSampleY: Typically