nCine::Texture class
#include <nCine/Graphics/Texture.h>

Image data uploaded to the GPU and sampled by shaders.

Wraps a backend texture object. It can be created empty with a given format and size, loaded from an image file or filled from raw texels, and configured with filtering, wrapping and channel swizzling before being bound by a material.

SamplerFilter, SamplerWrapping and SwizzleChannel are declared in RhiTypes.h.

Base classes

class Object: Base class of all nCine objects.

Public types

using Format = PixelFormat: Pixel formats for an empty texture.

Public static variables

static Format ColorTargetFormat constexpr: Pixel format the engine's opaque color render targets are created with.

Public static functions

static auto sType() -> ObjectType

Constructors, destructors, conversion operators

Texture(): Creates an OpenGL texture name.
Texture(const char* name, Format format, std::int32_t mipMapCount, std::int32_t width, std::int32_t height): Creates an empty texture with the specified format, MIP levels and size.
Texture(const char* name, Format format, std::int32_t mipMapCount, Vector2i size): Creates an empty texture with the specified format, MIP levels and size given as a vector.
Texture(const char* name, Format format, std::int32_t width, std::int32_t height): Creates an empty texture with the specified format and size.
Texture(const char* name, Format format, Vector2i size): Creates an empty texture with the specified format and size given as a vector.
Texture(StringView filename) explicit: Creates a texture from an image file.
~Texture() override
Texture(const Texture&) deleted
Texture(Texture&&)

Public functions

auto operator=(const Texture&) -> Texture& deleted
auto operator=(Texture&&) -> Texture&
void Init(const char* name, Format format, std::int32_t mipMapCount, std::int32_t width, std::int32_t height): Initializes an empty texture with the specified format, MIP levels and size.
void Init(const char* name, Format format, std::int32_t mipMapCount, Vector2i size): Initializes an empty texture with the specified format, MIP levels and size given as a vector.
void Init(const char* name, Format format, std::int32_t width, std::int32_t height): Initializes an empty texture with the specified format and size.
void Init(const char* name, Format format, Vector2i size): Initializes an empty texture with the specified format and size given as a vector.
auto LoadFromFile(StringView filename) -> bool: Loads the texture from an image file.
auto LoadFromTexels(const std::uint8_t* bufferPtr) -> bool: Loads all texels in raw format from a memory buffer into the first MIP level.
auto LoadFromTexels(const std::uint8_t* bufferPtr, std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height) -> bool: Loads texels in raw format from a memory buffer into a sub-region of the first MIP level.
auto LoadFromTexels(const std::uint8_t* bufferPtr, Recti region) -> bool: Loads texels in raw format from a memory buffer into a rectangular sub-region of the first MIP level.
auto LoadFromTexels(const std::uint8_t* bufferPtr, std::int32_t level, std::int32_t x, std::int32_t y, std::int32_t width, std::int32_t height) -> bool: Loads texels in raw format from a memory buffer into a sub-region of the specified MIP level.
auto LoadFromTexels(const std::uint8_t* bufferPtr, std::int32_t level, Recti region) -> bool: Loads texels in raw format from a memory buffer into a rectangular sub-region of the specified MIP level.
auto MapStreamingTexels(std::int32_t& strideBytes) -> void*: Returns a writable pointer to the texture's own storage, for content rebuilt every frame.
auto SaveToMemory(std::uint8_t* bufferPtr) -> bool: Saves all texels of the first MIP level in raw format to a memory buffer.
auto SaveToMemory(std::uint8_t* bufferPtr, std::int32_t level) -> bool: Saves all texels of the specified MIP level in raw format to a memory buffer.
auto GetWidth() const -> std::int32_t: Returns the texture width.
auto GetHeight() const -> std::int32_t: Returns the texture height.
auto GetMipMapLevels() const -> std::int32_t: Returns the number of texture MIP map levels.
auto GetSize() const -> Vector2i: Returns the texture size.
auto GetRect() const -> Recti: Returns the texture rectangle.
auto IsCompressed() const -> bool: Returns true if the texture holds compressed data.
auto GetChannelCount() const -> std::uint32_t: Returns the number of color channels.
auto GetDataSize() const -> std::uint32_t: Returns the amount of video memory needed to load the texture.
auto GetMinFiltering() const -> SamplerFilter: Returns the texture filtering for minification.
auto GetMagFiltering() const -> SamplerFilter: Returns the texture filtering for magnification.
auto GetWrap() const -> SamplerWrapping: Returns the texture wrapping for both s and t coordinates.
void SetMinFiltering(SamplerFilter filter): Sets the texture filtering for minification.
void SetMagFiltering(SamplerFilter filter): Sets the texture filtering for magnification.
void SetWrap(SamplerWrapping wrapMode): Sets the texture wrapping for both s and t coordinates.
void SetSwizzle(SwizzleChannel r, SwizzleChannel g, SwizzleChannel b, SwizzleChannel a): Remaps the channels returned when the texture is sampled.
void SetTextureLabel(const char* label): Sets the backend object label for the texture, for debugging.
auto GetGuiTexId() const -> void*: Returns the opaque user data pointer used as ImGui's ImTextureID.

Function documentation

void* nCine::Texture::MapStreamingTexels(std::int32_t& strideBytes)

Returns a writable pointer to the texture's own storage, for content rebuilt every frame.

Only backends that advertise RHI_CAP_STREAMING_TEXTURES have this, and even there it is only answered for the formats the hardware stores verbatim; it returns nullptr otherwise, and the caller has to go through LoadFromTexels() instead. strideBytes receives the distance between rows, which is not width * bytesPerPixel when the storage is padded.

What is written is not mirrored into the host copy the texture keeps, so a texture written this way must be written whole, every time, and never read back.

void nCine::Texture::SetSwizzle(SwizzleChannel r, SwizzleChannel g, SwizzleChannel b, SwizzleChannel a)

Remaps the channels returned when the texture is sampled.

The default mapping is Red, Green, Blue, Alpha. Swizzling lets a reduced-channel texture (e.g., an RG8 sprite holding a palette index plus alpha) be sampled as if it were RGBA8 in the shader.

Variable documentation

static Format nCine::Texture::ColorTargetFormat constexpr

Pixel format the engine's opaque color render targets are created with.

RHI_USE_FB16 (the NCINE_RHI_USE_FB16 option) is a performance switch, so on the OpenGL family backend it covers every color surface it can rather than only the presented one: the scene, blur and rescale targets become RGB565, which halves both their memory and the bandwidth each post-processing pass reads and writes them with.

Targets that carry alpha keep 8 bits per channel regardless - the only 16-bit RGBA layout is RGBA4, and 16 levels per channel band visibly in the UI overlay and in the light falloff. The software rasterizer also keeps 4-byte RGBA render targets: its inner loops work on RGBA8 either way, so a packed target would only add a pack/unpack per span, which is why its 16-bit mode stays confined to the screen buffer - there it halves the per-frame upload and pays off.

nCine::Texture class #include <nCine/Graphics/Texture.h>