material.h

#include <modkit/material.h>26 functions · 4 structs · 4 enums · 8 typedefs · 3 macros

Material how an object shades (the three.js ShaderMaterial analog).

A material is unopinionated: a way-to-shade (a pipeline, or a shader+state the engine bakes into one) plus the uniform VALUES and textures that shader needs. It owns NO lights lighting is a separate frame-level concern (lighting.h); the built-in lit material's shader reads light uniforms from there. It's just a reusable bundle over the spine. During draw resolution, material state expands first and the common resolver appends enabled providers before applying explicit draw bindings last. mk_material_t m = mk_material_unlit(0xff8844ff, MK_TEXTURE_INVALID); mk_pass_draw(&(mk_draw_desc){ .geometry = sphere, .material = m, .transform = mtx });

Functions

mk_material_alpha_modefunction

mk_material_alpha_mode_t mk_material_alpha_mode(mk_material_t)

Perform the material alpha mode operation.

Parameter	Type	Description
	mk_material_t	—

Returns The resulting handle or value.

mk_material_applyfunction

void mk_material_apply(mk_material_t, struct mk_draw_desc *out)

Apply material.

Parameter	Type	Description
	mk_material_t	—
out	struct mk_draw_desc *	Value for out.

mk_material_createfunction

mk_material_t mk_material_create(const mk_material_desc *desc)

The general way.

Uniform/sampler names resolve through the shader (which must

Parameter	Type	Description
desc	const mk_material_desc *	Configuration descriptor.

Returns The resulting handle or value. have declared them, e.g. via mk_shader_load_desc).

mk_material_desc_initfunction

mk_material_desc mk_material_desc_init(void)

Initialize a descriptor including explicit invalid-handle sentinels.

Returns The resulting value.

mk_material_destroyfunction

void mk_material_destroy(mk_material_t)

Destroy the material.

Parameter	Type	Description
	mk_material_t	—

mk_material_instanced_pipelinefunction

mk_pipeline_t mk_material_instanced_pipeline(mk_material_t)

Perform the material instanced pipeline operation.

Parameter	Type	Description
	mk_material_t	—

Returns The resulting handle or value.

mk_material_is_validfunction

bool mk_material_is_valid(mk_material_t m)

Test whether the material is valid.

Parameter	Type	Description
m	mk_material_t	Value for m.

Returns True when the condition holds.

mk_material_litfunction

mk_material_t mk_material_lit(uint32_t base_color, mk_texture_t albedo, float shininess)

Lit (Blinn-Phong), shaded by the frame-level light (lighting.h).

base_color

Parameter	Type	Description
base_color	uint32_t	Value for base color.
albedo	mk_texture_t	Value for albedo.
shininess	float	Value for shininess.

Returns The resulting handle or value. RGBA; albedo optional (MK_TEXTURE_INVALID => white); shininess 0 => default.

mk_material_pass_variantfunction

mk_material_t mk_material_pass_variant(mk_material_t, mk_material_pass_role role)

Perform the material pass variant operation.

Parameter	Type	Description
	mk_material_t	—
role	mk_material_pass_role	Value for role.

Returns The resulting handle or value.

mk_material_pinfunction

bool mk_material_pin(mk_material_t)

Perform the material pin operation.

Parameter	Type	Description
	mk_material_t	—

Returns True when the operation succeeds.

mk_material_pipelinefunction

mk_pipeline_t mk_material_pipeline(mk_material_t)

Perform the material pipeline operation.

Parameter	Type	Description
	mk_material_t	—

Returns The resulting handle or value.

mk_material_providersfunction

mk_shader_provider_mask_t mk_material_providers(mk_material_t)

Perform the material providers operation.

Parameter	Type	Description
	mk_material_t	—

Returns The resulting handle or value.

mk_material_set_colorfunction

void mk_material_set_color(mk_material_t, uint32_t rgba)

Set color on the material.

Parameter	Type	Description
	mk_material_t	—
rgba	uint32_t	Value for RGBA.

mk_material_set_env_providerfunction

void mk_material_set_env_provider(mk_material_env_provider provider)

Set env provider on the material.

Parameter	Type	Description
provider	mk_material_env_provider	Value for provider.

mk_material_set_mat4function

void mk_material_set_mat4(mk_material_t, const char *name, const float v[16])

Set mat4 on the material.

Parameter	Type	Description
	mk_material_t	—
name	const char *	Stable name.
v	const float	Value for v.

mk_material_set_pass_variantfunction

mk_result mk_material_set_pass_variant(mk_material_t material, mk_material_pass_role role, mk_material_t variant)

Atomically replace one non-color pass dependency.

Self-reference and dependency cycles are rejected without changing the

Parameter	Type	Description
material	mk_material_t	Value for material.
role	mk_material_pass_role	Value for role.
variant	mk_material_t	Value for variant.

Returns MK_SUCCESS or an error result. previous variant. Pass MK_MATERIAL_INVALID to clear the role.

mk_material_set_texturefunction

void mk_material_set_texture(mk_material_t, uint8_t stage, const char *sampler, mk_texture_t)

Set texture on the material.

Parameter	Type	Description
	mk_material_t	—
stage	uint8_t	Value for stage.
sampler	const char *	Value for sampler.
	mk_texture_t	—

mk_material_set_texture_samplerfunction

void mk_material_set_texture_sampler(mk_material_t, uint8_t stage, const char *sampler, mk_texture_t, uint32_t sampler_flags)

Set texture sampler on the material.

Parameter	Type	Description
	mk_material_t	—
stage	uint8_t	Value for stage.
sampler	const char *	Value for sampler.
	mk_texture_t	—
sampler_flags	uint32_t	Value for sampler flags.

mk_material_set_transmission_providerfunction

void mk_material_set_transmission_provider(mk_material_env_provider provider)

Register the transmission provider invoked for draws requesting MK_PROVIDER_TRANSMISSION (the PBR package registers this from mk_pbr_transmission_capture).

It appends the captured opaque-scene framebuffer +

Parameter	Type	Description
provider	mk_material_env_provider	Value for provider. view-projection + frame params. Pass NULL to unregister.

mk_material_set_vec4function

void mk_material_set_vec4(mk_material_t, const char *name, const float v[4])

Set vec4 on the material.

Parameter	Type	Description
	mk_material_t	—
name	const char *	Stable name.
v	const float	Value for v.

mk_material_shaderfunction

mk_material_t mk_material_shader(mk_pipeline_t pipeline)

Custom material over a pre-baked pipeline (also the 2D shader-paint path).

Parameter	Type	Description
pipeline	mk_pipeline_t	Value for pipeline.

Returns The resulting handle or value. Set uniform values/textures via the setters below.

mk_material_system_initfunction

void mk_material_system_init(void)

Initialize the material system.

mk_material_system_shutdownfunction

void mk_material_system_shutdown(void)

Perform the material system shutdown operation.

mk_material_traitsfunction

uint32_t mk_material_traits(mk_material_t)

Perform the material traits operation.

Parameter	Type	Description
	mk_material_t	—

Returns The resulting value.

mk_material_unlitfunction

mk_material_t mk_material_unlit(uint32_t base_color, mk_texture_t albedo)

Unlit: albedo * base_color * vertex_color.

base_color is RGBA 0xRRGGBBAA;

Parameter	Type	Description
base_color	uint32_t	Value for base color.
albedo	mk_texture_t	Value for albedo.

Returns The resulting handle or value. pass MK_TEXTURE_INVALID for albedo to use a white default.

mk_material_unpinfunction

void mk_material_unpin(mk_material_t)

Perform the material unpin operation.

Parameter	Type	Description
	mk_material_t	—

Structs

mk_material_descstruct

Data for material desc.

Field	Type	Description
name	const char *	The name.
pipeline	mk_pipeline_t	HOW to shade (preferred).
shader	mk_shader_t	...or inline shortcut: engine bakes a pipeline iff pipeline invalid
state	uint64_t	inline-shortcut state; 0 => sensible 3D default
uniforms	mk_material_uniform	The uniforms.
uniform_count	uint8_t	The uniform count.
textures	mk_material_texture	The textures.
texture_count	uint8_t	The texture count.
providers	mk_shader_provider_mask_t	The providers.
alpha_mode	mk_material_alpha_mode_t	The alpha mode.
traits	uint32_t	The traits.
instanced_pipeline	mk_pipeline_t	compatible 64-byte matrix ABI, or invalid
shadow_compare_pipeline	mk_pipeline_t	Optional hardware-comparison receiver programs.
shadow_compare_instanced_pipeline	mk_pipeline_t	The shadow compare instanced pipeline.
shadow_compare_shader	mk_shader_t	The shadow compare shader.
shadow_compare_instanced_shader	mk_shader_t	The shadow compare instanced shader.
pass_variants	mk_material_t	The pass variants.

mk_material_tstruct

Data for material.

Field	Type	Description
id	uint32_t	The ID.

mk_material_texturestruct

A texture binding carried by the material.

Field	Type	Description
sampler	const char *	sampler uniform name in the shader
stage	uint8_t	texture stage
texture	mk_texture_t	strongly retained by the material
sampler_flags	uint32_t	MK_SAMPLER_* override.
has_sampler_override	bool	false uses texture sampler state

mk_material_uniformstruct

A uniform value carried by the material.

name must match the shader.

Field	Type	Description
name	const char *	The name.
type	mk_uniform_type_t	VEC4 / MAT3 / MAT4.
value	float	up to a mat4

Enums

@017300340270265270115177205060162102132317054335enum

Values for provider.

Value	Description
MK_PROVIDER_VIEW	Selects view.
MK_PROVIDER_OUTPUT	Selects output.
MK_PROVIDER_AMBIENT	Selects ambient.
MK_PROVIDER_DIRECT_LIGHTS	Selects direct lights.
MK_PROVIDER_CLUSTERS	Selects clusters.
MK_PROVIDER_SHADOWS	Selects shadows.
MK_PROVIDER_IBL	Selects ibl.
MK_PROVIDER_TRANSMISSION	Selects transmission.

mk_material_alpha_mode_tenum

Values for material alpha mode.

Value	Description
MK_MATERIAL_ALPHA_OPAQUE	Selects opaque.
MK_MATERIAL_ALPHA_MASK	Selects mask.
MK_MATERIAL_ALPHA_BLEND	Selects blend.

mk_material_pass_roleenum

Values for material pass role.

Value	Description
MK_MATERIAL_PASS_COLOR	Selects color.
MK_MATERIAL_PASS_SHADOW_DEPTH	Selects shadow depth.
MK_MATERIAL_PASS_SHADOW_PACKED_DEPTH	Selects shadow packed depth.
MK_MATERIAL_PASS_COUNT	Selects count.

mk_material_trait_tenum

Values for material trait.

Value	Description
MK_MATERIAL_TRAIT_TRANSMISSIVE	Selects transmissive.
MK_MATERIAL_TRAIT_SHADOW_CAPABLE	Selects shadow capable.
MK_MATERIAL_TRAIT_INSTANCING_CAPABLE	Selects instancing capable.

Typedefs

mk_material_alpha_mode_ttypedef

typedef enum mk_material_alpha_mode_t mk_material_alpha_mode_t

Values for material alpha mode.

mk_material_desctypedef

typedef struct mk_material_desc mk_material_desc

Data for material desc.

mk_material_env_providertypedef

typedef void(*) mk_material_env_provider(struct mk_draw_desc *out)

Register the environment provider invoked for draws requesting MK_PROVIDER_IBL.

The provider appends its uniforms/textures (SH, prefiltered, BRDF LUT, params) to the draw. Pass NULL to unregister. Core has no IBL dependency of its own.

mk_material_pass_roletypedef

typedef enum mk_material_pass_role mk_material_pass_role

Values for material pass role.

mk_material_texturetypedef

typedef struct mk_material_texture mk_material_texture

A texture binding carried by the material.

mk_material_trait_ttypedef

typedef enum mk_material_trait_t mk_material_trait_t

Values for material trait.

mk_material_uniformtypedef

typedef struct mk_material_uniform mk_material_uniform

A uniform value carried by the material.

name must match the shader.

mk_shader_provider_mask_ttypedef

typedef uint32_t mk_shader_provider_mask_t

Type used for shader provider mask.

Macros

MK_MATERIAL_INVALIDdefine

MK_MATERIAL_INVALID

Invalid sentinel for material.

MK_MATERIAL_MAX_TEXTURESdefine

MK_MATERIAL_MAX_TEXTURES

Maximum supported material textures.

MK_MATERIAL_MAX_UNIFORMSdefine

MK_MATERIAL_MAX_UNIFORMS

Maximum supported material uniforms.