nCine::RHI::GS::GsTexture class
#include <nCine/Graphics/RHI/GS/GsTexture.h>

Texture object of the GS 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 residency in the Graphics Synthesizer's local memory, placed by GsVram in whole pages:

R8 index textures become PSMT8, with the colours coming from a CLUT the device selects per draw out of the CLUT slab (from the instance's palOffset) - the GS resolves the lookup in the texture read, so indices upload as they are.
RG8 (index + per-pixel alpha) has no paletted GS equivalent, because a PSMT8 texel's alpha comes from its CLUT entry. Those keep only the host store and the device asks for a per-palette-row CPU bake to PSMCT32 (EnsureBakedColor), cached until the row or the texel content changes.
RGB8 / RGBA8 upload as PSMCT32. Unlike the PowerVR - which has no 32-bit sampled format and had to convert to ARGB4444 - the GS sampples 32-bit directly, so these keep full precision. PSMCT16 would halve the footprint but its alpha is a single bit, which is useless for blended sprite art, and true-colour sheets are few once the content is indexed.
The shared 256x256 palette texture (labelled "Palettes") is intercepted: it keeps only the host store and the device loads its rows into CLUT slots on demand.

Render targets take a PSMCT16 surface out of the layout's render-target reserve rather than the streaming cache, and are never evicted - there is no host copy to rebuild one from.

Residency

The host store is the source of truth and local memory is a cache, exactly as on the Dreamcast: when GsVram runs out of pages the least recently used stores are dropped (see AllocatePages()), and a texture drawn again afterwards is re-uploaded from its host copy by AcquireTexturePage(). Unlike the PVR backend the host stores are not run-length compressed: a rebuild here is a plain DMA out of main memory (the GS does the block swizzling itself), so keeping the copy in the layout the transfer wants makes a rebuild cost almost no CPU at all. The Dreamcast traded CPU time for main memory because it only had 16 MB and had to twiddle in software; with 32 MB and a DMA engine the trade goes the other way.

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.
static std::int32_t BakedSlotCount constexpr: Number of per-palette-row baked copies kept for RG8 textures.

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).
static auto AllocatePages(std::uint32_t pageCount, const GsTexture* keepAlive) -> std::uint32_t: Allocates local-memory pages, freeing the least recently used stores if necessary.

Constructors, destructors, conversion operators

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

Public functions

auto operator=(const GsTexture&) -> GsTexture& 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.
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.
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 the GS).
auto GetMagFiltering() const -> nCine::SamplerFilter: Returns the magnification filter.
auto GetMagFilter() const -> nCine::SamplerFilter: Alias of GetMagFiltering().
auto GetMinFiltering() const -> nCine::SamplerFilter: Returns the minification filter.
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 is PSMT8 (draws need a CLUT selected).
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 CLUTs).
auto GetTexturePage() const -> std::uint32_t: Returns the first page of the local-memory store, or GsVram::InvalidPage when none exists.
auto AcquireTexturePage() -> std::uint32_t: Returns the first page of the store, re-uploading it if it was reclaimed.
auto GetPsm() const -> GsPsm: Returns the pixel storage mode the local-memory store was uploaded in.
auto GetBufferPitch() const -> std::int32_t: Returns the store's buffer pitch in TEXELS, which is what libdraw wants in texbuffer_t::width.
auto GetPaddedWidth() const -> std::int32_t: Returns the power-of-two sampled width (TEX0.TW is a log2 field).
auto GetPaddedHeight() const -> std::int32_t: Returns the power-of-two sampled height (TEX0.TH is a log2 field).
auto GetUScale() const -> float: Returns the U compensation factor for the power-of-two sampled extent (realW / paddedW).
auto GetVScale() const -> float: Returns the V compensation factor for the power-of-two sampled extent (realH / paddedH).
auto EnsureBakedColor(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette) -> std::uint32_t: Returns the page of a PSMCT32 copy of an RG8 store baked through one palette row.
auto GetBakedBufferPitch() const -> std::int32_t: Returns the buffer pitch in texels of the baked copies (they share the store's sampled extent).
auto MapStreamingTexels(std::int32_t& strideBytes) -> void*: Always returns nullptr on the GS - local memory cannot be written by the CPU.
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).
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

static std::uint32_t nCine::RHI::GS::GsTexture::AllocatePages(std::uint32_t pageCount, const GsTexture* keepAlive)

Allocates local-memory pages, freeing the least recently used stores if necessary.

The 4 MB of local memory is shared by the display buffers, the render-target reserve, the CLUT slab and every texture, so a level with many tilesets (or a menu section that pulls in more graphics) exhausts it - the measured working set of a whole level is larger than the cache by design. The stores are a cache of the copies kept in main memory, so instead of failing the allocation the oldest ones are dropped and re-transferred when they are needed again.

keepAlive is spared by the eviction walk, so a texture cannot evict itself while growing.

std::uint32_t nCine::RHI::GS::GsTexture::AcquireTexturePage()

Returns the first page of the store, re-uploading it if it was reclaimed.

Should be used by the draw path: running out of local memory drops the least recently used stores (see AllocatePages()), and a texture that is drawn again afterwards has to be transferred from its main-memory copy once more.

std::uint32_t nCine::RHI::GS::GsTexture::EnsureBakedColor(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette)

Returns the page of a PSMCT32 copy of an RG8 store baked through one palette row.

Analogous to the PVR backend's ARGB4444 bake: the index is resolved through paletteRow (256 RGBA8 entries) and the alpha comes from the texel's own alpha byte. One cached copy per slot, rebuilt when the row, generation or content changes. Returns GsVram::InvalidPage on failure.

void* nCine::RHI::GS::GsTexture::MapStreamingTexels(std::int32_t& strideBytes)

Always returns nullptr on the GS - local memory cannot be written by the CPU.

The PVR and GU backends answer this for content that is rebuilt every frame (the cinematics), so a frame can be produced straight where it will be sampled. The Graphics Synthesizer has no host mapping of its local memory at all: everything arrives through a GIF transfer, so there is no pointer to hand out. RHI_CAP_STREAMING_TEXTURES is deliberately left undefined for this backend so that no caller reaches here in the first place.

nCine::RHI::GS::GsTexture class #include <nCine/Graphics/RHI/GS/GsTexture.h>