Classes
struct	emitter_appearance_desc
	Color / scale / speed-based appearance authoring. More...

struct	emitter_desc
	Full authoring description for an emitter (no transforms / runtime). More...

struct	emitter_emission_desc
	Emission rate, shape, and lifetime cycle authoring. More...

struct	emitter_handle

struct	emitter_motion_desc
	Motion / forces / trajectory authoring. More...

struct	emitter_playback_desc
	Playback gates (playing / paused). More...

struct	emitter_render_desc
	Render / texture-sheet authoring (constant per emitter). More...

struct	emitter_sim_constants
	Hot-loop constants baked from desc (CPU now, CB-shaped for GPU later). More...

struct	emitter_sim_state
	Mutable simulation bookkeeping owned by the soa emitter instance. More...

struct	emitter_transform_state
	Per-frame transform inputs. Authoring desc never owns these. More...

struct	gpu_pack_uniforms
	Uniform vec4 packing for compute (set as float[4] arrays). More...

struct	gpu_sim_particle
	Packed sim particle for compute (80 bytes / 5 x vec4). More...

Enumerations
enum class	particle_sim_backend : uint8_t { cpu = 0 , gpu = 1 }
	Selects CPU vs resident-GPU simulation backend. More...

enum class	emitter_shape : int { sphere = 0 , hemisphere , circle , box , rect , count }
	Emission volume shape. Ordinals match legacy EmitterShape for content compatibility. More...

enum class	emitter_direction : int { up = 0 , outward , inward , count }
	Initial emission direction. Ordinals match legacy EmitterDirection. More...

enum class	spawn_location : int { inside = 0 , surface , count }
	Where particles spawn within the shape. Ordinals match legacy EmitterSpawnLocation. More...

enum class	simulation_space : int { world = 0 , local , count }
	Simulation space. Ordinals match legacy SimulationSpace. More...

enum class	texture_mode : int { multi_channel = 0 , mask , count }
	Texture interpretation. Ordinals match legacy TextureMode. More...

enum class	render_mode : int { billboard = 0 , horizontal_billboard , vertical_billboard , count }
	Billboard / facing mode. Ordinals match legacy RenderMode. More...

enum class	blend_mode : int { normal = 0 , additive , multiply }
	Blend mode. Ordinals match legacy BlendMode. More...

enum class	emitter_feature : uint32_t { none = 0 , align_to_direction = 1u << 0 , texsheet = 1u << 1 , color_by_speed = 1u << 2 , size_by_speed = 1u << 3 , lifetime_by_emitter_speed = 1u << 4 , local_space = 1u << 5 , non_linear_ease = 1u << 6 }
	Feature bits baked from authoring desc for specialized update/render paths. More...

Functions
auto	gpu_feature_mask (emitter_feature features) -> uint32_t

void	init (uint16_t max_emitters=64)
	Initialize the soa particle system.

void	init_gpu (rtti::context &ctx)
	Load compute pack program and enable GPU backend when available.

void	shutdown ()
	Shutdown and free all emitters / GPU resources.

void	set_default_sim_backend (particle_sim_backend backend)
	Set default sim backend for new / unset emitters (cpu remains fallback).

auto	get_default_sim_backend () -> particle_sim_backend
	Current default sim backend.

void	set_emitter_sim_backend (emitter_handle handle, particle_sim_backend backend)
	Override backend for one emitter.

auto	get_emitter_sim_backend (emitter_handle handle) -> particle_sim_backend
	Effective backend for an emitter (after availability checks).

auto	is_gpu_sim_available () -> bool
	True when compute pack program loaded successfully.

auto	create_emitter (emitter_shape shape, emitter_direction direction, uint32_t max_particles) -> emitter_handle
	Create an emitter with shape/direction and capacity.

void	destroy_emitter (emitter_handle handle)
	Destroy an emitter and free its particle storage.

void	reset_emitter (emitter_handle handle)
	Clear particles and reset sim bookkeeping.

void	update_emitter (emitter_handle handle, float dt, const emitter_desc &desc, emitter_transform_state &transform, emitter_playback_desc &playback)
	Advance simulation for one emitter.

void	update_emitter_bounds_only (emitter_handle handle, const emitter_desc &desc, emitter_transform_state &transform)
	Refresh transform-driven world bounds without advancing sim (renderer-based freeze).

void	sync_gpu_simulation ()
	Flush staged GPU spawns and advance resident GPU sim for awake emitters.

auto	has_updated (emitter_handle handle) -> bool
	True after the first successful update.

void	get_aabb (emitter_handle handle, math::bbox &out_aabb)
	World-space AABB used for culling.

auto	get_num_particles (emitter_handle handle) -> uint32_t
	Live particle count.

auto	render_emitter_batch (const emitter_handle handles, uint32_t count, uint8_t view, bgfx::ProgramHandle program, const float mtx_view, const math::vec3 &eye, bgfx::TextureHandle texture, uint64_t blend_state, bool sort_by_depth=true) -> uint32_t
	Submit a homogeneous material batch (same texture / texture_mode / blend).

auto	is_valid (emitter_handle handle) -> bool

constexpr auto	operator\| (emitter_feature a, emitter_feature b) -> emitter_feature

constexpr auto	operator& (emitter_feature a, emitter_feature b) -> emitter_feature

constexpr auto	has_feature (emitter_feature mask, emitter_feature bit) -> bool

Variables
constexpr uint16_t	k_gpu_instance_stride = 96
	GPU instance row matches vs_particle_instanced i_data0..i_data5 (96 bytes).

constexpr uint32_t	k_gpu_instance_floats = k_gpu_instance_stride / sizeof(float)

constexpr uint32_t	k_gpu_sim_floats_per_particle = 20

constexpr uint32_t	k_gpu_sim_vec4s_per_particle = 5

constexpr uint32_t	k_gpu_lut_size = 256

constexpr uint32_t	k_gpu_cs_threads = 64

Enumeration Type Documentation

◆ blend_mode

enum class unravel::ps_soa::blend_mode : int

strong

Blend mode. Ordinals match legacy BlendMode.

Enumerator
normal
additive
multiply

Definition at line 75 of file particle_types.h.

◆ emitter_direction

enum class unravel::ps_soa::emitter_direction : int

strong

Initial emission direction. Ordinals match legacy EmitterDirection.

Enumerator
up
outward
inward
count

Definition at line 33 of file particle_types.h.

◆ emitter_feature

enum class unravel::ps_soa::emitter_feature : uint32_t

strong

Feature bits baked from authoring desc for specialized update/render paths.

Enumerator
none
align_to_direction
texsheet
color_by_speed
size_by_speed
lifetime_by_emitter_speed
local_space
non_linear_ease

Definition at line 83 of file particle_types.h.

◆ emitter_shape

enum class unravel::ps_soa::emitter_shape : int

strong

Emission volume shape. Ordinals match legacy EmitterShape for content compatibility.

Enumerator
sphere
hemisphere
circle
box
rect
count

Definition at line 22 of file particle_types.h.

◆ particle_sim_backend

enum class unravel::ps_soa::particle_sim_backend : uint8_t

strong

Selects CPU vs resident-GPU simulation backend.

Enumerator
cpu
gpu

Definition at line 13 of file particle_gpu_schema.h.

◆ render_mode

enum class unravel::ps_soa::render_mode : int

strong

Billboard / facing mode. Ordinals match legacy RenderMode.

Enumerator
billboard
horizontal_billboard
vertical_billboard
count

Definition at line 66 of file particle_types.h.

◆ simulation_space

enum class unravel::ps_soa::simulation_space : int

strong

Simulation space. Ordinals match legacy SimulationSpace.

Enumerator
world
local
count

Definition at line 50 of file particle_types.h.

◆ spawn_location

enum class unravel::ps_soa::spawn_location : int

strong

Where particles spawn within the shape. Ordinals match legacy EmitterSpawnLocation.

Enumerator
inside
surface
count

Definition at line 42 of file particle_types.h.

◆ texture_mode

enum class unravel::ps_soa::texture_mode : int

strong

Texture interpretation. Ordinals match legacy TextureMode.

Enumerator
multi_channel
mask
count

Definition at line 58 of file particle_types.h.

Function Documentation

◆ create_emitter()

auto unravel::ps_soa::create_emitter	(	emitter_shape	shape,
		emitter_direction	direction,
		uint32_t	max_particles ) -> emitter_handle

Create an emitter with shape/direction and capacity.

Definition at line 2377 of file particle_system_soa.cpp.

◆ destroy_emitter()

void unravel::ps_soa::destroy_emitter ( emitter_handle handle )

Destroy an emitter and free its particle storage.

Definition at line 2382 of file particle_system_soa.cpp.

◆ get_aabb()

void unravel::ps_soa::get_aabb	(	emitter_handle	handle,
		math::bbox &	out_aabb )

World-space AABB used for culling.

Definition at line 2418 of file particle_system_soa.cpp.

◆ get_default_sim_backend()

auto unravel::ps_soa::get_default_sim_backend ( ) -> particle_sim_backend

Current default sim backend.

Definition at line 2357 of file particle_system_soa.cpp.

◆ get_emitter_sim_backend()

auto unravel::ps_soa::get_emitter_sim_backend ( emitter_handle handle ) -> particle_sim_backend

Effective backend for an emitter (after availability checks).

Definition at line 2367 of file particle_system_soa.cpp.

◆ get_num_particles()

auto unravel::ps_soa::get_num_particles ( emitter_handle handle ) -> uint32_t

Live particle count.

Definition at line 2423 of file particle_system_soa.cpp.

◆ gpu_feature_mask()

auto unravel::ps_soa::gpu_feature_mask ( emitter_feature features ) -> uint32_t

inline

Definition at line 85 of file particle_gpu_schema.h.

◆ has_feature()

auto unravel::ps_soa::has_feature	(	emitter_feature	mask,
		emitter_feature	bit ) -> bool

inlineconstexpr

Definition at line 105 of file particle_types.h.

◆ has_updated()

auto unravel::ps_soa::has_updated ( emitter_handle handle ) -> bool

True after the first successful update.

Definition at line 2413 of file particle_system_soa.cpp.

◆ init()

void unravel::ps_soa::init ( uint16_t max_emitters = 64 )

Initialize the soa particle system.

Parameters

max_emitters Maximum concurrent emitters.

Definition at line 2337 of file particle_system_soa.cpp.

◆ init_gpu()

void unravel::ps_soa::init_gpu ( rtti::context & ctx )

Load compute pack program and enable GPU backend when available.

Parameters

ctx	Runtime context with asset_manager.

Definition at line 2342 of file particle_system_soa.cpp.

◆ is_gpu_sim_available()

auto unravel::ps_soa::is_gpu_sim_available ( ) -> bool

True when compute pack program loaded successfully.

Definition at line 2372 of file particle_system_soa.cpp.

◆ is_valid()

auto unravel::ps_soa::is_valid ( emitter_handle handle ) -> bool

inline

Definition at line 16 of file particle_types.h.

◆ operator&()

auto unravel::ps_soa::operator&	(	emitter_feature	a,
		emitter_feature	b ) -> emitter_feature

inlineconstexpr

Definition at line 100 of file particle_types.h.

◆ operator|()

auto unravel::ps_soa::operator\|	(	emitter_feature	a,
		emitter_feature	b ) -> emitter_feature

inlineconstexpr

Definition at line 95 of file particle_types.h.

◆ render_emitter_batch()

auto unravel::ps_soa::render_emitter_batch	(	const emitter_handle *	handles,
		uint32_t	count,
		uint8_t	view,
		bgfx::ProgramHandle	program,
		const float *	mtx_view,
		const math::vec3 &	eye,
		bgfx::TextureHandle	texture,
		uint64_t	blend_state,
		bool	sort_by_depth = true ) -> uint32_t

Submit a homogeneous material batch (same texture / texture_mode / blend).

Parameters

sort_by_depth When true, back-to-front sort (Normal blend). When false, emission order.

Returns: Number of instances submitted.

Definition at line 2428 of file particle_system_soa.cpp.

◆ reset_emitter()

void unravel::ps_soa::reset_emitter ( emitter_handle handle )

Clear particles and reset sim bookkeeping.

Definition at line 2387 of file particle_system_soa.cpp.

◆ set_default_sim_backend()

void unravel::ps_soa::set_default_sim_backend ( particle_sim_backend backend )

Set default sim backend for new / unset emitters (cpu remains fallback).

Definition at line 2352 of file particle_system_soa.cpp.

◆ set_emitter_sim_backend()

void unravel::ps_soa::set_emitter_sim_backend	(	emitter_handle	handle,
		particle_sim_backend	backend )

Override backend for one emitter.

Definition at line 2362 of file particle_system_soa.cpp.

◆ shutdown()

void unravel::ps_soa::shutdown ( )

Shutdown and free all emitters / GPU resources.

Definition at line 2347 of file particle_system_soa.cpp.

◆ sync_gpu_simulation()

void unravel::ps_soa::sync_gpu_simulation ( )

Flush staged GPU spawns and advance resident GPU sim for awake emitters.

Note: Call once per frame on the main/render thread after parallel update_emitter.

Definition at line 2408 of file particle_system_soa.cpp.

◆ update_emitter()

void unravel::ps_soa::update_emitter	(	emitter_handle	handle,
		float	dt,
		const emitter_desc &	desc,
		emitter_transform_state &	transform,
		emitter_playback_desc &	playback )

Advance simulation for one emitter.

Parameters

handle	Emitter handle.
dt	Frame delta seconds.
desc	Authoring description (gradients, rates, render flags). Playback fields in desc are ignored.
transform	Current/previous world transform; previous is updated after the call.
playback	Mutable playing/paused; may be cleared when a one-shot emitter finishes.

Definition at line 2392 of file particle_system_soa.cpp.

◆ update_emitter_bounds_only()

void unravel::ps_soa::update_emitter_bounds_only	(	emitter_handle	handle,
		const emitter_desc &	desc,
		emitter_transform_state &	transform )

Refresh transform-driven world bounds without advancing sim (renderer-based freeze).

Definition at line 2401 of file particle_system_soa.cpp.

Variable Documentation

◆ k_gpu_cs_threads

uint32_t unravel::ps_soa::k_gpu_cs_threads = 64

constexpr

Definition at line 25 of file particle_gpu_schema.h.

◆ k_gpu_instance_floats

uint32_t unravel::ps_soa::k_gpu_instance_floats = k_gpu_instance_stride / sizeof(float)

constexpr

Definition at line 21 of file particle_gpu_schema.h.

◆ k_gpu_instance_stride

uint16_t unravel::ps_soa::k_gpu_instance_stride = 96

constexpr

GPU instance row matches vs_particle_instanced i_data0..i_data5 (96 bytes).

Definition at line 20 of file particle_gpu_schema.h.

◆ k_gpu_lut_size

uint32_t unravel::ps_soa::k_gpu_lut_size = 256

constexpr

Definition at line 24 of file particle_gpu_schema.h.

◆ k_gpu_sim_floats_per_particle

uint32_t unravel::ps_soa::k_gpu_sim_floats_per_particle = 20

constexpr

Definition at line 22 of file particle_gpu_schema.h.

◆ k_gpu_sim_vec4s_per_particle

uint32_t unravel::ps_soa::k_gpu_sim_vec4s_per_particle = 5

constexpr

Definition at line 23 of file particle_gpu_schema.h.

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

◆ blend_mode

◆ emitter_direction

◆ emitter_feature

◆ emitter_shape

◆ particle_sim_backend

◆ render_mode

◆ simulation_space

◆ spawn_location

◆ texture_mode

Function Documentation

◆ create_emitter()

◆ destroy_emitter()

◆ get_aabb()

◆ get_default_sim_backend()

◆ get_emitter_sim_backend()

◆ get_num_particles()

◆ gpu_feature_mask()

◆ has_feature()

◆ has_updated()

◆ init()

◆ init_gpu()

◆ is_gpu_sim_available()

◆ is_valid()

◆ operator&()

◆ operator|()

◆ render_emitter_batch()

◆ reset_emitter()

◆ set_default_sim_backend()

◆ set_emitter_sim_backend()

◆ shutdown()

◆ sync_gpu_simulation()

◆ update_emitter()

◆ update_emitter_bounds_only()

Variable Documentation

◆ k_gpu_cs_threads

◆ k_gpu_instance_floats

◆ k_gpu_instance_stride

◆ k_gpu_lut_size

◆ k_gpu_sim_floats_per_particle

◆ k_gpu_sim_vec4s_per_particle