Skip to content

KDGpu::Surface

Module: Public API

Represents a platform-specific window surface for presentation. More...

#include <KDGpu/surface.h>

Public Functions

Name
Surface()
~Surface()
Surface(Surface && other)
Surface & operator=(Surface && other)
Surface(const Surface & ) =delete
Surface & operator=(const Surface & ) =delete
Handle< Surface_t > handle() const
bool isValid() const
operator Handle< Surface_t >() const

Friends

Name
class Instance
class VulkanGraphicsApi

Detailed Description

1
class KDGpu::Surface;

Represents a platform-specific window surface for presentation.

Vulkan equivalent:VkSurfaceKHR

Surface represents a native window or display surface where rendered images can be presented. It abstracts platform-specific windowing systems (X11, Wayland, Win32, etc.).

Key features:

  • Platform-independent surface abstraction
  • Query surface capabilities and formats
  • Create swapchains for presentation
  • Check adapter compatibility

Lifetime:Surface objects are created by Instance from platform window handles and should remain valid while the swapchain is in use. They use RAII and clean up automatically.

Usage

Creating a surface (with platform window):

1
2
3
4
5
6
    // Platform-specific (example for XCB on Linux)
    // xcb_connection_t *connection = /* ... */;
    // xcb_window_t window = /* ... */;
    KDGpu::Surface surface = instance.createSurface(KDGpu::SurfaceOptions{
            /* Set underlying window handle based on platform */
    });

Filename: kdgpu_doc_snippets.cpp

Checking adapter surface support:

1
2
3
4
5
6
7
8
9
    KDGpu::Adapter *adapter = instance.selectAdapter(KDGpu::AdapterDeviceType::DiscreteGpu);

    // Check if adapter supports presenting to this surface
    auto queueTypes = adapter->queueTypes();
    for (size_t i = 0; i < queueTypes.size(); ++i) {
        if (adapter->supportsPresentation(surface, i)) {
            // Queue family i can present to this surface
        }
    }

Filename: kdgpu_doc_snippets.cpp

Querying surface capabilities:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
    auto swapchainProps = adapter->swapchainProperties(surface.handle());

    // Check supported formats
    for (const auto &format : swapchainProps.formats) {
        if (format.format == KDGpu::Format::B8G8R8A8_SRGB) {
            // Surface supports SRGB format
        }
    }

    // Get surface size limits
    uint32_t minWidth = swapchainProps.capabilities.minImageExtent.width;
    uint32_t maxWidth = swapchainProps.capabilities.maxImageExtent.width;
    uint32_t minImages = swapchainProps.capabilities.minImageCount;
    uint32_t maxImages = swapchainProps.capabilities.maxImageCount;

Filename: kdgpu_doc_snippets.cpp

Creating a swapchain from surface:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
    KDGpu::Device device = adapter->createDevice();

    // Create swapchain for presenting to surface
    uint32_t windowWidth = 1920, windowHeight = 1080;
    KDGpu::Swapchain swapchain = device.createSwapchain(KDGpu::SwapchainOptions{
            .surface = surface.handle(),
            .minImageCount = 3, // Triple buffering
            .imageExtent = { windowWidth, windowHeight },
            .imageUsageFlags = KDGpu::TextureUsageFlagBits::ColorAttachmentBit,
    });

Filename: kdgpu_doc_snippets.cpp

Complete window integration example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
    // Create instance
    KDGpu::Instance instanceComplete = api->createInstance(instanceOptions);

    // Create surface from window
    KDGpu::Surface surfaceComplete = instanceComplete.createSurface(surfaceOptions);

    // Select adapter that supports the surface
    KDGpu::Adapter *adapterComplete = instanceComplete.selectAdapter(KDGpu::AdapterDeviceType::DiscreteGpu);

    // Query supported formats
    auto swapchainPropsComplete = adapterComplete->swapchainProperties(surfaceComplete.handle());
    KDGpu::Format surfaceFormat = swapchainPropsComplete.formats[0].format;

    // Create device
    KDGpu::Device deviceComplete = adapterComplete->createDevice();

    // Create swapchain
    KDGpu::Swapchain swapchainComplete = deviceComplete.createSwapchain(KDGpu::SwapchainOptions{
            .surface = surfaceComplete.handle(),
            .format = surfaceFormat,
            .minImageCount = 3,
            .imageExtent = { width, height },
            .imageUsageFlags = KDGpu::TextureUsageFlagBits::ColorAttachmentBit,
    });

Filename: kdgpu_doc_snippets.cpp

Vulkan mapping:

  • Surface creation -> vkCreateXXXSurfaceKHR() (platform-specific)
  • Used in vkGetPhysicalDeviceSurfaceSupportKHR()
  • Used in vkGetPhysicalDeviceSurfaceCapabilitiesKHR()
  • Used in vkCreateSwapchainKHR()

See also:

Instance, Swapchain, Adapter, Device

KDGpu API Overview

KDGpu to Vulkan API Mapping

Public Functions Documentation

function Surface

1
Surface()

function ~Surface

1
~Surface()

function Surface

1
2
3
Surface(
    Surface && other
)

function operator=

1
2
3
Surface & operator=(
    Surface && other
)

function Surface

1
2
3
Surface(
    const Surface & 
) =delete

function operator=

1
2
3
Surface & operator=(
    const Surface & 
) =delete

function handle

1
inline Handle< Surface_t > handle() const

function isValid

1
inline bool isValid() const

function operator Handle< Surface_t >

1
inline operator Handle< Surface_t >() const

Friends

friend Instance

1
2
3
friend class Instance(
    Instance 
);

friend VulkanGraphicsApi

1
2
3
friend class VulkanGraphicsApi(
    VulkanGraphicsApi 
);

Updated on 2026-03-31 at 00:02:07 +0000