template<class AllocationPolicy>
glpp::core::object::texture_atlas_t class

customizable container class for for textures

texture_atlas_t is a container class for textures with identical access parameters. Static and dynamic access is possible. Static meaning the texture id of the fetched texture is known at shader compile time and dynamic meaning the texture id is provided by a shader variable. The layout of textures in graphic memory can be customized with AllocationPolicy template parameter.

Public types

using allocation_hint_t = typename AllocationPolicy::allocation_hint_t
key hint type for allocation in specific places
using key_storage_t = typename AllocationPolicy::key_storage_t
key storage type
using key_t = typename AllocationPolicy::key_t
key type to reference entries

Constructors, destructors, conversion operators

template<class... Args>
texture_atlas_t(Args && ... args) explicit
constructor
texture_atlas_t(texture_atlas_t&& mov) defaulted noexcept
move constructor
texture_atlas_t(const texture_atlas_t& cpy) deleted
copy constructor

Public functions

auto at(const key_t key) -> entry_t
bounds checked access to entries
auto at(const key_t key) const -> const entry_t
bounds checked access to entries
auto bind_to_texture_slot() const -> texture_atlas_slot_t<AllocationPolicy>
bind textures of the texture atlas next free texture units
auto contains(const key_t key) const -> bool
check if a given key is contained in the atlas
auto declaration(const std::string_view name) const -> std::string
get declaration for shader compilation
auto dynamic_fetch(const std::string_view name, const std::string_view key, const std::string_view uv) const -> std::string
return string to fetch a texel inside shader code
auto dynamic_fetch(const std::string_view name, const std::string_view key, const glm::vec2 uv) const -> std::string
return string to fetch a texel inside shader code
auto empty() const -> bool
check if atlas is empty
void erase(const key_t key)
erase entry from the texture atlas
void erase(const entry_t entry)
erase entry from the texture atlas
auto fetch(const std::string_view name, const key_t key, const std::string_view uv) const -> std::string
return string to fetch a texel inside shader code
auto fetch(const std::string_view name, const key_t key, const glm::vec2 uv) const -> std::string
return string to fetch a texel inside shader code
auto get(const key_t key) -> entry_t
access to entries
auto get(const key_t key) const -> const entry_t
access to entries
auto insert() -> entry_t
insert element into atlas
auto insert(const allocation_hint_t allocation_hint) -> entry_t
insert element into atlas
template<class PixelFormat>
auto insert(const image_t<PixelFormat>& image) -> entry_t
insert element into atlas
template<class PixelFormat>
auto insert(const allocation_hint_t allocation_hint, const image_t<PixelFormat>& image) -> entry_t
insert element into atlas
auto keys() const -> key_storage_t
get the key range of the texture atlas
auto max_size() const -> size_t
maximum size of the texture atlas
auto operator=(texture_atlas_t&& mov) -> texture_atlas_t& defaulted noexcept
move assignment operator
auto operator=(const texture_atlas_t& cpy) -> texture_atlas_t& deleted
copy assignment operator
auto operator[](const key_t key) -> entry_t
random access operator
auto size() const -> size_t
size of texture atlas

Function documentation

template<class AllocationPolicy>
template<class... Args>
glpp::core::object::texture_atlas_t<AllocationPolicy>::texture_atlas_t(Args && ... args) explicit

constructor

Parameters
args [in] paramets that will be passed to the AllocationPolicy on construction

This is the constructor for texture_atlas_t. The arguments will be forwarded to the AllocationPolicy. Usually no parameters should be necessary to create a texture_atlas_t. If the AllocationPolicy does require parameters it will be documented with the policy.

template<class AllocationPolicy>
glpp::core::object::texture_atlas_t<AllocationPolicy>::texture_atlas_t(texture_atlas_t&& mov) defaulted noexcept

move constructor

texture_atlas_t is move constructible.

template<class AllocationPolicy>
glpp::core::object::texture_atlas_t<AllocationPolicy>::texture_atlas_t(const texture_atlas_t& cpy) deleted

copy constructor

texture_atlas_t is not copy constructible.

template<class AllocationPolicy>
entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::at(const key_t key)

bounds checked access to entries

Parameters
key [in] key of texture that shall be accessed
Returns texture_atlas_entry_t instance that enables access to the requested entry

This member function allows access to entries in the atlas. The function will check if the requested key is contained in the atlas before access. If the key does not exist an exception is thrown.

template<class AllocationPolicy>
const entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::at(const key_t key) const

bounds checked access to entries

Parameters
key [in] key of texture that shall be accessed
Returns texture_atlas_entry_t instance that enables access to the requested entry

This member function allows access to entries in the atlas. The function will check if the requested key is contained in the atlas before access. If the key does not exist an exception is thrown.

template<class AllocationPolicy>
texture_atlas_slot_t<AllocationPolicy> glpp::core::object::texture_atlas_t<AllocationPolicy>::bind_to_texture_slot() const

bind textures of the texture atlas next free texture units

Returns texture_atlas_slot_t object representing the bindings

This function will bind the textures to the next free texture units. If there are no more free texture unit to bind to, the function will throw a std::runtime_error.

template<class AllocationPolicy>
bool glpp::core::object::texture_atlas_t<AllocationPolicy>::contains(const key_t key) const

check if a given key is contained in the atlas

Parameters
key [in] key that shall be checked
Returns true if key is contained, false if not.

Check whether a given key is contained in the texture atlas.

template<class AllocationPolicy>
std::string glpp::core::object::texture_atlas_t<AllocationPolicy>::declaration(const std::string_view name) const

get declaration for shader compilation

Parameters
name [in] binding name of textur atlas in the shader code
Returns std::string with shadercode encoding the declaration of texture samplers

This function will return a GLSL declaration of zero, one or more texture samplers, that are necessary to fetch the pixel data from the texture entries in this texture atlas. The name parameter is used to specify the binding name of the shader atlas. Analog to texture_t the texture_atlas_t needs to be bound to a renderer object via a name. This name is used to differenciate and identify different texture atlases in one shader or across shader boundaries.

template<class AllocationPolicy>
std::string glpp::core::object::texture_atlas_t<AllocationPolicy>::dynamic_fetch(const std::string_view name, const std::string_view key, const std::string_view uv) const

return string to fetch a texel inside shader code

Parameters
name [in] name of the texture_atlas_t binding to the renderer
key [in] either the name of a shader variable or a fixed value
uv [in] either name of a shader variable of type vec2 or a vec2 value
Returns std::string with GLSL code

This function is basically the same as the normal fetch with the main difference, that a std::string_view is used to specify the key. This string_view can encode a constant value or a shader variable of type key_t. If a variable name is provided as key, this function can be used to dynamically fetch texels at shader run time.

template<class AllocationPolicy>
std::string glpp::core::object::texture_atlas_t<AllocationPolicy>::dynamic_fetch(const std::string_view name, const std::string_view key, const glm::vec2 uv) const

return string to fetch a texel inside shader code

Parameters
name [in] name of the texture_atlas_t binding to the renderer
key [in] either the name of a shader variable or a fixed value
uv [in] value for the uv coordinates that shall be fetched in the shader

This function is basically the same as the normal fetch with the main difference, that a std::string_view is used to specify the key. This string_view can encode a constant value or a shader variable of type key_t. If a variable name is provided as key, this function can be used to dynamically fetch texels at shader run time.

template<class AllocationPolicy>
bool glpp::core::object::texture_atlas_t<AllocationPolicy>::empty() const

check if atlas is empty

Returns True, if no textures are contained in the atlas. False otherwise.

This function if there are textures existant in this atlas. It's equivalent to the size() == 0.

template<class AllocationPolicy>
void glpp::core::object::texture_atlas_t<AllocationPolicy>::erase(const key_t key)

erase entry from the texture atlas

Parameters
key [in] key of element that should be erased

Erase an element with a given key from the texture atlas. This function will throw an exception, if the key is not contained in the atlas. texture_atlas_entry_t refering to the key will be invalidated.

template<class AllocationPolicy>
void glpp::core::object::texture_atlas_t<AllocationPolicy>::erase(const entry_t entry)

erase entry from the texture atlas

Parameters
entry [in] entry that shall be erased

Erase an element with a given key from the texture atlas. This function will throw an exception, if the entry is invalid. The texture_atlas_entry_t provided and all other texture_atlas_entry_t that refer to the same key will be invalidated.

template<class AllocationPolicy>
std::string glpp::core::object::texture_atlas_t<AllocationPolicy>::fetch(const std::string_view name, const key_t key, const std::string_view uv) const

return string to fetch a texel inside shader code

Parameters
name [in] name of the texture_atlas_t binding to the renderer
key [in] key of the texture entry that shall be fetched
uv [in] either name of a shader variable of type vec2 or a vec2 value
Returns std::string with GLSL code

This function will generate shader code, that can be used to fetch pixel values from a texture atlas.

template<class AllocationPolicy>
std::string glpp::core::object::texture_atlas_t<AllocationPolicy>::fetch(const std::string_view name, const key_t key, const glm::vec2 uv) const

return string to fetch a texel inside shader code

Parameters
name [in] name of the texture_atlas_t binding to the renderer
key [in] key of the texture entry that shall be fetched
uv [in] value for the uv coordinates that shall be fetched in the shader
Returns std::string with GLSL code

This function will generate shader code, that can be used to fetch pixel values from a texture atlas.

template<class AllocationPolicy>
entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::get(const key_t key)

access to entries

Parameters
key [in] key of texture that shall be accessed
Returns texture_atlas_entry_t instance that enables access to the requested entry

This member function allows access to entries in the atlas. The function will NOT check if the requested key is contained in the atlas before access. If the key does not exist, the returned texture_atlas_entry_t will be invalid.

template<class AllocationPolicy>
const entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::get(const key_t key) const

access to entries

Parameters
key [in] key of texture that shall be accessed
Returns texture_atlas_entry_t instance that enables access to the requested entry

This member function allows access to entries in the atlas. The function will NOT check if the requested key is contained in the atlas before access. If the key does not exist, the returned texture_atlas_entry_t will be invalid.

template<class AllocationPolicy>
entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::insert()

insert element into atlas

Returns texture_atlas_entry_t instance refering to the inserted entry

This member function will insert a new entry into the texture atlas.

template<class AllocationPolicy>
entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::insert(const allocation_hint_t allocation_hint)

insert element into atlas

Parameters
allocation_hint [in] allocation hint
Returns texture_atlas_entry_t instance refering to the inserted entry

This member function will insert a new entry into the texture atlas. Depending on the AllocationPolicy the allocation_hint parameter might or might not be ignored. Trying to allocate a key, that is already taken or invalid keys will throw an exception.

template<class AllocationPolicy>
template<class PixelFormat>
entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::insert(const image_t<PixelFormat>& image)

insert element into atlas

Parameters
image [in] pixel data for the inserted texture
Returns texture_atlas_entry_t instance refering to the inserted entry

This member function will insert a new entry into the texture atlas. The entry will allocate a texture on construction and copy over the pixel data from image.

template<class AllocationPolicy>
template<class PixelFormat>
entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::insert(const allocation_hint_t allocation_hint, const image_t<PixelFormat>& image)

insert element into atlas

Parameters
allocation_hint [in] allocation hint
image [in] pixel data for the inserted texture
Returns texture_atlas_entry_t instance refering to the inserted entry

This member function will insert a new entry into the texture atlas. This overload is a combination of the allocation_hint overload and the image_t overload.

template<class AllocationPolicy>
key_storage_t glpp::core::object::texture_atlas_t<AllocationPolicy>::keys() const

get the key range of the texture atlas

Returns key range

This member function will return an iteratable range of key_t with all keys, that are contained in the texture atlas.

template<class AllocationPolicy>
size_t glpp::core::object::texture_atlas_t<AllocationPolicy>::max_size() const

maximum size of the texture atlas

Returns theoretical maximum of entries into a single instance of the texture atlas

This function will return a theoretical maximum number of entries to the atlas. Depending on the allocation policy provided it might or might not be possible to use the full amount of max_size(). The multi_policy_t policy will most likely not allow for the full amount of entries, as that would require all texture units to be free for this one texture atlas.

template<class AllocationPolicy>
texture_atlas_t& glpp::core::object::texture_atlas_t<AllocationPolicy>::operator=(texture_atlas_t&& mov) defaulted noexcept

move assignment operator

texture_atlas_t is move assignable.

template<class AllocationPolicy>
texture_atlas_t& glpp::core::object::texture_atlas_t<AllocationPolicy>::operator=(const texture_atlas_t& cpy) deleted

copy assignment operator

texture_atlas_t is not copy assignable.

template<class AllocationPolicy>
entry_t glpp::core::object::texture_atlas_t<AllocationPolicy>::operator[](const key_t key)

random access operator

Parameters
key [in] key of texture that shall be accessed
Returns texture_atlas_entry_t instance that enables access to the requested entry

This operator takes a key_t key and returns a texture_atlas_entry_t instance. This entry acts like a reference wrapper to the requested texture entry. If key is not contained in the atlas a new element will be inserted and a texture_atlas_entry_t to this element will be returned.

template<class AllocationPolicy>
size_t glpp::core::object::texture_atlas_t<AllocationPolicy>::size() const

size of texture atlas

Returns count of entries

This function returns the count of entries/keys inside the texture atlas.