shader.h

#include <modkit/shader.h>21 functions · 6 structs · 1 enums · 5 typedefs · 7 macros

Shader and uniform abstraction.

GPU shader programs and uniforms. Uses generational handles for use-after-free detection. For low-level GPU interop, include modkit.h for escape hatch accessors.

Functions

`mk_shader_destroy`function

void mk_shader_destroy(mk_shader_t shader)

Get underlying GPU program handle (escape hatch).

Requires modkit.h. Destroy shader and release resources.

Parameter	Type	Description
`shader`	`mk_shader_t`	Value for shader.

`mk_shader_is_valid`function

bool mk_shader_is_valid(mk_shader_t shader)

Check if a shader is publicly valid and not pending destruction.

Parameter	Type	Description
`shader`	`mk_shader_t`	Value for shader.

Returns True when the condition holds.

`mk_shader_load`function

mk_shader_t mk_shader_load(const char *vs_path, const char *fs_path)

Load shader program from binary files.

Parameter	Type	Description
`vs_path`	`const char *`	Path to vertex shader .bin file
`fs_path`	`const char *`	Path to fragment shader .bin file

Returns Shader handle or MK_SHADER_INVALID on failure

`mk_shader_load_compute`function

mk_shader_t mk_shader_load_compute(const char *cs_path)

Load a COMPUTE program from a binary file.

A compute program is a single shader (no vertex/fragment). The returned mk_shader_t is used with mk_dispatch()/mk_encoder_dispatch().

Parameter	Type	Description
`cs_path`	`const char *`	Path to compute shader .bin file

Returns Shader handle or MK_SHADER_INVALID on failure

`mk_shader_load_compute_desc`function

mk_shader_t mk_shader_load_compute_desc(const mk_compute_shader_desc *desc)

Load a compute program with uniforms created before the program links.

Uniform ownership and lookup are identical to mk_shader_load_desc().

Parameter	Type	Description
`desc`	`const mk_compute_shader_desc *`	Configuration descriptor.

Returns The resulting handle or value.

`mk_shader_load_compute_mem`function

mk_shader_t mk_shader_load_compute_mem(const void *cs_data, uint32_t cs_size)

Load a COMPUTE program from memory (embedded data).

Parameter	Type	Description
`cs_data`	`const void *`	Compute shader data
`cs_size`	`uint32_t`	Compute shader size

Returns Shader handle or MK_SHADER_INVALID on failure

`mk_shader_load_desc`function

mk_shader_t mk_shader_load_desc(const mk_shader_desc *desc)

Load a shader program, creating the declared uniforms BEFORE the program links (see block comment above).

The uniforms are owned by the shader: look them up with mk_shader_uniform() and do NOT destroy them yourself mk_shader_destroy() releases them.

Parameter	Type	Description
`desc`	`const mk_shader_desc *`	Shader descriptor.

Returns Shader handle or MK_SHADER_INVALID on failure.

`mk_shader_load_mem`function

mk_shader_t mk_shader_load_mem(const void *vs_data, uint32_t vs_size, const void *fs_data, uint32_t fs_size)

Load shader program from memory (embedded data).

Parameter	Type	Description
`vs_data`	`const void *`	Vertex shader data
`vs_size`	`uint32_t`	Vertex shader size
`fs_data`	`const void *`	Fragment shader data
`fs_size`	`uint32_t`	Fragment shader size

Returns Shader handle or MK_SHADER_INVALID on failure

`mk_shader_pin`function

bool mk_shader_pin(mk_shader_t shader)

Perform the shader pin operation.

Parameter	Type	Description
`shader`	`mk_shader_t`	Value for shader.

Returns True when the operation succeeds.

`mk_shader_replace_compute_mem`function

mk_result mk_shader_replace_compute_mem(mk_shader_t shader, const void *cs_data, uint32_t cs_size)

Compute equivalent of mk_shader_replace_mem().

Parameter	Type	Description
`shader`	`mk_shader_t`	Value for shader.
`cs_data`	`const void *`	Value for cs data.
`cs_size`	`uint32_t`	Cs size in bytes.

Returns MK_SUCCESS or an error result.

`mk_shader_replace_mem`function

mk_result mk_shader_replace_mem(mk_shader_t shader, const void *vs_data, uint32_t vs_size, const void *fs_data, uint32_t fs_size)

Replace a graphics program without changing its public mk_shader_t handle.

Existing pipelines/materials resolve the new program automatically. The previous program remains active if the replacement cannot be created.

Parameter	Type	Description
`shader`	`mk_shader_t`	Value for shader.
`vs_data`	`const void *`	Value for vs data.
`vs_size`	`uint32_t`	Vs size in bytes.
`fs_data`	`const void *`	Value for fs data.
`fs_size`	`uint32_t`	Fs size in bytes.

Returns MK_SUCCESS or an error result.

`mk_shader_system_init`function

void mk_shader_system_init(void)

Initialize the shader system.

`mk_shader_system_shutdown`function

void mk_shader_system_shutdown(void)

Perform the shader system shutdown operation.

`mk_shader_uniform`function

mk_uniform_t mk_shader_uniform(mk_shader_t shader, const char *name)

Look up a uniform declared in the mk_shader_desc this shader was loaded with.

Returns MK_UNIFORM_INVALID for unknown names or shaders not loaded via mk_shader_load_desc().

Parameter	Type	Description
`shader`	`mk_shader_t`	Value for shader.
`name`	`const char *`	Stable name.

Returns The resulting handle or value.

`mk_shader_unpin`function

void mk_shader_unpin(mk_shader_t shader)

Perform the shader unpin operation.

Parameter	Type	Description
`shader`	`mk_shader_t`	Value for shader.

`mk_uniform_create`function

mk_uniform_t mk_uniform_create(const char *name, mk_uniform_type_t type, uint16_t count)

Create uniform.

Parameter	Type	Description
`name`	`const char *`	Uniform name (must match shader)
`type`	`mk_uniform_type_t`	Uniform type
`count`	`uint16_t`	Array count (1 for non-arrays)

Returns Uniform handle or MK_UNIFORM_INVALID on failure

`mk_uniform_destroy`function

void mk_uniform_destroy(mk_uniform_t uniform)

Get underlying GPU uniform handle (escape hatch).

Requires modkit.h. Destroy uniform and release resources.

Parameter	Type	Description
`uniform`	`mk_uniform_t`	Value for uniform.

`mk_uniform_info`function

bool mk_uniform_info(mk_uniform_t uniform, mk_uniform_info_t *out_info)

Query a uniform's name/type/array-count.

Returns false for an invalid handle.

Parameter	Type	Description
`uniform`	`mk_uniform_t`	Value for uniform.
`out_info`	`mk_uniform_info_t *`	Receives the info.

Returns True when the operation succeeds.

`mk_uniform_is_valid`function

bool mk_uniform_is_valid(mk_uniform_t uniform)

Check if uniform handle is valid.

Parameter	Type	Description
`uniform`	`mk_uniform_t`	Value for uniform.

Returns True when the condition holds.

`mk_uniform_pin`function

bool mk_uniform_pin(mk_uniform_t uniform)

Retain/release an internal reference.

New retains reject pending handles.

Parameter	Type	Description
`uniform`	`mk_uniform_t`	Value for uniform.

Returns True when the operation succeeds.

`mk_uniform_unpin`function

void mk_uniform_unpin(mk_uniform_t uniform)

Perform the uniform unpin operation.

Parameter	Type	Description
`uniform`	`mk_uniform_t`	Value for uniform.

Structs

`mk_compute_shader_desc`struct

Compute shader descriptor.

Uniform declarations follow the same ownership rules as mk_shader_desc: they are created before linking and destroyed with the returned shader handle.

Field	Type	Description
`name`	`const char *`	Debug name (optional, NULL ok).
`cs_data`	`const void *`	Compute shader binary.
`cs_size`	`uint32_t`	The cs size.
`uniforms`	`mk_shader_uniform_decl`	The uniforms.
`uniform_count`	`uint8_t`	0 => count non-NULL names

`mk_shader_desc`struct

Shader descriptor.

Zero-init = sane defaults. uniform_count 0 => entries are counted up to the first NULL name.

Field	Type	Description
`name`	`const char *`	Debug name (optional, NULL ok).
`vs_data`	`const void *`	Vertex shader binary.
`vs_size`	`uint32_t`	The vs size.
`fs_data`	`const void *`	Fragment shader binary.
`fs_size`	`uint32_t`	The fs size.
`uniforms`	`mk_shader_uniform_decl`	The uniforms.
`uniform_count`	`uint8_t`	0 => count non-NULL names

`mk_shader_t`struct

Data for shader.

Field	Type	Description
`id`	`uint32_t`	The ID.

`mk_shader_uniform_decl`struct

A uniform declaration: created before the program links.

Field	Type	Description
`name`	`const char *`	Uniform name (must match the shader).
`type`	`mk_uniform_type_t`	SAMPLER / VEC4 / MAT3 / MAT4.
`count`	`uint16_t`	Array count; 0 => 1.

`mk_uniform_info`struct

Uniform reflection info.

Field	Type	Description
`name`	`char`	uniform name as seen by the shader
`type`	`mk_uniform_type_t`	uniform type
`count`	`uint16_t`	array element count

`mk_uniform_t`struct

Data for uniform.

Field	Type	Description
`id`	`uint32_t`	The ID.

Enums

`mk_uniform_type`enum

Uniform types.

Value	Description
`MK_UNIFORM_SAMPLER`	Texture sampler.
`MK_UNIFORM_VEC4`	4 floats
`MK_UNIFORM_MAT3`	3x3 matrix
`MK_UNIFORM_MAT4`	4x4 matrix

Typedefs

`mk_compute_shader_desc`typedef

typedef struct mk_compute_shader_desc mk_compute_shader_desc

Compute shader descriptor.

Uniform declarations follow the same ownership rules as mk_shader_desc: they are created before linking and destroyed with the returned shader handle.

`mk_shader_desc`typedef

typedef struct mk_shader_desc mk_shader_desc

Shader descriptor.

Zero-init = sane defaults. uniform_count 0 => entries are counted up to the first NULL name.

`mk_shader_uniform_decl`typedef

typedef struct mk_shader_uniform_decl mk_shader_uniform_decl

A uniform declaration: created before the program links.

`mk_uniform_info_t`typedef

typedef struct mk_uniform_info mk_uniform_info_t

Uniform reflection info.

`mk_uniform_type_t`typedef

typedef enum mk_uniform_type mk_uniform_type_t

Uniform types.

Macros

`MK_SHADER_INVALID`define

MK_SHADER_INVALID

Invalid sentinel for shader.

`mk_shader_load_compute_multi`define

mk_shader_load_compute_multi(cs)

Helper macro for loading a multi-profile compute shader (runtime renderer selection).

Works with a cs_*.sc compiled via modkit_add_shaders_multi(). Usage: mk_shader_load_compute_multi(cs_plasma)

`mk_shader_load_embedded`define

mk_shader_load_embedded(vs, fs)

Helper macro for loading shader from embedded data (single profile).

Usage: mk_shader_load_embedded(vs_array, fs_array)

`mk_shader_load_multi`define

mk_shader_load_multi(vs, fs)

Helper macro for loading multi-profile shaders (runtime renderer selection).

Works with shaders compiled using modkit_add_shaders_multi(). The _data() and _size() functions are auto-generated in the shader header. Usage: mk_shader_load_multi(vs_name, fs_name) Example: mk_shader_load_multi(vs_cube, fs_cube)

`MK_SHADER_MAX_UNIFORMS`define

MK_SHADER_MAX_UNIFORMS

Maximum supported shader uniforms.

`MK_SHADER_MULTI`define

MK_SHADER_MULTI(vs, fs)

Initialize a desc's vs/fs fields from multi-profile embedded shaders (modkit_add_shaders_multi).

Use inside a mk_shader_desc initializer.

`MK_UNIFORM_INVALID`define

MK_UNIFORM_INVALID

Invalid sentinel for uniform.

shader.h

Functions

mk_shader_destroyfunction

mk_shader_is_validfunction

mk_shader_loadfunction

mk_shader_load_computefunction

mk_shader_load_compute_descfunction

mk_shader_load_compute_memfunction

mk_shader_load_descfunction

mk_shader_load_memfunction

mk_shader_pinfunction

mk_shader_replace_compute_memfunction

mk_shader_replace_memfunction

mk_shader_system_initfunction

mk_shader_system_shutdownfunction

mk_shader_uniformfunction

mk_shader_unpinfunction

mk_uniform_createfunction

mk_uniform_destroyfunction

mk_uniform_infofunction

mk_uniform_is_validfunction

mk_uniform_pinfunction

mk_uniform_unpinfunction

Structs

mk_compute_shader_descstruct

mk_shader_descstruct

mk_shader_tstruct

mk_shader_uniform_declstruct

mk_uniform_infostruct

mk_uniform_tstruct

Enums

mk_uniform_typeenum

Typedefs

mk_compute_shader_desctypedef

mk_shader_desctypedef

mk_shader_uniform_decltypedef

mk_uniform_info_ttypedef

mk_uniform_type_ttypedef

Macros

MK_SHADER_INVALIDdefine

mk_shader_load_compute_multidefine

mk_shader_load_embeddeddefine

mk_shader_load_multidefine

MK_SHADER_MAX_UNIFORMSdefine

MK_SHADER_MULTIdefine

MK_UNIFORM_INVALIDdefine

`mk_shader_destroy`function

`mk_shader_is_valid`function

`mk_shader_load`function

`mk_shader_load_compute`function

`mk_shader_load_compute_desc`function

`mk_shader_load_compute_mem`function

`mk_shader_load_desc`function

`mk_shader_load_mem`function

`mk_shader_pin`function

`mk_shader_replace_compute_mem`function

`mk_shader_replace_mem`function

`mk_shader_system_init`function

`mk_shader_system_shutdown`function

`mk_shader_uniform`function

`mk_shader_unpin`function

`mk_uniform_create`function

`mk_uniform_destroy`function

`mk_uniform_info`function

`mk_uniform_is_valid`function

`mk_uniform_pin`function

`mk_uniform_unpin`function

`mk_compute_shader_desc`struct

`mk_shader_desc`struct

`mk_shader_t`struct

`mk_shader_uniform_decl`struct

`mk_uniform_info`struct

`mk_uniform_t`struct

`mk_uniform_type`enum

`mk_compute_shader_desc`typedef

`mk_shader_desc`typedef

`mk_shader_uniform_decl`typedef

`mk_uniform_info_t`typedef

`mk_uniform_type_t`typedef

`MK_SHADER_INVALID`define

`mk_shader_load_compute_multi`define

`mk_shader_load_embedded`define

`mk_shader_load_multi`define

`MK_SHADER_MAX_UNIFORMS`define

`MK_SHADER_MULTI`define

`MK_UNIFORM_INVALID`define