Texture¶

High-level texture handling utilities.

Overview¶

Typical use cases:

Handling texture loading, manipulation, and atlas creation

TODO:

Constant atlas loader
Move uv rects to a separate SSBO for skipping rebuilds
More texture formats

Header¶

Metadata¶

Author: Estorc
Version: v1.0
Copyright: Copyright (c) 2025 Estorc MIT License.

Types¶

Type Definitions¶
Type	Description
`RaeptorCogs::Singletons::TextureAtlasMap`	Map of texture atlases by type.
`RaeptorCogs::TextureAtlasTypeKey`	Type key for texture atlas map.

using RaeptorCogs::Singletons::TextureAtlasMap = std::map<TextureAtlasTypeKey, std::vector<std::shared_ptr<TextureAtlas>>>¶

Map of texture atlases by type.

Used by the TextureAtlasManager singleton to manage texture atlases.

See also

TextureAtlasManager

using RaeptorCogs::TextureAtlasTypeKey = std::tuple<unsigned int, unsigned int>¶

Type key for texture atlas map.

Used to uniquely identify texture atlases based on their filtering options.

Enums¶

Enumerations¶
Enum	Description
`RaeptorCogs::TextureAtlasFlags`	Texture atlas flags enumeration.

enum class RaeptorCogs::TextureAtlasFlags : uint32_t ¶

Texture atlas flags enumeration.

Defines flags for texture atlas management.

Values:

enumerator NONE¶

enumerator NEEDS_REBUILD¶

Structs¶

Structures¶
Struct	Description
`RaeptorCogs::Texture::OnLoadProxy`	Proxy structure for setting the onLoad callback.
`RaeptorCogs::TextureOptions`	Texture loading options structure.

struct OnLoadProxy¶

Proxy structure for setting the onLoad callback.

Allows users to set a callback function that is invoked when the texture is loaded.

Public Functions

inline void operator=(std::function<void()> fn)¶

Assignment operator to set the onLoad callback.

Note

If the texture is already loaded, the callback is invoked immediately.

Parameters:: fn – Callback function to be invoked when the texture is loaded.

Public Members

std::shared_ptr<TextureBase> ptr¶

Shared pointer to the TextureBase instance.

Used to access and set the onLoad_ callback.

Note

Used internally by the OnLoadProxy structure.

struct TextureOptions¶

Texture loading options structure.

Defines options for loading textures.

Note

Default values are provided for all options.

Public Members

unsigned int minFilter = GL_LINEAR_MIPMAP_LINEAR ¶: Minification filter for the texture.

unsigned int magFilter = GL_LINEAR ¶: Magnification filter for the texture.

unsigned int s_width = 0¶: Desired width after scaling. 0 means original width.

unsigned int s_height = 0¶: Desired height after scaling. 0 means original height.

int priority = 0¶

Loading priority of the texture.

Higher priority textures are loaded before lower priority ones.

Classes¶

Classes¶
Class	Description
`RaeptorCogs::Singletons::TextureAtlasManager`	Texture atlas manager singleton class.
`RaeptorCogs::Texture`	High-level texture handler class.
`RaeptorCogs::TextureAtlas`	Texture atlas class.
`RaeptorCogs::TextureBase`	Base texture class.

class TextureAtlasManager¶

Texture atlas manager singleton class.

Manages texture atlases and provides methods to add, remove, and retrieve atlases.

See also

TextureAtlas

Public Functions

void addAtlas(std::shared_ptr<TextureAtlas> atlas)¶

Add a texture atlas to the manager.

Parameters:: atlas – Shared pointer to the texture atlas to add.

void removeAtlas(const TextureAtlas *atlas)¶

Remove a texture atlas from the manager.

Parameters:: atlas – Pointer to the texture atlas to remove.

void sort(TextureAtlasTypeKey key)¶

Sort texture atlases of a specific type.

Parameters:: key – Type key of the texture atlases to sort.

std::shared_ptr<TextureAtlas> getAtlas(TextureAtlasTypeKey key)¶

Get a texture atlas of a specific type.

Note

If no suitable atlas exists returns nullptr.

Parameters:: key – Type key of the texture atlas to retrieve.
Returns:: Shared pointer to the retrieved texture atlas.

Private Functions

TextureAtlasManager() = default¶

Private constructor for TextureAtlasManager.

Use the SingletonAccessor to access the singleton instance.

~TextureAtlasManager()¶: Destructor for TextureAtlasManager.

Private Members

TextureAtlasMap atlases¶

Map of texture atlases.

See also

TextureAtlasMap

friend SingletonAccessor< TextureAtlasManager >

class Texture¶

High-level texture handler class.

Wraps around TextureBase to provide easy-to-use texture management.

RaeptorCogs::Texture tex("path/to/texture.png");
tex.bind();
uint32_t textureID = tex.getID();

Public Functions

inline Texture()¶

Default constructor for Texture.

Initializes the texture to a null state.

inline Texture(nullptr_t)¶

Constructor for Texture from nullptr.

Initializes the texture to a null state.

inline Texture(std::shared_ptr<TextureBase> p)¶

Constructor for Texture from a shared pointer to TextureBase.

Parameters:: p – Shared pointer to the TextureBase instance.

inline Texture(const Image &img)¶

Constructor for Texture from an Image.

Parameters:: img – Image structure containing pixel data and dimensions.

inline Texture(unsigned int width, unsigned int height, TextureOptions options = TextureOptions())¶

Constructor for Texture with specified dimensions.

Parameters:

width – Width of the texture in pixels.
height – Height of the texture in pixels.
options – Texture loading options.

inline Texture(const FileData &fileData, TextureOptions options = TextureOptions())¶

Constructor for Texture from file data.

Parameters:

fileData – Vector containing raw file data.
options – Texture loading options.

inline Texture(const char *filepath, TextureOptions options = TextureOptions())¶

Constructor for Texture from a file path.

Parameters:

filepath – Path to the texture file.
options – Texture loading options.

inline const TextureBase &get() const¶

Dereference operator to access the underlying TextureBase.

Returns:: Reference to the TextureBase instance.

inline const TextureBase &operator*() const¶

Dereference operator to access the underlying TextureBase.

Returns:: Reference to the TextureBase instance.

inline const TextureBase *operator->() const¶

Arrow operator to access members of the underlying TextureBase.

Returns:: Pointer to the TextureBase instance.

inline TextureBase &get()¶

Dereference operator to access the underlying TextureBase.

Returns:: Reference to the TextureBase instance.

inline TextureBase &operator*()¶

Dereference operator to access the underlying TextureBase.

Returns:: Reference to the TextureBase instance.

inline TextureBase *operator->()¶

Arrow operator to access members of the underlying TextureBase.

Returns:: Pointer to the TextureBase instance.

inline explicit operator bool() const noexcept¶

Boolean conversion operator.

Returns:: true if the texture is valid (non-null), false otherwise.

Public Members

OnLoadProxy onLoad = {ptr}¶

On-load callback proxy.

Allows setting a callback function that is invoked when the texture is loaded.

Texture texture("path/to/texture.png");
texture.onLoad = []() {
   std::cout << "Texture loaded!" << std::endl;
};

Private Members

std::shared_ptr<TextureBase> ptr¶

Shared pointer to the underlying TextureBase instance.

Manages the lifetime of the texture.

Note

Used internally by the Texture class.

struct OnLoadProxy

Proxy structure for setting the onLoad callback.

Allows users to set a callback function that is invoked when the texture is loaded.

Public Functions

inline void operator=(std::function<void()> fn)

Assignment operator to set the onLoad callback.

Note

If the texture is already loaded, the callback is invoked immediately.

Parameters:: fn – Callback function to be invoked when the texture is loaded.

Public Members

std::shared_ptr<TextureBase> ptr

Shared pointer to the TextureBase instance.

Used to access and set the onLoad_ callback.

Note

Used internally by the OnLoadProxy structure.

class TextureAtlas¶

Texture atlas class.

Manages a collection of textures packed into a single atlas texture.

Public Functions

TextureAtlas()¶: Default constructor for TextureAtlas.

TextureAtlas(glm::ivec2 size, unsigned int minFilter = GL_LINEAR_MIPMAP_NEAREST, unsigned int magFilter = GL_LINEAR)¶

Constructor for TextureAtlas with specified size and filtering options.

Note

Textures added to the atlas will be packed using stb_rect_pack.

Parameters:

size – Size of the atlas (width, height) in pixels.
minFilter – Minification filter for the atlas texture.
magFilter – Magnification filter for the atlas texture.

void bind()¶

Bind the atlas texture for rendering.

See also

GAPI::Common::TextureData::bind()

void unbind() const¶

Unbind the atlas texture.

See also

GAPI::Common::TextureData::unbind()

void uploadTexture(GLint x, GLint y, GLint width, GLint height, const void *data, bool newAtlas)¶

Upload a texture to the atlas at the specified position.

See also

GAPI::Common::TextureData::build()

Note

The pixel data should be in RGBA format.

Parameters:

x – X position in the atlas to upload the texture.
y – Y position in the atlas to upload the texture.
width – Width of the texture to upload.
height – Height of the texture to upload.
data – Pointer to the pixel data of the texture.
newAtlas – Whether this is a new atlas upload (true) or an update (false).

bool tryAddTexture(TextureBase *texture, int width, int height)¶

Try to add a texture to the atlas.

Note

The texture’s rectangle and UV rectangle will be set upon successful addition.

Parameters:

texture – Pointer to the texture to add.
width – Width of the texture in pixels.
height – Height of the texture in pixels.

Returns:

true if the texture was successfully added, false otherwise.

void removeTexture(const TextureBase &texture)¶

Remove a texture from the atlas.

Note

This method is called automatically when a texture is destroyed.

Warning

The atlas will be repacked after removal, which may be a costly operation.

Parameters:: texture – Reference to the texture to remove.

uint32_t getID() const¶

Get the texture ID of the atlas.

Returns:: The GAPI texture ID of the atlas.

int getWidth() const¶

Get the width of the atlas.

Returns:: The width of the atlas in pixels.

int getHeight() const¶

Get the height of the atlas.

Returns:: The height of the atlas in pixels.

int getFreeSpace() const¶

Get the amount of free space in the atlas.

Returns:: The amount of free space in pixels.

bool needsRebuild() const¶

Check if the atlas GPU linking needs to be rebuilt.

Note

This tell the renderer to rebuild uv rectangles in the GPU.

Returns:: true if the atlas needs to be rebuilt, false otherwise.

inline TextureAtlasTypeKey getTypeKey() const¶

Get the type key for the texture atlas.

Returns:: The TextureAtlasTypeKey representing the atlas’s filtering options.

Private Members

glm::ivec2 size¶

Size of the texture atlas.

(width, height) in pixels.

std::vector<TextureBase*> textures¶

List of textures in the atlas.

See also

TextureBase

GAPI::ObjectHandler<GAPI::Common::TextureData> glTexture¶

GAPI texture handler for the atlas.

See also

GAPI::Common::TextureData

stbrp_context ctx¶: STB rect pack context for packing textures.

std::vector<stbrp_node> nodes¶: Nodes used for packing textures.

TextureAtlasFlags flags = TextureAtlasFlags::NONE ¶

Texture atlas flags.

See also

TextureAtlasFlags

unsigned int minFilter = GL_LINEAR_MIPMAP_NEAREST ¶: Minification filter for the atlas texture.

unsigned int magFilter = GL_LINEAR ¶: Magnification filter for the atlas texture.

int freeSpace = 0¶: Amount of free space in the atlas.

Note

Used to quickly check if a new texture can fit.

class TextureBase¶

Base texture class.

Provides common functionality for textures, including atlas management.

RaeptorCogs::Texture tex("path/to/texture.png");
tex.bind();
uint32_t textureID = tex.getID();

See also

Texture

Note

Should not be used directly. Use the Texture wrapper class instead.

Public Functions

~TextureBase()¶

Destructor for TextureBase.

Cleans up resources and removes the texture from its atlas if applicable.

See also

TextureAtlas::removeTexture()

void bind() const¶

Bind the texture for rendering.

See also

TextureAtlas::bind()

bool isOpaque() const¶

Check if the texture is fully opaque.

Returns:: true if the texture is fully opaque, false otherwise.

bool isLoaded() const¶

Check if the texture has been loaded.

Returns:: true if the texture is loaded, false otherwise.

void setAtlas(std::shared_ptr<TextureAtlas> atlas)¶

Set the texture atlas for this texture.

Parameters:: atlas – Shared pointer to the texture atlas.

float getX() const¶

Get the X position of the texture in the atlas.

Returns:: X position in pixels.

float getY() const¶

Get the Y position of the texture in the atlas.

Returns:: Y position in pixels.

float getWidth() const¶

Get the width of the texture in the atlas.

Returns:: Width in pixels.

float getHeight() const¶

Get the height of the texture in the atlas.

Returns:: Height in pixels.

glm::vec4 getRect()¶

Get the rectangle of the texture in the atlas.

Returns:: Rectangle (x, y, width, height) in pixels.

glm::vec4 getUVRect()¶

Get the UV rectangle of the texture in the atlas.

Returns:: UV rectangle (u, v, u_width, v_height) in normalized coordinates [0, 1].

TextureAtlas *getAtlas() const¶

Get the texture atlas this texture belongs to.

Returns:: Pointer to the texture atlas, or nullptr if not assigned.

uint32_t getID() const¶

Get the GAPI texture ID of this texture.

Returns:: The GAPI texture ID, or 0 if not loaded.

bool needsRebuild() const¶

Check if the texture GPU linking needs to be rebuilt.

Note

This tell the renderer to rebuild uv rectangles in the GPU.

Returns:: true if the texture needs to be rebuilt, false otherwise.

Private Functions

void upload(const Image &img)¶

Upload image data to the texture.

Parameters:: img – Image structure containing pixel data and dimensions.

inline TextureBase()¶

Private constructor for TextureBase.

Use the handler class Texture to create and manage TextureBase instances.

void setRect(const glm::vec4 &rect)¶

Set the rectangle of the texture in the atlas.

Parameters:: rect – Rectangle (x, y, width, height) in pixels.

void setUVRect(const glm::vec4 &uv)¶

Set the UV rectangle of the texture in the atlas.

Parameters:: uv – UV rectangle (u, v, u_width, v_height) in normalized coordinates [0, 1].

Private Members

std::function<void()> onLoad_¶

Callback function invoked when the texture is loaded.

Can be set by the user to perform actions once the texture is ready.

std::weak_ptr<TextureAtlas> atlas¶

Weak pointer to the texture atlas this texture belongs to.

See also

TextureAtlas

glm::vec4 rect¶

Rectangle of the texture in the atlas.

(x, y, width, height) in pixels.

glm::vec4 uvRect¶

UV rectangle of the texture in the atlas.

(u, v, u_width, v_height) in normalized coordinates [0, 1].

bool opaque¶

Opaqueness flag of the texture.

true if the texture is fully opaque, false otherwise.

Private Static Functions

static std::shared_ptr<TextureBase> create(const Image &img)¶

Factory method to create a TextureBase from an Image.

Parameters:: img – Image structure containing pixel data and dimensions.
Returns:: Shared pointer to the created TextureBase instance.

static std::shared_ptr<TextureBase> create(unsigned int width, unsigned int height, TextureOptions options = TextureOptions())¶

Factory method to create a TextureBase with specified dimensions.

Parameters:

width – Width of the texture in pixels.
height – Height of the texture in pixels.
options – Texture loading options.

Returns:

Shared pointer to the created TextureBase instance.

static std::shared_ptr<TextureBase> create(const FileData &fileData, TextureOptions options = TextureOptions())¶

Factory method to create a TextureBase from file data.

Parameters:

fileData – Vector containing raw file data.
options – Texture loading options.

Returns:

Shared pointer to the created TextureBase instance.

static std::shared_ptr<TextureBase> create(const std::filesystem::path &filepath, TextureOptions options = TextureOptions())¶

Factory method to create a TextureBase from a file path.

Parameters:

filepath – Path to the texture file.
options – Texture loading options.

Returns:

Shared pointer to the created TextureBase instance.

Friends

friend class Texture

friend class TextureAtlas

Functions¶

Functions¶
Function	Description
`std::operator<<(std::ostream &os, const RaeptorCogs::TextureOptions &options)`	Output stream operator for TextureOptions.

inline std::ostream &std::operator<<(std::ostream &os, const RaeptorCogs::TextureOptions &options)¶

Output stream operator for TextureOptions.

Parameters:

os – Output stream.
options – TextureOptions instance to output.

Returns:

Reference to the output stream.

Variables¶

unsigned int RaeptorCogs::ATLAS_PADDING = 1¶: Padding around textures in the atlas to prevent bleeding.

unsigned int RaeptorCogs::COMMON_ATLAS_SIZE = 1024¶: Common atlas dimensions.