texture_system.h File Reference

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 "renderer/renderer_types.h"

Go to the source code of this file.

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

Macros
#define	DEFAULT_TEXTURE_NAME   "default"
	The default texture name. More...
#define	DEFAULT_DIFFUSE_TEXTURE_NAME   "default_DIFF"
	The default diffuse texture name. More...
#define	DEFAULT_SPECULAR_TEXTURE_NAME   "default_SPEC"
	The default specular texture name. More...
#define	DEFAULT_NORMAL_TEXTURE_NAME   "default_NORM"
	The default normal texture name. More...

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

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 texture *	texture_system_acquire (const char *name, b8 auto_release)
	Attempts to acquire a texture with the given name. 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. More...
KAPI texture *	texture_system_acquire_cube (const char *name, b8 auto_release)
	Attempts to acquire a cubemap texture with the given name. 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. Requires textures with name as the base, one for each side of a cube, in the following order: More...
KAPI texture *	texture_system_acquire_writeable (const char *name, u32 width, u32 height, u8 channel_count, b8 has_transparency)
	Attempts to acquire a writeable texture with the given name. This does not point to nor attempt to load a texture file. Does also increment the reference counter. NOTE: Writeable textures are not auto-released. More...
KAPI void	texture_system_release (const char *name)
	Releases a texture with the given name. Ignores non-existant textures. Decreases the reference counter by 1. If the reference counter reaches 0 and auto_release was set to true, the texture is unloaded, releasing internal resources. More...
KAPI void	texture_system_wrap_internal (const char *name, u32 width, u32 height, u8 channel_count, b8 has_transparency, b8 is_writeable, b8 register_texture, void *internal_data, texture *out_texture)
	Wraps the provided internal data in a texture structure using the parameters provided. This is best used for when the renderer system creates internal resources and they should be passed off to the texture system. Can be looked up by name via the acquire methods. NOTE: Wrapped textures are not auto-released. More...
KAPI b8	texture_system_set_internal (texture *t, void *internal_data)
	Sets the internal data of a texture. Useful for replacing internal data from within the renderer for wrapped textures, for example. More...
KAPI b8	texture_system_resize (texture *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_system_write_data (texture *t, u32 offset, u32 size, void *data)
	Writes the given data to the provided texture. May only be used on writeable textures. More...
KAPI texture *	texture_system_get_default_texture (void)
	Gets a pointer to the default texture. No reference counting is done for default textures. More...
KAPI texture *	texture_system_get_default_diffuse_texture (void)
	Gets a pointer to the default diffuse texture. No reference counting is done for default textures. More...
KAPI texture *	texture_system_get_default_specular_texture (void)
	Gets a pointer to the default specular texture. No reference counting is done for default textures. More...
KAPI texture *	texture_system_get_default_normal_texture (void)
	Gets a pointer to the default normal texture. No reference counting is done for default textures. More...

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

1.0

Date

2022-01-11

Copyright

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

Macro Definition Documentation

DEFAULT_DIFFUSE_TEXTURE_NAME

#define DEFAULT_DIFFUSE_TEXTURE_NAME   "default_DIFF"

The default diffuse texture name.

DEFAULT_NORMAL_TEXTURE_NAME

#define DEFAULT_NORMAL_TEXTURE_NAME   "default_NORM"

The default normal texture name.

DEFAULT_SPECULAR_TEXTURE_NAME

#define DEFAULT_SPECULAR_TEXTURE_NAME   "default_SPEC"

The default specular texture name.

DEFAULT_TEXTURE_NAME

#define DEFAULT_TEXTURE_NAME   "default"

The default texture name.

Typedef Documentation

texture_system_config

typedef struct texture_system_config texture_system_config

The texture system configuration.

Function Documentation

texture_system_acquire()

KAPI texture* texture_system_acquire	(	const char *	name,
		b8	auto_release
	)

Attempts to acquire a texture with the given name. 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.

Parameters

name	The name of the texture to find.
auto_release	Indicates if the texture should auto-release when its reference count is 0. Only takes effect the first time the texture is acquired.

Returns

A pointer to the loaded texture. Can be a pointer to the default texture if not found.

texture_system_acquire_cube()

KAPI texture* texture_system_acquire_cube	(	const char *	name,
		b8	auto_release
	)

Attempts to acquire a cubemap texture with the given name. 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. Requires textures with name as the base, one for each side of a cube, in the following order:

• 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 name is "skybox".

Parameters

name	The name of the texture to find. Used as a base string for actual texture names.
auto_release	Indicates if the texture should auto-release when its reference count is 0. Only takes effect the first time the texture is acquired.

Returns

A pointer to the loaded texture. Can be a pointer to the default texture if not found.

texture_system_acquire_writeable()

KAPI texture* texture_system_acquire_writeable	(	const char *	name,
		u32	width,
		u32	height,
		u8	channel_count,
		b8	has_transparency
	)

Attempts to acquire a writeable texture with the given name. This does not point to nor attempt to load a texture file. Does also increment the reference counter. NOTE: Writeable textures are not auto-released.

Parameters

name	The name of the texture to acquire.
width	The texture width in pixels.
height	The texture height in pixels.
channel_count	The number of channels in the texture (typically 4 for RGBA)
has_transparency	Indicates if the texture will have transparency.

Returns

A pointer to the generated texture.

texture_system_get_default_diffuse_texture()

KAPI texture* texture_system_get_default_diffuse_texture

(

void

)

Gets a pointer to the default diffuse texture. No reference counting is done for default textures.

texture_system_get_default_normal_texture()

KAPI texture* texture_system_get_default_normal_texture

(

void

)

Gets a pointer to the default normal texture. No reference counting is done for default textures.

texture_system_get_default_specular_texture()

KAPI texture* texture_system_get_default_specular_texture

(

void

)

Gets a pointer to the default specular texture. No reference counting is done for default textures.

texture_system_get_default_texture()

KAPI texture* texture_system_get_default_texture

(

void

)

Gets a pointer to the default texture. No reference counting is done for default textures.

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_release()

KAPI void texture_system_release

(

const char *

name

)

Releases a texture with the given name. Ignores non-existant textures. Decreases the reference counter by 1. If the reference counter reaches 0 and auto_release was set to true, the texture is unloaded, releasing internal resources.

Parameters

name	The name of the texture to unload.

texture_system_resize()

KAPI b8 texture_system_resize	(	texture *	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	A pointer to 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_set_internal()

KAPI b8 texture_system_set_internal	(	texture *	t,
		void *	internal_data
	)

Sets the internal data of a texture. Useful for replacing internal data from within the renderer for wrapped textures, for example.

Parameters

t	A pointer to the texture to be updated.
internal_data	A pointer to the internal data to be set.

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_system_wrap_internal()

KAPI void texture_system_wrap_internal	(	const char *	name,
		u32	width,
		u32	height,
		u8	channel_count,
		b8	has_transparency,
		b8	is_writeable,
		b8	register_texture,
		void *	internal_data,
		texture *	out_texture
	)

Wraps the provided internal data in a texture structure using the parameters provided. This is best used for when the renderer system creates internal resources and they should be passed off to the texture system. Can be looked up by name via the acquire methods. NOTE: Wrapped textures are not auto-released.

Parameters

name	The name of the texture.
width	The texture width in pixels.
height	The texture height in pixels.
channel_count	The number of channels in the texture (typically 4 for RGBA)
has_transparency	Indicates if the texture will have transparency.
is_writeable	Indicates if the texture is writeable.
internal_data	A pointer to the internal data to be set on the texture.
register_texture	Indicates if the texture should be registered with the system.
out_texture	An optional pointer to hold the wrapped texture. If null, a new pointer is allocated and returned instead.

texture_system_write_data()

KAPI b8 texture_system_write_data	(	texture *	t,
		u32	offset,
		u32	size,
		void *	data
	)

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

Parameters

t	A pointer to 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.