Multi-frame 1-bpp resources with host-driven frame playback. More...

Macros
#define	HOST_SPRITE_MAX_PER_CANVAS 8
	Maximum sprites per canvas.
#define	HOST_SPRITE_MAX_FRAMES 32
	Maximum frames per sprite.
#define	HOST_SPRITE_ARENA_BYTES 65536
	Shared pixel arena for all sprite data (frames + masks + durations).
#define	HOST_SPRITE_ONCE 0 /* play to the last frame and hold it */
#define	HOST_SPRITE_LOOP 1 /* wrap around; finite runs hold the last */
#define	HOST_SPRITE_PING_PONG 2 /* forward then backward per cycle */
#define	HOST_SPRITE_FLAG_OPAQUE 0x01 /* unset data bits paint white */
#define	HOST_SPRITE_FLAG_FLIP_H 0x02 /* mirror horizontally when drawn */
#define	HOST_SPRITE_FLAG_FLIP_V 0x04 /* mirror vertically when drawn */
#define	HOST_SPRITE_FLAG_ROT_90

Functions
int	host_sprite_create (uint16_t frame_w, uint16_t frame_h, uint16_t frame_count, const uint8_t *frames, uint32_t len)
	Create a sprite from a packed 1-bpp frame sheet in plugin memory.
int	host_sprite_create_from_surface (uint32_t surface, uint16_t frame_w, uint16_t frame_h, uint16_t frame_count)
	Create a sprite by slicing a surface into a row-major grid of frame_w x frame_h cells.
int	host_sprite_set_mask (uint32_t sprite, const uint8_t *mask, uint32_t len)
	Attach a transparency mask plane (same sheet layout and size as the frame data). Mask bit set = pixel painted; overrides HOST_SPRITE_FLAG_OPAQUE.
int	host_sprite_create_from_image (const uint8_t *data, uint32_t len, uint16_t target_w, uint16_t frame_h)
	Create a sprite straight from an encoded PNG/JPEG.
int	host_sprite_set_flags (uint32_t sprite, uint8_t flags)
	Replace the sprite's flag set (HOST_SPRITE_FLAG_*).
int	host_sprite_set_scale (uint32_t sprite, uint8_t scale)
	Integer upscale factor applied whenever the sprite is drawn.
int	host_sprite_set_frame (uint32_t sprite, uint16_t frame)
	Jump to a frame. A running playback continues from it.
int	host_sprite_get_frame (uint32_t sprite, uint16_t *out)
	Read the currently displayed frame index.
int	host_sprite_set_frame_durations (uint32_t sprite, const uint16_t *ms, uint16_t count)
	Optional per-frame durations in milliseconds.
int	host_sprite_play (uint32_t sprite, uint8_t mode, uint16_t frame_ms, uint16_t repeat, uint32_t done_action_id)
	Start host-driven playback from frame 0.
int	host_sprite_stop (uint32_t sprite)
	Stop playback, keeping the current frame on screen.
int	host_sprite_destroy (uint32_t sprite)
	Destroy a sprite and reclaim its arena bytes. Recorded draw-sprite commands referencing it are skipped from then on.

Detailed Description

Multi-frame 1-bpp resources with host-driven frame playback.

A sprite is a frame sheet: frame_count frames of w x h pixels stacked vertically, packed rows MSB-first, set bit = black - the same layout as the surface, QR and image APIs, so host_image_render output slices straight into frames. Draw it into the canvas by reference with host_view_canvas_draw_sprite (inside an element for movement/z/tweens) and let host_sprite_play advance frames on the host clock.

Transparency: by default set bits paint black and unset bits are transparent. HOST_SPRITE_FLAG_OPAQUE paints unset bits white. A mask plane (host_sprite_set_mask) gives per-pixel control: mask bit set = pixel painted (black or white per the data bit), unset = transparent.

Sprites live in the canvas: they are freed when the canvas is popped or cleared, and creating them requires an open canvas view. To create sheets once and reuse them across screen rebuilds, clear with host_view_canvas_clear_ex (HOST_CANVAS_CLEAR_KEEP_SPRITES) - assets survive, playback stops. No capability required - pure compute with a hard memory cap.

Macro Definition Documentation

◆ HOST_SPRITE_ARENA_BYTES

#define HOST_SPRITE_ARENA_BYTES 65536

Shared pixel arena for all sprite data (frames + masks + durations).

Definition at line 2328 of file host_api.h.

◆ HOST_SPRITE_FLAG_FLIP_H

#define HOST_SPRITE_FLAG_FLIP_H 0x02 /* mirror horizontally when drawn */

Definition at line 2337 of file host_api.h.

◆ HOST_SPRITE_FLAG_FLIP_V

#define HOST_SPRITE_FLAG_FLIP_V 0x04 /* mirror vertically when drawn */

Definition at line 2338 of file host_api.h.

◆ HOST_SPRITE_FLAG_OPAQUE

#define HOST_SPRITE_FLAG_OPAQUE 0x01 /* unset data bits paint white */

Definition at line 2336 of file host_api.h.

◆ HOST_SPRITE_FLAG_ROT_90

#define HOST_SPRITE_FLAG_ROT_90

Value:

0x08 /* rotate 90 deg clockwise (before the
flips; combine for 180/270). The
drawn box becomes h x w.            */

Definition at line 2339 of file host_api.h.

◆ HOST_SPRITE_LOOP

#define HOST_SPRITE_LOOP 1 /* wrap around; finite runs hold the last */

Definition at line 2332 of file host_api.h.

◆ HOST_SPRITE_MAX_FRAMES

#define HOST_SPRITE_MAX_FRAMES 32

Maximum frames per sprite.

Definition at line 2326 of file host_api.h.

◆ HOST_SPRITE_MAX_PER_CANVAS

#define HOST_SPRITE_MAX_PER_CANVAS 8

Maximum sprites per canvas.

Definition at line 2324 of file host_api.h.

◆ HOST_SPRITE_ONCE

#define HOST_SPRITE_ONCE 0 /* play to the last frame and hold it */

Definition at line 2331 of file host_api.h.

◆ HOST_SPRITE_PING_PONG

#define HOST_SPRITE_PING_PONG 2 /* forward then backward per cycle */

Definition at line 2333 of file host_api.h.

Function Documentation

◆ host_sprite_create()

int host_sprite_create	(	uint16_t	frame_w,
		uint16_t	frame_h,
		uint16_t	frame_count,
		const uint8_t *	frames,
		uint32_t	len )

Create a sprite from a packed 1-bpp frame sheet in plugin memory.

The data is copied into the host's sprite arena; the buffer may be reused.

Parameters

frame_w	Frame width in pixels, >= 1.
frame_h	Frame height in pixels, >= 1.
frame_count	1..HOST_SPRITE_MAX_FRAMES.
frames	Sheet bytes, frames stacked vertically.
len	Must be >= ((frame_w + 7) / 8) * frame_h * frame_count.

Returns: Sprite handle >= 1, HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY (slots or arena exhausted), HOST_ERR_NOT_FOUND (no canvas).

Definition at line 346 of file host_api_canvas.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY, and HOST_ERR_NOT_FOUND.

Referenced by cdc::plugin_manager::w_host_sprite_create().

◆ host_sprite_create_from_image()

int host_sprite_create_from_image	(	const uint8_t *	data,
		uint32_t	len,
		uint16_t	target_w,
		uint16_t	frame_h )

Create a sprite straight from an encoded PNG/JPEG.

The image is decoded, scaled to target_w (aspect preserved), dithered to 1-bpp (the host_image_render pipeline) and sliced vertically into frames of frame_h pixels; a partial last frame is dropped. Compose the source as one tall filmstrip.

Returns: Sprite handle >= 1, HOST_ERR_INVALID_ARG, HOST_ERR_GENERIC (decode failed), HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND (no canvas).

Definition at line 379 of file host_api_canvas.cpp.

References HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND, host_image_render(), HOST_OK, and cdc::core::psramAlloc().

Referenced by cdc::plugin_manager::w_host_sprite_create_from_image().

◆ host_sprite_create_from_surface()

int host_sprite_create_from_surface	(	uint32_t	surface,
		uint16_t	frame_w,
		uint16_t	frame_h,
		uint16_t	frame_count )

Create a sprite by slicing a surface into a row-major grid of frame_w x frame_h cells.

Compose frames with text, shapes or decoded PNGs on a surface first, then snapshot it. Pixels are copied; the surface may be destroyed afterwards.

Parameters

frame_count Cells taken from the grid, left-to-right, top-to-bottom.

Returns: Sprite handle >= 1, HOST_ERR_NOT_FOUND (surface/canvas), HOST_ERR_INVALID_ARG (grid does not fit), HOST_ERR_NO_MEMORY.

Definition at line 339 of file host_api_surface.cpp.

References cdc::plugin_manager::PluginUiState::canvasView(), HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND, and cdc::plugin_manager::PluginUiState::instance().

Referenced by cdc::plugin_manager::w_host_sprite_create_from_surface().

◆ host_sprite_destroy()

int host_sprite_destroy ( uint32_t sprite )

Destroy a sprite and reclaim its arena bytes. Recorded draw-sprite commands referencing it are skipped from then on.

Definition at line 449 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_sprite_destroy().

◆ host_sprite_get_frame()

int host_sprite_get_frame	(	uint32_t	sprite,
		uint16_t *	out )

Read the currently displayed frame index.

Definition at line 414 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

Referenced by cdc::plugin_manager::w_host_sprite_get_frame().

◆ host_sprite_play()

int host_sprite_play	(	uint32_t	sprite,
		uint8_t	mode,
		uint16_t	frame_ms,
		uint16_t	repeat,
		uint32_t	done_action_id )

Start host-driven playback from frame 0.

The canvas is committed automatically while playback runs (see host_view_canvas_set_anim_policy).

Parameters

mode	HOST_SPRITE_ONCE / LOOP / PING_PONG.
frame_ms	Per-frame duration, floored at 50 ms (overridden by host_sprite_set_frame_durations).
repeat	Extra cycles: 0 = one pass, HOST_ANIM_REPEAT_FOREVER = endless. A PING_PONG cycle is one full there-and-back.
done_action_id	plugin_on_action(id, sprite, final_frame) when a finite playback completes; 0 = none.