Surface & Swapchain Management

[rudrabeniwal]

Add Vulkan Surface & Swapchain Management

Overview

This pull request introduces Vulkan surface and swapchain management system in Cyfra. This should be a good base for any future improvements to the rendering pipeline.

Features

• Surface Abstraction

  • Surface encapsulates VkSurfaceKHR, managing its lifecycle via GLFW.
  • Supports platform-specific extension validation.
  • RAII-style management for automatic resource cleanup.

• SurfaceCapabilities

  • Lets us query formats, presentation modes, surface size, and image counts.
  • Helps pick the best configuration for the GPU and window.

• SurfaceFactory

  • Builds surfaces in a way that works on all platforms.
  • It also checks if necessary Vulkan extensions are available and fails fast if not.

• SurfaceManager

  • Manages multiple surfaces simultaneously.
  • Handles window events like resize and close via GLFW callbacks.
  • Provides centralized lifecycle and cleanup management.

• SwapChainManager

  • Automates selection and creation of optimal swapchain parameters.
  • Manages lifecycle of swapchain and associated VkImageView objects.
  • Supports manual recreation of swapchains on window resize events.

• Image View Handling

  • Automatically creates/destroys image views for each swapchain image.
  • Prevents memory leaks through scoped cleanup mechanisms.

• Unit Tests

  • Full test coverage using ScalaTest:
    • SurfaceTest.scala
    • SurfaceCapabilitiesTest.scala
    • SurfaceFactoryTest.scala
    • SurfaceManagerTest.scala

Technical Details

Architecture

• Layered Design

  • Base Layer: Surface — raw Vulkan handle and lifecycle
  • Capabilities Layer: SurfaceCapabilities — figures out what the surface supports
  • Factory Layer: SurfaceFactory — builds surfaces based on the platform
  • Manager Layer: SurfaceManager and SwapChainManager — manage everything over time

• Design Patterns

  • Factory and Manager patterns to organize and test things better.
  • Used RAII and Using(MemoryStack) to keep memory under control.

• Memory & Error Management

  • Uses close() to clean up.
  • Throws VulkanAssertionError on Vulkan API failures.
  • All Vulkan resources are manually tracked and released correctly.

Testing

Unit Test Coverage:

• SurfaceTest: Validates surface creation, destruction, and presentation support.
• SurfaceCapabilitiesTest: Tests querying of formats, presentation modes, image counts, extents, and optimal selection logic.
• SurfaceFactoryTest: Ensures platform-specific extensions are handled correctly and surfaces are created successfully.
• SurfaceManagerTest: Verifies multi-surface management, event handling (resize/close), and lifecycle operations.

Potential Issues & Limitations

• Platform Extensions: May fail on unsupported platforms; SurfaceFactory ensures early detection.
• Resize Handling: Swapchain recreation is manual for now; automated handling is a planned feature.
• Thread Safety: SurfaceManager is not thread-safe — needs external locks.

Future Improvements

• Automatic swapchain recreation on window resize.
• Support for multi-GPU systems and device groups.
• Thread-safe surface and swapchain management.
• Handle window events in the background for smoother performance.
• Extended image usages (e.g., compute, transfer).
• Integration with high-level rendering systems and multiple rendering pipelines.