assets.h

#include <modkit/assets.h>42 functions · 5 structs · 4 enums · 16 typedefs · 4 macros

Unified asset loading system with path resolution.

Provides a unified interface for loading various asset types (models, textures, fonts, audio, files) with support for search paths to simplify asset management across platforms. Usage:

Functions

mk_asset_mount_validfunction

bool mk_asset_mount_valid(mk_asset_mount_t mount)

Perform the asset mount valid operation.

Parameter	Type	Description
mount	mk_asset_mount_t	Value for mount.

Returns True when the operation succeeds.

mk_asset_request_validfunction

bool mk_asset_request_valid(mk_asset_request_t req)

Request valid for the asset.

Parameter	Type	Description
req	mk_asset_request_t	Value for req.

Returns True when the operation succeeds.

mk_assets_add_pathfunction

bool mk_assets_add_path(const char *path)

Add a search path for asset resolution.

Paths are searched in the order they were added.

Parameter	Type	Description
path	const char *	Directory path to search (will be copied)

Returns true if path was added, false if max paths reached

mk_assets_cancelfunction

void mk_assets_cancel(mk_asset_request_t request)

Cancel a pending async request.

Callback will NOT be called after cancellation.

Parameter	Type	Description
request	mk_asset_request_t	Request handle from async load call

mk_assets_clear_pathsfunction

void mk_assets_clear_paths(void)

Clear all search paths.

mk_assets_existsfunction

bool mk_assets_exists(const char *path)

Check if a file exists at the given path.

Parameter	Type	Description
path	const char *	Path to check (absolute or relative)

Returns true if file exists

mk_assets_get_pathfunction

const char * mk_assets_get_path(int index)

Get a search path by index.

Parameter	Type	Description
index	int	Path index (0 to path_count-1)

Returns Path string or NULL if index is invalid

mk_assets_get_path_countfunction

int mk_assets_get_path_count(void)

Get number of registered search paths.

Returns The resulting value.

mk_assets_get_statefunction

mk_asset_state_t mk_assets_get_state(mk_asset_request_t request)

Get the current state of an async request.

Parameter	Type	Description
request	mk_asset_request_t	Request handle

Returns Current state or MK_ASSET_STATE_ERROR if invalid

mk_assets_initfunction

bool mk_assets_init(void)

Initialize the assets system.

Called automatically on first use.

Returns true on success

mk_assets_load_atlas_assetfunction

mk_atlas_t mk_assets_load_atlas_asset(const char *catalog_path)

Load an atlas through loose paths or mounted catalogs.

catalog_path is a base logical path. The loader reads <path>.png and <path>.json, uploads the image, and parses TexturePacker metadata.

Parameter	Type	Description
catalog_path	const char *	Value for catalog path.

Returns The resulting handle or value.

mk_assets_load_compute_shaderfunction

mk_shader_t mk_assets_load_compute_shader(const char *logical_id)

Load a cooked compute shader variant for the active bgfx renderer.

Declared catalog uniforms follow the same ownership rules as graphics shaders.

Parameter	Type	Description
logical_id	const char *	Value for logical ID.

Returns The resulting handle or value.

mk_assets_load_filefunction

void * mk_assets_load_file(const char *path, size_t *out_size)

Load raw file data into memory using search paths.

The returned data must be freed by the caller using free().

Parameter	Type	Description
path	const char *	Relative or absolute path to file
out_size	size_t *	Pointer to receive file size (can be NULL)

Returns Pointer to file data or NULL on failure

mk_assets_load_file_asyncfunction

mk_asset_request_t mk_assets_load_file_async(const char *path, mk_asset_data_callback_t callback, mk_asset_progress_callback_t progress_cb, void *user_data)

Load a file asynchronously.

On web: uses Fetch API with progress tracking. On native: uses async I/O or processes in poll loop.

Parameter	Type	Description
path	const char *	Path to file (resolved via search paths)
callback	mk_asset_data_callback_t	Called when load completes (data must be freed by caller)
progress_cb	mk_asset_progress_callback_t	Called during loading (can be NULL)
user_data	void *	Passed to callbacks

Returns Request handle for cancellation/status

mk_assets_load_fontfunction

mk_font_t mk_assets_load_font(const char *path, float size)

Load a font using search paths.

Parameter	Type	Description
path	const char *	Relative or absolute path to font file
size	float	Font size in pixels

Returns Font handle or MK_FONT_INVALID on failure

mk_assets_load_font_asyncfunction

mk_asset_request_t mk_assets_load_font_async(const char *path, float size, mk_asset_font_callback_t callback, mk_asset_progress_callback_t progress_cb, void *user_data)

Load a font asynchronously.

Parameter	Type	Description
path	const char *	Value for path.
size	float	Size in bytes.
callback	mk_asset_font_callback_t	Completion callback.
progress_cb	mk_asset_progress_callback_t	Value for progress.
user_data	void *	Caller-provided context.

Returns The resulting handle or value.

mk_assets_load_font_exfunction

mk_font_t mk_assets_load_font_ex(const mk_font_load_desc_t *desc)

Load a raw or cooked font through asset search paths with explicit options.

desc->path is resolved by the asset system; desc->data is ignored.

Parameter	Type	Description
desc	const mk_font_load_desc_t *	Configuration descriptor.

Returns The resulting handle or value.

mk_assets_load_giffunction

mk_gif_t mk_assets_load_gif(const char *path, const mk_gif_desc *desc)

Load an animated GIF using asset search paths.

Parameter	Type	Description
path	const char *	Value for path.
desc	const mk_gif_desc *	Configuration descriptor.

Returns The resulting handle or value.

mk_assets_load_gif_asyncfunction

mk_asset_request_t mk_assets_load_gif_async(const char *path, const mk_gif_desc *desc, mk_asset_gif_callback_t callback, mk_asset_progress_callback_t progress_cb, void *user_data)

Load and decode an animated GIF asynchronously.

Native builds read, validate, and decode on the asset worker, then create the texture and invoke the callback on the main thread. Web builds perform validation, decode, and texture creation in the fetch completion path.

Parameter	Type	Description
path	const char *	Value for path.
desc	const mk_gif_desc *	Configuration descriptor.
callback	mk_asset_gif_callback_t	Completion callback.
progress_cb	mk_asset_progress_callback_t	Value for progress.
user_data	void *	Caller-provided context.

Returns The resulting handle or value.

mk_assets_load_shaderfunction

mk_shader_t mk_assets_load_shader(const char *logical_id)

Load a cooked graphics shader variant for the active bgfx renderer.

Declared catalog uniforms are created before linking and owned by the shader.

Parameter	Type	Description
logical_id	const char *	Value for logical ID.

Returns The resulting handle or value.

mk_assets_load_soundfunction

mk_result mk_assets_load_sound(const char *path, const mk_sound_desc *desc, mk_sound_t *out_sound)

Load a sound using search paths.

Supports: WAV, MP3, OGG, FLAC

Parameter	Type	Description
path	const char *	Relative or absolute path to audio file
desc	const mk_sound_desc *	Sound loading descriptor. NULL inherits cooked streaming and spatial defaults for catalog audio, or ordinary defaults for uncooked files. A non-NULL descriptor overrides cooked policy.
out_sound	mk_sound_t *	Receives the sound handle

Returns MK_SUCCESS or an error result.

mk_assets_load_sound_asyncfunction

mk_asset_request_t mk_assets_load_sound_async(const char *path, const mk_sound_desc *desc, mk_asset_sound_callback_t callback, mk_asset_progress_callback_t progress_cb, void *user_data)

Load a sound asynchronously.

A NULL descriptor inherits cooked audio policy using the same rules as mk_assets_load_sound().

Parameter	Type	Description
path	const char *	Value for path.
desc	const mk_sound_desc *	Configuration descriptor.
callback	mk_asset_sound_callback_t	Completion callback.
progress_cb	mk_asset_progress_callback_t	Value for progress.
user_data	void *	Caller-provided context.

Returns The resulting handle or value.

mk_assets_load_stringfunction

char * mk_assets_load_string(const char *path)

Load file as null-terminated string using search paths.

The returned string must be freed by the caller using free().

Parameter	Type	Description
path	const char *	Relative or absolute path to file

Returns Null-terminated string or NULL on failure

mk_assets_load_texturefunction

mk_texture_t mk_assets_load_texture(const char *path, uint32_t flags)

Load a texture using search paths.

Supports: PNG, JPG, TGA, BMP, HDR, EXR

Parameter	Type	Description
path	const char *	Relative or absolute path to texture file
flags	uint32_t	Loading flags (MK_TEXTURE_*)

Returns Texture handle or MK_TEXTURE_INVALID on failure

mk_assets_load_texture_asyncfunction

mk_asset_request_t mk_assets_load_texture_async(const char *path, uint32_t flags, mk_asset_texture_callback_t callback, mk_asset_progress_callback_t progress_cb, void *user_data)

Load a texture asynchronously.

Parameter	Type	Description
path	const char *	Value for path.
flags	uint32_t	Value for flags.
callback	mk_asset_texture_callback_t	Completion callback.
progress_cb	mk_asset_progress_callback_t	Value for progress.
user_data	void *	Caller-provided context.

Returns The resulting handle or value.

mk_assets_load_videofunction

mk_result mk_assets_load_video(const char *logical_id, const mk_video_desc *desc, mk_video_t *out_video)

Create and asynchronously open a video from a logical asset stream.

Parameter	Type	Description
logical_id	const char *	Value for logical ID.
desc	const mk_video_desc *	Configuration descriptor.
out_video	mk_video_t *	Receives the video.

Returns MK_SUCCESS or an error result.

mk_assets_mountfunction

mk_asset_mount_t mk_assets_mount(const char *catalog_directory, int32_t priority)

Mount a cooked loose catalog directory.

Higher priorities shadow lower priorities; newer mounts win equal priorities.

Parameter	Type	Description
catalog_directory	const char *	Value for catalog directory.
priority	int32_t	Value for priority.

Returns The resulting handle or value.

mk_assets_pollfunction

void mk_assets_poll(void)

Poll async asset loading.

Processes completed downloads and invokes callbacks. On native: also processes pending sync loads. Called automatically by mk_frame_begin() if using mk_app_run().

mk_assets_remove_pathfunction

bool mk_assets_remove_path(const char *path)

Remove a search path.

Parameter	Type	Description
path	const char *	Path to remove

Returns true if path was found and removed

mk_assets_replace_compute_shaderfunction

mk_result mk_assets_replace_compute_shader(const char *logical_id, mk_shader_t shader)

Compute equivalent of mk_assets_replace_shader().

Parameter	Type	Description
logical_id	const char *	Value for logical ID.
shader	mk_shader_t	Value for shader.

Returns MK_SUCCESS or an error result.

mk_assets_replace_shaderfunction

mk_result mk_assets_replace_shader(const char *logical_id, mk_shader_t shader)

Replace a live shader's program from the latest cooked catalog variant without changing its handle.

Pipelines and materials keep referring to the same shader. Uniform declarations must remain compatible with the original catalog entry.

Parameter	Type	Description
logical_id	const char *	Value for logical ID.
shader	mk_shader_t	Value for shader.

Returns MK_SUCCESS or an error result.

mk_assets_resolvefunction

bool mk_assets_resolve(const char *relative_path, char *out_path, size_t out_size)

Resolve a relative path to a physical path using search paths.

Tries each search path in order until the file is found. Mounted catalog objects and archive entries are intentionally not resolved.

Parameter	Type	Description
relative_path	const char *	Relative path to resolve
out_path	char *	Buffer to receive the resolved path
out_size	size_t	Size of the output buffer

Returns true if file was found and path resolved

mk_assets_shutdownfunction

void mk_assets_shutdown(void)

Shutdown the assets system.

Clears all search paths.

mk_assets_stream_closefunction

void mk_assets_stream_close(mk_asset_stream_t stream)

Close assets stream.

Parameter	Type	Description
stream	mk_asset_stream_t	Value for stream.

mk_assets_stream_openfunction

mk_result mk_assets_stream_open(const char *path, mk_asset_stream_t *out_stream)

Open an asset without copying it into one large allocation.

Packed objects are read directly from their bounded, uncompressed ZIP entry. Cooked objects are SHA-256 verified on their first open per mounted snapshot.

Parameter	Type	Description
path	const char *	Value for path.
out_stream	mk_asset_stream_t *	Receives the stream.

Returns MK_SUCCESS or an error result.

mk_assets_stream_readfunction

mk_result mk_assets_stream_read(mk_asset_stream_t stream, void *data, size_t byte_count, size_t *out_bytes_read)

Read up to byte_count bytes.

Parameter	Type	Description
stream	mk_asset_stream_t	Value for stream.
data	void *	Data buffer.
byte_count	size_t	Number of byte entries.
out_bytes_read	size_t *	Receives the bytes read.

Returns MK_SUCCESS or an error result.

mk_assets_stream_seekfunction

mk_result mk_assets_stream_seek(mk_asset_stream_t stream, int64_t offset, mk_asset_seek_origin_t origin)

Seek within the stream.

Parameter	Type	Description
stream	mk_asset_stream_t	Value for stream.
offset	int64_t	Value for offset.
origin	mk_asset_seek_origin_t	Value for origin.

Returns MK_SUCCESS or an error result.

mk_assets_stream_sizefunction

uint64_t mk_assets_stream_size(mk_asset_stream_t stream)

Perform the assets stream size operation.

Parameter	Type	Description
stream	mk_asset_stream_t	Value for stream.

Returns The resulting value.

mk_assets_stream_tellfunction

uint64_t mk_assets_stream_tell(mk_asset_stream_t stream)

Perform the assets stream tell operation.

Parameter	Type	Description
stream	mk_asset_stream_t	Value for stream.

Returns The resulting value.

mk_assets_unmountfunction

bool mk_assets_unmount(mk_asset_mount_t mount)

Release one reference to a mount.

In-flight async loads retain their snapshot.

Parameter	Type	Description
mount	mk_asset_mount_t	Value for mount.

Returns True when the operation succeeds.

mk_assets_unwatchfunction

bool mk_assets_unwatch(mk_asset_mount_t mount)

Stop watching a mount.

Parameter	Type	Description
mount	mk_asset_mount_t	Value for mount.

Returns True when the operation succeeds.

mk_assets_watchfunction

bool mk_assets_watch(mk_asset_mount_t mount, mk_asset_watch_callback_t callback, void *user_data)

Watch a loose catalog for atomic catalog replacements on native desktop.

Polling is 200 ms with a 100 ms quiet debounce. The callback runs from mk_assets_poll() on the main thread; change strings live only for the call. Calling watch again replaces the callback. Unsupported platforms return false.

Parameter	Type	Description
mount	mk_asset_mount_t	Value for mount.
callback	mk_asset_watch_callback_t	Completion callback.
user_data	void *	Caller-provided context.

Returns True when the operation succeeds.

Structs

mk_asset_changestruct

Data for asset change.

Field	Type	Description
id	const char *	The ID.
type	mk_asset_type_t	The type.
kind	mk_asset_change_kind_t	The kind.

mk_asset_mountstruct

Data for asset mount.

Field	Type	Description
index	uint32_t	The index.
generation	uint32_t	The generation.

mk_asset_progressstruct

Asset loading progress info.

Field	Type	Description
path	const char *	Asset path being loaded.
bytes_loaded	size_t	Bytes downloaded so far.
bytes_total	size_t	Total bytes (0 if unknown).
percent	float	0.0 to 1.0 (-1 if unknown)
state	mk_asset_state_t	Current state.
error	const char *	Error message if state == ERROR.

mk_asset_requeststruct

Async request handle for tracking operations.

Field	Type	Description
id	uint32_t	The ID.

mk_asset_streamstruct

Opaque, seekable byte stream over a loose or packed asset.

Field	Type	Description
impl	void *	The impl.

Enums

mk_asset_change_kindenum

Values for asset change kind.

Value	Description
MK_ASSET_CHANGE_ADDED	Selects added.
MK_ASSET_CHANGE_MODIFIED	Selects modified.
MK_ASSET_CHANGE_REMOVED	Selects removed.

mk_asset_seek_originenum

Values for asset seek origin.

Value	Description
MK_ASSET_SEEK_BEGIN	Selects begin.
MK_ASSET_SEEK_CURRENT	Selects current.
MK_ASSET_SEEK_END	Selects end.

mk_asset_stateenum

Asset loading state.

Value	Description
MK_ASSET_STATE_PENDING	Queued but not started.
MK_ASSET_STATE_LOADING	Currently downloading/loading.
MK_ASSET_STATE_COMPLETE	Loaded successfully.
MK_ASSET_STATE_ERROR	Failed to load.

mk_asset_typeenum

Asset type enumeration for generic asset handling.

Value	Description
MK_ASSET_MODEL	Selects model.
MK_ASSET_TEXTURE	Selects texture.
MK_ASSET_FONT	Selects font.
MK_ASSET_AUDIO	Selects audio.
MK_ASSET_JSON	Selects JSON.
MK_ASSET_BINARY	Selects binary.
MK_ASSET_SHADER	Selects shader.
MK_ASSET_IBL	Selects ibl.
MK_ASSET_MIDI	Selects MIDI.
MK_ASSET_SOUNDFONT	Selects soundfont.
MK_ASSET_VIDEO	Selects video.

Typedefs

mk_asset_change_kind_ttypedef

typedef enum mk_asset_change_kind mk_asset_change_kind_t

Values for asset change kind.

mk_asset_change_ttypedef

typedef struct mk_asset_change mk_asset_change_t

Data for asset change.

mk_asset_data_callback_ttypedef

typedef void(*) mk_asset_data_callback_t(const char *path, void *data, size_t size, void *user_data)

Generic async callback - receives raw data.

On success: data is non-NULL and must be freed by caller. On error: data is NULL.

mk_asset_font_callback_ttypedef

typedef void(*) mk_asset_font_callback_t(const char *path, mk_font_t font, void *user_data)

Type used for asset font callback.

mk_asset_gif_callback_ttypedef

typedef void(*) mk_asset_gif_callback_t(const char *path, mk_gif_t gif, void *user_data)

Type used for asset gif callback.

mk_asset_mount_ttypedef

typedef struct mk_asset_mount mk_asset_mount_t

Data for asset mount.

mk_asset_progress_callback_ttypedef

typedef void(*) mk_asset_progress_callback_t(const mk_asset_progress_t *progress, void *user_data)

Progress callback for async loading.

mk_asset_progress_ttypedef

typedef struct mk_asset_progress mk_asset_progress_t

Asset loading progress info.

mk_asset_request_ttypedef

typedef struct mk_asset_request mk_asset_request_t

Async request handle for tracking operations.

mk_asset_seek_origin_ttypedef

typedef enum mk_asset_seek_origin mk_asset_seek_origin_t

Values for asset seek origin.

mk_asset_sound_callback_ttypedef

typedef void(*) mk_asset_sound_callback_t(const char *path, mk_sound_t sound, void *user_data)

Type used for asset sound callback.

mk_asset_state_ttypedef

typedef enum mk_asset_state mk_asset_state_t

Asset loading state.

mk_asset_stream_ttypedef

typedef struct mk_asset_stream mk_asset_stream_t

Opaque, seekable byte stream over a loose or packed asset.

mk_asset_texture_callback_ttypedef

typedef void(*) mk_asset_texture_callback_t(const char *path, mk_texture_t texture, void *user_data)

Typed callbacks for specific asset types.

mk_asset_type_ttypedef

typedef enum mk_asset_type mk_asset_type_t

Asset type enumeration for generic asset handling.

mk_asset_watch_callback_ttypedef

typedef void(*) mk_asset_watch_callback_t(mk_asset_mount_t mount, const mk_asset_change_t *changes, size_t change_count, void *user_data)

Type used for asset watch callback.

Macros

MK_ASSET_MOUNT_INVALIDdefine

MK_ASSET_MOUNT_INVALID

Invalid sentinel for asset mount.

MK_ASSET_REQUEST_INVALIDdefine

MK_ASSET_REQUEST_INVALID

Invalid sentinel for asset request.

MK_ASSETS_MAX_PATH_LENdefine

MK_ASSETS_MAX_PATH_LEN

Maximum supported assets path len.

MK_ASSETS_MAX_PATHSdefine

MK_ASSETS_MAX_PATHS

Maximum supported assets paths.