nCine::RHI::GU::GuTexture class
#include <nCine/Graphics/RHI/GU/GuTexture.h>

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

Keeps a LINEAR host store of level 0 in the uploaded pixel format (the same native R8/RG8/RGBA8 layout the software and PVR backends use) plus a second store the Allegrex GE can sample directly. The GE reads textures out of ordinary addressable memory, so that store lives in main memory rather than in the 2 MB of video memory - only render targets and the display buffers are worth putting there - but it still has to satisfy three hardware requirements the host store does not:

Power-of-two dimensions, at most 512 per axis (the texture size register holds log2 of each axis in 4 bits, and u/v addressing is 9-bit). Anything larger is split into pages of at most 512x512, and the draw path selects the page a primitive's texture rectangle falls into and rebases its texture coordinates onto it (see AcquirePage()). Every sprite/tile draw samples one small sub-rect of an atlas, so a primitive practically never straddles a page boundary.
A format the GE samples. R8 index textures become GU_PSM_T8 read through a hardware CLUT (the direct analogue of the PowerVR's palette banks and the GX's TLUTs) - the CLUT itself is loaded per draw by the device from whatever palette texture the material bound. RG8 (index + per-pixel alpha) has no paletted equivalent, because a paletted texel's alpha comes from the CLUT entry, so those get the same per-palette-row CPU bake the other consoles use, into GU_PSM_4444 (EnsureBakedStore()). RGB8/RGBA8 convert to GU_PSM_4444 as well, and RGB565 to GU_PSM_5650 (whose channel order is the reverse of the engine's).
The CPU cache written back, since the GE reads main memory without seeing the data cache. Every store rebuild ends in a writeback of exactly the bytes it wrote.

Static content is additionally stored swizzled (the GE's 16-byte x 8-row block interleave), which is substantially cheaper to sample; content that is replaced repeatedly (the cinematic frames) drops the swizzle after its second upload, because interleaving it every frame would cost more than it saves. MapStreamingTexels() lets such a texture be built straight in the GE store.

Mip levels above 0 and compressed formats are accepted but not stored, exactly like on the other fixed-function backends: the game never uses either.

Public types

struct Page: One GE-addressable piece of the texture.

Public static variables

static std::uint32_t MaxTextureUnits constexpr: Number of texture units tracked by the device.
static std::int32_t MaxPageDimension constexpr: The dimension a single GE texture cannot exceed, per axis (a hardware limit).

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

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

Public functions

auto operator=(const GuTexture&) -> GuTexture& 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 (nullptr before an upload).
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 GU).
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.
void SetRenderTarget(bool isRenderTarget): Marks the texture as (or no longer as) a color render target; becoming one allocates its surface.
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 store holds palette indices (draws resolve them through a CLUT).
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 (its rows become CLUTs).
auto AcquirePage(std::int32_t texelX, std::int32_t texelY) -> const Page*: Builds the GE store if it is missing and returns the page holding the given source texel.
auto GetGuPixelFormat() const -> std::int32_t: Returns the GU_PSM_* pixel format of the GE store (valid once a page exists).
auto GetPageCountX() const -> std::int32_t: Number of pages the image is split into along each axis (1 x 1 for anything up to 512x512).
auto GetPageCountY() const -> std::int32_t: Number of pages the image is split into along each axis.
auto EnsureBakedStore(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette) -> bool: Makes the GE store hold this RG8 texture baked through one palette row.
auto MapStreamingTexels(std::int32_t& strideBytes) -> void*: Returns a writable pointer to the GE store, for content that is rebuilt every frame.
auto GetRenderTargetSurface() const -> void*: Returns the surface the GE renders into when this texture is a render target, or nullptr.
auto GetRenderTargetStride() const -> std::int32_t: Returns the row pitch in texels of GetRenderTargetSurface().
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 CLUTs.

Function documentation

const Page* nCine::RHI::GU::GuTexture::AcquirePage(std::int32_t texelX, std::int32_t texelY)

Builds the GE store if it is missing and returns the page holding the given source texel.

texelX / texelY are clamped into the image, so the min corner of any texture rectangle is a valid argument. Returns nullptr when there is nothing to sample (no upload yet, an unsupported format, or an RG8 store whose bake has not been requested - see EnsureBakedStore()).

bool nCine::RHI::GU::GuTexture::EnsureBakedStore(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette)

Makes the GE store hold this RG8 texture baked through one palette row.

Index resolved through paletteRow (256 RGBA8 entries), alpha from the texel's own alpha byte, written as GU_PSM_4444 - the analogue of PVR::PvrTexture::EnsureBakedArgb4444(). A small number of bakes is cached, so the common "one extra palette row" case (a sprite and its recolored twin) does not rebuild anything; AcquirePage() then hands out the pages of the matching bake. Returns false when the bake could not be produced.

void* nCine::RHI::GU::GuTexture::MapStreamingTexels(std::int32_t& strideBytes)

Returns a writable pointer to the GE store, for content that is rebuilt every frame.

Answered only for the format the hardware samples verbatim out of memory (RGB565), which is what lets the cinematics build a frame straight where the GE will read it instead of into a buffer that is then copied into the host store and converted a second time. Returns nullptr for anything else, and whenever the store cannot be allocated.

strideBytes receives the row pitch, which is the power-of-two padded page width rather than the texture's own. Nothing written here reaches the host copy, so such a texture must be rewritten in full every frame and never read back. The channel order is the GE's (GU_PSM_5650, red in the low bits) rather than the engine's, so the bytes are swapped in place once per frame before the GE sees them (AcquirePage()).

nCine::RHI::GU::GuTexture class #include <nCine/Graphics/RHI/GU/GuTexture.h>