KDGpu::Texture
Module: Public API
Represents a GPU texture/image for rendering, sampling, and storage. More...
#include <KDGpu/texture.h>
Public Functions
Friends
Detailed Description
Represents a GPU texture/image for rendering, sampling, and storage.
Vulkan equivalent:VkImage
Texture represents a multidimensional image on the GPU that can be used as a render target, sampled in shaders, or used for general storage. Textures can be 1D, 2D, 3D, or cube maps.
Key features:
- 1D, 2D, 3D, and cube map support
- Mipmapping and multisampling
- Various formats (color, depth, stencil, compressed)
- Multiple usage modes (color attachment, depth, sampled, storage)
- CPU-accessible mapping for linear textures
Lifetime: Textures are created by Device and must remain valid while referenced by pipelines, descriptor sets, or GPU commands. They use RAII and clean up automatically.
Usage
Creating a 2D color texture:
| KDGpu::Texture texture = device.createTexture(KDGpu::TextureOptions{
.type = KDGpu::TextureType::TextureType2D,
.format = KDGpu::Format::R8G8B8A8_SRGB,
.extent = { 1024, 1024, 1 },
.mipLevels = 1,
.usage = KDGpu::TextureUsageFlagBits::SampledBit | KDGpu::TextureUsageFlagBits::TransferDstBit,
.memoryUsage = KDGpu::MemoryUsage::GpuOnly,
});
|
Filename: kdgpu_doc_snippets.cpp
Creating a depth texture:
| uint32_t width = 1920, height = 1080;
KDGpu::Texture depthBuffer = device.createTexture(KDGpu::TextureOptions{
.type = KDGpu::TextureType::TextureType2D,
.format = KDGpu::Format::D32_SFLOAT,
.extent = { width, height, 1 },
.usage = KDGpu::TextureUsageFlagBits::DepthStencilAttachmentBit,
});
|
Filename: kdgpu_doc_snippets.cpp
Creating a render target texture:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17 | KDGpu::Texture renderTarget = device.createTexture(KDGpu::TextureOptions{
.type = KDGpu::TextureType::TextureType2D,
.format = KDGpu::Format::R8G8B8A8_UNORM,
.extent = { 1920, 1080, 1 },
.usage = KDGpu::TextureUsageFlagBits::ColorAttachmentBit | KDGpu::TextureUsageFlagBits::SampledBit,
});
KDGpu::TextureView renderView = renderTarget.createView();
auto renderPass = recorder.beginRenderPass(KDGpu::RenderPassCommandRecorderOptions{
.colorAttachments = {
{
.view = renderView,
.loadOperation = KDGpu::AttachmentLoadOperation::Clear,
},
},
});
|
Filename: kdgpu_doc_snippets.cpp
Creating a cube map texture:
| KDGpu::Texture cubemap = device.createTexture(KDGpu::TextureOptions{
.type = KDGpu::TextureType::TextureTypeCube,
.format = KDGpu::Format::R16G16B16A16_SFLOAT,
.extent = { 512, 512, 1 },
.mipLevels = 1,
.arrayLayers = 6, // 6 cube faces
.usage = KDGpu::TextureUsageFlagBits::SampledBit | KDGpu::TextureUsageFlagBits::TransferDstBit,
});
|
Filename: kdgpu_doc_snippets.cpp
Creating a texture with mipmaps:
| uint32_t mipLevels = static_cast<uint32_t>(std::floor(std::log2(std::max(1024, 1024)))) + 1;
KDGpu::Texture mipmappedTexture = device.createTexture(KDGpu::TextureOptions{
.type = KDGpu::TextureType::TextureType2D,
.format = KDGpu::Format::R8G8B8A8_SRGB,
.extent = { 1024, 1024, 1 },
.mipLevels = mipLevels,
.usage = KDGpu::TextureUsageFlagBits::SampledBit | KDGpu::TextureUsageFlagBits::TransferDstBit,
});
|
Filename: kdgpu_doc_snippets.cpp
Creating a multisampled texture (MSAA):
| KDGpu::Texture msaaTarget = device.createTexture(KDGpu::TextureOptions{
.type = KDGpu::TextureType::TextureType2D,
.format = KDGpu::Format::R8G8B8A8_SRGB,
.extent = { 1920, 1080, 1 },
.samples = KDGpu::SampleCountFlagBits::Samples4Bit,
.usage = KDGpu::TextureUsageFlagBits::ColorAttachmentBit,
});
|
Filename: kdgpu_doc_snippets.cpp
Resolving MSAA texture to non-MSAA texture:
| auto resolveRenderPass = recorder.beginRenderPass(KDGpu::RenderPassCommandRecorderOptions{
.colorAttachments = {
KDGpu::ColorAttachment{
.view = msaaTarget.createView(),
.resolveView = resolveTarget.createView(),
.loadOperation = KDGpu::AttachmentLoadOperation::Load,
.storeOperation = KDGpu::AttachmentStoreOperation::DontCare,
},
},
}); // MSAA target not needed after resolve
|
Filename: kdgpu_doc_snippets.cpp
Creating a storage image for compute shaders:
| KDGpu::Texture storageTexture = device.createTexture(KDGpu::TextureOptions{
.type = KDGpu::TextureType::TextureType2D,
.format = KDGpu::Format::R32G32B32A32_SFLOAT,
.extent = { 1024, 1024, 1 },
.usage = KDGpu::TextureUsageFlagBits::StorageBit | KDGpu::TextureUsageFlagBits::SampledBit,
});
// Write to texture in compute shader
// Read from texture in fragment shader
|
Filename: kdgpu_doc_snippets.cpp
Creating texture views for sampling:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 | // Full texture view
KDGpu::TextureView fullView = texture.createView();
// Single mip level view
KDGpu::TextureView mipView = texture.createView(KDGpu::TextureViewOptions{
.range = {
.aspectMask = KDGpu::TextureAspectFlagBits::ColorBit,
.baseMipLevel = 2,
.levelCount = 1,
},
});
// Cube map face view
KDGpu::TextureView faceView = cubemap.createView(KDGpu::TextureViewOptions{
.viewType = KDGpu::ViewType::ViewType2D,
.range = {
.aspectMask = KDGpu::TextureAspectFlagBits::ColorBit,
.baseArrayLayer = 0, // First face
.layerCount = 1,
},
});
|
Filename: kdgpu_doc_snippets.cpp
Uploading texture data:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35 | // 1. Create staging buffer with image data
KDGpu::Buffer textureStagingBuffer = device.createBuffer(KDGpu::BufferOptions{
.size = imageData.size(),
.usage = KDGpu::BufferUsageFlagBits::TransferSrcBit,
.memoryUsage = KDGpu::MemoryUsage::CpuToGpu,
},
imageData.data());
// 2. Copy to texture
KDGpu::CommandRecorder uploadRecorder = device.createCommandRecorder();
uploadRecorder.copyBufferToTexture(KDGpu::BufferToTextureCopy{
.srcBuffer = textureStagingBuffer,
.dstTexture = texture,
.dstTextureLayout = KDGpu::TextureLayout::TransferDstOptimal,
.regions = {
{
.textureSubResource = {
.aspectMask = KDGpu::TextureAspectFlagBits::ColorBit,
.mipLevel = 0,
},
.textureExtent = { 1024, 1024, 1 },
},
},
});
// 3. Transition to shader-readable layout
uploadRecorder.textureMemoryBarrier(KDGpu::TextureMemoryBarrierOptions{
.srcStages = KDGpu::PipelineStageFlagBit::TransferBit,
.srcMask = KDGpu::AccessFlagBit::TransferWriteBit,
.dstStages = KDGpu::PipelineStageFlagBit::FragmentShaderBit,
.dstMask = KDGpu::AccessFlagBit::ShaderReadBit,
.oldLayout = KDGpu::TextureLayout::TransferDstOptimal,
.newLayout = KDGpu::TextureLayout::ShaderReadOnlyOptimal,
.texture = texture,
});
|
Filename: kdgpu_doc_snippets.cpp
Common texture formats:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15 | // Color formats
KDGpu::Format rgba8 = KDGpu::Format::R8G8B8A8_UNORM; // Standard 8-bit RGBA
KDGpu::Format rgba8srgb = KDGpu::Format::R8G8B8A8_SRGB; // SRGB color space
KDGpu::Format rgba16f = KDGpu::Format::R16G16B16A16_SFLOAT; // HDR (half float)
KDGpu::Format rgba32f = KDGpu::Format::R32G32B32A32_SFLOAT; // HDR (full float)
KDGpu::Format bgra8srgb = KDGpu::Format::B8G8R8A8_SRGB; // Common swapchain format
// Depth formats
KDGpu::Format depth32 = KDGpu::Format::D32_SFLOAT; // 32-bit depth
KDGpu::Format depth24s8 = KDGpu::Format::D24_UNORM_S8_UINT; // 24-bit depth + 8-bit stencil
KDGpu::Format depth16 = KDGpu::Format::D16_UNORM; // 16-bit depth
// Compressed formats
KDGpu::Format bc1 = KDGpu::Format::BC1_RGB_SRGB_BLOCK; // DXT1
KDGpu::Format bc3 = KDGpu::Format::BC3_SRGB_BLOCK; // DXT5
|
Filename: kdgpu_doc_snippets.cpp
Vulkan mapping:
See also:
TextureView, Device, TextureOptions, Sampler
KDGpu API Overview
KDGpu to Vulkan API Mapping
Public Functions Documentation
function Texture
function ~Texture
function Texture
| Texture(
Texture && other
)
|
function operator=
| Texture & operator=(
Texture && other
)
|
function Texture
| Texture(
const Texture &
) =delete
|
function operator=
| Texture & operator=(
const Texture &
) =delete
|
function handle
| inline const Handle< Texture_t > & handle() const
|
function isValid
| inline bool isValid() const
|
function operator Handle< Texture_t >
| inline operator Handle< Texture_t >() const
|
function createView
| TextureView createView(
const TextureViewOptions & options =TextureViewOptions()
) const
|
function map
function unmap
function hostLayoutTransition
| void hostLayoutTransition(
const HostLayoutTransition & transition
)
|
function copyHostMemoryToTexture
| void copyHostMemoryToTexture(
const HostMemoryToTextureCopy & copy
)
|
function copyTextureToHostMemory
| void copyTextureToHostMemory(
const TextureToHostMemoryCopy & copy
)
|
function copyTextureToTextureHost
| void copyTextureToTextureHost(
const TextureToTextureCopyHost & copy
)
|
function getSubresourceLayout
| SubresourceLayout getSubresourceLayout(
const TextureSubresource & subresource =TextureSubresource()
) const
|
function generateMipMaps
| bool generateMipMaps(
Device & device,
Queue & transferQueue,
const Handle< Texture_t > & sourceTexture,
const TextureOptions & options,
TextureLayout oldLayout,
TextureLayout newLayout =TextureLayout::Undefined
)
|
Generate mipmaps by copying from another texture and then generating mipmaps for this texture.
Parameters:
- device KDGpuDevice
- transferQueue KDGpu Transfer Queue
- sourceTexture Texture to copy/blit from when creating the mipmaps
- options Texture Options for the target texture
- oldLayout Transitioning from this layout
- newLayout Transitioning to this layout when the mip map creation is done
Return: true when successful
function generateMipMaps
| bool generateMipMaps(
Device & device,
Queue & transferQueue,
const TextureOptions & options,
TextureLayout oldLayout,
TextureLayout newLayout =TextureLayout::Undefined
)
|
Generate mipmaps for this texture.
Parameters:
- device KDGpuDevice
- transferQueue KDGpu Transfer Queue
- options Texture Options for the target texture
- oldLayout Transitioning from this layout
- newLayout Transitioning to this layout when the mip map creation is done
Return: true when successful
function externalMemoryHandle
| MemoryHandle externalMemoryHandle() const
|
| uint64_t drmFormatModifier() const
|
Friends
friend Swapchain
| friend class Swapchain(
Swapchain
);
|
friend Device
| friend class Device(
Device
);
|
friend VulkanGraphicsApi
| friend class VulkanGraphicsApi(
VulkanGraphicsApi
);
|
friend operator==
| friend KDGPU_EXPORT bool operator==(
const Texture & a,
const Texture & b
);
|
Updated on 2026-03-31 at 00:02:07 +0000