nCine::RHI::GX::GxTexture class
#include <nCine/Graphics/RHI/GX/GxTexture.h>

Texture object of the GX backend (aliased as RHI::Texture).

Keeps two representations of level 0: a LINEAR host store in the uploaded pixel format (the same native R8/RG8/RGBA8 layout the software backend uses - needed for sub-updates, readback and the palette interception below), and a TILED GX store in main memory referenced by a GXTexObj:

R8 index textures tile to GX_TF_CI8; the palette (TLUT) is selected per draw by the device from the instance's palOffset, which is what makes runtime palette remaps work fixed-function.
RGBA8 / RGB8 textures tile to GX_TF_RGBA8.
RG8 (index + per-pixel alpha) has no GX equivalent - a CI8 texel's alpha can only come from the palette entry. Those textures keep only the linear store; the device CPU-bakes an RGBA8 tiled copy per palette row on first use (see EnsureBakedRgba()), cached until the palette row or the texel content changes. Only a small set of translucent indexed sprites uses RG8. The shared 256x256 palette texture (labelled "Palettes") is intercepted: it keeps only the linear store, and the device turns its rows into TLUTs on demand.

Mip levels above 0 and compressed formats are accepted but not stored.

Public static variables

static std::uint32_t MaxTextureUnits constexpr: Number of texture units tracked by the device.

Public static functions

static auto Unbind(std::uint32_t textureUnit) -> bool: Unbinds any texture from the specified texture unit.
static void SetUnpackAlignment(std::int32_t alignment): Sets the client pixel-row alignment of uploads (ignored, uploads are tightly packed).
static auto SupportsImmutableStorage() -> bool
static auto SupportsTextureReadback() -> bool
static void ClearErrors()
static auto CheckErrors() -> bool
static void CheckFormatSupport(PixelFormat format)
static auto BytesPerPixel(PixelFormat format) -> std::int32_t: Returns the number of bytes occupied by one texel of the given format (0 if unsupported).

Constructors, destructors, conversion operators

GxTexture(TextureTarget target) explicit
~GxTexture()
GxTexture(const GxTexture&) deleted

Public functions

auto operator=(const GxTexture&) -> GxTexture& deleted
auto GetUniqueId() const -> std::uint32_t: Returns a backend-neutral identifier uniquely identifying the texture (feeds material sort keys).
auto GetTarget() const -> TextureTarget: Returns the texture target.
auto GetWidth() const -> std::int32_t: Returns the width of level 0 in texels.
auto GetHeight() const -> std::int32_t: Returns the height of level 0 in texels.
auto GetFormat() const -> PixelFormat: Returns the pixel format of the linear host store (native, like the software backend).
auto GetUploadFormat() const -> PixelFormat: Returns the original upload format (R8/RG8 kept so the palette path can tell them apart).
auto GetStrideBytes() const -> std::int32_t: Returns the byte distance between two consecutive rows of the linear host store.
auto GetPixels(std::int32_t level = 0) const -> const std::uint8_t*: Returns the base pointer of the linear host store (may be nullptr before an upload).
auto MutablePixels() -> std::uint8_t*: Returns a writable base pointer of the linear host store (for render-target readback).
auto GetWrapS() const -> SamplerWrapping: Returns the horizontal texture-coordinate wrap mode.
auto GetWrapT() const -> SamplerWrapping: Returns the vertical texture-coordinate wrap mode (single stored mode).
auto GetSwizzle() const -> const SwizzleChannel*: Returns the four-channel sampling swizzle (identity by default; informational on GX).
auto GetMagFiltering() const -> nCine::SamplerFilter: Returns the magnification filter.
auto GetMagFilter() const -> nCine::SamplerFilter: Alias of GetMagFiltering().
auto IsRenderTarget() const -> bool: Returns true if the texture is bound as a color render target (EFB copy destination).
void SetRenderTarget(bool isRenderTarget): Marks the texture as (or no longer as) a color render target; becoming one allocates an RGBA8 tiled store to copy the EFB into.
auto GetContentVersion() const -> std::uint32_t: Returns a globally monotonic stamp of the texel store, advanced by every allocation or upload.
auto IsIndexed() const -> bool: Returns true when the tiled store is a CI8 index texture (draws need a TLUT bound).
auto NeedsPaletteBake() const -> bool: Returns true when the texture needs the per-palette-row CPU bake (RG8 index + alpha).
auto IsPaletteTexture() const -> bool: Returns true when this is the intercepted shared palette texture (rows become TLUTs).
auto GetTexObj() -> GXTexObj*: Returns the GX texture object of the tiled store, or nullptr when none exists.
auto EnsureBakedRgba(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette) -> GXTexObj*: Returns a GX texture object of an RGBA8 copy of an RG8 store baked through one palette row.
auto Bind(std::uint32_t textureUnit) const -> bool: Binds the texture to the specified texture unit on the device.
auto Bind() const -> bool: Binds the texture to texture unit 0.
auto Unbind() const -> bool: Unbinds the texture from the unit it was last bound to.
void TexImage2D(std::int32_t level, PixelFormat format, bool bgr, std::int32_t width, std::int32_t height, const void* data): Allocates level-0 storage of the given format/size and optionally uploads its texels.
void TexSubImage2D(std::int32_t level, std::int32_t xoffset, std::int32_t yoffset, std::int32_t width, std::int32_t height, PixelFormat format, bool bgr, const void* data): Updates a rectangular subregion of level 0.
void TexStorage2D(std::int32_t levels, PixelFormat format, std::int32_t width, std::int32_t height): Allocates immutable level-0 storage of the given format/size (no texels yet).
void CompressedTexImage2D(std::int32_t level, PixelFormat format, std::int32_t width, std::int32_t height, std::int32_t imageSize, const void* data): Compressed upload (unsupported, accepted as a no-op).
void CompressedTexSubImage2D(std::int32_t level, std::int32_t xoffset, std::int32_t yoffset, std::int32_t width, std::int32_t height, PixelFormat format, std::int32_t imageSize, const void* data): Compressed sub-upload (unsupported, accepted as a no-op).
void GetTexImage(std::int32_t level, PixelFormat format, bool bgr, void* pixels): Reads back level-0 texels of the linear host store into client memory.
void SetMinFiltering(nCine::SamplerFilter filter): Sets the minification filter.
void SetMagFiltering(nCine::SamplerFilter filter): Sets the magnification filter.
void SetWrap(SamplerWrapping wrap): Sets the wrap mode.
void SetSwizzle(SwizzleChannel r, SwizzleChannel g, SwizzleChannel b, SwizzleChannel a): Sets the sampling swizzle (stored, informational - the palette path keys off the upload format instead).
void SetMaxLevel(std::int32_t maxLevel): Sets the highest defined mipmap level (ignored).
void SetObjectLabel(StringView label): Sets a debug label; "Palettes" marks the shared palette texture whose rows become TLUTs.
auto GetRenderTargetStore() -> std::uint8_t*: Returns the base pointer of the tiled render-target store the EFB is copied into (render targets only).

Function documentation

GXTexObj* nCine::RHI::GX::GxTexture::GetTexObj()

Returns the GX texture object of the tiled store, or nullptr when none exists.

Valid for CI8 and RGBA8 textures and for render targets; nullptr for RG8 (use EnsureBakedRgba()) and for the palette texture (rows are TLUTs, not a texture).

GXTexObj* nCine::RHI::GX::GxTexture::EnsureBakedRgba(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette)

Returns a GX texture object of an RGBA8 copy of an RG8 store baked through one palette row.

The bake resolves each texel's palette index through paletteRow (256 RGBA8 entries) and takes alpha from the texel's own alpha byte. One baked copy is cached; it is rebuilt when a different palette row, a newer palette generation or newer texel content is requested.

nCine::RHI::GX::GxTexture class #include <nCine/Graphics/RHI/GX/GxTexture.h>