UI - Canvas animation

Host-driven tweens on canvas elements. More...

Classes
struct	host_anim_t
	Tween description for host_anim_start(); zero-init unused fields. More...

Macros
#define	HOST_ANIM_MAX   16
	Maximum concurrently live tweens per canvas.
#define	HOST_ANIM_REPEAT_FOREVER   0xFFFF
	repeat value meaning "repeat forever".
#define	HOST_EASE_LINEAR   0
#define	HOST_EASE_QUAD_IN   1
#define	HOST_EASE_QUAD_OUT   2
#define	HOST_EASE_QUAD_IN_OUT   3
#define	HOST_EASE_CUBIC_IN   4
#define	HOST_EASE_CUBIC_OUT   5
#define	HOST_EASE_CUBIC_IN_OUT   6
#define	HOST_EASE_OVERSHOOT   7 /* back-out: overshoots, then settles */
#define	HOST_EASE_BOUNCE   8 /* bounce-out: ball-drop rebound */
#define	HOST_EASE_STEP   9 /* holds the start, jumps at the end */
#define	HOST_EASE_ELASTIC   10 /* elastic-out: springy overshoot wobble */
#define	HOST_ANIM_FLAG_FROM_CURRENT
#define	HOST_ANIM_FLAG_YOYO   0x02 /* each repeat alternates direction */
#define	HOST_ANIM_FLAG_HIDE_DONE   0x04 /* hide the element on completion */
#define	HOST_ANIM_FLAG_SHOW_START
#define	HOST_ANIM_STATE_DELAYED   0
#define	HOST_ANIM_STATE_RUNNING   1
#define	HOST_ANIM_STATE_PAUSED   2

Functions
int	host_anim_start (const host_anim_t *cfg)
	Start (or queue, when start_after != 0) a tween on an element.
int	host_anim_cancel (uint32_t handle)
	Cancel a tween and its chained successors; handle 0 cancels all of the canvas's tweens. Elements keep their current offset; no completion actions fire.
int	host_anim_pause (uint32_t handle, bool paused)
	Pause (paused != 0) or resume a tween; delay time freezes too.
int	host_anim_state (uint32_t handle)
	Query a tween's state.
int	host_anim_active_count (void)
	Number of live tweens plus playing sprites (>= 0).
int	host_anim_blink (uint32_t elem_id, uint16_t period_ms, uint16_t count, uint32_t done_action_id)
	Convenience: blink an element.

Detailed Description

Host-driven tweens on canvas elements.

A tween animates an element's replay offset over time with an easing curve; the host advances it on its own clock, commits the canvas and fires plugin_on_action(done_action_id, anim_handle, elem_id) on completion - no per-frame plugin code needed. Sequencing is expressed with delay_ms (parallel staggering) and start_after (chains); repetition with repeat and the YOYO flag. See host_view_canvas_set_anim_policy for pacing and refresh behavior. No capability required.

Macro Definition Documentation

HOST_ANIM_FLAG_FROM_CURRENT

#define HOST_ANIM_FLAG_FROM_CURRENT

Value:

0x01 /* ignore from_x/y, start at the
element's live offset          */

Definition at line 1494 of file host_api.h.

HOST_ANIM_FLAG_HIDE_DONE

#define HOST_ANIM_FLAG_HIDE_DONE   0x04 /* hide the element on completion */

Definition at line 1496 of file host_api.h.

HOST_ANIM_FLAG_SHOW_START

#define HOST_ANIM_FLAG_SHOW_START

Value:

0x08 /* show the element when the delay
elapses                        */

Definition at line 1497 of file host_api.h.

HOST_ANIM_FLAG_YOYO

#define HOST_ANIM_FLAG_YOYO   0x02 /* each repeat alternates direction */

Definition at line 1495 of file host_api.h.

HOST_ANIM_MAX

#define HOST_ANIM_MAX   16

Maximum concurrently live tweens per canvas.

Definition at line 1476 of file host_api.h.

HOST_ANIM_REPEAT_FOREVER

#define HOST_ANIM_REPEAT_FOREVER   0xFFFF

repeat value meaning "repeat forever".

Definition at line 1478 of file host_api.h.

HOST_ANIM_STATE_DELAYED

#define HOST_ANIM_STATE_DELAYED   0

Definition at line 1538 of file host_api.h.

HOST_ANIM_STATE_PAUSED

#define HOST_ANIM_STATE_PAUSED   2

Definition at line 1540 of file host_api.h.

HOST_ANIM_STATE_RUNNING

#define HOST_ANIM_STATE_RUNNING   1

Definition at line 1539 of file host_api.h.

HOST_EASE_BOUNCE

#define HOST_EASE_BOUNCE   8 /* bounce-out: ball-drop rebound */

Definition at line 1489 of file host_api.h.

HOST_EASE_CUBIC_IN

#define HOST_EASE_CUBIC_IN   4

Definition at line 1485 of file host_api.h.

HOST_EASE_CUBIC_IN_OUT

#define HOST_EASE_CUBIC_IN_OUT   6

Definition at line 1487 of file host_api.h.

HOST_EASE_CUBIC_OUT

#define HOST_EASE_CUBIC_OUT   5

Definition at line 1486 of file host_api.h.

HOST_EASE_ELASTIC

#define HOST_EASE_ELASTIC   10 /* elastic-out: springy overshoot wobble */

Definition at line 1491 of file host_api.h.

HOST_EASE_LINEAR

#define HOST_EASE_LINEAR   0

Definition at line 1481 of file host_api.h.

HOST_EASE_OVERSHOOT

#define HOST_EASE_OVERSHOOT   7 /* back-out: overshoots, then settles */

Definition at line 1488 of file host_api.h.

HOST_EASE_QUAD_IN

#define HOST_EASE_QUAD_IN   1

Definition at line 1482 of file host_api.h.

HOST_EASE_QUAD_IN_OUT

#define HOST_EASE_QUAD_IN_OUT   3

Definition at line 1484 of file host_api.h.

HOST_EASE_QUAD_OUT

#define HOST_EASE_QUAD_OUT   2

Definition at line 1483 of file host_api.h.

HOST_EASE_STEP

#define HOST_EASE_STEP   9 /* holds the start, jumps at the end */

Definition at line 1490 of file host_api.h.

Referenced by host_anim_start().

Function Documentation

host_anim_active_count()

int host_anim_active_count

(

void

)

Number of live tweens plus playing sprites (>= 0).

Definition at line 511 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND.

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

host_anim_blink()

int host_anim_blink	(	uint32_t	elem_id,
		uint16_t	period_ms,
		uint16_t	count,
		uint32_t	done_action_id )

Convenience: blink an element.

Toggles visibility every period_ms for count on/off cycles (HOST_ANIM_REPEAT_FOREVER = endless), ending visible. Occupies one tween slot; done_action_id fires as in host_anim_start.

Returns

Blink handle >= 1 (cancel/pause like a tween), HOST_ERR_NOT_FOUND, HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY.

Definition at line 518 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_anim_blink().

host_anim_cancel()

int host_anim_cancel

(

uint32_t

handle

)

Cancel a tween and its chained successors; handle 0 cancels all of the canvas's tweens. Elements keep their current offset; no completion actions fire.

Returns

HOST_OK, HOST_ERR_NOT_FOUND.

Definition at line 489 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_anim_pause()

int host_anim_pause	(	uint32_t	handle,
		bool	paused )

Pause (paused != 0) or resume a tween; delay time freezes too.

Definition at line 496 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND, and HOST_OK.

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

host_anim_start()

int host_anim_start

(

const host_anim_t *

cfg

)

Start (or queue, when start_after != 0) a tween on an element.

Returns

Tween handle >= 1, HOST_ERR_NOT_FOUND (element/predecessor/canvas), HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY (all slots live).

Definition at line 458 of file host_api_canvas.cpp.

References host_anim_t::delay_ms, cdc::ui::anim::TweenConfig::delayMs, host_anim_t::done_action_id, cdc::ui::anim::TweenConfig::doneActionId, host_anim_t::duration_ms, cdc::ui::anim::TweenConfig::durationMs, cdc::ui::anim::TweenConfig::easing, host_anim_t::easing, host_anim_t::elem_id, cdc::ui::anim::TweenConfig::elemId, cdc::ui::anim::TweenConfig::flags, host_anim_t::flags, host_anim_t::from_x, host_anim_t::from_y, cdc::ui::anim::TweenConfig::fromX, cdc::ui::anim::TweenConfig::fromY, HOST_EASE_STEP, HOST_ERR_INVALID_ARG, HOST_ERR_NO_MEMORY, HOST_ERR_NOT_FOUND, cdc::ui::anim::TweenConfig::repeat, host_anim_t::repeat, host_anim_t::start_after, cdc::ui::anim::TweenConfig::startAfter, host_anim_t::to_x, host_anim_t::to_y, cdc::ui::anim::TweenConfig::toX, and cdc::ui::anim::TweenConfig::toY.

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

host_anim_state()

int host_anim_state

(

uint32_t

handle

)

Query a tween's state.

Returns

HOST_ANIM_STATE_*, or HOST_ERR_NOT_FOUND once completed/cancelled (handles are recycled after completion).

Definition at line 503 of file host_api_canvas.cpp.

References HOST_ERR_NOT_FOUND.

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