Extension-side analog of the firmware's BaseAnimation. More...

#include <rgbx_animation.h>

Public Member Functions
virtual void	init ()
	Called once, on the sandboxed thread, after every (re)load and before the first tick.

virtual void	tick (uint32_t dt_ms)=0
	Called once per frame; render into the framebuffer via setPixel()/fill().

virtual bool	goodMoment () const
	Queried after every tick(): return true when the frame just rendered ended at a natural switch boundary (end of a scroll/clip/cycle), so shuffle mode (issue #121) may switch away without visual jarring.

Protected Member Functions
size_t	width () const
	Framebuffer width in pixels (manifest value).

size_t	height () const
	Framebuffer height in pixels (manifest value).

void	setPixel (size_t x, size_t y, uint8_t r, uint8_t g, uint8_t b)
	Write one pixel (out-of-range coordinates are ignored).

void	fill (uint8_t r, uint8_t g, uint8_t b)
	Fill the whole framebuffer with one color.

uint32_t	paramU32 (size_t i) const
	Value of UINT32 parameter i.

uint32_t	param (size_t i) const
	Alias of paramU32() kept for early extensions.

uint32_t	paramColor (size_t i) const
	Value of COLOR parameter i.

bool	paramBool (size_t i) const
	Value of BOOL parameter i.

float	paramF32 (size_t i) const
	Value of FLOAT parameter i.

const char *	paramString (size_t i) const
	Value of STRING parameter i.

IMU snapshot accessors
All read zero on a build or board with no IMU, so an animation can use them unconditionally.
float	accelX () const
	Accelerometer X for this tick.

float	accelY () const
	Accelerometer Y for this tick.

float	accelZ () const
	Accelerometer Z for this tick.

float	gyroX () const
	Gyroscope X for this tick.

float	gyroY () const
	Gyroscope Y for this tick.

float	gyroZ () const
	Gyroscope Z for this tick.

Button accessors
Both read zero when no buttons are present. proto0 mapping: 0=Up, 1=Left, 2=Right, 3=Down, 4=Wake.
uint32_t	buttonsPressed () const
	Raw pressed-since-last-tick bitmask.

bool	buttonWasPressed (size_t id) const
	Whether one button was pressed since the previous tick.

Audio snapshot accessors
All read zero when audio is absent or silent, so an animation can use them unconditionally. Bands are ordered low frequencies first.
float	bandEnergy (size_t b) const
	Smoothed energy of one coarse band.

bool	isBeat (size_t b) const
	Whether a beat fired in one band this frame.

float	displayBucket (size_t i) const
	Energy of one fine-grained spectrum bucket, for bar-graph style visualisation.

static constexpr size_t	numBands ()
	Number of coarse audio bands.

static constexpr size_t	numDisplayBuckets ()
	Number of fine-grained display buckets.

Detailed Description

Extension-side analog of the firmware's BaseAnimation.

Subclass it and instantiate with RGBX_ANIMATION() below.

Member Function Documentation

◆ accelX()

float rgbx::Animation::accelX ( ) const

inlineprotected

Accelerometer X for this tick.

Returns: Acceleration in m/s^2.

◆ accelY()

float rgbx::Animation::accelY ( ) const

inlineprotected

Accelerometer Y for this tick.

Returns: Acceleration in m/s^2.

◆ accelZ()

float rgbx::Animation::accelZ ( ) const

inlineprotected

Accelerometer Z for this tick.

Returns: Acceleration in m/s^2.

◆ bandEnergy()

float rgbx::Animation::bandEnergy ( size_t b ) const

inlineprotected

Smoothed energy of one coarse band.

Parameters

b	Band index, 0 .. numBands()-1.

Returns: Smoothed band energy, or 0 if b is out of range.

◆ buttonsPressed()

uint32_t rgbx::Animation::buttonsPressed ( ) const

inlineprotected

Raw pressed-since-last-tick bitmask.

Returns: Bitmask where bit i is set if button i was pressed since the previous tick.

◆ buttonWasPressed()

bool rgbx::Animation::buttonWasPressed ( size_t id ) const

inlineprotected

Whether one button was pressed since the previous tick.

Parameters

id	Button id (proto0: 0=Up, 1=Left, 2=Right, 3=Down, 4=Wake).

Returns: true if that button was pressed, false if not or id is >= 32.

◆ displayBucket()

float rgbx::Animation::displayBucket ( size_t i ) const

inlineprotected

Energy of one fine-grained spectrum bucket, for bar-graph style visualisation.

Parameters

i	Bucket index, 0 .. numDisplayBuckets()-1.

Returns: Raw bucket power (mean |X_k|^2 over the bucket's FFT bins — NOT normalised: bass sits near 0.04–1, treble near 1e-5, a ~60 dB tilt), or 0 if i is out of range. Map it through the dB window in rgbx_audio_bars.h (rgbx_audio_bar_height()) before drawing a bar; a linear value * 255 pins the bass and never lights the treble.

◆ fill()

void rgbx::Animation::fill	(	uint8_t	r,
		uint8_t	g,
		uint8_t	b )

inlineprotected

Fill the whole framebuffer with one color.

Parameters

r	Red channel, 0-255.
g	Green channel, 0-255.
b	Blue channel, 0-255.

◆ goodMoment()

virtual bool rgbx::Animation::goodMoment ( ) const

inlinevirtual

Queried after every tick(): return true when the frame just rendered ended at a natural switch boundary (end of a scroll/clip/cycle), so shuffle mode (issue #121) may switch away without visual jarring.

Default: every frame is a good moment — matching built-in animations with no override. Backed by the optional rgbx_good_moment export, which RGBX_ANIMATION() always emits for wrapper-based extensions.

Returns: true if this is a natural point to switch animations.

◆ gyroX()

float rgbx::Animation::gyroX ( ) const

inlineprotected

Gyroscope X for this tick.

Returns: Angular rate in rad/s.

◆ gyroY()

float rgbx::Animation::gyroY ( ) const

inlineprotected

Gyroscope Y for this tick.

Returns: Angular rate in rad/s.

◆ gyroZ()

float rgbx::Animation::gyroZ ( ) const

inlineprotected

Gyroscope Z for this tick.

Returns: Angular rate in rad/s.

◆ height()

size_t rgbx::Animation::height ( ) const

inlineprotected

Framebuffer height in pixels (manifest value).

Returns: Height in pixels, as declared to RGBX_ANIMATION().

◆ isBeat()

bool rgbx::Animation::isBeat ( size_t b ) const

inlineprotected

Whether a beat fired in one band this frame.

Parameters

b	Band index, 0 .. numBands()-1.

Returns: true if a beat was detected, false if not or b is out of range.

◆ numBands()

static constexpr size_t rgbx::Animation::numBands ( )

inlinestaticconstexprprotected

Number of coarse audio bands.

Returns: RGBX_AUDIO_NUM_BANDS.

◆ numDisplayBuckets()

static constexpr size_t rgbx::Animation::numDisplayBuckets ( )

inlinestaticconstexprprotected

Number of fine-grained display buckets.

Returns: RGBX_AUDIO_NUM_DISPLAY_BUCKETS.

◆ param()

uint32_t rgbx::Animation::param ( size_t i ) const

inlineprotected

Alias of paramU32() kept for early extensions.

Parameters

i	Parameter index in manifest declaration order.

Returns: The current value, or 0 if i is out of range.

◆ paramBool()

bool rgbx::Animation::paramBool ( size_t i ) const

inlineprotected

Value of BOOL parameter i.

Parameters

i	Parameter index in manifest declaration order.

Returns: The current value, or false if i is out of range.

◆ paramColor()

uint32_t rgbx::Animation::paramColor ( size_t i ) const

inlineprotected

Value of COLOR parameter i.

Parameters

i	Parameter index in manifest declaration order.

Returns: The color as 0x00RRGGBB, or 0 if i is out of range.

◆ paramF32()

float rgbx::Animation::paramF32 ( size_t i ) const

inlineprotected

Value of FLOAT parameter i.

The float rides in the shared uint32_t params[] slot as its raw IEEE-754 bit pattern (see RGBX_PARAM_FLOAT), so this accessor bit-casts via memcpy — a static_cast would silently yield the integer-converted value instead.

Parameters

i	Parameter index in manifest declaration order.

Returns: The current value, or 0.0f if i is out of range.

◆ paramString()

const char * rgbx::Animation::paramString ( size_t i ) const

inlineprotected

Value of STRING parameter i.

String values live in rgbx_inputs::param_strings, slotted by declaration order among the string-typed params only — this accessor does that mapping for you, so i is the plain manifest index.

Parameters

i	Parameter index in manifest declaration order.

Returns: A NUL-terminated string, or "" if i is out of range or does not name an RGBX_PARAM_STRING parameter. Never NULL.

◆ paramU32()

uint32_t rgbx::Animation::paramU32 ( size_t i ) const

inlineprotected

Value of UINT32 parameter i.

Parameters

i	Parameter index in manifest declaration order.

Returns: The current value, or 0 if i is out of range.

◆ setPixel()

void rgbx::Animation::setPixel	(	size_t	x,
		size_t	y,
		uint8_t	r,
		uint8_t	g,
		uint8_t	b )

inlineprotected

Write one pixel (out-of-range coordinates are ignored).

Parameters

x	Column, 0 .. width()-1. Out-of-range values are a no-op.
y	Row, 0 .. height()-1. Out-of-range values are a no-op.
r	Red channel, 0-255.
g	Green channel, 0-255.
b	Blue channel, 0-255.

Note: Render near full scale. The host multiplies every pixel by the global brightness factor (default 0.02), so an animation that dims itself to e.g. 32/255 is invisible on the panel.

◆ tick()

virtual void rgbx::Animation::tick ( uint32_t dt_ms )

pure virtual

Called once per frame; render into the framebuffer via setPixel()/fill().

Must return well within the host's per-tick CPU budget or the extension is aborted and unloaded.

Parameters

dt_ms Nominal milliseconds since the previous tick.

◆ width()

size_t rgbx::Animation::width ( ) const

inlineprotected

Framebuffer width in pixels (manifest value).

Returns: Width in pixels, as declared to RGBX_ANIMATION().

The documentation for this class was generated from the following file:

fw/include/rgbx/rgbx_animation.h

Public Member Functions

Protected Member Functions

Audio snapshot accessors

Detailed Description

Member Function Documentation

◆ accelX()

◆ accelY()

◆ accelZ()

◆ bandEnergy()

◆ buttonsPressed()

◆ buttonWasPressed()

◆ displayBucket()

◆ fill()

◆ goodMoment()

◆ gyroX()

◆ gyroY()

◆ gyroZ()

◆ height()

◆ isBeat()

◆ numBands()

◆ numDisplayBuckets()

◆ param()

◆ paramBool()

◆ paramColor()

◆ paramF32()

◆ paramString()

◆ paramU32()

◆ setPixel()

◆ tick()

◆ width()