shadows.h

#include <modkit/shadows.h>10 functions · 6 structs · 2 enums · 9 typedefs · 2 macros

Transactional punctual-light shadow atlas preparation.

Functions

mk_shadows_atlas_texturefunction

mk_texture_t mk_shadows_atlas_texture(void)

Perform the shadows atlas texture operation.

Returns The resulting handle or value.

mk_shadows_commitfunction

bool mk_shadows_commit(void)

Publish only when all required passes succeeded; otherwise retain the last atlas.

Returns True when the operation succeeds.

mk_shadows_complete_passfunction

void mk_shadows_complete_pass(uint32_t index, bool success)

Report a required pass after its pass has ended.

Parameter	Type	Description
index	uint32_t	Zero-based index.
success	bool	Value for success.

mk_shadows_get_passfunction

bool mk_shadows_get_pass(uint32_t index, mk_shadow_pass_desc *out)

Get pass from the shadows.

Parameter	Type	Description
index	uint32_t	Zero-based index.
out	mk_shadow_pass_desc *	Value for out.

Returns True when the operation succeeds.

mk_shadows_get_statsfunction

void mk_shadows_get_stats(mk_shadow_stats *out)

Get stats from the shadows.

Parameter	Type	Description
out	mk_shadow_stats *	Value for out.

mk_shadows_pass_countfunction

uint32_t mk_shadows_pass_count(void)

Perform the shadows pass count operation.

Returns The resulting value.

mk_shadows_preparefunction

bool mk_shadows_prepare(const mk_shadow_prepare_desc *desc)

Build a pending generation from the immutable light snapshot of this frame.

Parameter	Type	Description
desc	const mk_shadow_prepare_desc *	Configuration descriptor.

Returns True when the operation succeeds.

mk_shadows_renderfunction

bool mk_shadows_render(const mk_shadow_prepare_desc *desc, mk_shadow_draw_callback draw, void *user_data)

Prepare, render, and transactionally publish all required shadow passes.

Parameter	Type	Description
desc	const mk_shadow_prepare_desc *	Configuration descriptor.
draw	mk_shadow_draw_callback	Value for draw.
user_data	void *	Caller-provided context.

Returns True when the operation succeeds.

mk_shadows_system_initfunction

void mk_shadows_system_init(void)

Initialize the shadows system.

mk_shadows_system_shutdownfunction

void mk_shadows_system_shutdown(void)

Perform the shadows system shutdown operation.

Structs

mk_shadow_exceptionstruct

Data for shadow exception.

Field	Type	Description
light_index	uint16_t	The light index.
requested_resolution	uint16_t	The requested resolution.
actual_resolution	uint16_t	The actual resolution.
face_count	uint8_t	The face count.
reason	mk_shadow_exception_reason	The reason.

mk_shadow_light_overridestruct

Data for shadow light override.

Field	Type	Description
light_index	uint16_t	The light index.
resolution	uint16_t	Zero keeps the type default.
max_distance	float	Required for infinite point/spot lights.
depth_bias	float	The depth bias.
normal_bias	float	The normal bias.
cascade_count	uint8_t	Directional only; zero keeps the setting.

mk_shadow_pass_descstruct

Data for shadow pass desc.

Field	Type	Description
pass	mk_pass_desc	The pass.
view	float	The view.
projection	float	The projection.
light_index	uint16_t	The light index.
cascade	uint8_t	The cascade.
cube_face	uint8_t	The cube face.
shadow_slot	uint16_t	The shadow slot.
atlas_scale_bias	float	scale.xy, bias.xy in sampled atlas UV.
max_distance	float	The max distance.
depth_bias	float	The depth bias.
normal_bias	float	The normal bias.
point_face_seam_tolerance	float	The point face seam tolerance.

mk_shadow_prepare_descstruct

Data for shadow prepare desc.

Field	Type	Description
camera	const mk_camera *	The camera.
settings	mk_shadow_settings	The settings.
overrides	const mk_shadow_light_override *	The overrides.
override_count	uint16_t	The override count.
caster_generation	uint64_t	The caster generation.

mk_shadow_settingsstruct

Data for shadow settings.

Field	Type	Description
atlas_size	uint16_t	Zero selects 4096 desktop, 2048 web.
directional_tile_size	uint16_t	Zero selects 1024.
spot_tile_size	uint16_t	Zero selects 1024.
point_face_size	uint16_t	Zero selects 512.
minimum_tile_size	uint16_t	Zero selects 128.
directional_cascades	uint8_t	Zero selects four; valid range 1..4.
atlas_ring_size	uint16_t	Deprecated minimum; effective size is frame latency + 1.
directional_max_distance	float	Zero selects min(camera far, 100).
cascade_split_lambda	float	Zero selects 0.65.
cascade_blend	float	Zero selects 0.10 of the cascade interval.
depth_bias	float	Zero selects 0.0015 normalized depth at 1024px.
normal_bias	float	Zero selects at least 0.01 world units.
point_face_seam_tolerance	float	Zero selects a 0.02 dominant-axis blend band.

mk_shadow_statsstruct

Data for shadow stats.

Field	Type	Description
pending_generation	uint64_t	The pending generation.
published_generation	uint64_t	The published generation.
atlas_bytes	uint64_t	Allocated atlas bytes; includes old and replacement rings during a resize.
required_passes	uint32_t	The required passes.
completed_passes	uint32_t	The completed passes.
downscaled_tiles	uint32_t	The downscaled tiles.
dropped_lights	uint32_t	The dropped lights.
exceptions	mk_shadow_exception	The exceptions.
exception_count	uint8_t	The exception count.
exceptions_truncated	bool	The exceptions truncated.
atlas_size	uint16_t	The atlas size.
atlas_ring_size	uint16_t	The atlas ring size.
depth_mode	mk_shadow_depth_mode	The depth mode.
active	bool	The active.
reused	bool	The reused.
pending	bool	The pending.

Enums

mk_shadow_depth_modeenum

Values for shadow depth mode.

Value	Description
MK_SHADOW_DEPTH_NONE	Selects none.
MK_SHADOW_DEPTH_D16_COMPARE	Selects d16 compare.
MK_SHADOW_DEPTH_D16_MANUAL	Selects d16 manual.
MK_SHADOW_DEPTH_RGBA8_PACKED	Selects rgba8 packed.

mk_shadow_exception_reasonenum

Values for shadow exception reason.

Value	Description
MK_SHADOW_EXCEPTION_DOWNSCALED	Selects downscaled.
MK_SHADOW_EXCEPTION_PASS_CAPACITY	Selects pass capacity.
MK_SHADOW_EXCEPTION_ATLAS_CAPACITY	Selects atlas capacity.
MK_SHADOW_EXCEPTION_MISSING_DISTANCE	Selects missing distance.

Typedefs

mk_shadow_depth_modetypedef

typedef enum mk_shadow_depth_mode mk_shadow_depth_mode

Values for shadow depth mode.

mk_shadow_draw_callbacktypedef

typedef bool(*) mk_shadow_draw_callback(const mk_shadow_pass_desc *pass, void *user_data)

Callback used for shadow draw callback.

mk_shadow_exceptiontypedef

typedef struct mk_shadow_exception mk_shadow_exception

Data for shadow exception.

mk_shadow_exception_reasontypedef

typedef enum mk_shadow_exception_reason mk_shadow_exception_reason

Values for shadow exception reason.

mk_shadow_light_overridetypedef

typedef struct mk_shadow_light_override mk_shadow_light_override

Data for shadow light override.

mk_shadow_pass_desctypedef

typedef struct mk_shadow_pass_desc mk_shadow_pass_desc

Data for shadow pass desc.

mk_shadow_prepare_desctypedef

typedef struct mk_shadow_prepare_desc mk_shadow_prepare_desc

Data for shadow prepare desc.

mk_shadow_settingstypedef

typedef struct mk_shadow_settings mk_shadow_settings

Data for shadow settings.

mk_shadow_statstypedef

typedef struct mk_shadow_stats mk_shadow_stats

Data for shadow stats.

Macros

MK_SHADOW_MAX_EXCEPTIONSdefine

MK_SHADOW_MAX_EXCEPTIONS

Maximum supported shadow exceptions.

MODKIT_MAX_SHADOW_PASSESdefine

MODKIT_MAX_SHADOW_PASSES

Maximum supported modkit shadow passes.