particle_scene.h

#include <modkit/particle_scene.h>8 functions · 4 structs · 7 typedefs

Optional retained-scene bridge for particle playback instances.

Functions

mk_particle_scene_attachfunction

mk_particle_instance_t mk_particle_scene_attach(mk_particle_scene_t bridge, mk_scene_node_t node, mk_particle_effect_t effect)

Attach an effect to a node and return the bridge-owned playback instance.

Reattaching the same node first destroys its previous owned instance. GPU mesh geometry resolved into the effect is registered automatically. Applications supplying geometry out of band should immediately register each mesh with mk_particle_mesh_set_geometry() on the returned instance.

Parameter	Type	Description
bridge	mk_particle_scene_t	Value for bridge.
node	mk_scene_node_t	Value for node.
effect	mk_particle_effect_t	Value for effect.

Returns The resulting handle or value.

mk_particle_scene_createfunction

mk_particle_scene_t mk_particle_scene_create(const mk_particle_scene_desc *desc)

Create particle scene.

Parameter	Type	Description
desc	const mk_particle_scene_desc *	Configuration descriptor.

Returns The resulting handle or value.

mk_particle_scene_destroyfunction

void mk_particle_scene_destroy(mk_particle_scene_t bridge)

Destroy the particle scene.

Parameter	Type	Description
bridge	mk_particle_scene_t	Value for bridge.

mk_particle_scene_detachfunction

mk_result mk_particle_scene_detach(mk_particle_scene_t bridge, mk_scene_node_t node)

Detach particle scene.

Parameter	Type	Description
bridge	mk_particle_scene_t	Value for bridge.
node	mk_scene_node_t	Value for node.

Returns MK_SUCCESS or an error result.

mk_particle_scene_get_statsfunction

void mk_particle_scene_get_stats(const mk_particle_scene_t bridge, mk_particle_scene_stats *out_stats)

Get stats from the particle scene.

Parameter	Type	Description
bridge	const mk_particle_scene_t	Value for bridge.
out_stats	mk_particle_scene_stats *	Receives the stats.

mk_particle_scene_instancefunction

bool mk_particle_scene_instance(mk_particle_scene_t bridge, mk_scene_node_t node, mk_particle_instance_t *out_instance)

Perform the particle scene instance operation.

Parameter	Type	Description
bridge	mk_particle_scene_t	Value for bridge.
node	mk_scene_node_t	Value for node.
out_instance	mk_particle_instance_t *	Receives the instance.

Returns True when the operation succeeds.

mk_particle_scene_render_submitfunction

mk_result mk_particle_scene_render_submit(const mk_particle_scene_submit_desc *desc, void *user_data)

Batteries-included mk_particle_scene_submit_fn.

Pass this as mk_particle_scene_desc.submit and point submit_user_data at an application-owned mk_particle_scene_render_adapter. A NULL adapter selects all built-in defaults. Texture, CPU mesh geometry, atlas, blend, billboard, and custom-pipeline choices can be supplied per emitter by resolve. GPU mesh geometry must already be registered with mk_particle_mesh_set_geometry(); resolve may leave geometry invalid or return the same registered handle. During retained-scene rendering, consecutive compatible CPU emitters are submitted as one transient batch. The resolver is still called once per emitter, submitted/rejected statistics still count emitters, and GPU emitters remain individual indirect submissions.

Parameter	Type	Description
desc	const mk_particle_scene_submit_desc *	Configuration descriptor.
user_data	void *	Caller-provided context.

Returns MK_SUCCESS or an error result.

mk_particle_scene_syncfunction

mk_result mk_particle_scene_sync(mk_particle_scene_t bridge)

Synchronize node world transforms and enabled state without advancing time.

Scene rendering calls this automatically before particle GPU preparation.

Parameter	Type	Description
bridge	mk_particle_scene_t	Value for bridge.

Returns MK_SUCCESS or an error result.

Structs

mk_particle_scene_descstruct

Data for particle scene desc.

Field	Type	Description
scene	mk_scene_t	The scene.
world	mk_particle_world_t *	The world.
submit	mk_particle_scene_submit_fn	The submit.
submit_user_data	void *	The submit user data.
attachment_capacity	uint32_t	0 selects 32 and grows as needed.

mk_particle_scene_render_adapterstruct

Data for particle scene render adapter.

Field	Type	Description
defaults	mk_particle_render_desc	The defaults.
resolve	mk_particle_scene_render_resolve_fn	The resolve.
user_data	void *	The user data.

mk_particle_scene_statsstruct

Data for particle scene stats.

Field	Type	Description
attachments	uint32_t	The attachments.
visible	uint32_t	The visible.
culled	uint32_t	The culled.
submitted	uint32_t	The submitted.
rejected	uint32_t	The rejected.

mk_particle_scene_submit_descstruct

Data for particle scene submit desc.

Field	Type	Description
collection	const mk_scene_collection_t *	The collection.
world	mk_particle_world_t *	The world.
instance	mk_particle_instance_t	The instance.
node	mk_scene_node_t	The node.
emitter_index	uint32_t	The emitter index.
world_matrix	mk_mat4	The world matrix.
min_bounds	mk_vec3	The min bounds.
max_bounds	mk_vec3	The max bounds.
has_bounds	bool	The has bounds.

Typedefs

mk_particle_scene_desctypedef

typedef struct mk_particle_scene_desc mk_particle_scene_desc

Data for particle scene desc.

mk_particle_scene_render_adaptertypedef

typedef struct mk_particle_scene_render_adapter mk_particle_scene_render_adapter

Data for particle scene render adapter.

mk_particle_scene_render_resolve_fntypedef

typedef bool(*) mk_particle_scene_render_resolve_fn(const mk_particle_scene_submit_desc *submit, mk_particle_render_desc *render, void *user_data)

Optional style resolver used by the built-in scene submit adapter.

The render descriptor starts with adapter.defaults and the collected scene camera. Return false when an emitter has no renderable style.

mk_particle_scene_statstypedef

typedef struct mk_particle_scene_stats mk_particle_scene_stats

Data for particle scene stats.

mk_particle_scene_submit_desctypedef

typedef struct mk_particle_scene_submit_desc mk_particle_scene_submit_desc

Data for particle scene submit desc.

mk_particle_scene_submit_fntypedef

typedef mk_result(*) mk_particle_scene_submit_fn(const mk_particle_scene_submit_desc *desc, void *user_data)

Submit one visible emitter into the active transparent scene pass.

GPU emitters have already been prepared for the current frame. The callback may use mk_particle_apply_gpu_draw(), mk_particle_get_render_view(), or mk_particle_get_trail_view(), then submit through the ordinary pass API. It must not destroy or mutate the bridge or its particle world.

mk_particle_scene_ttypedef

typedef struct mk_particle_scene* mk_particle_scene_t

Type used for particle scene.