Particle

The particle widget renders dynamic visual effects on screen, such as fireworks, snow, bubbles, lightning, and more. The system includes a rich set of preset effects that developers can use directly to add vivid animations to their applications.

Feature Overview

The particle widget is built on a high-performance particle engine, providing a complete 2D particle system for dynamic visual effects on embedded devices.

Emission Shapes

Multiple geometric emission sources for flexible control over initial particle distribution:

Shape	Description
Point	Emit from a single coordinate. Ideal for burst and jet effects.
Line	Emit uniformly along a line segment. Ideal for rain, snow, and edge-based effects.
Circle	Emit randomly within a circular area.
Rect	Emit randomly within a rectangular area. Ideal for full-screen distribution.
Ring	Emit within an annular region between inner and outer radii. Ideal for vortex and galaxy effects.

Trajectory Models

Three particle motion models:

Trajectory	Description
Linear	Constant velocity motion with configurable damping.
Gravity	Physics-based gravity simulation with acceleration, wind force, and damping.
Orbit	Orbital motion around a specified center point.

Color System

Color Mode	Description
Solid	Fixed single color.
Random	Randomly selected from a palette of up to 8 colors.
Gradient	Smooth transition from start color to end color over the particle's lifetime.
Rainbow	Automatic hue cycling over the particle's lifetime.

Interaction Modes

Built-in touch interaction behaviors:

Behavior	Description
Follow Touch	Emitter follows touch position in real time.
Trail	Emits particles opposite to the touch movement direction, forming a trailing effect.
Touch Feedback	Burst on press, continuous emission on drag, final burst on release.
Pulse	Emission rate oscillates periodically.
Breathe	Particle opacity oscillates periodically, creating a breathing glow.

Rendering Features

Three blend modes: Normal (standard alpha), Additive (glow), Multiply (darken)
Four easing functions: Linear, Ease In, Ease Out, Ease In Out — controlling opacity and scale curves
Independent per-particle scale, rotation, and opacity animation with velocity-aligned orientation
Boundary behaviors: Kill, Reflect, Wrap

Extensibility

Custom callbacks: 6 callback hooks (particle init, per-frame update, pre-render, death event, emitter start/stop) for fully custom behaviors
Multi-emitter stacking: up to 16 independent effects running simultaneously on a single widget
Configuration serialization: effect configs can be exported in binary format and loaded from memory or filesystem for resource management and dynamic switching

Usage

Running the Particle Demo

Enable the particle demo via menuconfig. In the configuration UI, complete the following steps and save:

Go to Enable HoneyGUI Framework → HoneyGUI Feature Configuration, enable Enable Particle System
Go back, enter Select HoneyGUI Demo, select Particle System Demo (this option depends on the previous step — the particle system must be enabled first)

Note

Select HoneyGUI Demo is a single-choice menu. Selecting Particle System Demo will automatically deselect any previously chosen demo.

After launch, a selection menu (Launcher) is displayed. Tap an effect name to preview it, and tap the Back button at the top to return to the menu.

Using Preset Effects

Each preset effect provides a standalone configuration function and demo entry point:

#include "effect_snow.h"

/* Option 1: Initialize with default configuration */
gui_particle_widget_t *widget = effect_snow_demo_init();

/* Option 2: Get configuration and customize */
particle_effect_config_t config;
effect_snow_config(&config);

/* Adjust parameters as needed, e.g. emission rate */
config.emission.rate = 30.0f;

/* Create particle widget and load configuration */
gui_obj_t *root = gui_obj_get_root();
gui_particle_widget_t *widget = gui_particle_widget_create(
    root, "my_snow", 0, 0, screen_w, screen_h, 256);
gui_particle_widget_add_effect(widget, &config);

All preset effect headers and source files are located in example/widget/particle/, named as effect_<name>.c/h.

Preset Effects

The particle system provides the following preset effects, ready to use out of the box. Each effect has been carefully tuned for different application scenarios.

Effect	Description	Preview
Galaxy	Rotating spiral galaxy with particles distributed along spiral arms, converging toward the center. Blue-purple outer gradient to white-pink core.
Firework	Timed bursts at random positions. Particles spread outward and fall with gravity. Multi-color random palette.
Trail	Continuously emits particles following touch position, forming a drag trail. Emits on press, stops on release.
Touch	Burst on tap, continuous emission on drag, final burst on release. Ideal for touch interaction feedback.
Snow	Snowflakes gently fall from the top of the screen with light wind drift and random rotation.
Bubble	Bubbles rise from the bottom, bounce off boundaries, and gradually expand.
Custom	Demonstrates custom callback usage with sine-wave lateral perturbation and rainbow color cycling. Serves as a reference template for custom effects.
Tunnel	Particles radiate outward from screen center at high speed, simulating a warp-speed effect with perspective scaling.
Rocket	Dual-layer system: bright flame layer and gray smoke layer, simulating rocket thruster exhaust.
Vortex	Particles spiral from the outer ring with rainbow colors. Rotation speeds up and size shrinks near the center.
Lightning	Procedurally generated jagged bolt paths simulating real lightning discharge, with recursive branching and flicker fade-out.
Fireflies	Glowing dots randomly distributed across the screen, slowly drifting with breathing opacity.
Ripple	Touch-triggered concentric rings expanding outward, simulating water ripples with secondary waves.
Rain	Raindrops fall diagonally from the top with wind drift. Splash particles are generated on impact.
MagicCircle	Two magic circle images rotating in opposite directions, with orange-red sparks floating upward.
LightBeam	Three colored laser beams reflecting off screen edges, with flash effects on bounce and additive color blending.

Note

The preset effect library is continuously expanding. We recommend regularly syncing the repository and running the Particle Demo to access the latest effect additions.

API

Defines

PARTICLE_INVALID_HANDLE 0: Invalid effect handle constant

PARTICLE_WIDGET_MAX_EFFECTS 16: Maximum number of effects per widget

Typedefs

typedef uint32_t particle_effect_handle_t: Effect handle type for managing effects

typedef void (*gui_particle_update_cb_t)(void *user_data): User update callback type

Enums

enum gui_particle_render_mode_t

Particle System Widget Adapter for HoneyGUI.

This module provides the HoneyGUI widget wrapper for the particle system. It bridges the independent particle system core with HoneyGUI's widget system.

Features:

Inherits from gui_obj_t for seamless integration
Implements prepare/draw/end callbacks
Provides render callback that uses gui_img for particle rendering
Convenience interfaces for adding preset effects

Enable particle performance profiling

When enabled, the particle widget will collect timing statistics for:

Particle update (physics simulation)
Particle rendering (drawing to buffer and blit)

Statistics are printed at the end of each frame via gui_log().

Particle rendering mode (default: DIRECT)

Values:

enumerator PARTICLE_RENDER_DIRECT: Strip-based rendering, low memory, avoids PSRAM bottleneck

enumerator PARTICLE_RENDER_BUFFERED: Full-frame cache, fast blit, higher memory usage

Functions

gui_particle_widget_t *gui_particle_widget_create(gui_obj_t *parent, const char *name, int16_t x, int16_t y, int16_t w, int16_t h, uint16_t pool_capacity)

Create a particle system widget.

Creates a new particle widget and initializes the underlying particle system.

Parameters:

parent -- Parent widget to attach to
name -- Widget name
x -- X coordinate relative to parent
y -- Y coordinate relative to parent
w -- Widget width
h -- Widget height
pool_capacity -- Maximum number of particles in the pool

Returns:

Pointer to created widget, or NULL on failure

particle_system_t *gui_particle_widget_get_system(gui_particle_widget_t *widget)

Get the particle system instance.

Returns the underlying particle system for direct manipulation.

Parameters:: widget -- Particle widget
Returns:: Pointer to particle system, or NULL if widget is invalid

void gui_particle_widget_set_default_image(gui_particle_widget_t *widget, void *image)

Set default particle image.

Sets the default image used for particles that don't have a specific image.

Parameters:

widget -- Particle widget
image -- Pointer to image data (HoneyGUI image format)

void gui_particle_widget_clear(gui_particle_widget_t *widget)

Clear all particles.

Removes all active particles from the system.

Parameters:: widget -- Particle widget

uint16_t gui_particle_widget_get_active_count(gui_particle_widget_t *widget)

Get active particle count.

Parameters:: widget -- Particle widget
Returns:: Number of active particles

void gui_particle_widget_set_render_mode(gui_particle_widget_t *widget, gui_particle_render_mode_t mode): Set rendering mode (DIRECT or BUFFERED)

gui_particle_render_mode_t gui_particle_widget_get_render_mode(gui_particle_widget_t *widget): Get current rendering mode.

void gui_particle_widget_set_update_cb(gui_particle_widget_t *widget, gui_particle_update_cb_t cb, void *user_data)

Set user update callback.

Sets a callback function that will be called every frame during the prepare phase. This can be used to trigger periodic effects like auto-firing fireworks.

Parameters:

widget -- Particle widget
cb -- Callback function
user_data -- User data passed to callback

particle_effect_handle_t gui_particle_widget_add_effect(gui_particle_widget_t *widget, const particle_effect_config_t *config)

Add an effect from configuration.

Creates an emitter from the provided configuration and adds it to the particle system. Returns a handle for subsequent operations.

The function automatically sets up touch event handling based on the behavior mode in the configuration.

Note

Requirements: 14.1, 14.2, 14.4

Parameters:

widget -- Particle widget
config -- Effect configuration

Returns:

Effect handle, or PARTICLE_INVALID_HANDLE on failure

void gui_particle_widget_remove_effect(gui_particle_widget_t *widget, particle_effect_handle_t handle)

Remove an effect by handle.

Removes the effect associated with the given handle from the widget. The emitter is destroyed and all associated particles will expire naturally.

Note

Requirements: 14.3

Parameters:

widget -- Particle widget
handle -- Effect handle returned by gui_particle_widget_add_effect()

void gui_particle_widget_trigger_burst(gui_particle_widget_t *widget, particle_effect_handle_t handle)

Trigger a burst for an effect.

Triggers an immediate burst of particles for the specified effect. Uses the burst_count from the effect's configuration.

Note

Requirements: 14.5

Parameters:

widget -- Particle widget
handle -- Effect handle

void gui_particle_widget_update_position(gui_particle_widget_t *widget, particle_effect_handle_t handle, float x, float y)

Update effect position.

Updates the emitter position for effects that support position following (FOLLOW_TOUCH, TRAIL, TOUCH_FEEDBACK behavior modes).

Note

Requirements: 14.5

Parameters:

widget -- Particle widget
handle -- Effect handle
x -- New X position
y -- New Y position

void gui_particle_widget_stop_effect(gui_particle_widget_t *widget, particle_effect_handle_t handle)

Stop an effect (disable emitter)

Disables the emitter for the specified effect, stopping particle emission. Existing particles will continue to animate until they expire. The effect can be restarted by calling gui_particle_widget_update_position().

Note

Requirements: 14.5

Parameters:

widget -- Particle widget
handle -- Effect handle

struct particle_effect_entry_t

Effect entry structure for tracking effects.

Public Members

particle_effect_handle_t handle: Effect handle

particle_emitter_t *emitter: Associated emitter

particle_behavior_mode_t behavior: Behavior mode

uint8_t active: Whether effect is active

struct gui_particle_widget_t

Particle widget structure.

Extends gui_obj_t to integrate particle system with HoneyGUI.

Public Members

gui_obj_t base: Base object structure (must be first)

particle_system_t *ps: Particle system instance

particle_platform_config_t config: Platform configuration

particle_effect_entry_t effects[PARTICLE_WIDGET_MAX_EFFECTS]: Effect entries

uint32_t next_handle: Next handle to assign

particle_emitter_t *trail_emitter: Trail effect emitter (if added)

float prev_x: Previous X position for trail

float prev_y: Previous Y position for trail

uint8_t trail_active: Trail tracking active flag

particle_emitter_t *touch_emitter: Touch effect emitter (if added)

uint8_t touch_active: Touch tracking active flag

void *default_image: Default particle image resource

gui_particle_update_cb_t update_cb: User update callback

void *update_cb_data: User data for update callback

gui_particle_render_mode_t render_mode: Rendering mode (DIRECT or BUFFERED)

uint8_t *ramless_cache: Full frame cache for buffered mode

uint8_t ramless_cache_valid: Whether cache is valid for current frame

struct draw_img *draw_img: Pre-allocated draw_img (computed in prepare)