Fixed-slot store for multi-frame 1-bpp sprites with host-driven playback. Pixel data lives in an injected arena (PSRAM, owner-held). More...

#include <CanvasAnim.h>

Classes
struct	FrameView
	Replay accessors: geometry, flags and pixel pointers of a sprite. More...

Public Member Functions
void	setArena (uint8_t *buf, uint32_t cap)
	Inject the pixel arena. Must happen before create(); resets the store.
bool	hasArena () const
int32_t	create (uint16_t w, uint16_t h, uint16_t frameCount, const uint8_t *data, uint32_t len)
	Copy a frame sheet into the arena and allocate a sprite slot.
bool	setMask (uint32_t handle, const uint8_t *mask, uint32_t len)
	Attach a mask plane (same sheet layout/size as the frame data).
bool	setFrameDurations (uint32_t handle, const uint16_t *ms, uint16_t count)
bool	destroy (uint32_t handle)
bool	setFlags (uint32_t handle, uint8_t flags)
bool	setScale (uint32_t handle, uint8_t scale)
	Integer upscale factor 1..4 applied when the sprite is drawn.
bool	setFrame (uint32_t handle, uint16_t frame)
int32_t	frame (uint32_t handle) const
	Current frame or -1.
bool	scroll (uint32_t handle, uint16_t windowW, uint16_t stepPx, uint16_t gapPx, uint16_t frameMs, uint32_t nowMs)
	Turn the sprite into a horizontal scroller (marquee backing).
bool	play (uint32_t handle, uint8_t mode, uint16_t frameMs, uint16_t repeat, uint32_t doneActionId, uint32_t nowMs)
bool	stop (uint32_t handle)
void	stopAll ()
bool	anyPlaying () const
void	shiftTime (uint32_t deltaMs)
void	reset ()
bool	advance (uint32_t nowMs, Completion done, uint8_t doneCap, uint8_t doneCount)
bool	frameView (uint32_t handle, FrameView *out) const

Static Public Attributes
static constexpr uint8_t	MAX_SPRITES = 8
static constexpr uint16_t	MAX_FRAMES = 32

Detailed Description

Fixed-slot store for multi-frame 1-bpp sprites with host-driven playback. Pixel data lives in an injected arena (PSRAM, owner-held).

Sheet layout: frames stacked vertically, rows byte-padded, MSB first, set bit = black (the surface/QR/image convention). An optional mask plane uses the same layout; mask bit set = pixel painted.

Definition at line 212 of file CanvasAnim.h.

Member Function Documentation

◆ advance()

bool cdc::ui::anim::SpriteStore::advance	(	uint32_t	nowMs,
		Completion *	done,
		uint8_t	doneCap,
		uint8_t *	doneCount )

Advance playback; fills completions for finished ONCE/finite runs.

Returns: true when any visible frame index changed.

Definition at line 599 of file CanvasAnim.cpp.

References cdc::ui::anim::Completion::doneActionId, cdc::ui::anim::Completion::handle, cdc::ui::anim::Completion::refId, cdc::ui::anim::REPEAT_FOREVER, cdc::ui::anim::SPRITE_LOOP, cdc::ui::anim::SPRITE_ONCE, and cdc::ui::anim::SPRITE_PING_PONG.

◆ anyPlaying()

bool cdc::ui::anim::SpriteStore::anyPlaying ( ) const

Definition at line 581 of file CanvasAnim.cpp.

◆ create()

int32_t cdc::ui::anim::SpriteStore::create	(	uint16_t	w,
		uint16_t	h,
		uint16_t	frameCount,
		const uint8_t *	data,
		uint32_t	len )

Copy a frame sheet into the arena and allocate a sprite slot.

Returns: Handle >= 1, 0 = invalid geometry, -1 = out of slots/arena.

Definition at line 406 of file CanvasAnim.cpp.

References MAX_FRAMES.

◆ destroy()

bool cdc::ui::anim::SpriteStore::destroy ( uint32_t handle )

Definition at line 475 of file CanvasAnim.cpp.

◆ frame()

int32_t cdc::ui::anim::SpriteStore::frame ( uint32_t handle ) const

Current frame or -1.

Definition at line 536 of file CanvasAnim.cpp.

Referenced by setFrame().

◆ frameView()

bool cdc::ui::anim::SpriteStore::frameView	(	uint32_t	handle,
		FrameView *	out ) const

Definition at line 674 of file CanvasAnim.cpp.

References cdc::ui::anim::SpriteStore::FrameView::data, cdc::ui::anim::SpriteStore::FrameView::flags, cdc::ui::anim::SpriteStore::FrameView::h, cdc::ui::anim::SpriteStore::FrameView::mask, cdc::ui::anim::SpriteStore::FrameView::scale, cdc::ui::anim::SpriteStore::FrameView::scrollGap, cdc::ui::anim::SpriteStore::FrameView::scrollWindow, cdc::ui::anim::SpriteStore::FrameView::scrollX, and cdc::ui::anim::SpriteStore::FrameView::w.

◆ hasArena()

bool cdc::ui::anim::SpriteStore::hasArena ( ) const

inline

Definition at line 219 of file CanvasAnim.h.

◆ play()

bool cdc::ui::anim::SpriteStore::play	(	uint32_t	handle,
		uint8_t	mode,
		uint16_t	frameMs,
		uint16_t	repeat,
		uint32_t	doneActionId,
		uint32_t	nowMs )

Definition at line 551 of file CanvasAnim.cpp.

References cdc::ui::anim::SPRITE_PING_PONG.

◆ reset()

void cdc::ui::anim::SpriteStore::reset ( )

Definition at line 594 of file CanvasAnim.cpp.

◆ scroll()

bool cdc::ui::anim::SpriteStore::scroll	(	uint32_t	handle,
		uint16_t	windowW,
		uint16_t	stepPx,
		uint16_t	gapPx,
		uint16_t	frameMs,
		uint32_t	nowMs )

Turn the sprite into a horizontal scroller (marquee backing).

The renderer shows a windowW-wide window into the (single-frame) content; advance() slides it by stepPx per beat, wrapping seamlessly with gapPx of blank space between repetitions.

Definition at line 512 of file CanvasAnim.cpp.

References cdc::ui::anim::REPEAT_FOREVER, and cdc::ui::anim::SPRITE_LOOP.

◆ setArena()

void cdc::ui::anim::SpriteStore::setArena	(	uint8_t *	buf,
		uint32_t	cap )

Inject the pixel arena. Must happen before create(); resets the store.

Definition at line 362 of file CanvasAnim.cpp.

◆ setFlags()

bool cdc::ui::anim::SpriteStore::setFlags	(	uint32_t	handle,
		uint8_t	flags )

Definition at line 498 of file CanvasAnim.cpp.

References flags.

◆ setFrame()

bool cdc::ui::anim::SpriteStore::setFrame	(	uint32_t	handle,
		uint16_t	frame )

Definition at line 529 of file CanvasAnim.cpp.

References frame().

◆ setFrameDurations()

bool cdc::ui::anim::SpriteStore::setFrameDurations	(	uint32_t	handle,
		const uint16_t *	ms,
		uint16_t	count )

Optional per-frame durations; count must equal frameCount (0 reverts to the global frame duration passed to play()).

Definition at line 453 of file CanvasAnim.cpp.

◆ setMask()

bool cdc::ui::anim::SpriteStore::setMask	(	uint32_t	handle,
		const uint8_t *	mask,
		uint32_t	len )

Attach a mask plane (same sheet layout/size as the frame data).

Definition at line 440 of file CanvasAnim.cpp.

◆ setScale()

bool cdc::ui::anim::SpriteStore::setScale	(	uint32_t	handle,
		uint8_t	scale )

Integer upscale factor 1..4 applied when the sprite is drawn.

Definition at line 505 of file CanvasAnim.cpp.

References cdc::ui::scale.

◆ shiftTime()

void cdc::ui::anim::SpriteStore::shiftTime ( uint32_t deltaMs )

Definition at line 588 of file CanvasAnim.cpp.

◆ stop()

bool cdc::ui::anim::SpriteStore::stop ( uint32_t handle )

Definition at line 568 of file CanvasAnim.cpp.

◆ stopAll()

void cdc::ui::anim::SpriteStore::stopAll ( )

Stop playback on every sprite, keeping assets and frame indices (a keep-sprites canvas clear must not leave orphans driving the animation clock).

Definition at line 575 of file CanvasAnim.cpp.

Member Data Documentation

◆ MAX_FRAMES

uint16_t cdc::ui::anim::SpriteStore::MAX_FRAMES = 32

staticconstexpr

Definition at line 215 of file CanvasAnim.h.

Referenced by create().

◆ MAX_SPRITES

uint8_t cdc::ui::anim::SpriteStore::MAX_SPRITES = 8