nCine::RHI::Vulkan::VulkanTexture class
#include <nCine/Graphics/RHI/Vulkan/VulkanTexture.h>

Texture object of the Vulkan 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 VkImage + VkImageView + VkSampler from this surface: a staging-buffer upload for CPU textures, or a colour-attachment image for render targets. The sampling swizzle is applied through the image view's VkComponentMapping (no texel baking, unlike D3D11). 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

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

Public functions

auto operator=(const VulkanTexture&) -> VulkanTexture& deleted
void EnsureGpu() const
Materializes the VkImage/view/sampler if missing (does NOT upload texels; see RecordStreamingUpload()).
auto HasPendingUpload() const -> bool
true if CPU texels are pending upload to the GPU image (a streaming update not yet recorded)
void RecordStreamingUpload(std::uint64_t cmdBuffer) const
Records the pending CPU->GPU texel upload (staging copy + layout barriers) into cmdBuffer (an opaque VkCommandBuffer); the device frees the staging buffer once the frame completes.
auto GpuImage() const -> std::uint64_t
Returns the VkImage (as std::uint64_t), creating it on demand; 0 if unavailable.
auto GpuView() const -> std::uint64_t
Returns the sampling VkImageView (with the swizzle component mapping).
auto GpuSampler() const -> std::uint64_t
Returns the VkSampler matching the current filter/wrap.
auto GpuFormat() const -> std::uint32_t
Returns the VkFormat of the image.
auto GetCurrentLayout() const -> std::uint32_t
Returns the last-known VkImageLayout of the image (device layout tracking).
void SetCurrentLayout(std::uint32_t layout) const
Records the current VkImageLayout (the device updates this after each transition).
void ReleaseGpu() const
Releases the GPU image / 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 image with the color-attachment 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).
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.