This file contains the texture system, which handles the acquisition and releasing of textures. It also reference monitors textures, and can auto-release them when they no longer have any references, if configured to do so. More...

#include <assets/kasset_types.h>
#include <core_render_types.h>
#include "kresources/kresource_types.h"

Data Structures
struct	texture_system_config
	The texture system configuration. More...

struct	ktexture_load_options

Macros
#define	DEFAULT_TEXTURE_NAME "Texture.Default"
	The default texture name. More...

#define	DEFAULT_BASE_COLOUR_TEXTURE_NAME "Texture.DefaultBase"
	The default base colour texture name. More...

#define	DEFAULT_SPECULAR_TEXTURE_NAME "Texture.DefaultSpecular"
	The default specular texture name. More...

#define	DEFAULT_NORMAL_TEXTURE_NAME "Texture.DefaultNormal"
	The default normal texture name. More...

#define	DEFAULT_MRA_TEXTURE_NAME "Texture.DefaultMRA"
	The default combined (metallic, roughness, AO) texture name. More...

#define	DEFAULT_CUBE_TEXTURE_NAME "Texture.DefaultCube"
	The default cube texture name. More...

#define	DEFAULT_WATER_NORMAL_TEXTURE_NAME "Texture.DefaultWaterNormal"
	The default water normal texture name. More...

#define	DEFAULT_WATER_DUDV_TEXTURE_NAME "Texture.DefaultWaterDUDV"
	The default water derivative (dudv) texture name. More...

Typedefs
typedef struct texture_system_config	texture_system_config
	The texture system configuration. More...

typedef void(*	PFN_texture_loaded_callback) (ktexture texture, void *listener)

typedef struct ktexture_load_options	ktexture_load_options

Functions
b8	texture_system_initialize (u64 memory_requirement, void state, void *config)
	Initializes the texture system. Should be called twice; once to get the memory requirement (passing state=0), and a second time passing an allocated block of memory to actually initialize the system. More...

void	texture_system_shutdown (void *state)
	Shuts down the texture system. More...

KAPI ktexture	texture_acquire (kname image_asset_name, void *listener, PFN_texture_loaded_callback callback)
	Attempts to acquire a texture using the given image asset name. Asynchronous. More...

KAPI ktexture	texture_acquire_sync (kname image_asset_name)
	Attempts to acquire a texture using the given image asset name. Synchronous. More...

KAPI void	texture_release (ktexture texture)
	Releases resources for the given texture. More...

KAPI ktexture	texture_acquire_from_package (kname image_asset_name, kname package_name, void *listener, PFN_texture_loaded_callback callback)
	Attempts to acquire a texture using the given image asset name, loaded from the provided package. Asynchronous. More...

KAPI ktexture	texture_acquire_from_package_sync (kname image_asset_name, kname package_name)
	Attempts to acquire a texture using the given image asset name, loaded from the provided package. Synchronous. More...

KAPI ktexture	texture_cubemap_acquire (kname image_asset_name_prefix, void *listener, PFN_texture_loaded_callback callback)
	Attempts to acquire a cubemap texture with the given image asset name. Asynchronous. More...

KAPI ktexture	texture_cubemap_acquire_sync (kname image_asset_name_prefix)
	Attempts to acquire a cubemap texture with the given image asset name. Synchronous. More...

KAPI ktexture	texture_cubemap_acquire_from_package (kname image_asset_name_prefix, kname package_name, void *listener, PFN_texture_loaded_callback callback)
	Attempts to acquire a cubemap texture with the given image asset name from the provided package. Asynchronous. More...

KAPI ktexture	texture_cubemap_acquire_from_package_sync (kname image_asset_name_prefix, kname package_name)
	Attempts to acquire a cubemap texture with the given image asset name from the provided package. Synchronous. More...

KAPI ktexture	texture_acquire_from_image (const kasset_image *image, kname name)

KAPI ktexture	texture_acquire_from_pixel_data (kpixel_format format, u32 pixel_array_size, void *pixels, u32 width, u32 height, kname name)

KAPI ktexture	texture_cubemap_acquire_from_pixel_data (kpixel_format format, u32 pixel_array_size, void *pixels, u32 width, u32 height, kname name)

KAPI ktexture	texture_acquire_with_options (ktexture_load_options options, void *listener, PFN_texture_loaded_callback callback)

KAPI ktexture	texture_acquire_with_options_sync (ktexture_load_options options)

KAPI b8	texture_resize (ktexture t, u32 width, u32 height, b8 regenerate_internal_data)
	Resizes the given texture. May only be done on writeable textures. Potentially regenerates internal data, if configured to do so. More...

KAPI b8	texture_write_data (ktexture t, u32 offset, u32 size, void *data)
	Writes the given data to the provided texture. May only be used on writeable textures. More...

KAPI u32	texture_width_get (ktexture t)

KAPI u32	texture_height_get (ktexture t)

KAPI b8	texture_dimensions_get (ktexture t, u32 out_width, u32 out_height)

KAPI khandle	texture_renderer_handle_get (ktexture t)

KAPI ktexture_flag_bits	texture_flags_get (ktexture t)

KAPI b8	texture_is_loaded (ktexture t)

Detailed Description

This file contains the texture system, which handles the acquisition and releasing of textures. It also reference monitors textures, and can auto-release them when they no longer have any references, if configured to do so.

Author: Travis Vroman (travi.nosp@m.s@ko.nosp@m.hieng.nosp@m.ine..nosp@m.com)

Version: 2.0

Date: 2022-01-11

Copyright: Kohi Game Engine is Copyright (c) Travis Vroman 2021-2025

Macro Definition Documentation

◆ DEFAULT_BASE_COLOUR_TEXTURE_NAME

#define DEFAULT_BASE_COLOUR_TEXTURE_NAME "Texture.DefaultBase"

The default base colour texture name.

◆ DEFAULT_CUBE_TEXTURE_NAME

#define DEFAULT_CUBE_TEXTURE_NAME "Texture.DefaultCube"

The default cube texture name.

◆ DEFAULT_MRA_TEXTURE_NAME

#define DEFAULT_MRA_TEXTURE_NAME "Texture.DefaultMRA"

The default combined (metallic, roughness, AO) texture name.

◆ DEFAULT_NORMAL_TEXTURE_NAME

#define DEFAULT_NORMAL_TEXTURE_NAME "Texture.DefaultNormal"

The default normal texture name.

◆ DEFAULT_SPECULAR_TEXTURE_NAME

#define DEFAULT_SPECULAR_TEXTURE_NAME "Texture.DefaultSpecular"

The default specular texture name.

◆ DEFAULT_TEXTURE_NAME

#define DEFAULT_TEXTURE_NAME "Texture.Default"

The default texture name.

◆ DEFAULT_WATER_DUDV_TEXTURE_NAME

#define DEFAULT_WATER_DUDV_TEXTURE_NAME "Texture.DefaultWaterDUDV"

The default water derivative (dudv) texture name.

◆ DEFAULT_WATER_NORMAL_TEXTURE_NAME

#define DEFAULT_WATER_NORMAL_TEXTURE_NAME "Texture.DefaultWaterNormal"

The default water normal texture name.

Typedef Documentation

◆ ktexture_load_options

typedef struct ktexture_load_options ktexture_load_options

◆ PFN_texture_loaded_callback

typedef void(* PFN_texture_loaded_callback) (ktexture texture, void *listener)

◆ texture_system_config

typedef struct texture_system_config texture_system_config

The texture system configuration.

Function Documentation

◆ texture_acquire()

KAPI ktexture texture_acquire	(	kname	image_asset_name,
		void *	listener,
		PFN_texture_loaded_callback	callback
	)

Attempts to acquire a texture using the given image asset name. Asynchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default texture is returned. If the texture is found and loaded, its reference counter is incremented. The image_asset_name is also used as the texture name. Loads from the application package. Texture will be auto-released when reference count reaches 0. Texture will be of KTEXTURE_TYPE_2D.

This function is considered to be asynchronous, and invokes the given callback when the texture is loaded.

Parameters

image_asset_name	The name of the image asset to load and use for the texture.
listener	A structure containing data to be passed along to the callback when the image is loaded. Optional.
callback	The callback to be made once the texture is loaded. Optional.

Returns: The texture to be loaded. The default texture if not found. INVALID_KTEXTURE if error. May/may not be loaded yet on return.

◆ texture_acquire_from_image()

KAPI ktexture texture_acquire_from_image	(	const kasset_image *	image,
		kname	name
	)

◆ texture_acquire_from_package()

KAPI ktexture texture_acquire_from_package	(	kname	image_asset_name,
		kname	package_name,
		void *	listener,
		PFN_texture_loaded_callback	callback
	)

Attempts to acquire a texture using the given image asset name, loaded from the provided package. Asynchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default texture is returned. If the texture is found and loaded, its reference counter is incremented. The image_asset_name is also used as the texture name. Loads from the application package. Texture will be auto-released when reference count reaches 0. Texture will be of KTEXTURE_TYPE_2D.

This function is considered to be asynchronous, and invokes the given callback when the texture is loaded.

Parameters

image_asset_name	The name of the image asset to load and use for the texture.
package_name	The name of the package to load the texture image asset from.
listener	A structure containing data to be passed along to the callback when the image is loaded. Optional.
callback	The callback to be made once the texture is loaded. Optional.

Returns: The texture to be loaded. The default texture if not found. INVALID_KTEXTURE if error. May/may not be loaded yet on return.

◆ texture_acquire_from_package_sync()

KAPI ktexture texture_acquire_from_package_sync	(	kname	image_asset_name,
		kname	package_name
	)

Attempts to acquire a texture using the given image asset name, loaded from the provided package. Synchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default texture is returned. If the texture is found and loaded, its reference counter is incremented. The image_asset_name is also used as the texture name. Loads from the application package. Texture will be auto-released when reference count reaches 0. Texture will be of KTEXTURE_TYPE_2D.

This function is considered to be synchronous and is guaranteed to be loaded on return.

Parameters

image_asset_name	The name of the image asset to load and use for the texture.
package_name	The name of the package to load the texture image asset from.

Returns: The loaded texture. Can be the default texture if not found. INVALID_KTEXTURE if error.

◆ texture_acquire_from_pixel_data()

KAPI ktexture texture_acquire_from_pixel_data	(	kpixel_format	format,
		u32	pixel_array_size,
		void *	pixels,
		u32	width,
		u32	height,
		kname	name
	)

◆ texture_acquire_sync()

KAPI ktexture texture_acquire_sync ( kname image_asset_name )

Attempts to acquire a texture using the given image asset name. Synchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default texture is returned. If the texture is found and loaded, its reference counter is incremented. The image_asset_name is also used as the texture name. Loads from the application package. Texture will be auto-released when reference count reaches 0. Texture will be of KTEXTURE_TYPE_2D.

This function is considered to be synchronous and is guaranteed to be loaded on return.

Parameters

image_asset_name The name of the image asset to load and use for the texture.

Returns: The loaded texture. Can be the default texture if not found. INVALID_KTEXTURE if error.

◆ texture_acquire_with_options()

KAPI ktexture texture_acquire_with_options	(	ktexture_load_options	options,
		void *	listener,
		PFN_texture_loaded_callback	callback
	)

◆ texture_acquire_with_options_sync()

KAPI ktexture texture_acquire_with_options_sync ( ktexture_load_options options )

◆ texture_cubemap_acquire()

KAPI ktexture texture_cubemap_acquire	(	kname	image_asset_name_prefix,
		void *	listener,
		PFN_texture_loaded_callback	callback
	)

Attempts to acquire a cubemap texture with the given image asset name. Asynchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default cubemap texture is returned. If the texture is found and loaded, its reference counter is incremented. Requires textures with image_asset_name_prefix as the base, one for each side of a cube.

name_f Front
name_b Back
name_u Up
name_d Down
name_r Right
name_l Left

For example, "skybox_f.png", "skybox_b.png", etc. where image_asset_name_prefix is "skybox".

This function is considered to be asynchronous, and invokes the given callback when the texture is loaded.

Parameters

image_asset_name_prefix	The prefix of the name of the image assets to load and use for the texture.
listener	The object listening for the callback to be made once the resource is loaded. Optional.
callback	The callback to be made once the resource is loaded. Optional.

Returns: The texture to be loaded. The default texture if not found. INVALID_KTEXTURE if error. May/may not be loaded yet on return.

◆ texture_cubemap_acquire_from_package()

KAPI ktexture texture_cubemap_acquire_from_package	(	kname	image_asset_name_prefix,
		kname	package_name,
		void *	listener,
		PFN_texture_loaded_callback	callback
	)

Attempts to acquire a cubemap texture with the given image asset name from the provided package. Asynchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default cubemap texture is returned. If the texture is found and loaded, its reference counter is incremented. Requires textures with image_asset_name_prefix as the base, one for each side of a cube.

name_f Front
name_b Back
name_u Up
name_d Down
name_r Right
name_l Left

For example, "skybox_f.png", "skybox_b.png", etc. where image_asset_name_prefix is "skybox".

This function is considered to be asynchronous, and invokes the given callback when the texture is loaded.

Parameters

image_asset_name_prefix	The prefix of the name of the image assets to load and use for the texture.
package_name	The name of the package from which to load the image assets from.
listener	The object listening for the callback to be made once the resource is loaded. Optional.
callback	The callback to be made once the resource is loaded. Optional.

Returns: The texture to be loaded. The default texture if not found. INVALID_KTEXTURE if error. May/may not be loaded yet on return.

◆ texture_cubemap_acquire_from_package_sync()

KAPI ktexture texture_cubemap_acquire_from_package_sync	(	kname	image_asset_name_prefix,
		kname	package_name
	)

Attempts to acquire a cubemap texture with the given image asset name from the provided package. Synchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default cubemap texture is returned. If the texture is found and loaded, its reference counter is incremented. Requires textures with image_asset_name_prefix as the base, one for each side of a cube.

name_f Front
name_b Back
name_u Up
name_d Down
name_r Right
name_l Left

For example, "skybox_f.png", "skybox_b.png", etc. where image_asset_name_prefix is "skybox".

This function is considered to be synchronous and is guaranteed to be loaded on return.

Parameters

image_asset_name_prefix	The prefix of the name of the image assets to load and use for the texture.
package_name	The name of the package from which to load the image assets from.

Returns: The loaded texture. Can be the default texture if not found. INVALID_KTEXTURE if error.

◆ texture_cubemap_acquire_from_pixel_data()

KAPI ktexture texture_cubemap_acquire_from_pixel_data	(	kpixel_format	format,
		u32	pixel_array_size,
		void *	pixels,
		u32	width,
		u32	height,
		kname	name
	)

◆ texture_cubemap_acquire_sync()

KAPI ktexture texture_cubemap_acquire_sync ( kname image_asset_name_prefix )

Attempts to acquire a cubemap texture with the given image asset name. Synchronous.

If it has not yet been loaded, this triggers it to load. If the texture is not found, a pointer to the default cubemap texture is returned. If the texture is found and loaded, its reference counter is incremented. Requires textures with image_asset_name_prefix as the base, one for each side of a cube.

name_f Front
name_b Back
name_u Up
name_d Down
name_r Right
name_l Left

For example, "skybox_f.png", "skybox_b.png", etc. where image_asset_name_prefix is "skybox".

This function is considered to be synchronous and is guaranteed to be loaded on return.

Parameters

image_asset_name_prefix The prefix of the name of the image assets to load and use for the texture.

Returns: The loaded texture. Can be the default texture if not found. INVALID_KTEXTURE if error.

◆ texture_dimensions_get()

KAPI b8 texture_dimensions_get	(	ktexture	t,
		u32 *	out_width,
		u32 *	out_height
	)

◆ texture_flags_get()

KAPI ktexture_flag_bits texture_flags_get ( ktexture t )

◆ texture_height_get()

KAPI u32 texture_height_get ( ktexture t )

◆ texture_is_loaded()

KAPI b8 texture_is_loaded ( ktexture t )

◆ texture_release()

KAPI void texture_release ( ktexture texture )

Releases resources for the given texture.

Parameters

t	A pointer to the texture to be released.

◆ texture_renderer_handle_get()

KAPI khandle texture_renderer_handle_get ( ktexture t )

◆ texture_resize()

KAPI b8 texture_resize	(	ktexture	t,
		u32	width,
		u32	height,
		b8	regenerate_internal_data
	)

Resizes the given texture. May only be done on writeable textures. Potentially regenerates internal data, if configured to do so.

Parameters

t	The texture to be resized.
width	The new width in pixels.
height	The new height in pixels.
regenerate_internal_data	Indicates if the internal data should be regenerated.

Returns: True on success; otherwise false.

◆ texture_system_initialize()

b8 texture_system_initialize	(	u64 *	memory_requirement,
		void *	state,
		void *	config
	)

Initializes the texture system. Should be called twice; once to get the memory requirement (passing state=0), and a second time passing an allocated block of memory to actually initialize the system.

Parameters

memory_requirement	A pointer to hold the memory requirement as it is calculated.
state	A block of memory to hold the state or, if gathering the memory requirement, 0.
config	The configuration (texture_system_config) for this system.

Returns: True on success; otherwise false.

◆ texture_system_shutdown()

void texture_system_shutdown ( void * state )

Shuts down the texture system.

Parameters

state The state block of memory for this system.

◆ texture_width_get()

KAPI u32 texture_width_get ( ktexture t )

◆ texture_write_data()

KAPI b8 texture_write_data	(	ktexture	t,
		u32	offset,
		u32	size,
		void *	data
	)

Writes the given data to the provided texture. May only be used on writeable textures.

Parameters

t	The texture to be written to.
offset	The offset in bytes from the beginning of the data to be written.
size	The number of bytes to be written.
data	A pointer to the data to be written.

Returns: True on success; otherwise false.

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ DEFAULT_BASE_COLOUR_TEXTURE_NAME

◆ DEFAULT_CUBE_TEXTURE_NAME

◆ DEFAULT_MRA_TEXTURE_NAME

◆ DEFAULT_NORMAL_TEXTURE_NAME

◆ DEFAULT_SPECULAR_TEXTURE_NAME

◆ DEFAULT_TEXTURE_NAME

◆ DEFAULT_WATER_DUDV_TEXTURE_NAME

◆ DEFAULT_WATER_NORMAL_TEXTURE_NAME

Typedef Documentation

◆ ktexture_load_options

◆ PFN_texture_loaded_callback

◆ texture_system_config

Function Documentation

◆ texture_acquire()

◆ texture_acquire_from_image()

◆ texture_acquire_from_package()

◆ texture_acquire_from_package_sync()

◆ texture_acquire_from_pixel_data()

◆ texture_acquire_sync()

◆ texture_acquire_with_options()

◆ texture_acquire_with_options_sync()

◆ texture_cubemap_acquire()

◆ texture_cubemap_acquire_from_package()

◆ texture_cubemap_acquire_from_package_sync()

◆ texture_cubemap_acquire_from_pixel_data()

◆ texture_cubemap_acquire_sync()

◆ texture_dimensions_get()

◆ texture_flags_get()

◆ texture_height_get()

◆ texture_is_loaded()

◆ texture_release()

◆ texture_renderer_handle_get()

◆ texture_resize()

◆ texture_system_initialize()

◆ texture_system_shutdown()

◆ texture_width_get()

◆ texture_write_data()