nCine::RHI::PVR::PvrTexture class
#include <nCine/Graphics/RHI/PVR/PvrTexture.h>

Texture object of the PVR 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 backend uses) plus a VRAM store padded up to the PowerVR's power-of-two dimension requirement (the padding is compensated by GetUScale() / GetVScale(), which the device multiplies into every submitted texture coordinate):

R8 index textures upload as twiddled 8bpp paletted texels; the palette BANK is selected per draw by the device from the instance's palOffset (4 hardware banks of 256 ARGB8888 entries).
RGBA8 / RGB8 textures convert to twiddled ARGB4444.
RG8 (index + per-pixel alpha) has no paletted PVR equivalent (a paletted texel's alpha comes from the palette entry), so those keep only the linear store and the device requests a per-palette-row CPU bake to ARGB4444 (EnsureBakedArgb4444), cached until the row or texel content changes. The shared 256x256 palette texture (labelled "Palettes") is intercepted: it keeps only the linear store and the device loads its rows into the hardware palette banks on demand.

Render targets allocate a non-twiddled RGB565 VRAM surface the tile accelerator renders into (pvr_scene_begin_txr). 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

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

Public functions

auto operator=(const PvrTexture&) -> PvrTexture& 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 when the store is compressed).
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 PVR).
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 (tile-accelerator RTT surface).
void SetRenderTarget(bool isRenderTarget): Marks the texture as (or no longer as) a color render target; becoming one allocates the RTT 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 VRAM store is 8bpp paletted (draws need a palette bank 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 palette banks).
auto GetVramPointer() const -> pvr_ptr_t: Returns the VRAM texture pointer, or nullptr when none exists (RG8 without a bake, palette texture).
auto AcquireVramPointer() -> pvr_ptr_t: Returns the VRAM texture pointer, rebuilding the store if it was reclaimed.
auto GetVramFormat() const -> std::uint32_t: Returns the PVR texture format word of the VRAM store WITHOUT the palette-bank bits (the device ors them in).
auto GetPaddedWidth() const -> std::int32_t: Returns the power-of-two padded VRAM width.
auto GetPaddedHeight() const -> std::int32_t: Returns the power-of-two padded VRAM height.
auto GetUScale() const -> float: Returns the U compensation factor for the power-of-two padding (realW / paddedW).
auto GetVScale() const -> float: Returns the V compensation factor for the power-of-two padding (realH / paddedH).
auto EnsureBakedArgb4444(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette) -> pvr_ptr_t: Returns the VRAM pointer of an ARGB4444 copy of an RG8 store baked through one palette row.
auto MapStreamingTexels(std::int32_t& strideBytes) -> void*: Returns a writable pointer to the VRAM store, for content that is rebuilt every frame.
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 palette banks.

Function documentation

const std::uint8_t* nCine::RHI::PVR::PvrTexture::GetPixels(std::int32_t level = 0) const

Returns the base pointer of the linear host store (may be nullptr before an upload).

Static R8/RG8 content keeps its host store run-length compressed to save main memory (see StorePixels()), in which case there is no linear pointer to hand out and this returns nullptr. The only external consumer on this backend is the device's palette-texture path, and the palette texture is never compressed.

pvr_ptr_t nCine::RHI::PVR::PvrTexture::AcquireVramPointer()

Returns the VRAM texture pointer, rebuilding the store if it was reclaimed.

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

pvr_ptr_t nCine::RHI::PVR::PvrTexture::EnsureBakedArgb4444(const std::uint32_t* paletteRow, std::uint32_t paletteRowIndex, std::uint32_t paletteGeneration, const void* palette)

Returns the VRAM pointer of an ARGB4444 copy of an RG8 store baked through one palette row.

Analogous to the GX backend's bake: index resolved through paletteRow (256 RGBA8 entries), alpha from the texel's own alpha byte; one cached copy, rebuilt when the row/generation/content changes. Returns nullptr on allocation failure.

void* nCine::RHI::PVR::PvrTexture::MapStreamingTexels(std::int32_t& strideBytes)

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

Answered only for the formats the hardware samples verbatim from video memory (RGB565), which is what lets the cinematics build a frame straight where it will be read from instead of into a buffer that is then copied into the host store and copied again into video memory. Returns nullptr for anything else, and for a store that cannot be allocated.

strideBytes receives the row pitch, which is the power-of-two padded 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.

nCine::RHI::PVR::PvrTexture class #include <nCine/Graphics/RHI/PVR/PvrTexture.h>