nCine::RHI::Metal::MetalTexture class
#include <nCine/Graphics/RHI/Metal/MetalTexture.h>

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

Wraps a single, tightly-packed level-0 pixel buffer in host memory and exposes the neutral upload surface Texture.cpp drives (TexImage2D, TexSubImage2D, TexStorage2D, filter/wrap/swizzle setters). It materializes the real MTL::Texture + MTL::SamplerState from this surface: every texture lives in GPU-private storage, CPU textures are filled through a staging-buffer blit the device records into the frame's command buffer right before the draw that samples them (so a texture re-uploaded every frame - the palette - lands at exactly the point of the frame the GL upload would, with no CPU/GPU race), render targets are colour attachments. The sampling swizzle is applied through a texture view (MTL::TextureSwizzleChannels, no texel baking, like Vulkan's component mapping). 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

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

Public functions

auto operator=(const MetalTexture&) -> MetalTexture& deleted
void EnsureGpu() const
Materializes the MTL::Texture / view / sampler if missing (does NOT upload texels; see RecordStreamingUpload()).
auto HasPendingUpload() const -> bool
true if CPU texels are pending upload to the GPU texture (a streaming update not yet recorded)
void RecordStreamingUpload(void* commandBuffer) const
Records the pending CPU->GPU texel upload (staging buffer + blit of the whole level 0) into commandBuffer (an opaque MTL::CommandBuffer*, outside any render encoder).
auto GpuTexture() const -> void*
Returns the MTL::Texture* (as void*), creating it on demand; nullptr if unavailable.
auto GpuView() const -> void*
Returns the MTL::Texture* to sample from (the swizzle view, or the texture itself for an identity swizzle).
auto GpuSampler() const -> void*
Returns the MTL::SamplerState* matching the current filter/wrap.
auto GpuFormat() const -> std::uint32_t
Returns the MTL::PixelFormat of the texture (as an integer).
void ReleaseGpu() const
Releases the GPU texture / view / sampler (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 (after any promotion to the RGBA8 store).
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 level 0.
auto GetPixels(std::int32_t level = 0) const -> const std::uint8_t*
Returns the base pointer of the level-0 texel 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 (rebuilds the GPU texture with the render-target usage when it changes).
auto MutablePixels() -> std::uint8_t*
Returns a writable base pointer of the level-0 texel store (for render-target output).
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.
void SetMinFiltering(nCine::SamplerFilter filter)
Sets the minification filter (stored).
void SetMagFiltering(nCine::SamplerFilter filter)
Sets the magnification filter (stored).
void SetWrap(SamplerWrapping wrap)
Sets the wrap mode (stored).
void SetSwizzle(SwizzleChannel r, SwizzleChannel g, SwizzleChannel b, SwizzleChannel a)
Sets the sampling swizzle (stored; rebuilds the GPU texture view).
void SetMaxLevel(std::int32_t maxLevel)
Sets the highest defined mipmap level (ignored).
void SetObjectLabel(StringView label)
Sets a debug label for the texture (ignored).
auto GetMagFiltering() const -> nCine::SamplerFilter
Returns the magnification filter.