Gx2Texture class
Texture object of the GX2 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 copy the hardware samples, refreshed from the host store whenever it went stale. Every format is promoted to RGBA8 in both, so the GPU side has one format, GX2_SURFACE_FORMAT_UNORM_R8_G8_B8_A8, whose byte order in memory is the store's own.
An ordinary texture is laid out GX2_TILE_MODE_LINEAR_ALIGNED, so an upload is a row copy at the surface pitch. A texture used as a colour attachment is tiled (GX2_TILE_MODE_DEFAULT), because the colour buffer that Gx2RenderTarget builds on the same surface renders much faster that way; the GPU writes it, so its GPU copy is the truth and the host store is never uploaded over it.
The swizzle costs nothing: GX2Texture::compMap selects a source channel or a constant for each output channel, so SetSwizzle() only recomputes that word and the texels stay as uploaded. The filter and wrap modes go into a GX2Sampler the draw path binds next to the texture (ApplySamplerState()).
The GPU copy is refreshed only when a draw binds the texture, and a queued draw of an earlier frame may still sample it then. A draw stamps the texture with its batch token (MarkUsed()); a refresh from the host store while that token has not retired moves the GPU copy to a fresh block and retires the old one, and MapStreamingTexels() waits for the token instead (its caller rewrites the texels in place).
Public static variables
-
static std::
uint32_t MaxTextureUnits constexpr - Number of texture units tracked by the device.
Public static functions
- static void ReleaseMem1Copies()
- Frees every GPU copy that lives in MEM1, before SDL destroys its MEM1 heap (the GPU must be idle).
-
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
- Gx2Texture(TextureTarget target) explicit
- ~Gx2Texture()
- Gx2Texture(const Gx2Texture&) deleted
Public functions
- auto operator=(const Gx2Texture&) -> Gx2Texture& deleted
- auto GetGx2Texture() const -> const GX2Texture*
- Returns the GX2 texture, materializing or refreshing the GPU copy if needed, or
nullptr. - auto GetSurface() const -> const GX2Surface*
- Returns the surface of the GPU copy, allocating it if needed (used by Gx2RenderTarget), or
nullptr. - void ReleaseGpu() const
- Releases the GPU copy (on re-allocation and destruction).
-
auto ApplySamplerState(std::
uint32_t textureUnit) const -> bool - Binds this texture and its sampler state to a pixel shader texture unit, returns
falseif it has no GPU copy. -
void MarkUsed(std::
uint32_t token) const - Records that a draw of the batch with
tokensamples the GPU copy (see Gx2Device::GetUseToken()). -
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
nullptrbefore an upload); the single-level store ignoreslevel. - 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
trueif 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).
- void AddAttachedTarget(Gx2RenderTarget* target)
- Records that a render target has this texture as a colour attachment (called by Gx2RenderTarget).
- void RemoveAttachedTarget(Gx2RenderTarget* target)
- Records that a render target no longer has this texture attached (called by Gx2RenderTarget).
- void SetPreferFastMemory(bool value)
- Asks for the render target's texels to go in MEM1 (see Gx2Memory).
-
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
static void nCine:: RHI:: GX2:: Gx2Texture:: ReleaseMem1Copies()
Frees every GPU copy that lives in MEM1, before SDL destroys its MEM1 heap (the GPU must be idle).
Their owners allocate them again the next time they are drawn into; their contents are lost, which is fine for render targets that are redrawn every frame.
void* nCine:: RHI:: GX2:: Gx2Texture:: 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 of the linear GPU copy, which can be wider than the texture. Nothing written here reaches the host store, so such a texture must be rewritten in full every frame. The caller's writes are flushed out of the CPU cache on the next bind.
void nCine:: RHI:: GX2:: Gx2Texture:: AddAttachedTarget(Gx2RenderTarget* target)
Records that a render target has this texture as a colour attachment (called by Gx2RenderTarget).
A texture can be attached to several targets at once (the upscale pass draws into one texture through three viewports). A texture destroyed while still attached tells those targets to forget it, because the engine may destroy a viewport's texture before the viewport (PlayerViewport does).
void nCine:: RHI:: GX2:: Gx2Texture:: SetPreferFastMemory(bool value)
Asks for the render target's texels to go in MEM1 (see Gx2Memory).
Applies from the next allocation of the GPU copy, and only while the texture is a render target; it falls back to MEM2 when MEM1 is full. Meant for the few targets drawn into and read every frame (the player scene targets, the compose target), which then cost about half the GPU time.