# shader_system.h ## Overview
Implements the shader system.
## Index
`tm_shader_blob_header_t`
`tm_shader_o`
`tm_shader_system_o`
`TM_CREATION_GRAPH_UPDATE_SHADER_CONSTANT_AND_RESOURCES`
`TM_CREATION_GRAPH_UPDATE_SHADER_INSTANCE`
`struct tm_creation_graph_update_shader_constant_resource_t`

Shader declaration
`TM_SHADER_DECLARATION_API_NAME`
`tm_shader_declaration_o`
`enum TM_SHADER_STAGE`
`enum TM_SHADER_SYSTEM_MAX`

`struct tm_shader_declaration_api`
`clear()`
`append_declaration()`
`append_render_states()`
`append_serialized_render_states()`
`append_static_sampler_states()`
`request_channel()`
`set_constant()`
`set_resource()`
`set_payload()`
`set_stage_export()`
`set_stage_system_semantic_import()`
`set_stage_system_semantic_export()`
`set_stage_attribute()`
`append_patch_code()`
`append_code()`
`append_common_code()`

Shader system context
`tm_shader_system_context_o`
`TM_SHADER_SYSTEM_API_NAME`

`struct tm_shader_system_api`
`create_context()`
`clone_context()`
`destroy_context()`
`set_render_graph()`
`activate_system()`
`deactivate_system()`

Shader
`TM_SHADER_SYSTEM_UNINITIALIZED_INSTANCE`
`struct tm_shader_constant_buffer_instance_t`
`struct tm_shader_resource_binder_instance_t`
`TM_SHADER_API_NAME`
`struct tm_shader_constant_update_t`
`struct tm_shader_resource_update_t`
`tm_shader_io_o`

`struct tm_shader_api`

Shader IO API
`create_constant_buffer_instances()`
`create_constant_buffer_instances_from_template()`
`destroy_constant_buffer_instances()`
`create_resource_binder_instances()`
`destroy_resource_binder_instances()`

Constant buffer reflection and updating
`reflect_constants()`
`lookup_constant()`
`update_constants()`
`update_constants_raw()`
`update_constant_buffer_instances_from_template()`
`read_constant_buffer()`

Resource reflection and updating
`reflect_resources()`
`lookup_resource()`
`update_resources()`
`read_resource_slot()`

Shader API
`max_passes()`
`assemble_shader_infos()`
`shader_io()`
`system_io()`
`name()`
`shader_version()`
`system_version()`

Shader repository
`enum tm_shader_state_overrides`
`TM_SHADER_REPOSITORY_INSTANCE_NAME`
`tm_shader_repository_o`
`TM_SHADER_REPOSITORY_API_NAME`
`enum tm_shader_system_background_status`

`struct tm_shader_system_background_create_i`
`user_data`
`done()`

`struct tm_shader_repository_api`
`create()`
`destroy()`

The Truth
`set_the_truth()`
`create_truth_types()`
`import_truth_declaration_from_config()`
`destroy_truth_declaration()`
`lookup_truth_declaration()`
`lookup_declaration_validity_hash()`
`load_shader_declaration()`
`last_modified()`
`host_save_state()`
`client_load_state()`

Shader Declarations
`create_shader_declaration()`
`destroy_shader_declaration()`

Utilities
`generate_system_includes()`
`update_shaders_from_directory()`
`allocator()`

Compile
`refresh_truth_shaders()`
`lookup_or_create_shader()`
`lookup_or_create_system()`
`create_shader_from_blob()`
`compile_shader()`
`create_from_declaration()`
`background_create_from_declaration()`
`destroy_shader()`
`destroy_system()`
`lookup_shader()`
`lookup_system()`
`recycle_resources()`
`shader_state_override()`
`lookup_shader_blob()`

## API
### `tm_shader_blob_header_t`
~~~c typedef struct tm_shader_blob_header_t tm_shader_blob_header_t; ~~~
### `tm_shader_o`
~~~c typedef struct tm_shader_o tm_shader_o; ~~~
### `tm_shader_system_o`
~~~c typedef struct tm_shader_system_o tm_shader_system_o; ~~~
### `TM_CREATION_GRAPH_UPDATE_SHADER_CONSTANT_AND_RESOURCES`
~~~c #define TM_CREATION_GRAPH_UPDATE_SHADER_CONSTANT_AND_RESOURCES ~~~
### `TM_CREATION_GRAPH_UPDATE_SHADER_INSTANCE`
~~~c #define TM_CREATION_GRAPH_UPDATE_SHADER_INSTANCE ~~~
### `struct tm_creation_graph_update_shader_constant_resource_t`
~~~c typedef struct tm_creation_graph_update_shader_constant_resource_t { const struct tm_creation_graph_output_t *draw_calls; const struct tm_shader_constant_buffer_instance_t *cbuffers; const tm_tt_id_t io_interface; uint64_t entity_id; struct tm_entity_context_o *entity_ctx; } tm_creation_graph_update_shader_constant_resource_t; ~~~

Shader declaration

### `TM_SHADER_DECLARATION_API_NAME`
~~~c #define TM_SHADER_DECLARATION_API_NAME "tm_shader_declaration_api" ~~~
### `tm_shader_declaration_o`
~~~c typedef struct tm_shader_declaration_o tm_shader_declaration_o; ~~~
### `enum TM_SHADER_STAGE`
~~~c enum { TM_SHADER_STAGE_VERTEX = 0b00000000001, TM_SHADER_STAGE_HULL = 0b00000000010, TM_SHADER_STAGE_DOMAIN = 0b00000000100, TM_SHADER_STAGE_GEOMETRY = 0b00000001000, TM_SHADER_STAGE_PIXEL = 0b00000010000, TM_SHADER_STAGE_COMPUTE = 0b00000100000, TM_SHADER_STAGE_RAYGEN = 0b00001000000, TM_SHADER_STAGE_ANY_HIT = 0b00010000000, TM_SHADER_STAGE_CLOSEST_HIT = 0b00100000000, TM_SHADER_STAGE_MISS = 0b01000000000, TM_SHADER_STAGE_INTERSECTION = 0b10000000000, TM_SHADER_STAGE_ALL = 0b11111111111, TM_SHADER_STAGE_MAX_STAGES = 11 }; ~~~
### `enum TM_SHADER_SYSTEM_MAX`
~~~c enum { TM_SHADER_SYSTEM_MAX_PASSES = 16, TM_SHADER_SYSTEM_MAX_ACTIVE_SYSTEMS = 16 }; ~~~
### `struct tm_shader_declaration_api`
#### `clear()` ~~~c void (*clear)(tm_shader_declaration_o *inst); ~~~ Clears any data previously added to the declaration. #### `append_declaration()` ~~~c void (*append_declaration)(tm_shader_declaration_o *inst, const tm_shader_declaration_o *src); ~~~ Appends/merges contents of `src` declaration into `inst`. #### `append_render_states()` ~~~c void (*append_render_states)(tm_shader_declaration_o *inst, uint32_t block_type, const struct tm_renderer_state_value_pair_t *states, uint32_t num_states); ~~~ Creates or overrides already specified render states. `block_type` is one of `enum tm_renderer_state_block_type`. #### `append_serialized_render_states()` ~~~c void (*append_serialized_render_states)(tm_shader_declaration_o *inst, uint32_t block_type, const uint8_t *data); ~~~ Creates or overrides already specified render states from a serialized render state block `data`. #### `append_static_sampler_states()` ~~~c void (*append_static_sampler_states)(tm_shader_declaration_o *inst, tm_strhash_t state_block_name_hash, const struct tm_renderer_state_value_pair_t *states, uint32_t num_states); ~~~ Adds a sampler block from the specified states and returns a handle to it. #### `request_channel()` ~~~c void (*request_channel)(tm_shader_declaration_o *inst, uint32_t stage_flag, const char *channel_name); ~~~ Requests to activate a named channel declared as optional in the exports block. #### `set_constant()` ~~~c void (*set_constant)(tm_shader_declaration_o *inst, tm_shader_constant_t constant); ~~~ Declares a local constant, if a constant with the same name already exists it will be overwritten. #### `set_resource()` ~~~c void (*set_resource)(tm_shader_declaration_o *inst, tm_shader_resource_t resource); ~~~ Declares a local resource, if a resource with the same name already exists its type will be overwritten. #### `set_payload()` ~~~c void (*set_payload)(tm_shader_declaration_o *inst, tm_shader_payload_t payload); ~~~ Declares a payload, if a payload with the same name already exists it will be overwritten. #### `set_stage_export()` ~~~c void (*set_stage_export)(tm_shader_declaration_o *inst, uint32_t stage_flag, tm_shader_stage_export_t stage_export); ~~~ Declares a constant that will be exported to the next stage. #### `set_stage_system_semantic_import()` ~~~c void (*set_stage_system_semantic_import)(tm_shader_declaration_o *inst, uint32_t stage_flag, tm_shader_system_semantic_type type); ~~~ Declares that stage identified by `stage_flag` wants to import a system semantic value specified in `type`. #### `set_stage_system_semantic_export()` ~~~c void (*set_stage_system_semantic_export)(tm_shader_declaration_o *inst, uint32_t stage_flag, tm_shader_system_semantic_type type); ~~~ Declares that stage identified by `stage_flag` wants to export a system semantic value specified in `type`. #### `set_stage_attribute()` ~~~c void (*set_stage_attribute)(tm_shader_declaration_o *inst, uint32_t stage_flag, tm_shader_stage_attribute_t attr); ~~~ Adds a stage attribute (`attr`) to the stage identified by `stage_flag`. #### `append_patch_code()` ~~~c void (*append_patch_code)(tm_shader_declaration_o *inst, uint32_t domain, const char *code, const char *source_file, uint32_t source_line); ~~~ Appends a shader code block specific to the hull shader patch constants. #### `append_code()` ~~~c void (*append_code)(tm_shader_declaration_o *inst, uint32_t stage_flag, const char *code, const char *source_file, uint32_t source_line); ~~~ Appends a shader code block specified in `code` to the defined stages in `stage_flag`. `source_file` and `source_line` should specify the file and line number where the appended code block originated. It will be used for shader error messages. #### `append_common_code()` ~~~c void (*append_common_code)(tm_shader_declaration_o *inst, const char *code, const char *source_file, uint32_t source_line); ~~~ Appends a shader code block specified in `code` to the common code block.

Shader system context

### `tm_shader_system_context_o`
~~~c typedef struct tm_shader_system_context_o tm_shader_system_context_o; ~~~
### `TM_SHADER_SYSTEM_API_NAME`
~~~c #define TM_SHADER_SYSTEM_API_NAME "tm_shader_system_api" ~~~
### `struct tm_shader_system_api`
Threading: Externally synchronized #### `create_context()` ~~~c tm_shader_system_context_o *(*create_context)(struct tm_allocator_i *allocator, struct tm_render_graph_o *render_graph); ~~~ Creates a shader context. `render_graph` is optional. If provided it's used for translating layer name hashes into sort keys. #### `clone_context()` ~~~c tm_shader_system_context_o *(*clone_context)(const tm_shader_system_context_o *src_context, struct tm_allocator_i *allocator); ~~~ Clones an existing shader system context. #### `destroy_context()` ~~~c void (*destroy_context)(tm_shader_system_context_o *context); ~~~ Destroys the context #### `set_render_graph()` ~~~c void (*set_render_graph)(tm_shader_system_context_o *context, struct tm_render_graph_o *render_graph); ~~~ Associated a render graph with the shader system context #### `activate_system()` ~~~c void (*activate_system)(struct tm_shader_system_context_o *context, struct tm_shader_system_o *system, const struct tm_shader_constant_buffer_instance_t *cbuffer_instances, uint32_t num_cbuffer_instances, const struct tm_shader_resource_binder_instance_t *rbinder_instances, uint32_t num_rbinder_instances); ~~~ Activates the specified shader system #### `deactivate_system()` ~~~c void (*deactivate_system)(struct tm_shader_system_context_o *context, struct tm_shader_system_o *system); ~~~ Decativates the specified shader system.

Shader

### `TM_SHADER_SYSTEM_UNINITIALIZED_INSTANCE`
~~~c enum { TM_SHADER_SYSTEM_UNINITIALIZED_INSTANCE = 0xffffffff }; ~~~
### `struct tm_shader_constant_buffer_instance_t`
~~~c typedef struct tm_shader_constant_buffer_instance_t { // Instance ID used internally by [[tm_shader_api]] to locate constants data of this instance. uint32_t instance_id; } tm_shader_constant_buffer_instance_t; ~~~
### `struct tm_shader_resource_binder_instance_t`
~~~c typedef struct tm_shader_resource_binder_instance_t { // Instance ID used internally by [[tm_shader_api]] to locate resource data of this instance. uint32_t instance_id; } tm_shader_resource_binder_instance_t; ~~~
### `TM_SHADER_API_NAME`
~~~c #define TM_SHADER_API_NAME "tm_shader_api" ~~~
### `struct tm_shader_constant_update_t`
~~~c typedef struct tm_shader_constant_update_t { // Instance id from [[tm_shader_constant_buffer_instance_t]]. uint32_t instance_id; // Constant offset returned from [[lookup_constant()]] or [[reflect_constants()]]. uint32_t constant_offset; // Byte offset from start of constant. uint32_t first_byte; // Number of bytes to write from data. uint32_t num_bytes; // Constant data. const void *data; } tm_shader_constant_update_t; ~~~
### `struct tm_shader_resource_update_t`
~~~c typedef struct tm_shader_resource_update_t { // Instance id from [[tm_shader_resource_binder_instance_t]]. uint32_t instance_id; // Resource slot returned from [[lookup_resource()]] or [[reflect_resources()]]. uint32_t resource_slot; // Index of first resource to update (must be zero unless tm_shader_resource_t.elements > 1). uint32_t first_resource; // Number of resources to write. uint32_t num_resources; // Resource data. const tm_renderer_handle_t *resources; // Resource view aspect flags (optional). const uint32_t *resources_view_aspect_flags; } tm_shader_resource_update_t; ~~~
### `tm_shader_io_o`
~~~c typedef struct tm_shader_io_o tm_shader_io_o; ~~~
### `struct tm_shader_api`

Shader IO API

#### `create_constant_buffer_instances()` ~~~c void (*create_constant_buffer_instances)(tm_shader_io_o *io, uint32_t num_instances, tm_shader_constant_buffer_instance_t *result); ~~~ Allocates space in the shaders global constant buffer for one or many instances of the specified shader. Threading: Internally synchronized. #### `create_constant_buffer_instances_from_template()` ~~~c void (*create_constant_buffer_instances_from_template)(tm_shader_io_o *io, struct tm_renderer_resource_command_buffer_o *resource_buffer, uint32_t num_instances, tm_shader_constant_buffer_instance_t *result, const tm_shader_constant_buffer_instance_t cbuf_template); ~~~ Allocates space in the shaders global constant buffer for one or many instances of the specified shader and prepopulates it with value from an existing constant buffer. Threading: Internally synchornized. #### `destroy_constant_buffer_instances()` ~~~c void (*destroy_constant_buffer_instances)(tm_shader_io_o *io, tm_shader_constant_buffer_instance_t *instances, uint32_t num_instances); ~~~ Frees the space in the shader global constant buffer previously created using `create_constant_buffer_instances()`. Threading: Internally synchronized. #### `create_resource_binder_instances()` ~~~c void (*create_resource_binder_instances)(tm_shader_io_o *io, uint32_t num_instances, tm_shader_resource_binder_instance_t *result); ~~~ Allocates one or many resource binder instances for the specified shader. Threading: Internally synchronized. #### `destroy_resource_binder_instances()` ~~~c void (*destroy_resource_binder_instances)(tm_shader_io_o *io, tm_shader_resource_binder_instance_t *instances, uint32_t num_instances); ~~~ Frees resource binder instances previously created using `create_resource_binder_instances` Threading: Internally synchronized.

Constant buffer reflection and updating

#### `reflect_constants()` ~~~c void (*reflect_constants)(tm_shader_io_o *io, uint32_t *num_constants, tm_shader_constant_t *constants, uint32_t *constant_offsets); ~~~ Retrieve reflection information of all constants in the constant buffer. `constants` and `constant_offsets` should be arrays with at least `num_constants` elements. Call this function with `constants` and `constant_offsets` as NULL to retrieve the number of constants (`num_constants`). Threading: Free-threaded, efficient concurrent access. #### `lookup_constant()` ~~~c bool (*lookup_constant)(tm_shader_io_o *io, tm_strhash_t name, tm_shader_constant_t *constant, uint32_t *constant_offset); ~~~ Lookup constant by name. Threading: Free-threaded, efficient concurrent access. #### `update_constants()` ~~~c void (*update_constants)(tm_shader_io_o *io, struct tm_renderer_resource_command_buffer_o *resource_buffer, const tm_shader_constant_update_t *constant_updates, uint32_t num_updates); ~~~ Update one or many constants. Threading: Free-threaded, efficient concurrent access. #### `update_constants_raw()` ~~~c void (*update_constants_raw)(tm_shader_io_o *io, struct tm_renderer_resource_command_buffer_o *resource_buffer, const uint32_t *instance_ids, const void **data, uint32_t offset, uint32_t size, uint32_t num_updates); ~~~ Updates one or many constants by memcpy data into the constant buffer. Threading: Free-threaded, efficient concurrent access. `data` is array source data to copy from, `offset` is local offset into constant buffer in bytes, `size` is number of bytes to copy per update. #### `update_constant_buffer_instances_from_template()` ~~~c void (*update_constant_buffer_instances_from_template)(tm_shader_io_o *io, struct tm_renderer_resource_command_buffer_o *resource_buffer, uint32_t num_instances, tm_shader_constant_buffer_instance_t *instances, const tm_shader_constant_buffer_instance_t cbuf_template); ~~~ Update constant buffer instances from template #### `read_constant_buffer()` ~~~c const void *(*read_constant_buffer)(tm_shader_io_o *io, tm_shader_constant_buffer_instance_t instance); ~~~ Returns the first byte of the CPU copy of the constant buffer for `instance`.

Resource reflection and updating

#### `reflect_resources()` ~~~c void (*reflect_resources)(tm_shader_io_o *io, uint32_t *num_resources, tm_shader_resource_t *resources, uint32_t *resource_slots); ~~~ Retrieve reflection information of all resources (except the implicit constant buffer) associated with the shader. `resources` and `resource_slots` should be arrays with at least `num_resources` elements. Call this function with `resources` and `resources_slots` as NULL to retrieve the number of resource (`num_resources`). Threading: Free-threaded, efficient concurrent access. #### `lookup_resource()` ~~~c bool (*lookup_resource)(tm_shader_io_o *io, tm_strhash_t name, tm_shader_resource_t *resource, uint32_t *resource_slot); ~~~ Lookup resource by name. Threading: Free-threaded, efficient concurrent access. #### `update_resources()` ~~~c void (*update_resources)(tm_shader_io_o *io, struct tm_renderer_resource_command_buffer_o *resource_buffer, const tm_shader_resource_update_t *resource_updates, uint32_t num_updates); ~~~ Update one or many resources. Threading: Free-threaded, efficient concurrent access. #### `read_resource_slot()` ~~~c const tm_renderer_handle_t *(*read_resource_slot)(tm_shader_io_o *io, tm_shader_resource_binder_instance_t instance, uint32_t slot, const uint32_t **aspects); ~~~ Returns the first `tm_renderer_handle_t` for the specified resource `slot` from the CPU copy of the resource binder for `instance`. If `aspects` is not null it hold the matching resource view aspect flags.

Shader API

#### `max_passes()` ~~~c uint8_t (*max_passes)(tm_shader_o *shader); ~~~ Returns the maximum number of passes the specified shader wants to render. Used to size `results` output of `assemble_shader_infos()` correctly. #### `assemble_shader_infos()` ~~~c uint8_t (*assemble_shader_infos)(tm_shader_o *shader, const tm_renderer_handle_t *state_override_blocks, uint32_t num_state_override_blocks, const tm_shader_system_context_o *context, tm_strhash_t visibility_context, struct tm_renderer_resource_command_buffer_o *resource_buffer, const tm_shader_constant_buffer_instance_t *cbuf_instances, const tm_shader_resource_binder_instance_t *rbinder_instances, uint32_t num_shaders, struct tm_renderer_shader_info_t *results); ~~~ Assembles `tm_renderer_shader_info_t` structs ready to use to issue draw or dispatch calls. If any of the resource slots in `rbinder_intances` has been changed since last call to `assemble_shader_info` the backend resource binder resource will be updated on the `resource_buffer`. Threading: Free-threaded, efficient concurrent access. Returns `true` if the assembly succeeds and the data returned in `results` is valid, else returns `false`. #### `shader_io()` ~~~c tm_shader_io_o *(*shader_io)(tm_shader_o *shader); ~~~ Returns the shader io object from a shader. #### `system_io()` ~~~c tm_shader_io_o *(*system_io)(tm_shader_system_o *system); ~~~ Returns the shader io object from a system. #### `name()` ~~~c tm_strhash_t (*name)(const tm_shader_o *shader); ~~~ Returns a unique identifier/name for the shader. #### `shader_version()` ~~~c uint32_t (*shader_version)(const tm_shader_o *shader); ~~~ Returns the version number of the shader. The version number is bumbed if the shader is reloaded or any of its associated buffers are resized. This can be used to monitor if things like shader binding tables for ray tracing needs to be rebuilt. #### `system_version()` ~~~c uint32_t (*system_version)(const tm_shader_system_o *system); ~~~ Returns the version number of the shader system.

Shader repository

### `enum tm_shader_state_overrides`
~~~c typedef enum tm_shader_state_overrides { TM_SHADER_STATE_OVERRIDE_DOUBLE_SIDED, TM_SHADER_STATE_OVERRIDE_FRONT_FACE_CW, TM_SHADER_STATE_OVERRIDE_MAX_SHADER_STATE_OVERRIDES } tm_shader_state_overrides; ~~~
### `TM_SHADER_REPOSITORY_INSTANCE_NAME`
~~~c #define TM_SHADER_REPOSITORY_INSTANCE_NAME "tm_shader_repository_o" ~~~
### `tm_shader_repository_o`
~~~c typedef struct tm_shader_repository_o tm_shader_repository_o; ~~~
### `TM_SHADER_REPOSITORY_API_NAME`
~~~c #define TM_SHADER_REPOSITORY_API_NAME "tm_shader_repository_api" ~~~
### `enum tm_shader_system_background_status`
~~~c enum tm_shader_system_background_status { TM_SHADER_SYSTEM_BACKGROUND_CREATE_STATUS_SUCCESS, TM_SHADER_SYSTEM_BACKGROUND_CREATE_STATUS_CANCEL, TM_SHADER_SYSTEM_BACKGROUND_CREATE_STATUS_ERROR, }; ~~~
### `struct tm_shader_system_background_create_i`
#### `user_data` ~~~c void *user_data; ~~~ #### `done()` ~~~c void (*done)(enum tm_shader_system_background_status status, const tm_shader_blob_header_t *blob, uint64_t blob_size, void *user_data); ~~~
### `struct tm_shader_repository_api`
#### `create()` ~~~c tm_shader_repository_o *(*create)(struct tm_shader_system_io_o *system_io, struct tm_allocator_i *a, struct tm_renderer_backend_i *backend, struct tm_renderer_shader_compiler_api *shader_compiler_api, struct tm_the_truth_o *tt); ~~~ Creates a repository and associates it with the specified shader system io. #### `destroy()` ~~~c void (*destroy)(tm_shader_repository_o *inst, struct tm_renderer_resource_command_buffer_o *resource_buffer); ~~~ Destroys a repository

The Truth

#### `set_the_truth()` ~~~c void (*set_the_truth)(tm_shader_repository_o *inst, struct tm_the_truth_o *tt); ~~~ Associate shader repository with new truth. #### `create_truth_types()` ~~~c void (*create_truth_types)(struct tm_the_truth_o *tt); ~~~ #### `import_truth_declaration_from_config()` ~~~c tm_tt_id_t (*import_truth_declaration_from_config)(tm_shader_repository_o *inst, const struct tm_config_i *config, const struct tm_json_parse_info_t *pi, tm_strhash_t name, const uint64_t validity_hash, const struct tm_file_time_o *time_stamp, const char *filename); ~~~ Imports a declaration into The Truth from a config file. #### `destroy_truth_declaration()` ~~~c void (*destroy_truth_declaration)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Removed the named shader declaration from The Truth. #### `lookup_truth_declaration()` ~~~c tm_tt_id_t (*lookup_truth_declaration)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Looks up a shader declaration from The Truth using `name`. #### `lookup_declaration_validity_hash()` ~~~c uint64_t (*lookup_declaration_validity_hash)(tm_shader_repository_o *inst, tm_tt_id_t id); ~~~ Returns the validity hash of the specified declaration (`id`). The validity hash is built dynamically from the validity hash of the declaration itself, combined with the validity hash of all of its dependencies (includes, and systems). #### `load_shader_declaration()` ~~~c void (*load_shader_declaration)(tm_shader_repository_o *inst, tm_shader_declaration_o *declaration, tm_tt_id_t id); ~~~ Populates a shader declaration from a Truth shader declaration identifies by `id` #### `last_modified()` ~~~c void (*last_modified)(tm_shader_repository_o *inst, tm_tt_id_t id, struct tm_file_time_o *modified); ~~~ Returns the timestamp associated with The Truth shader declaration identified by `id`. #### `host_save_state()` ~~~c void (*host_save_state)(tm_shader_repository_o *inst, char **carray, struct tm_allocator_i *a); ~~~ State serialization for collaboration. #### `client_load_state()` ~~~c void (*client_load_state)(tm_shader_repository_o *inst, struct tm_the_truth_o *tt, const char **state); ~~~

Shader Declarations

#### `create_shader_declaration()` ~~~c tm_shader_declaration_o *(*create_shader_declaration)(tm_shader_repository_o *inst, struct tm_allocator_i *a); ~~~ Creates an empty shader declaration. #### `destroy_shader_declaration()` ~~~c void (*destroy_shader_declaration)(tm_shader_repository_o *inst, tm_shader_declaration_o *declaration); ~~~ Destroys a shader declaration.

Utilities

#### `generate_system_includes()` ~~~c void (*generate_system_includes)(tm_shader_repository_o *inst, const char *output_path); ~~~ Generates raw C-structs for all system declarations found in the repository and writes them to separate files on disk under the specified output path. #### `update_shaders_from_directory()` ~~~c void (*update_shaders_from_directory)(struct tm_shader_repository_o *inst, const char *dir, bool recursive, struct tm_allocator_i *allocator, struct tm_renderer_resource_command_buffer_o *res_buf); ~~~ Loads new and updates dirty `.shader` files from `dir` and imports them into the shader repository. Note: This is somewhat temporary until we have a clearer concept of disk io. #### `allocator()` ~~~c struct tm_allocator_i *(*allocator)(tm_shader_repository_o *inst); ~~~ Returns the allocator owned by the repository.

Compile

#### `refresh_truth_shaders()` ~~~c void (*refresh_truth_shaders)(tm_shader_repository_o *inst); ~~~ Creates and compiles any dirty compilable shader declarations found in The Truth. #### `lookup_or_create_shader()` ~~~c tm_shader_o *(*lookup_or_create_shader)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Tries to look up a shader with `name` in the shader repository, if no shader with that name has been created a new shader is created, inserted into the repository and returned. #### `lookup_or_create_system()` ~~~c tm_shader_system_o *(*lookup_or_create_system)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Tries to look up a system with `name` in the shader repository, if no shader with that name has been created a new shader is created, inserted into the repository and returned. #### `create_shader_from_blob()` ~~~c tm_shader_o *(*create_shader_from_blob)(tm_shader_repository_o *inst, struct tm_renderer_resource_command_buffer_o *res_buf, const tm_shader_blob_header_t *shader_blob); ~~~ Creates a shader from a serialized shader blob. Thread-safety: internally synchronized. #### `compile_shader()` ~~~c bool (*compile_shader)(tm_shader_repository_o *inst, struct tm_renderer_resource_command_buffer_o *res_buf, tm_shader_o *shader, uint32_t active_shader_stages, uint64_t active_systems_bitmask, const tm_strhash_t *active_system_names, const tm_shader_declaration_o **active_systems, uint32_t num_active_systems, const tm_shader_declaration_o **declarations, uint32_t num_declarations, uint64_t validity_hash); ~~~ Tries to compile a shader variation defined by any number of active shader system specified in active_systems`, together with one or many shader declarations specified in `declarations`, if the compile succeeds the variation is inserted into `tm_shader_o` and true is returned. Thread-safety: externally synchronized. #### `create_from_declaration()` ~~~c bool (*create_from_declaration)(tm_shader_repository_o *inst, struct tm_renderer_resource_command_buffer_o *res_buf, tm_tt_id_t declaration, tm_strhash_t name, struct tm_shader_declaration_o *generated_code, const struct tm_shader_creation_graph_data_o *creation_graph_data); ~~~ Creates a `tm_shader_o` or `tm_shader_system_o` from a `TM_TT_TYPE__SHADER_SYSTEM_DECLARATION` passed in `declaration`. 'name' and 'generated_code' are optional parameters. If no name is specified `TM_TT_PROP__SHADER_DECLARATION__NAME` will be used. Thread-safety: externally synchronized. #### `background_create_from_declaration()` ~~~c void (*background_create_from_declaration)(tm_shader_repository_o *inst, tm_tt_id_t declaration, tm_strhash_t name, struct tm_shader_declaration_o *generated_code, const struct tm_shader_creation_graph_data_o *creation_graph_data, const tm_shader_system_background_create_i *callback); ~~~ Same as `create_from_declaration()` but runs the creation as a background task, when finished the `tm_shader_system_background_create_i->done()` will be called. User is responsible for keeping the 'generated_code' declaration alive until the creation process has completed. Compiled result will be stored as truth buffer and passed to `tm_shader_system_background_create_i`. Thread-safety: Internally synchronized #### `destroy_shader()` ~~~c void (*destroy_shader)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Destroys a previously created shader with the name `name`. #### `destroy_system()` ~~~c void (*destroy_system)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Destroys a previously created shader system with the name `name`. #### `lookup_shader()` ~~~c tm_shader_o *(*lookup_shader)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Looks up a previously created shader with the name `name`. #### `lookup_system()` ~~~c tm_shader_system_o *(*lookup_system)(tm_shader_repository_o *inst, tm_strhash_t name); ~~~ Looks up a previously created shader system with the name `name`. #### `recycle_resources()` ~~~c void (*recycle_resources)(tm_shader_repository_o *inst); ~~~ This should be called once per frame to recycle any pending shader resources. #### `shader_state_override()` ~~~c tm_renderer_handle_t (*shader_state_override)(tm_shader_repository_o *inst, tm_shader_state_overrides state_override); ~~~ Returns a render handle for the requested shader state override block. #### `lookup_shader_blob()` ~~~c const tm_shader_blob_header_t *(*lookup_shader_blob)(tm_shader_repository_o *inst, tm_strhash_t name, uint64_t *size); ~~~ Looks up a previously compiled shader blob (used as a high-level shader cache). Size of blob is returned in `size`.