particle_render.h

#include <modkit/particle_render.h>8 functions · 4 structs · 1 enums · 5 typedefs

Batteries-included pass submission for particle emitters.

Functions

`mk_particle_2d_space_camera`function

mk_particle_2d_space mk_particle_2d_space_camera(mk_camera2d camera)

Y-down Camera2D world coordinates.

Parameter	Type	Description
`camera`	`mk_camera2d`	Value for camera.

Returns The resulting value.

`mk_particle_2d_space_screen`function

mk_particle_2d_space mk_particle_2d_space_screen(float output_width, float output_height)

Screen-pixel coordinates with (0,0) at the output's top-left.

Parameter	Type	Description
`output_width`	`float`	Value for output width.
`output_height`	`float`	Value for output height.

Returns The resulting value.

`mk_particle_2d_space_virtual`function

mk_particle_2d_space mk_particle_2d_space_virtual(mk_viewport2d viewport)

Fitted virtual-resolution coordinates with (0,0) at the virtual top-left.

Parameter	Type	Description
`viewport`	`mk_viewport2d`	Value for viewport.

Returns The resulting value.

`mk_particle_mesh_set_geometry`function

mk_result mk_particle_mesh_set_geometry(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, mk_geometry_t geometry)

Bind immutable triangle geometry to a mesh emitter.

GPU mesh emitters require this binding before mk_particle_world_prepare_gpu() so the compute pass can publish the correct indexed or non-indexed indirect command. The emitter retains the geometry until it is rebound, cleared with MK_GEOMETRY_INVALID, or destroyed. CPU mesh rendering continues to use mk_particle_render_desc.geometry. Binding after this world has already been prepared in the current frame is rejected with MK_ERROR_INVALID_STATE. Platforms compiled without the GPU particle runtime return MK_ERROR_UNSUPPORTED.

Parameter	Type	Description
`world`	`mk_particle_world_t *`	Value for world.
`instance`	`mk_particle_instance_t`	Value for instance.
`emitter_index`	`uint32_t`	Value for emitter index.
`geometry`	`mk_geometry_t`	Value for geometry.

Returns MK_SUCCESS or an error result.

`mk_particle_render`function

mk_result mk_particle_render(mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, const mk_particle_render_desc *desc, mk_particle_render_report *out_report)

Submit one emitter into the currently active pass.

Parameter	Type	Description
`world`	`mk_particle_world_t *`	Value for world.
`instance`	`mk_particle_instance_t`	Value for instance.
`emitter_index`	`uint32_t`	Value for emitter index.
`desc`	`const mk_particle_render_desc *`	Configuration descriptor.
`out_report`	`mk_particle_render_report *`	Receives the report.

Returns MK_SUCCESS or an error result.

`mk_particle_render_batch`function

mk_result mk_particle_render_batch(mk_particle_world_t *world, const mk_particle_render_batch_item *items, uint32_t item_count, const mk_particle_render_desc *desc, mk_particle_render_report *out_report)

Submit a homogeneous CPU emitter group as one transient draw.

Every item must use the same renderer. desc supplies the shared texture, geometry, pipeline, blend, camera, and pass-order state, so applications partition items by those values before calling. GPU emitters use their device-local indirect draws and are rejected by this CPU batching path.

Parameter	Type	Description
`world`	`mk_particle_world_t *`	Value for world.
`items`	`const mk_particle_render_batch_item *`	Value for items.
`item_count`	`uint32_t`	Number of item entries.
`desc`	`const mk_particle_render_desc *`	Configuration descriptor.
`out_report`	`mk_particle_render_report *`	Receives the report.

Returns MK_SUCCESS or an error result.

`mk_particle_render_batch_ex`function

mk_result mk_particle_render_batch_ex(mk_encoder_t encoder, mk_view_id_t view, mk_particle_world_t *world, const mk_particle_render_batch_item *items, uint32_t item_count, const mk_particle_render_desc *desc, mk_particle_render_report *out_report)

Worker-encoder equivalent of mk_particle_render_batch().

Parameter	Type	Description
`encoder`	`mk_encoder_t`	Value for encoder.
`view`	`mk_view_id_t`	Value for view.
`world`	`mk_particle_world_t *`	Value for world.
`items`	`const mk_particle_render_batch_item *`	Value for items.
`item_count`	`uint32_t`	Number of item entries.
`desc`	`const mk_particle_render_desc *`	Configuration descriptor.
`out_report`	`mk_particle_render_report *`	Receives the report.

Returns MK_SUCCESS or an error result.

`mk_particle_render_ex`function

mk_result mk_particle_render_ex(mk_encoder_t encoder, mk_view_id_t view, mk_particle_world_t *world, mk_particle_instance_t instance, uint32_t emitter_index, const mk_particle_render_desc *desc, mk_particle_render_report *out_report)

Worker-encoder equivalent of mk_particle_render().

Parameter	Type	Description
`encoder`	`mk_encoder_t`	Value for encoder.
`view`	`mk_view_id_t`	Value for view.
`world`	`mk_particle_world_t *`	Value for world.
`instance`	`mk_particle_instance_t`	Value for instance.
`emitter_index`	`uint32_t`	Value for emitter index.
`desc`	`const mk_particle_render_desc *`	Configuration descriptor.
`out_report`	`mk_particle_render_report *`	Receives the report.

Returns MK_SUCCESS or an error result.

Structs

`mk_particle_2d_space`struct

Data for particle 2D space.

Field	Type	Description
`mode`	`mk_particle_2d_space_mode`	The mode.
`output_width`	`float`	The output width.
`output_height`	`float`	The output height.
`viewport`	`mk_viewport2d`	The viewport.
`camera`	`mk_camera2d`	The camera.

`mk_particle_render_batch_item`struct

Data for particle render batch item.

Field	Type	Description
`instance`	`mk_particle_instance_t`	The instance.
`emitter_index`	`uint32_t`	The emitter index.

`mk_particle_render_desc`struct

Per-submit renderer resources and camera basis.

Zero initialization selects a white texture, alpha blending, camera-facing billboards, a full [0,1] UV rectangle, and one atlas frame. Mesh emitters require geometry. Invalid texture and geometry fields use valid IDs authored in mk_particle_emitter_desc.references when available. Zero-valued style fields inherit mk_particle_emitter_desc.render_style; set ignore_effect_style to use only this descriptor's style. A custom pipeline must consume Modkit's documented particle instance or trail ABI and the standard particle uniforms.

Field	Type	Description
`texture`	`mk_texture_t`	The texture.
`geometry`	`mk_geometry_t`	The geometry.
`pipeline`	`mk_pipeline_t`	The pipeline.
`blend`	`mk_particle_blend_mode`	The blend.
`billboard`	`mk_particle_billboard_mode`	The billboard.
`billboard_axis`	`mk_vec3`	Zero selects +Y.
`velocity_stretch`	`float`	Zero selects 1.
`uv_rect`	`mk_vec4`	x, y, width, height; all-zero selects 0,0,1,1.
`atlas_columns`	`uint16_t`	Zero selects 1.
`atlas_rows`	`uint16_t`	Zero selects 1.
`atlas_frames`	`uint32_t`	Zero selects every atlas cell.
`alpha_cutoff`	`float`	Masked only; zero selects 0.5.
`view_position`	`mk_vec3`	The view position.
`view_forward`	`mk_vec3`	Zero selects -Z.
`view_up`	`mk_vec3`	Zero selects +Y.
`space_2d`	`mk_particle_2d_space`	The space 2D.
`phase`	`mk_draw_phase_t`	The phase.
`depth`	`uint32_t`	The depth.
`has_depth`	`bool`	The has depth.
`ignore_effect_style`	`bool`	The ignore effect style.

`mk_particle_render_report`struct

Data for particle render report.

Field	Type	Description
`result`	`mk_result`	The result.
`backend`	`mk_particle_backend`	The backend.
`renderer`	`mk_particle_renderer_type`	The renderer.
`particles`	`uint32_t`	The particles.
`vertices`	`uint32_t`	The vertices.
`draw_calls`	`uint32_t`	The draw calls.
`transient_failures`	`uint32_t`	The transient failures.

Enums

`mk_particle_2d_space_mode`enum

Values for particle 2D space mode.

Value	Description
`MK_PARTICLE_2D_PASS`	Selects pass.
`MK_PARTICLE_2D_SCREEN`	Selects screen.
`MK_PARTICLE_2D_VIRTUAL`	Selects virtual.
`MK_PARTICLE_2D_CAMERA`	Selects camera.

Typedefs

`mk_particle_2d_space`typedef

typedef struct mk_particle_2d_space mk_particle_2d_space

Data for particle 2D space.

`mk_particle_2d_space_mode`typedef

typedef enum mk_particle_2d_space_mode mk_particle_2d_space_mode

Values for particle 2D space mode.

`mk_particle_render_batch_item`typedef

typedef struct mk_particle_render_batch_item mk_particle_render_batch_item

Data for particle render batch item.

`mk_particle_render_desc`typedef

typedef struct mk_particle_render_desc mk_particle_render_desc

Per-submit renderer resources and camera basis.

Zero initialization selects a white texture, alpha blending, camera-facing billboards, a full [0,1] UV rectangle, and one atlas frame. Mesh emitters require geometry. Invalid texture and geometry fields use valid IDs authored in mk_particle_emitter_desc.references when available. Zero-valued style fields inherit mk_particle_emitter_desc.render_style; set ignore_effect_style to use only this descriptor's style. A custom pipeline must consume Modkit's documented particle instance or trail ABI and the standard particle uniforms.

`mk_particle_render_report`typedef

typedef struct mk_particle_render_report mk_particle_render_report

Data for particle render report.