nCine::RHI::GXM::GxmTexture class
#include <nCine/Graphics/RHI/GXM/GxmTexture.h>

Texture object of the sceGxm 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 and lets the sampling swizzle be baked into the texels (sceGxm can express a channel swizzle in the texture format, but only for a fixed set of patterns).

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 GPU copy is laid out linearly, in one of the two layouts sceGxm offers for that:

  • SCE_GXM_TEXTURE_LINEAR when the width is a multiple of 8, which the hardware needs because a linear texture has no stride of its own (see SceGxmTexture: its control words carry only a width and a height) and derives the row pitch from the width. This is the fully featured layout - every addressing mode, mip filtering - and is what the atlases and the power-of-two render targets get.
  • SCE_GXM_TEXTURE_LINEAR_STRIDED otherwise, which carries an explicit stride and so accepts any width, at the cost of mip filtering and a separate minification filter (the hardware rejects both with SCE_GXM_ERROR_UNSUPPORTED on a strided texture, so they are not programmed for one).

A colour attachment needs its stride padded to a multiple of 8 texels on top of that, because sceGxmColorSurfaceInit() rejects anything else with SCE_GXM_ERROR_INVALID_ALIGNMENT - which is why a render target whose width is not already a multiple of 8 is always a strided texture.

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

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

Public functions

auto operator=(const GxmTexture&) -> GxmTexture& deleted
auto GetGxmTexture() const -> const SceGxmTexture*
Returns the sceGxm 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 GxmRenderTarget).
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).
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 (baked into the GPU copy's texels).
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.