nCine::RHI::RSX::RsxTexture class
#include <nCine/Graphics/RHI/RSX/RsxTexture.h>

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

Exposes the neutral upload surface Texture.cpp drives (TexImage2D, TexSubImage2D, TexStorage2D, filter/wrap/swizzle setters) and keeps the texels twice: once in a host store the uploads write into, and once in the GPU-visible copy the hardware samples, refreshed from the host store whenever it went stale. Every format is promoted to RGBA8 in both, which keeps one texture format on the GPU side.

A texture bound as a colour attachment is the exception: the GPU writes it, so its GPU-visible copy is* the truth and the host store is only kept for a readback. That is also why the two live in separate allocations at all - the render target's surface has to stay put across frames while the host store may be reallocated by an upload.

The swizzle is free here, and that is the one real difference from the sceGxm backend.** sceGxm can only express a fixed set of channel patterns, so GxmTexture bakes the engine's swizzle into the texels and re-bakes them whenever it changes. The RSX has a general remap field in its texture control structure: each of the four output channels independently selects a source channel, or a constant zero or one. So the texels are uploaded once and never rewritten, and SetSwizzle() only recomputes a word.

That same field also absorbs the endianness problem the format list creates. The RSX's 32-bit colour format is A8R8G8B8 - a word, not a byte order - and the engine's RGBA8 store read as a big-endian word lands as 0xRRGGBBAA, so the hardware sees red where alpha belongs and so on round the cycle. Rather than byte-swapping every upload, BuildRemap() composes that fixed rotation with whatever swizzle the engine asked for, and the GPU does both in the sampler for nothing.

The GPU copy is laid out linearly (GCM_TEXTURE_FORMAT_LIN) with an explicit pitch, which the RSX carries in the control structure - so unlike sceGxm there is no width-dependent choice of layout and no addressing mode lost to it. The pitch is rounded up to 64 bytes, which is what a colour surface needs when the texture is also a render target, so one rule covers both uses.

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

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

Public functions

auto operator=(const RsxTexture&) -> RsxTexture& deleted
auto GetGcmTexture() const -> const gcmTexture*: Returns the libgcm texture control structure, materializing the GPU copy if needed, or nullptr.
auto GetSurfaceData() const -> void*: Returns the GPU-visible base address of the texels, allocating the copy if needed (used by RsxRenderTarget).
auto GetSurfaceStride() const -> std::uint32_t: Returns the byte distance between two rows of the GPU copy (its surface stride).
void ReleaseGpu() const: Releases the GPU-visible copy (on re-allocation and destruction).
void ApplySamplerState(std::uint32_t textureUnit) const: Programs this texture's filter and wrap modes onto a texture unit.
auto MapStreamingTexels(std::int32_t& strideBytes) -> void*: Returns a writable pointer to the GPU-visible store, for content rebuilt every frame.
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 stored texels (always RGBA8 after the promotion).
auto GetUploadFormat() const -> PixelFormat: Returns the original upload format before promotion (R8/RG8/RGB8 kept).
auto GetStrideBytes() const -> std::int32_t: Returns the byte distance between two consecutive rows of the host store.
auto GetPixels(std::int32_t level = 0) const -> const std::uint8_t*: Returns the base pointer of the level-0 host store (may be nullptr before an upload); the single-level store ignores level.
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, same as GetWrapS()).
auto GetSwizzle() const -> const SwizzleChannel*: Returns the four-channel sampling swizzle (identity by default).
auto GetMagFilter() const -> nCine::SamplerFilter: Returns the magnification filter (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 (the GPU copy is rebuilt, since the GPU writes it from then on).
auto MutablePixels() -> std::uint8_t*: Returns a writable base pointer of the level-0 host store.
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 by this backend, 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 by this backend, accepted as a no-op).
void GetTexImage(std::int32_t level, PixelFormat format, bool bgr, void* pixels): Reads back level-0 texels into client memory (from the GPU copy when the texture is a render target).
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 (recomputes the remap word; the texels are not touched).
void SetMaxLevel(std::int32_t maxLevel): Sets the highest defined mipmap level (ignored, the store is single-level).
void SetObjectLabel(StringView label): Sets a debug label for the texture (ignored).
auto GetMagFiltering() const -> nCine::SamplerFilter: Returns the magnification filter.

Function documentation

void nCine::RHI::RSX::RsxTexture::ApplySamplerState(std::uint32_t textureUnit) const

Programs this texture's filter and wrap modes onto a texture unit.

Unlike sceGxm, which keeps sampler state inside the texture structure, the RSX carries it in command-buffer methods - so it is re-issued per draw by RsxDevice::DrawCommon() rather than baked in once, and this is part of the backend surface rather than an internal detail.

void* nCine::RHI::RSX::RsxTexture::MapStreamingTexels(std::int32_t& strideBytes)

Returns a writable pointer to the GPU-visible store, for content rebuilt every frame.

Lets the cinematics produce a frame straight where the GPU will sample it instead of writing the host store and copying it across. Answered only for an ordinary RGBA8 texture: a colour attachment is written by the GPU, so handing its texels to the CPU would race the frame.

strideBytes receives the row pitch, which is the 64-byte aligned one the GPU copy was allocated with rather than the texture's own width. Nothing written here reaches the host store, so such a texture must be rewritten in full every frame - and never read back, because this memory is local video memory the PPE reads at a crawl (see RsxVram).

nCine::RHI::RSX::RsxTexture class #include <nCine/Graphics/RHI/RSX/RsxTexture.h>