valentineus/fparkan
1
Fork 0
Code Issues Pull Requests 1 Actions Releases Activity
Files
c8876d65eb4e6ba183987db6aaae7d00669d45b4
fparkan/adapters/fparkan-render-vulkan/src/lib.rs
T

4598 lines
153 KiB
Rust
Raw Blame History

#![allow(unsafe_code)]
#![cfg_attr(
test,
allow(
clippy::cast_possible_truncation,
clippy::cast_possible_wrap,
clippy::cast_precision_loss,
clippy::expect_used,
clippy::float_cmp,
clippy::identity_op,
clippy::too_many_lines,
clippy::uninlined_format_args,
clippy::map_unwrap_or,
clippy::needless_raw_string_hashes,
clippy::semicolon_if_nothing_returned,
clippy::type_complexity,
clippy::panic,
clippy::unwrap_used
)
)]
#![deny(unsafe_op_in_unsafe_fn)]
//! Vulkan adapter facade and migration-ready backend surface contract.
//!
//! This module intentionally keeps backend-agnostic command validation in the
//! shared render crate while exposing deterministic lifecycle telemetry used by
//! Stage 0 acceptance evidence.
//!
//! This crate is the declared low-level Vulkan boundary.
use ash::{
khr::{surface, swapchain},
vk,
};
use fparkan_binary::{sha256, sha256_hex};
use fparkan_platform::{NativeWindowHandles, RenderRequest};
use fparkan_render::{
canonical_capture, validate_command_list, FrameOutput, RenderBackend, RenderCommand,
RenderCommandList, RenderError,
};
use std::collections::BTreeSet;
use std::ffi::{CStr, CString};
use std::os::raw::c_char;
use std::sync::atomic::{AtomicU32, Ordering};
use std::sync::Mutex;
use std::time::{SystemTime, UNIX_EPOCH};
/// Minimum Vulkan API version accepted by the Stage 0 backend.
pub const MIN_VULKAN_API_VERSION: u32 = vk::API_VERSION_1_1;
const KHR_SWAPCHAIN_EXTENSION: &str = "VK_KHR_swapchain";
const KHR_PORTABILITY_SUBSET_EXTENSION: &str = "VK_KHR_portability_subset";
const KHR_PORTABILITY_ENUMERATION_EXTENSION: &str = "VK_KHR_portability_enumeration";
const EXT_DEBUG_UTILS_EXTENSION: &str = "VK_EXT_debug_utils";
const VALIDATION_LAYER_NAME: &str = "VK_LAYER_KHRONOS_validation";
const SPIRV_MAGIC: u32 = 0x0723_0203;
const SPIRV_VERSION_1_0: u32 = 0x0001_0000;
const TRIANGLE_VERTEX_SHADER_WORDS: &[u32] = &[
SPIRV_MAGIC,
SPIRV_VERSION_1_0,
0x0008_000b,
0x0000_0021,
0x0000_0000,
0x0002_0011,
0x0000_0001,
0x0006_000b,
0x0000_0001,
0x4c53_4c47,
0x6474_732e,
0x3035_342e,
0x0000_0000,
0x0003_000e,
0x0000_0000,
0x0000_0001,
0x0009_000f,
0x0000_0000,
0x0000_0004,
0x6e69_616d,
0x0000_0000,
0x0000_0009,
0x0000_000b,
0x0000_0013,
0x0000_0018,
0x0003_0003,
0x0000_0002,
0x0000_01c2,
0x0004_0005,
0x0000_0004,
0x6e69_616d,
0x0000_0000,
0x0005_0005,
0x0000_0009,
0x5f74_756f,
0x6f6c_6f63,
0x0000_0072,
0x0005_0005,
0x0000_000b,
0x635f_6e69,
0x726f_6c6f,
0x0000_0000,
0x0006_0005,
0x0000_0011,
0x505f_6c67,
0x6556_7265,
0x7865_7472,
0x0000_0000,
0x0006_0006,
0x0000_0011,
0x0000_0000,
0x505f_6c67,
0x7469_736f,
0x006e_6f69,
0x0007_0006,
0x0000_0011,
0x0000_0001,
0x505f_6c67,
0x746e_696f,
0x657a_6953,
0x0000_0000,
0x0007_0006,
0x0000_0011,
0x0000_0002,
0x435f_6c67,
0x4470_696c,
0x6174_7369,
0x0065_636e,
0x0007_0006,
0x0000_0011,
0x0000_0003,
0x435f_6c67,
0x446c_6c75,
0x6174_7369,
0x0065_636e,
0x0003_0005,
0x0000_0013,
0x0000_0000,
0x0005_0005,
0x0000_0018,
0x705f_6e69,
0x7469_736f,
0x006e_6f69,
0x0004_0047,
0x0000_0009,
0x0000_001e,
0x0000_0000,
0x0004_0047,
0x0000_000b,
0x0000_001e,
0x0000_0001,
0x0003_0047,
0x0000_0011,
0x0000_0002,
0x0005_0048,
0x0000_0011,
0x0000_0000,
0x0000_000b,
0x0000_0000,
0x0005_0048,
0x0000_0011,
0x0000_0001,
0x0000_000b,
0x0000_0001,
0x0005_0048,
0x0000_0011,
0x0000_0002,
0x0000_000b,
0x0000_0003,
0x0005_0048,
0x0000_0011,
0x0000_0003,
0x0000_000b,
0x0000_0004,
0x0004_0047,
0x0000_0018,
0x0000_001e,
0x0000_0000,
0x0002_0013,
0x0000_0002,
0x0003_0021,
0x0000_0003,
0x0000_0002,
0x0003_0016,
0x0000_0006,
0x0000_0020,
0x0004_0017,
0x0000_0007,
0x0000_0006,
0x0000_0003,
0x0004_0020,
0x0000_0008,
0x0000_0003,
0x0000_0007,
0x0004_003b,
0x0000_0008,
0x0000_0009,
0x0000_0003,
0x0004_0020,
0x0000_000a,
0x0000_0001,
0x0000_0007,
0x0004_003b,
0x0000_000a,
0x0000_000b,
0x0000_0001,
0x0004_0017,
0x0000_000d,
0x0000_0006,
0x0000_0004,
0x0004_0015,
0x0000_000e,
0x0000_0020,
0x0000_0000,
0x0004_002b,
0x0000_000e,
0x0000_000f,
0x0000_0001,
0x0004_001c,
0x0000_0010,
0x0000_0006,
0x0000_000f,
0x0006_001e,
0x0000_0011,
0x0000_000d,
0x0000_0006,
0x0000_0010,
0x0000_0010,
0x0004_0020,
0x0000_0012,
0x0000_0003,
0x0000_0011,
0x0004_003b,
0x0000_0012,
0x0000_0013,
0x0000_0003,
0x0004_0015,
0x0000_0014,
0x0000_0020,
0x0000_0001,
0x0004_002b,
0x0000_0014,
0x0000_0015,
0x0000_0000,
0x0004_0017,
0x0000_0016,
0x0000_0006,
0x0000_0002,
0x0004_0020,
0x0000_0017,
0x0000_0001,
0x0000_0016,
0x0004_003b,
0x0000_0017,
0x0000_0018,
0x0000_0001,
0x0004_002b,
0x0000_0006,
0x0000_001a,
0x0000_0000,
0x0004_002b,
0x0000_0006,
0x0000_001b,
0x3f80_0000,
0x0004_0020,
0x0000_001f,
0x0000_0003,
0x0000_000d,
0x0005_0036,
0x0000_0002,
0x0000_0004,
0x0000_0000,
0x0000_0003,
0x0002_00f8,
0x0000_0005,
0x0004_003d,
0x0000_0007,
0x0000_000c,
0x0000_000b,
0x0003_003e,
0x0000_0009,
0x0000_000c,
0x0004_003d,
0x0000_0016,
0x0000_0019,
0x0000_0018,
0x0005_0051,
0x0000_0006,
0x0000_001c,
0x0000_0019,
0x0000_0000,
0x0005_0051,
0x0000_0006,
0x0000_001d,
0x0000_0019,
0x0000_0001,
0x0007_0050,
0x0000_000d,
0x0000_001e,
0x0000_001c,
0x0000_001d,
0x0000_001a,
0x0000_001b,
0x0005_0041,
0x0000_001f,
0x0000_0020,
0x0000_0013,
0x0000_0015,
0x0003_003e,
0x0000_0020,
0x0000_001e,
0x0001_00fd,
0x0001_0038,
];
const TRIANGLE_FRAGMENT_SHADER_WORDS: &[u32] = &[
SPIRV_MAGIC,
SPIRV_VERSION_1_0,
0x0008_000b,
0x0000_0013,
0x0000_0000,
0x0002_0011,
0x0000_0001,
0x0006_000b,
0x0000_0001,
0x4c53_4c47,
0x6474_732e,
0x3035_342e,
0x0000_0000,
0x0003_000e,
0x0000_0000,
0x0000_0001,
0x0007_000f,
0x0000_0004,
0x0000_0004,
0x6e69_616d,
0x0000_0000,
0x0000_0009,
0x0000_000c,
0x0003_0010,
0x0000_0004,
0x0000_0007,
0x0003_0003,
0x0000_0002,
0x0000_01c2,
0x0004_0005,
0x0000_0004,
0x6e69_616d,
0x0000_0000,
0x0005_0005,
0x0000_0009,
0x5f74_756f,
0x6f6c_6f63,
0x0000_0072,
0x0005_0005,
0x0000_000c,
0x635f_6e69,
0x726f_6c6f,
0x0000_0000,
0x0004_0047,
0x0000_0009,
0x0000_001e,
0x0000_0000,
0x0004_0047,
0x0000_000c,
0x0000_001e,
0x0000_0000,
0x0002_0013,
0x0000_0002,
0x0003_0021,
0x0000_0003,
0x0000_0002,
0x0003_0016,
0x0000_0006,
0x0000_0020,
0x0004_0017,
0x0000_0007,
0x0000_0006,
0x0000_0004,
0x0004_0020,
0x0000_0008,
0x0000_0003,
0x0000_0007,
0x0004_003b,
0x0000_0008,
0x0000_0009,
0x0000_0003,
0x0004_0017,
0x0000_000a,
0x0000_0006,
0x0000_0003,
0x0004_0020,
0x0000_000b,
0x0000_0001,
0x0000_000a,
0x0004_003b,
0x0000_000b,
0x0000_000c,
0x0000_0001,
0x0004_002b,
0x0000_0006,
0x0000_000e,
0x3f80_0000,
0x0005_0036,
0x0000_0002,
0x0000_0004,
0x0000_0000,
0x0000_0003,
0x0002_00f8,
0x0000_0005,
0x0004_003d,
0x0000_000a,
0x0000_000d,
0x0000_000c,
0x0005_0051,
0x0000_0006,
0x0000_000f,
0x0000_000d,
0x0000_0000,
0x0005_0051,
0x0000_0006,
0x0000_0010,
0x0000_000d,
0x0000_0001,
0x0005_0051,
0x0000_0006,
0x0000_0011,
0x0000_000d,
0x0000_0002,
0x0007_0050,
0x0000_0007,
0x0000_0012,
0x0000_000f,
0x0000_0010,
0x0000_0011,
0x0000_000e,
0x0003_003e,
0x0000_0009,
0x0000_0012,
0x0001_00fd,
0x0001_0038,
];
/// Shader compiler/toolchain identifiers pinned in the Stage 0 manifest.
pub const SHADER_COMPILER_ID: &str = "shaderc-offline-stage0@pinned-manifest";
/// SPIR-V validator identifier pinned in the Stage 0 manifest.
pub const SPIRV_VALIDATOR_ID: &str = "spirv-val-stage0@pinned-manifest";
/// Vulkan shader stage.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum VulkanShaderStage {
/// Vertex stage.
Vertex,
/// Fragment stage.
Fragment,
}
impl VulkanShaderStage {
const fn as_str(self) -> &'static str {
match self {
Self::Vertex => "vertex",
Self::Fragment => "fragment",
}
}
}
/// Offline SPIR-V shader manifest entry.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanShaderModuleManifest {
/// Logical shader name.
pub name: &'static str,
/// Shader stage.
pub stage: VulkanShaderStage,
/// SPIR-V entry point.
pub entry_point: &'static str,
/// Descriptor set count.
pub descriptor_sets: u32,
/// Push constant byte count.
pub push_constant_bytes: u32,
/// SPIR-V words.
pub words: &'static [u32],
}
/// Shader manifest validation report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanShaderManifestReport {
/// Report schema version.
pub schema: u32,
/// Pinned compiler identifier.
pub compiler: &'static str,
/// Pinned validator identifier.
pub validator: &'static str,
/// Shader module reports.
pub modules: Vec<VulkanShaderModuleReport>,
/// Hash of the normalized shader manifest.
pub manifest_hash: String,
}
/// Shader module validation report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanShaderModuleReport {
/// Logical shader name.
pub name: &'static str,
/// Shader stage.
pub stage: VulkanShaderStage,
/// SPIR-V entry point.
pub entry_point: &'static str,
/// SPIR-V word count.
pub word_count: usize,
/// SPIR-V byte hash.
pub sha256: String,
}
/// Shader manifest validation error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanShaderManifestError {
/// SPIR-V module is too short to contain a header.
TooShort {
/// Shader name.
name: &'static str,
},
/// SPIR-V module has an invalid magic word.
InvalidMagic {
/// Shader name.
name: &'static str,
/// Found magic word.
found: u32,
},
/// SPIR-V module version is below 1.0.
UnsupportedVersion {
/// Shader name.
name: &'static str,
/// Found version word.
found: u32,
},
/// SPIR-V module declares an invalid bound.
InvalidBound {
/// Shader name.
name: &'static str,
},
}
impl std::fmt::Display for VulkanShaderManifestError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::TooShort { name } => write!(f, "shader {name} SPIR-V module is too short"),
Self::InvalidMagic { name, found } => {
write!(f, "shader {name} has invalid SPIR-V magic 0x{found:08x}")
}
Self::UnsupportedVersion { name, found } => write!(
f,
"shader {name} has unsupported SPIR-V version 0x{found:08x}"
),
Self::InvalidBound { name } => write!(f, "shader {name} has invalid SPIR-V bound"),
}
}
}
impl std::error::Error for VulkanShaderManifestError {}
/// Vulkan instance bootstrap configuration.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanInstanceConfig {
/// Application name reported to the loader.
pub application_name: String,
/// Required instance extensions, usually including surface extensions.
pub required_extensions: Vec<String>,
/// Whether `VK_KHR_portability_enumeration` and its create flag are enabled.
pub enable_portability_enumeration: bool,
/// Whether validation layers are requested.
pub enable_validation: bool,
}
impl VulkanInstanceConfig {
/// Returns a conservative instance configuration for smoke probes.
#[must_use]
pub fn smoke(application_name: impl Into<String>) -> Self {
Self {
application_name: application_name.into(),
required_extensions: Vec::new(),
enable_portability_enumeration: cfg!(target_os = "macos"),
enable_validation: false,
}
}
}
/// Deterministic Vulkan instance creation plan.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanInstancePlan {
/// Report schema version.
pub schema: u32,
/// Instance extensions requested at creation time.
pub enabled_extensions: Vec<String>,
/// Raw Vulkan instance creation flags.
pub create_flags: u32,
/// Whether validation was requested.
pub validation_requested: bool,
}
/// Created Vulkan instance probe.
pub struct VulkanInstanceProbe {
entry: ash::Entry,
instance: ash::Instance,
/// Deterministic instance creation report.
pub report: VulkanInstancePlan,
}
impl Drop for VulkanInstanceProbe {
fn drop(&mut self) {
// SAFETY: The `Instance` was created by this probe and is destroyed once during drop.
unsafe { self.instance.destroy_instance(None) };
}
}
/// Deterministic Vulkan surface creation plan.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanSurfacePlan {
/// Report schema version.
pub schema: u32,
/// Instance extensions required by the native display backend.
pub required_instance_extensions: Vec<String>,
}
/// Vulkan surface bootstrap error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanSurfaceError {
/// No native raw window/display handles were available.
MissingNativeHandles,
/// Required platform surface extensions could not be enumerated.
RequiredExtensionsFailed {
/// Vulkan result.
result: String,
},
/// A required extension pointer was not valid UTF-8.
InvalidExtensionName,
/// Surface creation failed.
CreateFailed {
/// Vulkan result.
result: String,
},
}
impl std::fmt::Display for VulkanSurfaceError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::MissingNativeHandles => {
write!(
f,
"native window/display handles are required for Vulkan surface creation"
)
}
Self::RequiredExtensionsFailed { result } => write!(
f,
"failed to enumerate required Vulkan surface extensions: {result}"
),
Self::InvalidExtensionName => {
write!(f, "Vulkan surface extension name is not valid UTF-8")
}
Self::CreateFailed { result } => write!(f, "Vulkan surface creation failed: {result}"),
}
}
}
impl std::error::Error for VulkanSurfaceError {}
/// Created Vulkan surface probe.
pub struct VulkanSurfaceProbe {
loader: surface::Instance,
surface: vk::SurfaceKHR,
/// Deterministic surface creation report.
pub report: VulkanSurfacePlan,
}
impl Drop for VulkanSurfaceProbe {
fn drop(&mut self) {
// SAFETY: The `SurfaceKHR` was created by this probe and is destroyed once during drop.
unsafe { self.loader.destroy_surface(self.surface, None) };
}
}
/// Live Vulkan device/surface capability probe.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanRuntimeCapabilityProbe {
/// Selected device/queue capability report.
pub capability: VulkanCapabilityReport,
/// Swapchain plan built from the selected device and live surface capabilities.
pub swapchain: VulkanSwapchainPlan,
}
/// Created Vulkan logical device probe.
pub struct VulkanLogicalDeviceProbe {
device: ash::Device,
physical_device: vk::PhysicalDevice,
/// Runtime capability report used for device selection.
pub runtime: VulkanRuntimeCapabilityProbe,
/// Deterministic logical device creation report.
pub report: VulkanLogicalDeviceReport,
}
impl Drop for VulkanLogicalDeviceProbe {
fn drop(&mut self) {
// SAFETY: The logical device was created by this probe and is destroyed once during drop.
unsafe { self.device.destroy_device(None) };
}
}
impl VulkanLogicalDeviceProbe {
/// Returns the graphics queue selected by the Stage 0 policy.
#[must_use]
pub fn graphics_queue(&self) -> vk::Queue {
// SAFETY: The queue-family index belongs to this live logical device.
unsafe {
self.device
.get_device_queue(self.report.graphics_queue_family, 0)
}
}
/// Returns the presentation queue selected by the Stage 0 policy.
#[must_use]
pub fn present_queue(&self) -> vk::Queue {
// SAFETY: The queue-family index belongs to this live logical device.
unsafe {
self.device
.get_device_queue(self.report.present_queue_family, 0)
}
}
/// Returns a shared reference to the live logical device.
#[must_use]
pub fn device(&self) -> &ash::Device {
&self.device
}
}
/// Logical device creation report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanLogicalDeviceReport {
/// Report schema version.
pub schema: u32,
/// Selected physical device name.
pub device_name: String,
/// Graphics queue-family index used by the logical device.
pub graphics_queue_family: u32,
/// Present queue-family index used by the logical device.
pub present_queue_family: u32,
/// Enabled device extensions.
pub enabled_extensions: Vec<String>,
}
/// Created Vulkan swapchain probe.
pub struct VulkanSwapchainProbe {
loader: swapchain::Device,
swapchain: vk::SwapchainKHR,
/// Deterministic swapchain creation report.
pub report: VulkanSwapchainReport,
}
impl Drop for VulkanSwapchainProbe {
fn drop(&mut self) {
// SAFETY: The swapchain was created by this probe and is destroyed once during drop.
unsafe { self.loader.destroy_swapchain(self.swapchain, None) };
}
}
impl VulkanSwapchainProbe {
/// Returns the live swapchain handle.
#[must_use]
pub fn swapchain(&self) -> vk::SwapchainKHR {
self.swapchain
}
/// Returns the swapchain extension loader for this live swapchain.
#[must_use]
pub fn loader(&self) -> &swapchain::Device {
&self.loader
}
}
/// Creates a live native Vulkan renderer for the Stage 0 smoke loop.
#[derive(Clone, Debug)]
pub struct VulkanSmokeRendererCreateInfo {
/// Application name reported to the Vulkan loader.
pub application_name: String,
/// Native window/display handles borrowed from a live window.
pub native_handles: NativeWindowHandles,
/// Initial drawable extent.
pub drawable_extent: (u32, u32),
/// Whether validation layers must be enabled.
pub enable_validation: bool,
}
/// Stable smoke renderer bootstrap report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanSmokeRendererReport {
/// Whether portability enumeration was enabled at instance creation.
pub portability_enumeration: bool,
/// Selected device name.
pub device_name: String,
/// Graphics queue-family index.
pub graphics_queue_family: u32,
/// Present queue-family index.
pub present_queue_family: u32,
/// Enabled logical-device extension count.
pub enabled_extension_count: u32,
/// Current swapchain extent.
pub swapchain_extent: (u32, u32),
/// Current swapchain image count.
pub swapchain_image_count: u32,
}
/// Measured validation counters from the live smoke loop.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanValidationReport {
/// Validation warnings observed by the debug messenger.
pub warning_count: u32,
/// Validation errors observed by the debug messenger.
pub error_count: u32,
/// Stable sorted VUID list.
pub vuids: Vec<String>,
}
/// Result of one rendered smoke frame.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum VulkanSmokeFrameOutcome {
/// A frame was submitted and presented.
Presented,
/// Rendering was skipped because the swapchain had to be recreated.
Recreated,
/// Rendering was skipped because the drawable extent is zero.
ZeroExtent,
}
/// Live smoke renderer error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanSmokeRendererError {
/// Instance bootstrap failed.
Instance(VulkanInstanceError),
/// Surface bootstrap failed.
Surface(VulkanSurfaceError),
/// Logical-device bootstrap failed.
LogicalDevice(VulkanLogicalDeviceError),
/// Swapchain bootstrap failed.
Swapchain(VulkanSwapchainProbeError),
/// Shader manifest validation failed.
ShaderManifest(VulkanShaderManifestError),
/// Vulkan operation failed.
VulkanOperation {
/// Operation context.
context: &'static str,
/// Raw Vulkan result text.
result: String,
},
/// No suitable memory type exists for the required properties.
MissingMemoryType {
/// Operation context.
context: &'static str,
},
/// Internal smoke renderer state was unexpectedly absent.
InvariantViolation {
/// Missing state context.
context: &'static str,
},
}
impl std::fmt::Display for VulkanSmokeRendererError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Instance(error) => write!(f, "{error}"),
Self::Surface(error) => write!(f, "{error}"),
Self::LogicalDevice(error) => write!(f, "{error}"),
Self::Swapchain(error) => write!(f, "{error}"),
Self::ShaderManifest(error) => write!(f, "{error}"),
Self::VulkanOperation { context, result } => {
write!(f, "{context}: {result}")
}
Self::MissingMemoryType { context } => {
write!(f, "{context}: no compatible Vulkan memory type")
}
Self::InvariantViolation { context } => {
write!(f, "renderer invariant violated: {context}")
}
}
}
}
impl std::error::Error for VulkanSmokeRendererError {}
struct VulkanValidationShared {
warning_count: AtomicU32,
error_count: AtomicU32,
vuids: Mutex<BTreeSet<String>>,
}
impl Default for VulkanValidationShared {
fn default() -> Self {
Self {
warning_count: AtomicU32::new(0),
error_count: AtomicU32::new(0),
vuids: Mutex::new(BTreeSet::new()),
}
}
}
struct VulkanValidationMessenger {
loader: ash::ext::debug_utils::Instance,
messenger: vk::DebugUtilsMessengerEXT,
shared: Box<VulkanValidationShared>,
}
impl VulkanValidationMessenger {
fn report(&self) -> VulkanValidationReport {
let vuids = self
.shared
.vuids
.lock()
.map(|values| values.iter().cloned().collect::<Vec<_>>())
.unwrap_or_default();
VulkanValidationReport {
warning_count: self.shared.warning_count.load(Ordering::Relaxed),
error_count: self.shared.error_count.load(Ordering::Relaxed),
vuids,
}
}
}
impl Drop for VulkanValidationMessenger {
fn drop(&mut self) {
// SAFETY: The messenger belongs to this instance-level loader and is destroyed once.
unsafe {
self.loader
.destroy_debug_utils_messenger(self.messenger, None);
};
}
}
unsafe extern "system" fn vulkan_validation_callback(
message_severity: vk::DebugUtilsMessageSeverityFlagsEXT,
_message_types: vk::DebugUtilsMessageTypeFlagsEXT,
callback_data: *const vk::DebugUtilsMessengerCallbackDataEXT<'_>,
user_data: *mut std::ffi::c_void,
) -> vk::Bool32 {
// SAFETY: The debug messenger stores a stable pointer to `VulkanValidationShared` for the messenger lifetime.
let Some(shared) = (unsafe { (user_data as *const VulkanValidationShared).as_ref() }) else {
return vk::FALSE;
};
if message_severity.contains(vk::DebugUtilsMessageSeverityFlagsEXT::ERROR) {
shared.error_count.fetch_add(1, Ordering::Relaxed);
} else if message_severity.contains(vk::DebugUtilsMessageSeverityFlagsEXT::WARNING) {
shared.warning_count.fetch_add(1, Ordering::Relaxed);
}
// SAFETY: Vulkan invokes the callback with either a null pointer or a valid callback-data payload.
let Some(callback_data) = (unsafe { callback_data.as_ref() }) else {
return vk::FALSE;
};
if let Some(vuid) = (!callback_data.p_message_id_name.is_null()).then(|| {
// SAFETY: `p_message_id_name` is a Vulkan-owned NUL-terminated string for the callback duration.
unsafe { CStr::from_ptr(callback_data.p_message_id_name) }
.to_string_lossy()
.into_owned()
}) {
if vuid.starts_with("VUID-") {
if let Ok(mut vuids) = shared.vuids.lock() {
vuids.insert(vuid);
}
}
}
vk::FALSE
}
struct VulkanAllocatedBuffer {
buffer: vk::Buffer,
memory: vk::DeviceMemory,
}
struct VulkanSwapchainResources {
image_views: Vec<vk::ImageView>,
render_pass: vk::RenderPass,
pipeline_layout: vk::PipelineLayout,
pipeline: vk::Pipeline,
framebuffers: Vec<vk::Framebuffer>,
command_buffers: Vec<vk::CommandBuffer>,
}
struct VulkanFrameSync {
image_available: vk::Semaphore,
render_finished: vk::Semaphore,
fence: vk::Fence,
}
/// Live Stage 0 Vulkan triangle renderer used by the smoke app.
pub struct VulkanSmokeRenderer {
instance: Option<VulkanInstanceProbe>,
validation: Option<VulkanValidationMessenger>,
surface: Option<VulkanSurfaceProbe>,
device: Option<VulkanLogicalDeviceProbe>,
swapchain: Option<VulkanSwapchainProbe>,
command_pool: vk::CommandPool,
swapchain_resources: Option<VulkanSwapchainResources>,
vertex_buffer: Option<VulkanAllocatedBuffer>,
index_buffer: Option<VulkanAllocatedBuffer>,
frame_sync: Vec<VulkanFrameSync>,
images_in_flight: Vec<vk::Fence>,
current_frame: usize,
pending_extent: Option<(u32, u32)>,
swapchain_recreate_count: u32,
report: VulkanSmokeRendererReport,
}
impl VulkanSmokeRenderer {
/// Creates a live Vulkan smoke renderer bound to a live native window.
///
/// # Errors
///
/// Returns [`VulkanSmokeRendererError`] when Vulkan bootstrap, pipeline creation,
/// memory allocation, or synchronization resource creation fails.
pub fn new(
create_info: &VulkanSmokeRendererCreateInfo,
) -> Result<Self, VulkanSmokeRendererError> {
validate_shader_manifest(&triangle_shader_manifest())
.map_err(VulkanSmokeRendererError::ShaderManifest)?;
let surface_plan = plan_vulkan_surface(Some(create_info.native_handles))
.map_err(VulkanSmokeRendererError::Surface)?;
let mut instance_config = VulkanInstanceConfig::smoke(&create_info.application_name);
instance_config
.required_extensions
.clone_from(&surface_plan.required_instance_extensions);
instance_config.enable_validation = create_info.enable_validation;
let instance = create_vulkan_instance_probe(&instance_config)
.map_err(VulkanSmokeRendererError::Instance)?;
let validation = if create_info.enable_validation {
Some(create_validation_messenger(&instance)?)
} else {
None
};
let surface = create_vulkan_surface_probe(&instance, Some(create_info.native_handles))
.map_err(VulkanSmokeRendererError::Surface)?;
let device =
create_vulkan_logical_device_probe(&instance, &surface, create_info.drawable_extent)
.map_err(VulkanSmokeRendererError::LogicalDevice)?;
let swapchain = create_vulkan_swapchain_probe_for_extent(
&instance,
&surface,
&device,
create_info.drawable_extent,
vk::SwapchainKHR::null(),
)
.map_err(VulkanSmokeRendererError::Swapchain)?;
let command_pool = create_command_pool(&device)?;
let vertex_buffer = Some(create_triangle_vertex_buffer(&instance, &device)?);
let index_buffer = Some(create_triangle_index_buffer(&instance, &device)?);
let mut renderer = Self {
instance: Some(instance),
validation,
surface: Some(surface),
device: Some(device),
swapchain: Some(swapchain),
command_pool,
swapchain_resources: None,
vertex_buffer,
index_buffer,
frame_sync: Vec::new(),
images_in_flight: Vec::new(),
current_frame: 0,
pending_extent: None,
swapchain_recreate_count: 0,
report: VulkanSmokeRendererReport {
portability_enumeration: instance_config.enable_portability_enumeration,
device_name: String::new(),
graphics_queue_family: 0,
present_queue_family: 0,
enabled_extension_count: 0,
swapchain_extent: (0, 0),
swapchain_image_count: 0,
},
};
renderer.rebuild_swapchain_resources(false)?;
let device_ref = renderer.device_ref()?;
let swapchain_ref = renderer.swapchain_ref()?;
renderer.report = VulkanSmokeRendererReport {
portability_enumeration: renderer
.instance
.as_ref()
.is_some_and(|instance| instance.report.create_flags != 0),
device_name: device_ref.report.device_name.clone(),
graphics_queue_family: device_ref.report.graphics_queue_family,
present_queue_family: device_ref.report.present_queue_family,
enabled_extension_count: device_ref
.report
.enabled_extensions
.len()
.try_into()
.unwrap_or(u32::MAX),
swapchain_extent: swapchain_ref.report.plan.extent,
swapchain_image_count: swapchain_ref.report.image_count,
};
Ok(renderer)
}
/// Returns the current bootstrap report.
#[must_use]
pub const fn report(&self) -> &VulkanSmokeRendererReport {
&self.report
}
/// Returns measured validation counters and VUIDs.
#[must_use]
pub fn validation_report(&self) -> VulkanValidationReport {
self.validation.as_ref().map_or(
VulkanValidationReport {
warning_count: 0,
error_count: 0,
vuids: Vec::new(),
},
VulkanValidationMessenger::report,
)
}
/// Returns the measured swapchain recreation count.
#[must_use]
pub const fn swapchain_recreate_count(&self) -> u32 {
self.swapchain_recreate_count
}
/// Requests swapchain recreation for a new drawable extent.
pub fn request_resize(&mut self, extent: (u32, u32)) {
self.pending_extent = Some(extent);
}
fn device_ref(&self) -> Result<&VulkanLogicalDeviceProbe, VulkanSmokeRendererError> {
self.device
.as_ref()
.ok_or(VulkanSmokeRendererError::InvariantViolation {
context: "logical device",
})
}
fn swapchain_ref(&self) -> Result<&VulkanSwapchainProbe, VulkanSmokeRendererError> {
self.swapchain
.as_ref()
.ok_or(VulkanSmokeRendererError::InvariantViolation {
context: "swapchain",
})
}
fn instance_ref(&self) -> Result<&VulkanInstanceProbe, VulkanSmokeRendererError> {
self.instance
.as_ref()
.ok_or(VulkanSmokeRendererError::InvariantViolation {
context: "instance",
})
}
fn surface_ref(&self) -> Result<&VulkanSurfaceProbe, VulkanSmokeRendererError> {
self.surface
.as_ref()
.ok_or(VulkanSmokeRendererError::InvariantViolation { context: "surface" })
}
fn resources_ref(&self) -> Result<&VulkanSwapchainResources, VulkanSmokeRendererError> {
self.swapchain_resources
.as_ref()
.ok_or(VulkanSmokeRendererError::InvariantViolation {
context: "swapchain resources",
})
}
fn vertex_buffer_ref(&self) -> Result<&VulkanAllocatedBuffer, VulkanSmokeRendererError> {
self.vertex_buffer
.as_ref()
.ok_or(VulkanSmokeRendererError::InvariantViolation {
context: "vertex buffer",
})
}
fn index_buffer_ref(&self) -> Result<&VulkanAllocatedBuffer, VulkanSmokeRendererError> {
self.index_buffer
.as_ref()
.ok_or(VulkanSmokeRendererError::InvariantViolation {
context: "index buffer",
})
}
/// Draws and presents one indexed-triangle frame.
///
/// # Errors
///
/// Returns [`VulkanSmokeRendererError`] when synchronization, command recording,
/// submission, or presentation fails.
#[allow(clippy::too_many_lines)]
pub fn draw_frame(&mut self) -> Result<VulkanSmokeFrameOutcome, VulkanSmokeRendererError> {
if let Some(extent) = self.pending_extent.take() {
if extent.0 == 0 || extent.1 == 0 {
self.pending_extent = Some(extent);
return Ok(VulkanSmokeFrameOutcome::ZeroExtent);
}
self.recreate_swapchain(extent)?;
return Ok(VulkanSmokeFrameOutcome::Recreated);
}
let sync = &self.frame_sync[self.current_frame];
let image_available = sync.image_available;
let render_finished = sync.render_finished;
let in_flight_fence = sync.fence;
// SAFETY: The fence belongs to this live logical device and is waited from one thread.
unsafe {
self.device_ref()?
.device()
.wait_for_fences(&[in_flight_fence], true, 1_000_000_000)
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkWaitForFences",
result: format!("{error:?}"),
})?;
// SAFETY: The swapchain, semaphore and fence inputs are live for the duration of the acquire call.
let acquire = unsafe {
self.swapchain_ref()?.loader().acquire_next_image(
self.swapchain_ref()?.swapchain(),
1_000_000_000,
image_available,
vk::Fence::null(),
)
};
let (image_index, acquire_suboptimal) = match acquire {
Ok(result) => result,
Err(vk::Result::ERROR_OUT_OF_DATE_KHR) => {
self.recreate_swapchain(self.report.swapchain_extent)?;
return Ok(VulkanSmokeFrameOutcome::Recreated);
}
Err(error) => {
return Err(VulkanSmokeRendererError::VulkanOperation {
context: "vkAcquireNextImageKHR",
result: format!("{error:?}"),
});
}
};
let image_index_usize = usize::try_from(image_index).unwrap_or(0);
let image_fence = self.images_in_flight[image_index_usize];
if image_fence != vk::Fence::null() {
// SAFETY: The fence belongs to this renderer and can be waited independently.
unsafe {
self.device_ref()?
.device()
.wait_for_fences(&[image_fence], true, 1_000_000_000)
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkWaitForFences(image)",
result: format!("{error:?}"),
})?;
}
self.images_in_flight[image_index_usize] = in_flight_fence;
// SAFETY: The fence belongs to this frame context and is not in use after the wait above.
unsafe { self.device_ref()?.device().reset_fences(&[in_flight_fence]) }.map_err(
|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkResetFences",
result: format!("{error:?}"),
},
)?;
self.record_command_buffer(image_index_usize)?;
let wait_semaphores = [image_available];
let wait_stages = [vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT];
let command_buffers = [self.resources_ref()?.command_buffers[image_index_usize]];
let signal_semaphores = [render_finished];
let submit_info = [vk::SubmitInfo::default()
.wait_semaphores(&wait_semaphores)
.wait_dst_stage_mask(&wait_stages)
.command_buffers(&command_buffers)
.signal_semaphores(&signal_semaphores)];
// SAFETY: Submission references live queue, sync objects and recorded command buffer.
unsafe {
self.device_ref()?.device().queue_submit(
self.device_ref()?.graphics_queue(),
&submit_info,
in_flight_fence,
)
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkQueueSubmit",
result: format!("{error:?}"),
})?;
let present_wait = [render_finished];
let swapchains = [self.swapchain_ref()?.swapchain()];
let image_indices = [image_index];
let present_info = vk::PresentInfoKHR::default()
.wait_semaphores(&present_wait)
.swapchains(&swapchains)
.image_indices(&image_indices);
// SAFETY: Presentation uses the rendered image index and a semaphore signaled by queue submission.
let present_suboptimal = match unsafe {
self.swapchain_ref()?
.loader()
.queue_present(self.device_ref()?.present_queue(), &present_info)
} {
Ok(suboptimal) => suboptimal,
Err(vk::Result::ERROR_OUT_OF_DATE_KHR) => {
self.recreate_swapchain(self.report.swapchain_extent)?;
return Ok(VulkanSmokeFrameOutcome::Recreated);
}
Err(error) => {
return Err(VulkanSmokeRendererError::VulkanOperation {
context: "vkQueuePresentKHR",
result: format!("{error:?}"),
});
}
};
self.current_frame = (self.current_frame + 1) % self.frame_sync.len().max(1);
if acquire_suboptimal || present_suboptimal {
self.recreate_swapchain(self.report.swapchain_extent)?;
Ok(VulkanSmokeFrameOutcome::Recreated)
} else {
Ok(VulkanSmokeFrameOutcome::Presented)
}
}
fn recreate_swapchain(&mut self, extent: (u32, u32)) -> Result<(), VulkanSmokeRendererError> {
let device = self.device_ref()?;
// SAFETY: The logical device remains live and idling at swapchain recreation boundaries.
unsafe { device.device().device_wait_idle() }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkDeviceWaitIdle",
result: format!("{error:?}"),
}
})?;
self.pending_extent = None;
self.rebuild_swapchain(extent)?;
self.swapchain_recreate_count = self.swapchain_recreate_count.saturating_add(1);
Ok(())
}
fn rebuild_swapchain(&mut self, extent: (u32, u32)) -> Result<(), VulkanSmokeRendererError> {
self.destroy_swapchain_resources();
let instance = self.instance_ref()?;
let surface = self.surface_ref()?;
let device = self.device_ref()?;
let old_swapchain = self
.swapchain
.as_ref()
.map_or(vk::SwapchainKHR::null(), VulkanSwapchainProbe::swapchain);
let new_swapchain = create_vulkan_swapchain_probe_for_extent(
instance,
surface,
device,
extent,
old_swapchain,
)
.map_err(VulkanSmokeRendererError::Swapchain)?;
self.swapchain = Some(new_swapchain);
self.rebuild_swapchain_resources(true)?;
Ok(())
}
fn rebuild_swapchain_resources(
&mut self,
reuse_command_pool: bool,
) -> Result<(), VulkanSmokeRendererError> {
let resources = {
let device = self.device_ref()?;
let swapchain = self.swapchain_ref()?;
create_swapchain_resources(
device,
swapchain,
self.command_pool,
self.vertex_buffer_ref()?,
self.index_buffer_ref()?,
reuse_command_pool,
)?
};
let frame_sync = {
let device = self.device_ref()?;
create_frame_sync(device)?
};
let swapchain_extent = self.swapchain_ref()?.report.plan.extent;
let swapchain_image_count = self.swapchain_ref()?.report.image_count;
self.images_in_flight = vec![vk::Fence::null(); resources.image_views.len()];
self.frame_sync = frame_sync;
self.report.swapchain_extent = swapchain_extent;
self.report.swapchain_image_count = swapchain_image_count;
self.swapchain_resources = Some(resources);
Ok(())
}
#[allow(clippy::too_many_lines)]
fn record_command_buffer(
&mut self,
image_index: usize,
) -> Result<(), VulkanSmokeRendererError> {
let device = self.device_ref()?;
let swapchain = self.swapchain_ref()?;
let resources = self.resources_ref()?;
let command_buffer = resources.command_buffers[image_index];
// SAFETY: The command buffer belongs to the resettable pool owned by this renderer.
unsafe {
device
.device()
.reset_command_buffer(command_buffer, vk::CommandBufferResetFlags::empty())
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkResetCommandBuffer",
result: format!("{error:?}"),
})?;
let begin_info = vk::CommandBufferBeginInfo::default();
// SAFETY: The command buffer is in the initial state after reset and recorded on one thread.
unsafe {
device
.device()
.begin_command_buffer(command_buffer, &begin_info)
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkBeginCommandBuffer",
result: format!("{error:?}"),
})?;
let pre_barrier = vk::ImageMemoryBarrier::default()
.old_layout(vk::ImageLayout::PRESENT_SRC_KHR)
.new_layout(vk::ImageLayout::COLOR_ATTACHMENT_OPTIMAL)
.src_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
.dst_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
.subresource_range(color_subresource_range())
.src_access_mask(vk::AccessFlags::empty())
.dst_access_mask(vk::AccessFlags::COLOR_ATTACHMENT_WRITE);
// SAFETY: The swapchain is live and queried only to resolve the current image handles.
let swapchain_images = unsafe {
swapchain
.loader()
.get_swapchain_images(swapchain.swapchain())
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkGetSwapchainImagesKHR",
result: format!("{error:?}"),
})?;
let pre_barrier = pre_barrier.image(swapchain_images[image_index]);
// SAFETY: The barriers operate on the acquired swapchain image owned by this command buffer submission.
unsafe {
device.device().cmd_pipeline_barrier(
command_buffer,
vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT,
vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT,
vk::DependencyFlags::empty(),
&[],
&[],
&[pre_barrier],
);
}
let clear_values = [vk::ClearValue {
color: vk::ClearColorValue {
float32: [0.05, 0.08, 0.11, 1.0],
},
}];
let render_area = vk::Rect2D {
offset: vk::Offset2D { x: 0, y: 0 },
extent: vk::Extent2D {
width: swapchain.report.plan.extent.0,
height: swapchain.report.plan.extent.1,
},
};
let render_pass_info = vk::RenderPassBeginInfo::default()
.render_pass(resources.render_pass)
.framebuffer(resources.framebuffers[image_index])
.render_area(render_area)
.clear_values(&clear_values);
// SAFETY: All commands target live frame resources owned by this renderer.
unsafe {
device.device().cmd_begin_render_pass(
command_buffer,
&render_pass_info,
vk::SubpassContents::INLINE,
);
device.device().cmd_bind_pipeline(
command_buffer,
vk::PipelineBindPoint::GRAPHICS,
resources.pipeline,
);
let vertex_buffers = [self.vertex_buffer_ref()?.buffer];
let offsets = [0_u64];
device
.device()
.cmd_bind_vertex_buffers(command_buffer, 0, &vertex_buffers, &offsets);
device.device().cmd_bind_index_buffer(
command_buffer,
self.index_buffer_ref()?.buffer,
0,
vk::IndexType::UINT16,
);
device
.device()
.cmd_draw_indexed(command_buffer, 3, 1, 0, 0, 0);
device.device().cmd_end_render_pass(command_buffer);
}
let post_barrier = vk::ImageMemoryBarrier::default()
.old_layout(vk::ImageLayout::COLOR_ATTACHMENT_OPTIMAL)
.new_layout(vk::ImageLayout::PRESENT_SRC_KHR)
.src_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
.dst_queue_family_index(vk::QUEUE_FAMILY_IGNORED)
.image(swapchain_images[image_index])
.subresource_range(color_subresource_range())
.src_access_mask(vk::AccessFlags::COLOR_ATTACHMENT_WRITE)
.dst_access_mask(vk::AccessFlags::empty());
// SAFETY: The post-render barrier transitions the same live swapchain image into present layout.
unsafe {
device.device().cmd_pipeline_barrier(
command_buffer,
vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT,
vk::PipelineStageFlags::BOTTOM_OF_PIPE,
vk::DependencyFlags::empty(),
&[],
&[],
&[post_barrier],
);
device.device().end_command_buffer(command_buffer)
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkEndCommandBuffer",
result: format!("{error:?}"),
})?;
Ok(())
}
fn destroy_swapchain_resources(&mut self) {
let Some(device) = self.device.as_ref() else {
return;
};
for sync in self.frame_sync.drain(..) {
// SAFETY: These sync objects belong to this device and are destroyed once.
unsafe {
device
.device()
.destroy_semaphore(sync.image_available, None);
device
.device()
.destroy_semaphore(sync.render_finished, None);
device.device().destroy_fence(sync.fence, None);
}
}
if let Some(resources) = self.swapchain_resources.take() {
destroy_swapchain_resources(device, self.command_pool, resources);
}
}
}
impl Drop for VulkanSmokeRenderer {
fn drop(&mut self) {
self.destroy_swapchain_resources();
if let Some(device) = self.device.as_ref() {
if let Some(buffer) = self.index_buffer.take() {
// SAFETY: Buffer and memory belong to this device and are destroyed once.
unsafe {
device.device().destroy_buffer(buffer.buffer, None);
device.device().free_memory(buffer.memory, None);
}
}
if let Some(buffer) = self.vertex_buffer.take() {
// SAFETY: Buffer and memory belong to this device and are destroyed once.
unsafe {
device.device().destroy_buffer(buffer.buffer, None);
device.device().free_memory(buffer.memory, None);
}
}
// SAFETY: The command pool belongs to this device and is destroyed once after buffers are freed.
unsafe {
device
.device()
.destroy_command_pool(self.command_pool, None);
};
// SAFETY: The logical device remains live until the renderer completes teardown.
let _ = unsafe { device.device().device_wait_idle() };
}
self.swapchain.take();
self.device.take();
self.surface.take();
self.validation.take();
self.instance.take();
}
}
fn create_validation_messenger(
instance: &VulkanInstanceProbe,
) -> Result<VulkanValidationMessenger, VulkanSmokeRendererError> {
let shared = Box::new(VulkanValidationShared::default());
let loader = ash::ext::debug_utils::Instance::new(&instance.entry, &instance.instance);
let create_info = vk::DebugUtilsMessengerCreateInfoEXT::default()
.message_severity(
vk::DebugUtilsMessageSeverityFlagsEXT::WARNING
| vk::DebugUtilsMessageSeverityFlagsEXT::ERROR,
)
.message_type(
vk::DebugUtilsMessageTypeFlagsEXT::GENERAL
| vk::DebugUtilsMessageTypeFlagsEXT::VALIDATION
| vk::DebugUtilsMessageTypeFlagsEXT::PERFORMANCE,
)
.pfn_user_callback(Some(vulkan_validation_callback))
.user_data((&raw const *shared).cast_mut().cast());
let messenger =
// SAFETY: The create info points at a stable boxed user-data allocation for the messenger lifetime.
unsafe { loader.create_debug_utils_messenger(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateDebugUtilsMessengerEXT",
result: format!("{error:?}"),
}
})?;
Ok(VulkanValidationMessenger {
loader,
messenger,
shared,
})
}
fn create_command_pool(
device: &VulkanLogicalDeviceProbe,
) -> Result<vk::CommandPool, VulkanSmokeRendererError> {
let create_info = vk::CommandPoolCreateInfo::default()
.queue_family_index(device.report.graphics_queue_family)
.flags(vk::CommandPoolCreateFlags::RESET_COMMAND_BUFFER);
// SAFETY: The queue-family index belongs to this live logical device.
unsafe { device.device().create_command_pool(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateCommandPool",
result: format!("{error:?}"),
}
})
}
fn create_triangle_vertex_buffer(
instance: &VulkanInstanceProbe,
device: &VulkanLogicalDeviceProbe,
) -> Result<VulkanAllocatedBuffer, VulkanSmokeRendererError> {
let vertices: [[f32; 5]; 3] = [
[0.0, -0.55, 1.0, 0.2, 0.2],
[0.55, 0.55, 0.2, 1.0, 0.2],
[-0.55, 0.55, 0.2, 0.4, 1.0],
];
let mut bytes = Vec::with_capacity(vertices.len() * 5 * std::mem::size_of::<f32>());
for vertex in vertices {
for value in vertex {
bytes.extend_from_slice(&value.to_ne_bytes());
}
}
create_host_visible_buffer(
instance,
device,
&bytes,
vk::BufferUsageFlags::VERTEX_BUFFER,
"triangle vertex buffer",
)
}
fn create_triangle_index_buffer(
instance: &VulkanInstanceProbe,
device: &VulkanLogicalDeviceProbe,
) -> Result<VulkanAllocatedBuffer, VulkanSmokeRendererError> {
let indices = [0_u16, 1_u16, 2_u16];
let mut bytes = Vec::with_capacity(indices.len() * std::mem::size_of::<u16>());
for index in indices {
bytes.extend_from_slice(&index.to_ne_bytes());
}
create_host_visible_buffer(
instance,
device,
&bytes,
vk::BufferUsageFlags::INDEX_BUFFER,
"triangle index buffer",
)
}
fn create_host_visible_buffer(
instance: &VulkanInstanceProbe,
device: &VulkanLogicalDeviceProbe,
bytes: &[u8],
usage: vk::BufferUsageFlags,
context: &'static str,
) -> Result<VulkanAllocatedBuffer, VulkanSmokeRendererError> {
let create_info = vk::BufferCreateInfo::default()
.size(bytes.len().try_into().unwrap_or(u64::MAX))
.usage(usage)
.sharing_mode(vk::SharingMode::EXCLUSIVE);
// SAFETY: The create info is stack-owned and references no external memory.
let buffer = unsafe { device.device().create_buffer(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context,
result: format!("{error:?}"),
}
})?;
// SAFETY: The buffer belongs to this device and is queried immediately after creation.
let requirements = unsafe { device.device().get_buffer_memory_requirements(buffer) };
let memory_type_index = find_memory_type(
instance,
device.physical_device,
requirements.memory_type_bits,
vk::MemoryPropertyFlags::HOST_VISIBLE | vk::MemoryPropertyFlags::HOST_COHERENT,
)
.ok_or(VulkanSmokeRendererError::MissingMemoryType { context })?;
let allocate_info = vk::MemoryAllocateInfo::default()
.allocation_size(requirements.size)
.memory_type_index(memory_type_index);
let memory =
// SAFETY: Allocation uses a memory type index selected from the physical-device requirements above.
unsafe { device.device().allocate_memory(&allocate_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context,
result: format!("{error:?}"),
}
})?;
// SAFETY: The buffer and allocation belong to the same live logical device.
unsafe { device.device().bind_buffer_memory(buffer, memory, 0) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context,
result: format!("{error:?}"),
}
})?;
// SAFETY: The allocation is HOST_VISIBLE, mapped for the full buffer size and unmapped before return.
let mapped = unsafe {
device
.device()
.map_memory(memory, 0, requirements.size, vk::MemoryMapFlags::empty())
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context,
result: format!("{error:?}"),
})?;
// SAFETY: The mapped pointer is valid for `bytes.len()` bytes and non-overlapping with the source slice.
unsafe {
std::ptr::copy_nonoverlapping(bytes.as_ptr(), mapped.cast::<u8>(), bytes.len());
device.device().unmap_memory(memory);
}
Ok(VulkanAllocatedBuffer { buffer, memory })
}
fn find_memory_type(
instance: &VulkanInstanceProbe,
physical_device: vk::PhysicalDevice,
memory_type_bits: u32,
required_properties: vk::MemoryPropertyFlags,
) -> Option<u32> {
// SAFETY: Physical-device memory properties are queried from a live instance-owned physical device.
let memory_properties = unsafe {
instance
.instance
.get_physical_device_memory_properties(physical_device)
};
memory_properties
.memory_types
.iter()
.enumerate()
.find_map(|(index, memory_type)| {
let supported = (memory_type_bits & (1_u32 << index)) != 0;
let has_properties = memory_type.property_flags.contains(required_properties);
(supported && has_properties).then(|| index.try_into().unwrap_or(u32::MAX))
})
}
fn create_swapchain_resources(
device: &VulkanLogicalDeviceProbe,
swapchain: &VulkanSwapchainProbe,
command_pool: vk::CommandPool,
_vertex_buffer: &VulkanAllocatedBuffer,
_index_buffer: &VulkanAllocatedBuffer,
_reuse_command_pool: bool,
) -> Result<VulkanSwapchainResources, VulkanSmokeRendererError> {
// SAFETY: The swapchain is live and owned by this renderer for the duration of the query.
let images = unsafe {
swapchain
.loader()
.get_swapchain_images(swapchain.swapchain())
}
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkGetSwapchainImagesKHR",
result: format!("{error:?}"),
})?;
let image_views = images
.iter()
.map(|image| create_image_view(device, *image, swapchain.report.plan.format.format))
.collect::<Result<Vec<_>, _>>()?;
let render_pass = create_render_pass(device, swapchain.report.plan.format.format)?;
let pipeline_layout = create_pipeline_layout(device)?;
let pipeline = create_graphics_pipeline(
device,
render_pass,
pipeline_layout,
swapchain.report.plan.extent,
)?;
let framebuffers = image_views
.iter()
.map(|image_view| {
create_framebuffer(
device,
render_pass,
*image_view,
swapchain.report.plan.extent,
)
})
.collect::<Result<Vec<_>, _>>()?;
let command_buffers = allocate_command_buffers(
device,
command_pool,
image_views.len().try_into().unwrap_or(u32::MAX),
)?;
Ok(VulkanSwapchainResources {
image_views,
render_pass,
pipeline_layout,
pipeline,
framebuffers,
command_buffers,
})
}
fn create_image_view(
device: &VulkanLogicalDeviceProbe,
image: vk::Image,
format: i32,
) -> Result<vk::ImageView, VulkanSmokeRendererError> {
let create_info = vk::ImageViewCreateInfo::default()
.image(image)
.view_type(vk::ImageViewType::TYPE_2D)
.format(vk::Format::from_raw(format))
.subresource_range(color_subresource_range());
// SAFETY: The image comes from the live swapchain and the subresource range covers its color aspect.
unsafe { device.device().create_image_view(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateImageView",
result: format!("{error:?}"),
}
})
}
fn create_render_pass(
device: &VulkanLogicalDeviceProbe,
format: i32,
) -> Result<vk::RenderPass, VulkanSmokeRendererError> {
let color_attachment = vk::AttachmentDescription::default()
.format(vk::Format::from_raw(format))
.samples(vk::SampleCountFlags::TYPE_1)
.load_op(vk::AttachmentLoadOp::CLEAR)
.store_op(vk::AttachmentStoreOp::STORE)
.initial_layout(vk::ImageLayout::COLOR_ATTACHMENT_OPTIMAL)
.final_layout(vk::ImageLayout::COLOR_ATTACHMENT_OPTIMAL);
let color_attachment_ref = vk::AttachmentReference::default()
.attachment(0)
.layout(vk::ImageLayout::COLOR_ATTACHMENT_OPTIMAL);
let color_attachments = [color_attachment_ref];
let subpass = vk::SubpassDescription::default()
.pipeline_bind_point(vk::PipelineBindPoint::GRAPHICS)
.color_attachments(&color_attachments);
let dependency = vk::SubpassDependency::default()
.src_subpass(vk::SUBPASS_EXTERNAL)
.dst_subpass(0)
.src_stage_mask(vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT)
.dst_stage_mask(vk::PipelineStageFlags::COLOR_ATTACHMENT_OUTPUT)
.dst_access_mask(vk::AccessFlags::COLOR_ATTACHMENT_WRITE);
let attachments = [color_attachment];
let subpasses = [subpass];
let dependencies = [dependency];
let create_info = vk::RenderPassCreateInfo::default()
.attachments(&attachments)
.subpasses(&subpasses)
.dependencies(&dependencies);
// SAFETY: The render-pass create info only references stack-owned descriptors.
unsafe { device.device().create_render_pass(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateRenderPass",
result: format!("{error:?}"),
}
})
}
fn create_pipeline_layout(
device: &VulkanLogicalDeviceProbe,
) -> Result<vk::PipelineLayout, VulkanSmokeRendererError> {
let create_info = vk::PipelineLayoutCreateInfo::default();
// SAFETY: The pipeline layout contains no descriptor sets or push constants.
unsafe { device.device().create_pipeline_layout(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreatePipelineLayout",
result: format!("{error:?}"),
}
})
}
fn extent_component_to_f32(value: u32) -> f32 {
u16::try_from(value).map_or(f32::from(u16::MAX), f32::from)
}
fn create_graphics_pipeline(
device: &VulkanLogicalDeviceProbe,
render_pass: vk::RenderPass,
pipeline_layout: vk::PipelineLayout,
extent: (u32, u32),
) -> Result<vk::Pipeline, VulkanSmokeRendererError> {
let entry_point = c"main";
let vertex_module = create_shader_module(device, TRIANGLE_VERTEX_SHADER_WORDS)?;
let fragment_module = create_shader_module(device, TRIANGLE_FRAGMENT_SHADER_WORDS)?;
let stage_create_infos = [
vk::PipelineShaderStageCreateInfo::default()
.stage(vk::ShaderStageFlags::VERTEX)
.module(vertex_module)
.name(entry_point),
vk::PipelineShaderStageCreateInfo::default()
.stage(vk::ShaderStageFlags::FRAGMENT)
.module(fragment_module)
.name(entry_point),
];
let binding_descriptions = [vk::VertexInputBindingDescription {
binding: 0,
stride: 20,
input_rate: vk::VertexInputRate::VERTEX,
}];
let attribute_descriptions = [
vk::VertexInputAttributeDescription {
location: 0,
binding: 0,
format: vk::Format::R32G32_SFLOAT,
offset: 0,
},
vk::VertexInputAttributeDescription {
location: 1,
binding: 0,
format: vk::Format::R32G32B32_SFLOAT,
offset: 8,
},
];
let vertex_input_state = vk::PipelineVertexInputStateCreateInfo::default()
.vertex_binding_descriptions(&binding_descriptions)
.vertex_attribute_descriptions(&attribute_descriptions);
let input_assembly_state = vk::PipelineInputAssemblyStateCreateInfo::default()
.topology(vk::PrimitiveTopology::TRIANGLE_LIST);
let viewports = [vk::Viewport {
x: 0.0,
y: 0.0,
width: extent_component_to_f32(extent.0),
height: extent_component_to_f32(extent.1),
min_depth: 0.0,
max_depth: 1.0,
}];
let scissors = [vk::Rect2D {
offset: vk::Offset2D { x: 0, y: 0 },
extent: vk::Extent2D {
width: extent.0,
height: extent.1,
},
}];
let viewport_state = vk::PipelineViewportStateCreateInfo::default()
.viewports(&viewports)
.scissors(&scissors);
let rasterization_state = vk::PipelineRasterizationStateCreateInfo::default()
.polygon_mode(vk::PolygonMode::FILL)
.cull_mode(vk::CullModeFlags::BACK)
.front_face(vk::FrontFace::CLOCKWISE)
.line_width(1.0);
let multisample_state = vk::PipelineMultisampleStateCreateInfo::default()
.rasterization_samples(vk::SampleCountFlags::TYPE_1);
let color_blend_attachment = [vk::PipelineColorBlendAttachmentState::default()
.color_write_mask(
vk::ColorComponentFlags::R
| vk::ColorComponentFlags::G
| vk::ColorComponentFlags::B
| vk::ColorComponentFlags::A,
)];
let color_blend_state =
vk::PipelineColorBlendStateCreateInfo::default().attachments(&color_blend_attachment);
let create_info = [vk::GraphicsPipelineCreateInfo::default()
.stages(&stage_create_infos)
.vertex_input_state(&vertex_input_state)
.input_assembly_state(&input_assembly_state)
.viewport_state(&viewport_state)
.rasterization_state(&rasterization_state)
.multisample_state(&multisample_state)
.color_blend_state(&color_blend_state)
.layout(pipeline_layout)
.render_pass(render_pass)
.subpass(0)];
// SAFETY: The pipeline creation references live shader modules and stack-owned fixed-function descriptors.
let pipeline = unsafe {
device
.device()
.create_graphics_pipelines(vk::PipelineCache::null(), &create_info, None)
}
.map_err(|(_, error)| VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateGraphicsPipelines",
result: format!("{error:?}"),
})?[0];
// SAFETY: Shader modules are no longer needed after pipeline creation completes.
unsafe {
device.device().destroy_shader_module(vertex_module, None);
device.device().destroy_shader_module(fragment_module, None);
}
Ok(pipeline)
}
fn create_shader_module(
device: &VulkanLogicalDeviceProbe,
words: &[u32],
) -> Result<vk::ShaderModule, VulkanSmokeRendererError> {
let create_info = vk::ShaderModuleCreateInfo::default().code(words);
// SAFETY: SPIR-V words are immutable and valid for the duration of the call.
unsafe { device.device().create_shader_module(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateShaderModule",
result: format!("{error:?}"),
}
})
}
fn create_framebuffer(
device: &VulkanLogicalDeviceProbe,
render_pass: vk::RenderPass,
image_view: vk::ImageView,
extent: (u32, u32),
) -> Result<vk::Framebuffer, VulkanSmokeRendererError> {
let attachments = [image_view];
let create_info = vk::FramebufferCreateInfo::default()
.render_pass(render_pass)
.attachments(&attachments)
.width(extent.0)
.height(extent.1)
.layers(1);
// SAFETY: The framebuffer attachments and render pass remain live for the duration of the call.
unsafe { device.device().create_framebuffer(&create_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateFramebuffer",
result: format!("{error:?}"),
}
})
}
fn allocate_command_buffers(
device: &VulkanLogicalDeviceProbe,
command_pool: vk::CommandPool,
count: u32,
) -> Result<Vec<vk::CommandBuffer>, VulkanSmokeRendererError> {
let allocate_info = vk::CommandBufferAllocateInfo::default()
.command_pool(command_pool)
.level(vk::CommandBufferLevel::PRIMARY)
.command_buffer_count(count);
// SAFETY: Command buffers are allocated from a live resettable pool owned by this device.
unsafe { device.device().allocate_command_buffers(&allocate_info) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkAllocateCommandBuffers",
result: format!("{error:?}"),
}
})
}
fn create_frame_sync(
device: &VulkanLogicalDeviceProbe,
) -> Result<Vec<VulkanFrameSync>, VulkanSmokeRendererError> {
let semaphore_info = vk::SemaphoreCreateInfo::default();
let fence_info = vk::FenceCreateInfo::default().flags(vk::FenceCreateFlags::SIGNALED);
let mut sync = Vec::with_capacity(2);
for _ in 0..2 {
// SAFETY: The sync objects belong to this live logical device and are destroyed at teardown.
let image_available = unsafe { device.device().create_semaphore(&semaphore_info, None) }
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateSemaphore(image_available)",
result: format!("{error:?}"),
})?;
// SAFETY: The sync objects belong to this live logical device and are destroyed at teardown.
let render_finished = unsafe { device.device().create_semaphore(&semaphore_info, None) }
.map_err(|error| VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateSemaphore(render_finished)",
result: format!("{error:?}"),
})?;
let fence =
// SAFETY: The fence belongs to this live logical device and is destroyed at teardown.
unsafe { device.device().create_fence(&fence_info, None) }.map_err(|error| {
VulkanSmokeRendererError::VulkanOperation {
context: "vkCreateFence",
result: format!("{error:?}"),
}
})?;
sync.push(VulkanFrameSync {
image_available,
render_finished,
fence,
});
}
Ok(sync)
}
fn destroy_swapchain_resources(
device: &VulkanLogicalDeviceProbe,
command_pool: vk::CommandPool,
resources: VulkanSwapchainResources,
) {
// SAFETY: All swapchain-dependent objects belong to this device and are destroyed once.
unsafe {
device
.device()
.free_command_buffers(command_pool, &resources.command_buffers);
for framebuffer in resources.framebuffers {
device.device().destroy_framebuffer(framebuffer, None);
}
device.device().destroy_pipeline(resources.pipeline, None);
device
.device()
.destroy_pipeline_layout(resources.pipeline_layout, None);
device
.device()
.destroy_render_pass(resources.render_pass, None);
for image_view in resources.image_views {
device.device().destroy_image_view(image_view, None);
}
}
}
fn color_subresource_range() -> vk::ImageSubresourceRange {
vk::ImageSubresourceRange::default()
.aspect_mask(vk::ImageAspectFlags::COLOR)
.base_mip_level(0)
.level_count(1)
.base_array_layer(0)
.layer_count(1)
}
/// Runtime swapchain creation report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanSwapchainReport {
/// Report schema version.
pub schema: u32,
/// Deterministic swapchain policy used for creation.
pub plan: VulkanSwapchainPlan,
/// Number of images returned by `vkGetSwapchainImagesKHR`.
pub image_count: u32,
}
/// Live Vulkan device/surface capability probe error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanRuntimeCapabilityError {
/// Physical device enumeration failed.
EnumerateDevicesFailed {
/// Vulkan result.
result: String,
},
/// Device extension enumeration failed.
EnumerateDeviceExtensionsFailed {
/// Device name or index context.
device: String,
/// Vulkan result.
result: String,
},
/// Queue-family present support query failed.
PresentSupportFailed {
/// Device name.
device: String,
/// Queue-family index.
queue_family: u32,
/// Vulkan result.
result: String,
},
/// Surface format query failed.
SurfaceFormatsFailed {
/// Device name.
device: String,
/// Vulkan result.
result: String,
},
/// Surface capability query failed.
SurfaceCapabilitiesFailed {
/// Device name.
device: String,
/// Vulkan result.
result: String,
},
/// Present mode query failed.
PresentModesFailed {
/// Device name.
device: String,
/// Vulkan result.
result: String,
},
/// No device satisfied Stage 0 capability policy.
Capability(VulkanCapabilityError),
/// Live surface capabilities could not produce a swapchain plan.
Swapchain(VulkanSwapchainError),
}
impl std::fmt::Display for VulkanRuntimeCapabilityError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::EnumerateDevicesFailed { result } => {
write!(f, "Vulkan physical device enumeration failed: {result}")
}
Self::EnumerateDeviceExtensionsFailed { device, result } => write!(
f,
"Vulkan device {device} extension enumeration failed: {result}"
),
Self::PresentSupportFailed {
device,
queue_family,
result,
} => write!(
f,
"Vulkan device {device} queue family {queue_family} present support query failed: {result}"
),
Self::SurfaceFormatsFailed { device, result } => write!(
f,
"Vulkan device {device} surface format query failed: {result}"
),
Self::SurfaceCapabilitiesFailed { device, result } => write!(
f,
"Vulkan device {device} surface capabilities query failed: {result}"
),
Self::PresentModesFailed { device, result } => write!(
f,
"Vulkan device {device} present mode query failed: {result}"
),
Self::Capability(error) => write!(f, "{error}"),
Self::Swapchain(error) => write!(f, "{error}"),
}
}
}
impl std::error::Error for VulkanRuntimeCapabilityError {}
/// Vulkan logical device creation error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanLogicalDeviceError {
/// Runtime capability probing failed.
Runtime(VulkanRuntimeCapabilityError),
/// Device extension name contained an interior NUL byte.
InvalidExtensionName {
/// Invalid extension name.
extension: String,
},
/// Logical device creation failed.
CreateFailed {
/// Selected device name.
device: String,
/// Vulkan result.
result: String,
},
}
impl std::fmt::Display for VulkanLogicalDeviceError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Runtime(error) => write!(f, "{error}"),
Self::InvalidExtensionName { extension } => write!(
f,
"Vulkan device extension name contains an interior NUL byte: {extension:?}"
),
Self::CreateFailed { device, result } => {
write!(
f,
"Vulkan logical device creation failed for {device}: {result}"
)
}
}
}
}
impl std::error::Error for VulkanLogicalDeviceError {}
/// Vulkan swapchain creation error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanSwapchainProbeError {
/// Surface capability query failed.
SurfaceCapabilitiesFailed {
/// Vulkan result.
result: String,
},
/// Swapchain creation failed.
CreateFailed {
/// Vulkan result.
result: String,
},
/// Swapchain image query failed.
ImagesFailed {
/// Vulkan result.
result: String,
},
}
impl std::fmt::Display for VulkanSwapchainProbeError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::SurfaceCapabilitiesFailed { result } => {
write!(f, "Vulkan surface capabilities query failed: {result}")
}
Self::CreateFailed { result } => {
write!(f, "Vulkan swapchain creation failed: {result}")
}
Self::ImagesFailed { result } => {
write!(f, "Vulkan swapchain image query failed: {result}")
}
}
}
}
impl std::error::Error for VulkanSwapchainProbeError {}
/// Builds a deterministic Vulkan surface plan from native window handles.
///
/// # Errors
///
/// Returns [`VulkanSurfaceError`] when no native handles exist or the platform
/// display backend has no Vulkan surface extension mapping.
pub fn plan_vulkan_surface(
handles: Option<NativeWindowHandles>,
) -> Result<VulkanSurfacePlan, VulkanSurfaceError> {
let handles = handles.ok_or(VulkanSurfaceError::MissingNativeHandles)?;
let required = ash_window::enumerate_required_extensions(handles.display).map_err(|error| {
VulkanSurfaceError::RequiredExtensionsFailed {
result: format!("{error:?}"),
}
})?;
let mut required_instance_extensions = Vec::with_capacity(required.len());
for extension in required {
let name = extension_name(*extension)?;
required_instance_extensions.push(name);
}
required_instance_extensions.sort();
required_instance_extensions.dedup();
Ok(VulkanSurfacePlan {
schema: 1,
required_instance_extensions,
})
}
/// Creates a Vulkan surface probe from native window handles.
///
/// # Errors
///
/// Returns [`VulkanSurfaceError`] when handles are missing, required extensions
/// cannot be planned, or `vkCreate*SurfaceKHR` fails.
pub fn create_vulkan_surface_probe(
instance: &VulkanInstanceProbe,
handles: Option<NativeWindowHandles>,
) -> Result<VulkanSurfaceProbe, VulkanSurfaceError> {
let handles = handles.ok_or(VulkanSurfaceError::MissingNativeHandles)?;
let report = plan_vulkan_surface(Some(handles))?;
// SAFETY: The platform handles are only used to create a child surface owned by this probe.
let surface = unsafe {
ash_window::create_surface(
&instance.entry,
&instance.instance,
handles.display,
handles.window,
None,
)
}
.map_err(|error| VulkanSurfaceError::CreateFailed {
result: format!("{error:?}"),
})?;
Ok(VulkanSurfaceProbe {
loader: surface::Instance::new(&instance.entry, &instance.instance),
surface,
report,
})
}
/// Probes live Vulkan device, queue, surface and swapchain capabilities.
///
/// # Errors
///
/// Returns [`VulkanRuntimeCapabilityError`] when device enumeration, surface
/// capability queries, Stage 0 device selection, or swapchain planning fails.
pub fn probe_vulkan_runtime_capabilities(
instance: &VulkanInstanceProbe,
surface: &VulkanSurfaceProbe,
drawable_extent: (u32, u32),
) -> Result<VulkanRuntimeCapabilityProbe, VulkanRuntimeCapabilityError> {
let selected = select_live_device_candidate(instance, surface, drawable_extent)?;
Ok(selected.runtime)
}
/// Creates a Vulkan logical device for the selected live surface-capable device.
///
/// # Errors
///
/// Returns [`VulkanLogicalDeviceError`] when runtime capability probing fails,
/// device extension names are invalid, or `vkCreateDevice` fails.
pub fn create_vulkan_logical_device_probe(
instance: &VulkanInstanceProbe,
surface: &VulkanSurfaceProbe,
drawable_extent: (u32, u32),
) -> Result<VulkanLogicalDeviceProbe, VulkanLogicalDeviceError> {
let selected = select_live_device_candidate(instance, surface, drawable_extent)
.map_err(VulkanLogicalDeviceError::Runtime)?;
let capability = &selected.runtime.capability;
let queue_priorities = [1.0_f32];
let queue_families = unique_queue_families(
capability.graphics_queue_family,
capability.present_queue_family,
);
let queue_infos = queue_families
.iter()
.map(|queue_family| {
vk::DeviceQueueCreateInfo::default()
.queue_family_index(*queue_family)
.queue_priorities(&queue_priorities)
})
.collect::<Vec<_>>();
let extension_names = device_extension_cstrings(&capability.enabled_extensions)
.map_err(|extension| VulkanLogicalDeviceError::InvalidExtensionName { extension })?;
let extension_ptrs = extension_names
.iter()
.map(|extension| extension.as_ptr())
.collect::<Vec<_>>();
let create_info = vk::DeviceCreateInfo::default()
.queue_create_infos(&queue_infos)
.enabled_extension_names(&extension_ptrs);
// SAFETY: `selected.physical_device` belongs to `instance`; create data lives for the call.
let device = unsafe {
instance
.instance
.create_device(selected.physical_device, &create_info, None)
}
.map_err(|error| VulkanLogicalDeviceError::CreateFailed {
device: capability.device_name.clone(),
result: format!("{error:?}"),
})?;
// SAFETY: Queue family indices came from validated live queue families requested above.
let _graphics_queue = unsafe { device.get_device_queue(capability.graphics_queue_family, 0) };
// SAFETY: Queue family indices came from validated live queue families requested above.
let _present_queue = unsafe { device.get_device_queue(capability.present_queue_family, 0) };
Ok(VulkanLogicalDeviceProbe {
device,
physical_device: selected.physical_device,
report: VulkanLogicalDeviceReport {
schema: 1,
device_name: capability.device_name.clone(),
graphics_queue_family: capability.graphics_queue_family,
present_queue_family: capability.present_queue_family,
enabled_extensions: capability.enabled_extensions.clone(),
},
runtime: selected.runtime,
})
}
/// Creates a Vulkan swapchain for the live logical device and surface.
///
/// # Errors
///
/// Returns [`VulkanSwapchainProbeError`] when live surface capability queries,
/// swapchain creation, or swapchain image enumeration fails.
pub fn create_vulkan_swapchain_probe(
instance: &VulkanInstanceProbe,
surface: &VulkanSurfaceProbe,
device: &VulkanLogicalDeviceProbe,
) -> Result<VulkanSwapchainProbe, VulkanSwapchainProbeError> {
create_vulkan_swapchain_probe_for_extent(
instance,
surface,
device,
device.runtime.swapchain.extent,
vk::SwapchainKHR::null(),
)
}
/// Creates a Vulkan swapchain for the live logical device and surface at a specific extent.
///
/// # Errors
///
/// Returns [`VulkanSwapchainProbeError`] when live surface capability queries,
/// swapchain creation, or swapchain image enumeration fails.
pub fn create_vulkan_swapchain_probe_for_extent(
instance: &VulkanInstanceProbe,
surface: &VulkanSurfaceProbe,
device: &VulkanLogicalDeviceProbe,
drawable_extent: (u32, u32),
old_swapchain: vk::SwapchainKHR,
) -> Result<VulkanSwapchainProbe, VulkanSwapchainProbeError> {
let raw_capabilities = {
// SAFETY: The physical device and surface are live query inputs and no handles are retained.
unsafe {
surface
.loader
.get_physical_device_surface_capabilities(device.physical_device, surface.surface)
}
}
.map_err(
|error| VulkanSwapchainProbeError::SurfaceCapabilitiesFailed {
result: format!("{error:?}"),
},
)?;
let surface_formats =
live_surface_formats(surface, device.physical_device, &device.report.device_name).map_err(
|error| VulkanSwapchainProbeError::CreateFailed {
result: error.to_string(),
},
)?;
let present_modes =
live_present_modes(surface, device.physical_device, &device.report.device_name).map_err(
|error| VulkanSwapchainProbeError::CreateFailed {
result: error.to_string(),
},
)?;
let capabilities =
live_surface_capabilities(surface, device.physical_device, &device.report.device_name)
.map_err(
|error| VulkanSwapchainProbeError::SurfaceCapabilitiesFailed {
result: error.to_string(),
},
)?;
let plan = plan_vulkan_swapchain(&VulkanSwapchainRequest {
drawable_extent,
formats: surface_formats,
present_modes,
capabilities,
preferred_present_mode: vk::PresentModeKHR::MAILBOX.as_raw(),
})
.map_err(|error| VulkanSwapchainProbeError::CreateFailed {
result: error.to_string(),
})?;
let queue_family_indices = unique_queue_families(
device.runtime.capability.graphics_queue_family,
device.runtime.capability.present_queue_family,
);
let sharing_mode = if queue_family_indices.len() > 1 {
vk::SharingMode::CONCURRENT
} else {
vk::SharingMode::EXCLUSIVE
};
let create_info = vk::SwapchainCreateInfoKHR::default()
.surface(surface.surface)
.min_image_count(plan.image_count)
.image_format(vk::Format::from_raw(plan.format.format))
.image_color_space(vk::ColorSpaceKHR::from_raw(plan.format.color_space))
.image_extent(vk::Extent2D {
width: plan.extent.0,
height: plan.extent.1,
})
.image_array_layers(1)
.image_usage(vk::ImageUsageFlags::COLOR_ATTACHMENT)
.image_sharing_mode(sharing_mode)
.queue_family_indices(&queue_family_indices)
.pre_transform(raw_capabilities.current_transform)
.composite_alpha(select_composite_alpha(
raw_capabilities.supported_composite_alpha,
))
.present_mode(vk::PresentModeKHR::from_raw(plan.present_mode))
.old_swapchain(old_swapchain)
.clipped(true);
let loader = swapchain::Device::new(&instance.instance, &device.device);
// SAFETY: The create info references live instance/device/surface handles for this call.
let swapchain = unsafe { loader.create_swapchain(&create_info, None) }.map_err(|error| {
VulkanSwapchainProbeError::CreateFailed {
result: format!("{error:?}"),
}
})?;
// SAFETY: The swapchain was created above and the returned image handles are owned by it.
let images = unsafe { loader.get_swapchain_images(swapchain) }.map_err(|error| {
VulkanSwapchainProbeError::ImagesFailed {
result: format!("{error:?}"),
}
})?;
Ok(VulkanSwapchainProbe {
loader,
swapchain,
report: VulkanSwapchainReport {
schema: 1,
plan,
image_count: images.len().try_into().unwrap_or(u32::MAX),
},
})
}
fn select_live_device_candidate(
instance: &VulkanInstanceProbe,
surface: &VulkanSurfaceProbe,
drawable_extent: (u32, u32),
) -> Result<SelectedLiveDevice, VulkanRuntimeCapabilityError> {
let devices = {
// SAFETY: The Vulkan instance is live for this query and no handles are retained.
unsafe { instance.instance.enumerate_physical_devices() }.map_err(|error| {
VulkanRuntimeCapabilityError::EnumerateDevicesFailed {
result: format!("{error:?}"),
}
})?
};
let mut best: Option<LiveDeviceCandidate> = None;
let mut last_error = None;
for (index, device) in devices.iter().copied().enumerate() {
let candidate = match live_device_candidate(instance, surface, device, index) {
Ok(candidate) => candidate,
Err(err) => {
last_error = Some(err);
continue;
}
};
match &best {
Some(existing)
if compare_reports(&candidate.capability, &existing.capability)
!= std::cmp::Ordering::Greater => {}
_ => best = Some(candidate),
}
}
let best = best.ok_or_else(|| {
last_error.unwrap_or(VulkanRuntimeCapabilityError::Capability(
VulkanCapabilityError::NoPhysicalDevice,
))
})?;
let swapchain = plan_vulkan_swapchain(&VulkanSwapchainRequest {
drawable_extent,
formats: best.surface_formats,
present_modes: best.present_modes,
capabilities: best.surface_capabilities,
preferred_present_mode: vk::PresentModeKHR::MAILBOX.as_raw(),
})
.map_err(VulkanRuntimeCapabilityError::Swapchain)?;
Ok(SelectedLiveDevice {
physical_device: best.physical_device,
runtime: VulkanRuntimeCapabilityProbe {
capability: best.capability,
swapchain,
},
})
}
struct SelectedLiveDevice {
physical_device: vk::PhysicalDevice,
runtime: VulkanRuntimeCapabilityProbe,
}
struct LiveDeviceCandidate {
physical_device: vk::PhysicalDevice,
capability: VulkanCapabilityReport,
surface_formats: Vec<VulkanSurfaceFormat>,
present_modes: Vec<i32>,
surface_capabilities: VulkanSwapchainSurfaceCapabilities,
}
fn live_device_candidate(
instance: &VulkanInstanceProbe,
surface: &VulkanSurfaceProbe,
device: vk::PhysicalDevice,
index: usize,
) -> Result<LiveDeviceCandidate, VulkanRuntimeCapabilityError> {
let properties = {
// SAFETY: `device` was returned by this live instance and the result is copied by value.
unsafe { instance.instance.get_physical_device_properties(device) }
};
let name = physical_device_name(&properties, index);
let queue_properties = {
// SAFETY: `device` was returned by this live instance and the result is owned by Rust.
unsafe {
instance
.instance
.get_physical_device_queue_family_properties(device)
}
};
let extensions = live_device_extensions(instance, device, &name)?;
let surface_formats = live_surface_formats(surface, device, &name)?;
let present_modes = live_present_modes(surface, device, &name)?;
let surface_capabilities = live_surface_capabilities(surface, device, &name)?;
let queue_families = queue_properties
.iter()
.enumerate()
.map(|(queue_index, properties)| {
let index = u32::try_from(queue_index).unwrap_or(u32::MAX);
let present = {
// SAFETY: The physical device, surface and queue-family index are live query inputs.
unsafe {
surface.loader.get_physical_device_surface_support(
device,
index,
surface.surface,
)
}
}
.map_err(|error| VulkanRuntimeCapabilityError::PresentSupportFailed {
device: name.clone(),
queue_family: index,
result: format!("{error:?}"),
})?;
Ok(VulkanQueueFamily {
index,
graphics: properties.queue_flags.contains(vk::QueueFlags::GRAPHICS),
present,
})
})
.collect::<Result<Vec<_>, VulkanRuntimeCapabilityError>>()?;
let record = VulkanPhysicalDeviceRecord {
name,
api_version: properties.api_version,
device_type: match properties.device_type {
vk::PhysicalDeviceType::DISCRETE_GPU => VulkanDeviceType::DiscreteGpu,
vk::PhysicalDeviceType::INTEGRATED_GPU => VulkanDeviceType::IntegratedGpu,
vk::PhysicalDeviceType::CPU => VulkanDeviceType::Cpu,
_ => VulkanDeviceType::Other,
},
extensions,
queue_families,
surface_formats: surface_formats.clone(),
};
let capability = validate_device(&record).map_err(VulkanRuntimeCapabilityError::Capability)?;
Ok(LiveDeviceCandidate {
physical_device: device,
capability,
surface_formats,
present_modes,
surface_capabilities,
})
}
fn unique_queue_families(graphics: u32, present: u32) -> Vec<u32> {
if graphics == present {
vec![graphics]
} else {
vec![graphics, present]
}
}
fn device_extension_cstrings(values: &[String]) -> Result<Vec<CString>, String> {
values
.iter()
.map(|extension| CString::new(extension.as_str()).map_err(|_| extension.clone()))
.collect()
}
fn physical_device_name(properties: &vk::PhysicalDeviceProperties, index: usize) -> String {
// SAFETY: Vulkan device names are fixed-size NUL-terminated C strings per the spec.
let name = unsafe { CStr::from_ptr(properties.device_name.as_ptr()) }
.to_string_lossy()
.trim()
.to_string();
if name.is_empty() {
format!("physical-device-{index}")
} else {
name
}
}
fn live_device_extensions(
instance: &VulkanInstanceProbe,
device: vk::PhysicalDevice,
name: &str,
) -> Result<Vec<String>, VulkanRuntimeCapabilityError> {
let properties = {
// SAFETY: `device` was returned by this live instance and no borrowed data escapes.
unsafe {
instance
.instance
.enumerate_device_extension_properties(device)
}
}
.map_err(
|error| VulkanRuntimeCapabilityError::EnumerateDeviceExtensionsFailed {
device: name.to_string(),
result: format!("{error:?}"),
},
)?;
let mut extensions = properties
.iter()
.map(|property| {
// SAFETY: Vulkan extension names are fixed-size NUL-terminated C strings per the spec.
unsafe { CStr::from_ptr(property.extension_name.as_ptr()) }
.to_string_lossy()
.into_owned()
})
.collect::<Vec<_>>();
extensions.sort();
extensions.dedup();
Ok(extensions)
}
fn live_surface_formats(
surface: &VulkanSurfaceProbe,
device: vk::PhysicalDevice,
name: &str,
) -> Result<Vec<VulkanSurfaceFormat>, VulkanRuntimeCapabilityError> {
let formats = {
// SAFETY: The physical device and surface are live query inputs and no handles are retained.
unsafe {
surface
.loader
.get_physical_device_surface_formats(device, surface.surface)
}
}
.map_err(|error| VulkanRuntimeCapabilityError::SurfaceFormatsFailed {
device: name.to_string(),
result: format!("{error:?}"),
})?;
Ok(formats
.into_iter()
.map(|format| VulkanSurfaceFormat {
format: format.format.as_raw(),
color_space: format.color_space.as_raw(),
})
.collect())
}
fn live_present_modes(
surface: &VulkanSurfaceProbe,
device: vk::PhysicalDevice,
name: &str,
) -> Result<Vec<i32>, VulkanRuntimeCapabilityError> {
let modes = {
// SAFETY: The physical device and surface are live query inputs and no handles are retained.
unsafe {
surface
.loader
.get_physical_device_surface_present_modes(device, surface.surface)
}
}
.map_err(|error| VulkanRuntimeCapabilityError::PresentModesFailed {
device: name.to_string(),
result: format!("{error:?}"),
})?;
Ok(modes.into_iter().map(vk::PresentModeKHR::as_raw).collect())
}
fn live_surface_capabilities(
surface: &VulkanSurfaceProbe,
device: vk::PhysicalDevice,
name: &str,
) -> Result<VulkanSwapchainSurfaceCapabilities, VulkanRuntimeCapabilityError> {
let capabilities = {
// SAFETY: The physical device and surface are live query inputs and no handles are retained.
unsafe {
surface
.loader
.get_physical_device_surface_capabilities(device, surface.surface)
}
}
.map_err(
|error| VulkanRuntimeCapabilityError::SurfaceCapabilitiesFailed {
device: name.to_string(),
result: format!("{error:?}"),
},
)?;
Ok(VulkanSwapchainSurfaceCapabilities {
current_extent: if capabilities.current_extent.width == u32::MAX {
None
} else {
Some((
capabilities.current_extent.width,
capabilities.current_extent.height,
))
},
min_extent: (
capabilities.min_image_extent.width,
capabilities.min_image_extent.height,
),
max_extent: (
capabilities.max_image_extent.width,
capabilities.max_image_extent.height,
),
min_image_count: capabilities.min_image_count,
max_image_count: capabilities.max_image_count,
})
}
/// Renders a deterministic JSON Vulkan surface plan.
#[must_use]
pub fn render_surface_plan_json(plan: &VulkanSurfacePlan) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&plan.schema.to_string());
out.push_str(",\"required_instance_extensions\":[");
for (index, extension) in plan.required_instance_extensions.iter().enumerate() {
if index > 0 {
out.push(',');
}
push_json_string(&mut out, extension);
}
out.push_str("]}");
out
}
fn extension_name(extension: *const c_char) -> Result<String, VulkanSurfaceError> {
// SAFETY: `ash-window` returns extension pointers to static NUL-terminated Vulkan names.
let name = unsafe { CStr::from_ptr(extension) };
name.to_str()
.map(str::to_string)
.map_err(|_| VulkanSurfaceError::InvalidExtensionName)
}
/// Vulkan instance bootstrap error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanInstanceError {
/// The Vulkan loader could not be opened.
Loader(VulkanLoaderError),
/// Application name contained an interior NUL byte.
InvalidApplicationName,
/// An extension name contained an interior NUL byte.
InvalidExtensionName {
/// Invalid extension name.
extension: String,
},
/// Validation layers were requested but unavailable.
MissingValidationLayer,
/// Instance creation failed.
CreateFailed {
/// Vulkan result.
result: String,
},
}
impl std::fmt::Display for VulkanInstanceError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Loader(error) => write!(f, "{error}"),
Self::InvalidApplicationName => {
write!(f, "Vulkan application name contains an interior NUL byte")
}
Self::InvalidExtensionName { extension } => {
write!(
f,
"Vulkan instance extension name contains an interior NUL byte: {extension:?}"
)
}
Self::MissingValidationLayer => {
write!(
f,
"Vulkan validation layer VK_LAYER_KHRONOS_validation is unavailable"
)
}
Self::CreateFailed { result } => write!(f, "Vulkan instance creation failed: {result}"),
}
}
}
impl std::error::Error for VulkanInstanceError {}
/// Builds the deterministic instance creation plan without touching the loader.
#[must_use]
pub fn plan_vulkan_instance(config: &VulkanInstanceConfig) -> VulkanInstancePlan {
let mut enabled_extensions = config.required_extensions.clone();
if config.enable_validation
&& !enabled_extensions
.iter()
.any(|extension| extension == EXT_DEBUG_UTILS_EXTENSION)
{
enabled_extensions.push(EXT_DEBUG_UTILS_EXTENSION.to_string());
}
if config.enable_portability_enumeration
&& !enabled_extensions
.iter()
.any(|extension| extension == KHR_PORTABILITY_ENUMERATION_EXTENSION)
{
enabled_extensions.push(KHR_PORTABILITY_ENUMERATION_EXTENSION.to_string());
}
enabled_extensions.sort();
enabled_extensions.dedup();
VulkanInstancePlan {
schema: 1,
enabled_extensions,
create_flags: if config.enable_portability_enumeration {
vk::InstanceCreateFlags::ENUMERATE_PORTABILITY_KHR.as_raw()
} else {
0
},
validation_requested: config.enable_validation,
}
}
/// Creates a Vulkan instance probe from the supplied configuration.
///
/// # Errors
///
/// Returns [`VulkanInstanceError`] when the loader is unavailable, names are not
/// valid C strings, or `vkCreateInstance` fails.
pub fn create_vulkan_instance_probe(
config: &VulkanInstanceConfig,
) -> Result<VulkanInstanceProbe, VulkanInstanceError> {
// SAFETY: Loading the entry only resolves loader symbols; no raw Vulkan handles escape.
let entry = unsafe { ash::Entry::load() }.map_err(|error| {
VulkanInstanceError::Loader(VulkanLoaderError::Unavailable {
message: error.to_string(),
})
})?;
let app_name = CString::new(config.application_name.clone())
.map_err(|_| VulkanInstanceError::InvalidApplicationName)?;
let engine_name = c"fparkan";
let plan = plan_vulkan_instance(config);
let extension_names = cstring_vec(&plan.enabled_extensions)?;
let extension_ptrs = cstring_ptrs(&extension_names);
let layer_names = validation_layer_cstrings(&entry, config.enable_validation)?;
let layer_ptrs = cstring_ptrs(&layer_names);
let app_info = vk::ApplicationInfo::default()
.application_name(&app_name)
.application_version(0)
.engine_name(engine_name)
.engine_version(0)
.api_version(MIN_VULKAN_API_VERSION);
let create_info = vk::InstanceCreateInfo::default()
.application_info(&app_info)
.enabled_extension_names(&extension_ptrs)
.enabled_layer_names(&layer_ptrs)
.flags(vk::InstanceCreateFlags::from_raw(plan.create_flags));
// SAFETY: `create_info` points to stack-owned Vulkan create data that lives for the call.
let instance = unsafe { entry.create_instance(&create_info, None) }.map_err(|error| {
VulkanInstanceError::CreateFailed {
result: format!("{error:?}"),
}
})?;
Ok(VulkanInstanceProbe {
entry,
instance,
report: plan,
})
}
fn validation_layer_cstrings(
entry: &ash::Entry,
enable_validation: bool,
) -> Result<Vec<CString>, VulkanInstanceError> {
if !enable_validation {
return Ok(Vec::new());
}
let available_layers =
// SAFETY: Enumerating instance layers reads loader-owned immutable metadata.
unsafe { entry.enumerate_instance_layer_properties() }.map_err(|error| {
VulkanInstanceError::CreateFailed {
result: format!("{error:?}"),
}
})?;
let validation_available = available_layers.iter().any(|layer| {
// SAFETY: Vulkan layer names are fixed-size NUL-terminated strings from the loader.
unsafe { CStr::from_ptr(layer.layer_name.as_ptr()) }
.to_string_lossy()
.as_ref()
== VALIDATION_LAYER_NAME
});
if !validation_available {
return Err(VulkanInstanceError::MissingValidationLayer);
}
Ok(vec![CString::new(VALIDATION_LAYER_NAME).map_err(|_| {
VulkanInstanceError::InvalidApplicationName
})?])
}
/// Renders a deterministic JSON Vulkan instance plan.
#[must_use]
pub fn render_instance_plan_json(plan: &VulkanInstancePlan) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&plan.schema.to_string());
out.push_str(",\"create_flags\":");
out.push_str(&plan.create_flags.to_string());
out.push_str(",\"validation_requested\":");
out.push_str(if plan.validation_requested {
"true"
} else {
"false"
});
out.push_str(",\"enabled_extensions\":[");
for (index, extension) in plan.enabled_extensions.iter().enumerate() {
if index > 0 {
out.push(',');
}
push_json_string(&mut out, extension);
}
out.push_str("]}");
out
}
fn cstring_vec(values: &[String]) -> Result<Vec<CString>, VulkanInstanceError> {
values
.iter()
.map(|extension| {
CString::new(extension.as_str()).map_err(|_| {
VulkanInstanceError::InvalidExtensionName {
extension: extension.clone(),
}
})
})
.collect()
}
fn cstring_ptrs(values: &[CString]) -> Vec<*const c_char> {
values.iter().map(|value| value.as_ptr()).collect()
}
/// Deterministic Vulkan loader probe report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanLoaderProbeReport {
/// Report schema version.
pub schema: u32,
/// Whether the Vulkan loader was opened successfully.
pub loader_available: bool,
/// Reported loader instance API version.
pub instance_api_version: u32,
}
/// Vulkan loader bootstrap error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanLoaderError {
/// The Vulkan loader library could not be opened.
Unavailable {
/// Loader error text.
message: String,
},
}
impl std::fmt::Display for VulkanLoaderError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Unavailable { message } => {
write!(f, "Vulkan loader is unavailable: {message}")
}
}
}
}
impl std::error::Error for VulkanLoaderError {}
/// Opens the Vulkan loader and reports the supported instance API version.
///
/// # Errors
///
/// Returns [`VulkanLoaderError`] when no Vulkan loader library can be opened on
/// the host.
pub fn probe_vulkan_loader() -> Result<VulkanLoaderProbeReport, VulkanLoaderError> {
// SAFETY: Loading the entry only resolves loader symbols; no raw Vulkan handles escape.
let entry = unsafe { ash::Entry::load() }.map_err(|error| VulkanLoaderError::Unavailable {
message: error.to_string(),
})?;
// SAFETY: The resolved entry only queries the loader-supported instance API version.
let version = unsafe { entry.try_enumerate_instance_version() }
.map_err(|error| VulkanLoaderError::Unavailable {
message: error.to_string(),
})?
.unwrap_or(vk::API_VERSION_1_0);
Ok(VulkanLoaderProbeReport {
schema: 1,
loader_available: true,
instance_api_version: version,
})
}
/// Returns the static Vulkan entry name used by loader probes.
#[must_use]
pub fn vulkan_entry_symbol_name() -> &'static CStr {
c"vkGetInstanceProcAddr"
}
/// Renders a deterministic JSON Vulkan loader report.
#[must_use]
pub fn render_loader_probe_report_json(report: &VulkanLoaderProbeReport) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&report.schema.to_string());
out.push_str(",\"loader_available\":");
out.push_str(if report.loader_available {
"true"
} else {
"false"
});
out.push_str(",\"instance_api\":\"");
out.push_str(&format_api_version(report.instance_api_version));
out.push_str("\"}");
out
}
/// Returns the built-in Stage 0 indexed-triangle shader manifest.
#[must_use]
pub fn triangle_shader_manifest() -> Vec<VulkanShaderModuleManifest> {
vec![
VulkanShaderModuleManifest {
name: "triangle.vert",
stage: VulkanShaderStage::Vertex,
entry_point: "main",
descriptor_sets: 0,
push_constant_bytes: 0,
words: TRIANGLE_VERTEX_SHADER_WORDS,
},
VulkanShaderModuleManifest {
name: "triangle.frag",
stage: VulkanShaderStage::Fragment,
entry_point: "main",
descriptor_sets: 0,
push_constant_bytes: 0,
words: TRIANGLE_FRAGMENT_SHADER_WORDS,
},
]
}
/// Validates shader SPIR-V containers and renders a deterministic report.
///
/// # Errors
///
/// Returns [`VulkanShaderManifestError`] when a module fails Stage 0 SPIR-V
/// container validation.
pub fn validate_shader_manifest(
modules: &[VulkanShaderModuleManifest],
) -> Result<VulkanShaderManifestReport, VulkanShaderManifestError> {
let mut reports = Vec::with_capacity(modules.len());
for module in modules {
validate_spirv_container(module)?;
let bytes = spirv_words_to_bytes(module.words);
reports.push(VulkanShaderModuleReport {
name: module.name,
stage: module.stage,
entry_point: module.entry_point,
word_count: module.words.len(),
sha256: sha256_hex(&sha256(&bytes)),
});
}
let normalized = render_shader_modules_json(&reports);
Ok(VulkanShaderManifestReport {
schema: 1,
compiler: SHADER_COMPILER_ID,
validator: SPIRV_VALIDATOR_ID,
modules: reports,
manifest_hash: sha256_hex(&sha256(normalized.as_bytes())),
})
}
fn validate_spirv_container(
module: &VulkanShaderModuleManifest,
) -> Result<(), VulkanShaderManifestError> {
if module.words.len() < 5 {
return Err(VulkanShaderManifestError::TooShort { name: module.name });
}
if module.words[0] != SPIRV_MAGIC {
return Err(VulkanShaderManifestError::InvalidMagic {
name: module.name,
found: module.words[0],
});
}
if module.words[1] < SPIRV_VERSION_1_0 {
return Err(VulkanShaderManifestError::UnsupportedVersion {
name: module.name,
found: module.words[1],
});
}
if module.words[3] == 0 {
return Err(VulkanShaderManifestError::InvalidBound { name: module.name });
}
Ok(())
}
fn spirv_words_to_bytes(words: &[u32]) -> Vec<u8> {
let mut out = Vec::with_capacity(words.len() * 4);
for word in words {
out.extend_from_slice(&word.to_le_bytes());
}
out
}
/// Renders a deterministic JSON shader manifest report.
#[must_use]
pub fn render_shader_manifest_report_json(report: &VulkanShaderManifestReport) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&report.schema.to_string());
out.push_str(",\"compiler\":");
push_json_string(&mut out, report.compiler);
out.push_str(",\"validator\":");
push_json_string(&mut out, report.validator);
out.push_str(",\"modules\":");
out.push_str(&render_shader_modules_json(&report.modules));
out.push_str(",\"manifest_hash\":");
push_json_string(&mut out, &report.manifest_hash);
out.push('}');
out
}
fn render_shader_modules_json(modules: &[VulkanShaderModuleReport]) -> String {
let mut out = String::new();
out.push('[');
for (index, module) in modules.iter().enumerate() {
if index > 0 {
out.push(',');
}
out.push_str("{\"name\":");
push_json_string(&mut out, module.name);
out.push_str(",\"stage\":\"");
out.push_str(module.stage.as_str());
out.push_str("\",\"entry_point\":");
push_json_string(&mut out, module.entry_point);
out.push_str(",\"word_count\":");
out.push_str(&module.word_count.to_string());
out.push_str(",\"sha256\":");
push_json_string(&mut out, &module.sha256);
out.push('}');
}
out.push(']');
out
}
/// Vulkan backend migration readiness.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum VulkanBackendState {
/// Adapter prepared and able to accept commands.
Ready,
/// Adapter is tracking a recoverable runtime surface/depth pipeline fault.
Degraded,
/// Adapter has encountered a non-recoverable error.
Error,
}
impl Default for VulkanBackendState {
fn default() -> Self {
Self::Degraded
}
}
/// Synthetic physical-device type used by deterministic capability scoring.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum VulkanDeviceType {
/// Discrete GPU.
DiscreteGpu,
/// Integrated GPU.
IntegratedGpu,
/// CPU or software Vulkan implementation.
Cpu,
/// Other or unknown implementation.
Other,
}
impl VulkanDeviceType {
const fn score_bonus(self) -> i32 {
match self {
Self::DiscreteGpu => 1_000,
Self::IntegratedGpu => 700,
Self::Cpu => 100,
Self::Other => 10,
}
}
}
/// Queue-family capabilities needed by the Stage 0 renderer.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct VulkanQueueFamily {
/// Stable queue-family index.
pub index: u32,
/// Whether the family supports graphics commands.
pub graphics: bool,
/// Whether the family supports presentation for the target surface.
pub present: bool,
}
/// Surface format capability needed by the Stage 0 swapchain policy.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct VulkanSurfaceFormat {
/// Vulkan format numeric value.
pub format: i32,
/// Vulkan color-space numeric value.
pub color_space: i32,
}
/// Surface capabilities needed by the Stage 0 swapchain policy.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct VulkanSwapchainSurfaceCapabilities {
/// Current surface extent, when dictated by the platform.
pub current_extent: Option<(u32, u32)>,
/// Minimum supported swapchain extent.
pub min_extent: (u32, u32),
/// Maximum supported swapchain extent.
pub max_extent: (u32, u32),
/// Minimum supported image count.
pub min_image_count: u32,
/// Maximum supported image count, or 0 when unbounded.
pub max_image_count: u32,
}
/// Deterministic swapchain planning input.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanSwapchainRequest {
/// Requested drawable extent.
pub drawable_extent: (u32, u32),
/// Available surface formats.
pub formats: Vec<VulkanSurfaceFormat>,
/// Available present modes as raw Vulkan values.
pub present_modes: Vec<i32>,
/// Surface capabilities.
pub capabilities: VulkanSwapchainSurfaceCapabilities,
/// Preferred present mode.
pub preferred_present_mode: i32,
}
/// Deterministic swapchain plan.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanSwapchainPlan {
/// Report schema version.
pub schema: u32,
/// Selected swapchain extent.
pub extent: (u32, u32),
/// Selected surface format.
pub format: VulkanSurfaceFormat,
/// Selected present mode raw Vulkan value.
pub present_mode: i32,
/// Selected image count.
pub image_count: u32,
}
/// Swapchain planning error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanSwapchainError {
/// No surface format was available.
MissingSurfaceFormat,
/// No present mode was available.
MissingPresentMode,
/// Requested or current extent is empty.
EmptyExtent,
}
impl std::fmt::Display for VulkanSwapchainError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::MissingSurfaceFormat => write!(f, "Vulkan swapchain has no surface format"),
Self::MissingPresentMode => write!(f, "Vulkan swapchain has no present mode"),
Self::EmptyExtent => write!(f, "Vulkan swapchain extent must be non-zero"),
}
}
}
impl std::error::Error for VulkanSwapchainError {}
/// Swapchain recreation reason.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum VulkanSwapchainRecreationReason {
/// Drawable extent changed.
Resize,
/// Vulkan reported `VK_ERROR_OUT_OF_DATE_KHR`.
OutOfDate,
/// Vulkan reported `VK_SUBOPTIMAL_KHR`.
Suboptimal,
}
/// Deterministic swapchain recreation report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanSwapchainRecreationReport {
/// Report schema version.
pub schema: u32,
/// Recreation reason.
pub reason: VulkanSwapchainRecreationReason,
/// Previous extent.
pub previous_extent: (u32, u32),
/// Next extent.
pub next_extent: (u32, u32),
}
/// Deterministic frame submission plan for command buffers and sync objects.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanFrameSubmissionPlan {
/// Report schema version.
pub schema: u32,
/// Frames allowed in flight.
pub frames_in_flight: u32,
/// Swapchain-backed primary command buffers.
pub command_buffers: u32,
/// Binary semaphores allocated per frame.
pub semaphores_per_frame: u32,
/// Fences allocated per frame.
pub fences_per_frame: u32,
/// Draw commands encoded into the frame.
pub draw_count: u32,
/// Total indexed vertices submitted by draw commands.
pub indexed_vertex_count: u32,
}
/// Synthetic physical-device capabilities used by negative tests and reports.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanPhysicalDeviceRecord {
/// Human-readable device name.
pub name: String,
/// Reported Vulkan API version.
pub api_version: u32,
/// Device class.
pub device_type: VulkanDeviceType,
/// Supported device-extension names.
pub extensions: Vec<String>,
/// Queue-family capabilities.
pub queue_families: Vec<VulkanQueueFamily>,
/// Surface formats accepted by the target surface.
pub surface_formats: Vec<VulkanSurfaceFormat>,
}
impl VulkanPhysicalDeviceRecord {
/// Returns whether the device supports an extension name.
#[must_use]
pub fn supports_extension(&self, extension: &str) -> bool {
self.extensions
.iter()
.any(|candidate| candidate == extension)
}
}
/// Selected device and queue capability report.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct VulkanCapabilityReport {
/// Report schema version.
pub schema: u32,
/// Selected device name.
pub device_name: String,
/// Selected Vulkan API version.
pub vulkan_api_version: u32,
/// Deterministic score used for device selection.
pub score: i32,
/// Graphics queue family index.
pub graphics_queue_family: u32,
/// Present queue family index.
pub present_queue_family: u32,
/// Whether portability subset is enabled for the selected device.
pub portability_subset: bool,
/// Enabled device extensions.
pub enabled_extensions: Vec<String>,
}
/// Vulkan capability selection error.
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum VulkanCapabilityError {
/// No physical devices were available.
NoPhysicalDevice,
/// Device API version is lower than the Stage 0 minimum.
ApiVersionTooLow {
/// Required Vulkan API version.
required: u32,
/// Reported Vulkan API version.
found: u32,
},
/// Required graphics queue is unavailable.
NoGraphicsQueue {
/// Device name that failed validation.
device: String,
},
/// Required present queue is unavailable.
NoPresentQueue {
/// Device name that failed validation.
device: String,
},
/// Swapchain device extension is unavailable.
MissingSwapchainExtension {
/// Device name that failed validation.
device: String,
},
/// No compatible surface format exists.
MissingSurfaceFormat {
/// Device name that failed validation.
device: String,
},
}
impl std::fmt::Display for VulkanCapabilityError {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::NoPhysicalDevice => write!(f, "no Vulkan physical device available"),
Self::ApiVersionTooLow { required, found } => write!(
f,
"Vulkan API version too low: required {}, found {}",
format_api_version(*required),
format_api_version(*found)
),
Self::NoGraphicsQueue { device } => {
write!(f, "Vulkan device {device} has no graphics queue")
}
Self::NoPresentQueue { device } => {
write!(f, "Vulkan device {device} has no present queue")
}
Self::MissingSwapchainExtension { device } => {
write!(f, "Vulkan device {device} lacks {KHR_SWAPCHAIN_EXTENSION}")
}
Self::MissingSurfaceFormat { device } => {
write!(f, "Vulkan device {device} has no compatible surface format")
}
}
}
}
impl std::error::Error for VulkanCapabilityError {}
/// Selects a Vulkan physical device using deterministic Stage 0 policy.
///
/// # Errors
///
/// Returns [`VulkanCapabilityError`] when no candidate satisfies the minimum
/// API version, queue, swapchain-extension and surface-format requirements.
pub fn select_physical_device(
devices: &[VulkanPhysicalDeviceRecord],
) -> Result<VulkanCapabilityReport, VulkanCapabilityError> {
if devices.is_empty() {
return Err(VulkanCapabilityError::NoPhysicalDevice);
}
let mut best = None;
let mut last_error = None;
for device in devices {
let report = match validate_device(device) {
Ok(report) => report,
Err(err) => {
last_error = Some(err);
continue;
}
};
match &best {
Some(existing) if compare_reports(&report, existing) != std::cmp::Ordering::Greater => {
}
_ => best = Some(report),
}
}
best.ok_or_else(|| last_error.unwrap_or(VulkanCapabilityError::NoPhysicalDevice))
}
/// Builds a deterministic swapchain plan from surface capabilities.
///
/// # Errors
///
/// Returns [`VulkanSwapchainError`] when formats, present modes or extent are
/// unusable.
pub fn plan_vulkan_swapchain(
request: &VulkanSwapchainRequest,
) -> Result<VulkanSwapchainPlan, VulkanSwapchainError> {
let format = select_surface_format(&request.formats)?;
let present_mode = select_present_mode(&request.present_modes, request.preferred_present_mode)?;
let extent = select_swapchain_extent(request)?;
if extent.0 == 0 || extent.1 == 0 {
return Err(VulkanSwapchainError::EmptyExtent);
}
Ok(VulkanSwapchainPlan {
schema: 1,
extent,
format,
present_mode,
image_count: select_image_count(request.capabilities),
})
}
fn select_surface_format(
formats: &[VulkanSurfaceFormat],
) -> Result<VulkanSurfaceFormat, VulkanSwapchainError> {
formats
.iter()
.copied()
.find(|format| {
format.format == vk::Format::B8G8R8A8_SRGB.as_raw()
&& format.color_space == vk::ColorSpaceKHR::SRGB_NONLINEAR.as_raw()
})
.or_else(|| formats.first().copied())
.ok_or(VulkanSwapchainError::MissingSurfaceFormat)
}
fn select_present_mode(present_modes: &[i32], preferred: i32) -> Result<i32, VulkanSwapchainError> {
if present_modes.contains(&preferred) {
Ok(preferred)
} else if present_modes.contains(&vk::PresentModeKHR::FIFO.as_raw()) {
Ok(vk::PresentModeKHR::FIFO.as_raw())
} else {
present_modes
.first()
.copied()
.ok_or(VulkanSwapchainError::MissingPresentMode)
}
}
fn select_swapchain_extent(
request: &VulkanSwapchainRequest,
) -> Result<(u32, u32), VulkanSwapchainError> {
if let Some(extent) = request.capabilities.current_extent {
return if extent.0 == 0 || extent.1 == 0 {
Err(VulkanSwapchainError::EmptyExtent)
} else {
Ok(extent)
};
}
let width = request.drawable_extent.0.clamp(
request.capabilities.min_extent.0,
request.capabilities.max_extent.0,
);
let height = request.drawable_extent.1.clamp(
request.capabilities.min_extent.1,
request.capabilities.max_extent.1,
);
Ok((width, height))
}
fn select_image_count(capabilities: VulkanSwapchainSurfaceCapabilities) -> u32 {
let requested = capabilities.min_image_count.saturating_add(1).max(2);
if capabilities.max_image_count == 0 {
requested
} else {
requested.min(capabilities.max_image_count)
}
}
fn select_composite_alpha(supported: vk::CompositeAlphaFlagsKHR) -> vk::CompositeAlphaFlagsKHR {
if supported.contains(vk::CompositeAlphaFlagsKHR::OPAQUE) {
vk::CompositeAlphaFlagsKHR::OPAQUE
} else if supported.contains(vk::CompositeAlphaFlagsKHR::PRE_MULTIPLIED) {
vk::CompositeAlphaFlagsKHR::PRE_MULTIPLIED
} else if supported.contains(vk::CompositeAlphaFlagsKHR::POST_MULTIPLIED) {
vk::CompositeAlphaFlagsKHR::POST_MULTIPLIED
} else {
vk::CompositeAlphaFlagsKHR::INHERIT
}
}
/// Builds a deterministic swapchain recreation report.
#[must_use]
pub const fn swapchain_recreation_report(
reason: VulkanSwapchainRecreationReason,
previous_extent: (u32, u32),
next_extent: (u32, u32),
) -> VulkanSwapchainRecreationReport {
VulkanSwapchainRecreationReport {
schema: 1,
reason,
previous_extent,
next_extent,
}
}
/// Builds a deterministic frame submission plan for a validated command list.
///
/// Stage 0 keeps this as a pure planning boundary so command-pool, command-buffer
/// and synchronization policy can be tested without requiring a native surface.
///
/// # Errors
///
/// Returns [`RenderError`] when the command list has invalid frame framing,
/// ordering, draw ranges, mesh bounds, or non-finite transforms.
pub fn plan_vulkan_frame_submission(
swapchain: &VulkanSwapchainPlan,
commands: &RenderCommandList,
) -> Result<VulkanFrameSubmissionPlan, RenderError> {
validate_command_list(commands)?;
let mut draw_count = 0_u32;
let mut indexed_vertex_count = 0_u32;
for command in &commands.commands {
if let RenderCommand::Draw(draw) = command {
draw_count = draw_count.saturating_add(1);
indexed_vertex_count = indexed_vertex_count.saturating_add(draw.range.count);
}
}
Ok(VulkanFrameSubmissionPlan {
schema: 1,
frames_in_flight: swapchain.image_count.clamp(1, 2),
command_buffers: swapchain.image_count,
semaphores_per_frame: 2,
fences_per_frame: 1,
draw_count,
indexed_vertex_count,
})
}
fn validate_device(
device: &VulkanPhysicalDeviceRecord,
) -> Result<VulkanCapabilityReport, VulkanCapabilityError> {
if device.api_version < MIN_VULKAN_API_VERSION {
return Err(VulkanCapabilityError::ApiVersionTooLow {
required: MIN_VULKAN_API_VERSION,
found: device.api_version,
});
}
if !device.supports_extension(KHR_SWAPCHAIN_EXTENSION) {
return Err(VulkanCapabilityError::MissingSwapchainExtension {
device: device.name.clone(),
});
}
if device.surface_formats.is_empty() {
return Err(VulkanCapabilityError::MissingSurfaceFormat {
device: device.name.clone(),
});
}
let (graphics_queue_family, present_queue_family) = select_queue_families(device)?;
let portability_subset = device.supports_extension(KHR_PORTABILITY_SUBSET_EXTENSION);
let mut enabled_extensions = vec![KHR_SWAPCHAIN_EXTENSION.to_string()];
if portability_subset {
enabled_extensions.push(KHR_PORTABILITY_SUBSET_EXTENSION.to_string());
}
Ok(VulkanCapabilityReport {
schema: 1,
device_name: device.name.clone(),
vulkan_api_version: device.api_version,
score: score_device(device, graphics_queue_family, present_queue_family),
graphics_queue_family,
present_queue_family,
portability_subset,
enabled_extensions,
})
}
fn select_queue_families(
device: &VulkanPhysicalDeviceRecord,
) -> Result<(u32, u32), VulkanCapabilityError> {
if let Some(unified) = device
.queue_families
.iter()
.find(|family| family.graphics && family.present)
{
return Ok((unified.index, unified.index));
}
let graphics_queue_family = device
.queue_families
.iter()
.find(|family| family.graphics)
.ok_or_else(|| VulkanCapabilityError::NoGraphicsQueue {
device: device.name.clone(),
})?
.index;
let present_queue_family = device
.queue_families
.iter()
.find(|family| family.present)
.ok_or_else(|| VulkanCapabilityError::NoPresentQueue {
device: device.name.clone(),
})?
.index;
Ok((graphics_queue_family, present_queue_family))
}
fn score_device(
device: &VulkanPhysicalDeviceRecord,
graphics_queue_family: u32,
present_queue_family: u32,
) -> i32 {
let unified_queue_bonus = if graphics_queue_family == present_queue_family {
100
} else {
0
};
let portability_penalty = if device.supports_extension(KHR_PORTABILITY_SUBSET_EXTENSION) {
-50
} else {
0
};
device.device_type.score_bonus()
+ unified_queue_bonus
+ portability_penalty
+ i32::try_from(device.surface_formats.len()).unwrap_or(i32::MAX)
}
fn compare_reports(
left: &VulkanCapabilityReport,
right: &VulkanCapabilityReport,
) -> std::cmp::Ordering {
left.score
.cmp(&right.score)
.then_with(|| right.device_name.cmp(&left.device_name))
}
/// Renders a deterministic JSON capability report.
#[must_use]
pub fn render_capability_report_json(report: &VulkanCapabilityReport) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&report.schema.to_string());
out.push_str(",\"vulkan_api\":\"");
out.push_str(&format_api_version(report.vulkan_api_version));
out.push_str("\",\"device_name\":");
push_json_string(&mut out, &report.device_name);
out.push_str(",\"score\":");
out.push_str(&report.score.to_string());
out.push_str(",\"graphics_queue_family\":");
out.push_str(&report.graphics_queue_family.to_string());
out.push_str(",\"present_queue_family\":");
out.push_str(&report.present_queue_family.to_string());
out.push_str(",\"portability_subset\":");
out.push_str(if report.portability_subset {
"true"
} else {
"false"
});
out.push_str(",\"enabled_extensions\":[");
for (index, extension) in report.enabled_extensions.iter().enumerate() {
if index > 0 {
out.push(',');
}
push_json_string(&mut out, extension);
}
out.push_str("]}");
out
}
/// Renders a deterministic JSON swapchain plan.
#[must_use]
pub fn render_swapchain_plan_json(plan: &VulkanSwapchainPlan) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&plan.schema.to_string());
out.push_str(",\"extent\":[");
out.push_str(&plan.extent.0.to_string());
out.push(',');
out.push_str(&plan.extent.1.to_string());
out.push_str("],\"format\":");
out.push_str(&plan.format.format.to_string());
out.push_str(",\"color_space\":");
out.push_str(&plan.format.color_space.to_string());
out.push_str(",\"present_mode\":");
out.push_str(&plan.present_mode.to_string());
out.push_str(",\"image_count\":");
out.push_str(&plan.image_count.to_string());
out.push('}');
out
}
/// Renders a deterministic JSON swapchain recreation report.
#[must_use]
pub fn render_swapchain_recreation_report_json(report: &VulkanSwapchainRecreationReport) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&report.schema.to_string());
out.push_str(",\"reason\":\"");
out.push_str(match report.reason {
VulkanSwapchainRecreationReason::Resize => "resize",
VulkanSwapchainRecreationReason::OutOfDate => "out_of_date",
VulkanSwapchainRecreationReason::Suboptimal => "suboptimal",
});
out.push_str("\",\"previous_extent\":[");
out.push_str(&report.previous_extent.0.to_string());
out.push(',');
out.push_str(&report.previous_extent.1.to_string());
out.push_str("],\"next_extent\":[");
out.push_str(&report.next_extent.0.to_string());
out.push(',');
out.push_str(&report.next_extent.1.to_string());
out.push_str("]}");
out
}
/// Renders a deterministic JSON frame submission plan.
#[must_use]
pub fn render_frame_submission_plan_json(plan: &VulkanFrameSubmissionPlan) -> String {
let mut out = String::new();
out.push_str("{\"schema\":");
out.push_str(&plan.schema.to_string());
out.push_str(",\"frames_in_flight\":");
out.push_str(&plan.frames_in_flight.to_string());
out.push_str(",\"command_buffers\":");
out.push_str(&plan.command_buffers.to_string());
out.push_str(",\"semaphores_per_frame\":");
out.push_str(&plan.semaphores_per_frame.to_string());
out.push_str(",\"fences_per_frame\":");
out.push_str(&plan.fences_per_frame.to_string());
out.push_str(",\"draw_count\":");
out.push_str(&plan.draw_count.to_string());
out.push_str(",\"indexed_vertex_count\":");
out.push_str(&plan.indexed_vertex_count.to_string());
out.push('}');
out
}
fn format_api_version(version: u32) -> String {
format!(
"{}.{}.{}",
vk::api_version_major(version),
vk::api_version_minor(version),
vk::api_version_patch(version)
)
}
fn push_json_string(out: &mut String, value: &str) {
out.push('"');
for ch in value.chars() {
match ch {
'"' => out.push_str("\\\""),
'\\' => out.push_str("\\\\"),
'\n' => out.push_str("\\n"),
'\r' => out.push_str("\\r"),
'\t' => out.push_str("\\t"),
c if c.is_control() => {
use std::fmt::Write as _;
let _ = write!(out, "\\u{:04x}", c as u32);
}
c => out.push(c),
}
}
out.push('"');
}
/// Diagnostics for Vulkan planning backend setup and frame progression.
#[derive(Clone, Debug, PartialEq)]
pub struct VulkanPlanningBackendReport {
/// Unix time at initialization.
pub initialized_at: u64,
/// Total frames executed.
pub frames_executed: u64,
/// Total command submissions.
pub submissions: u64,
/// Last command-capture byte size.
pub last_capture_size: usize,
/// Number of simulated present calls.
pub presents: u64,
/// Number of resize-driven surface plan refreshes.
pub resize_rebuilds: u64,
/// Last render request observed.
pub request: RenderRequest,
/// Last deterministic frame submission plan.
pub last_frame_submission: Option<VulkanFrameSubmissionPlan>,
}
impl Default for VulkanPlanningBackendReport {
fn default() -> Self {
Self {
initialized_at: SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_or(0, |duration| duration.as_secs()),
frames_executed: 0,
submissions: 0,
last_capture_size: 0,
presents: 0,
resize_rebuilds: 0,
request: RenderRequest::conservative(),
last_frame_submission: None,
}
}
}
/// Vulkan planning backend façade used by the game entrypoint.
#[derive(Debug)]
pub struct VulkanPlanningBackend {
state: VulkanBackendState,
report: VulkanPlanningBackendReport,
swapchain_plan: VulkanSwapchainPlan,
}
impl Default for VulkanPlanningBackend {
fn default() -> Self {
Self::new()
}
}
impl VulkanPlanningBackend {
/// Creates a new Vulkan planning backend façade.
#[must_use]
pub fn new() -> Self {
Self {
state: VulkanBackendState::Ready,
report: VulkanPlanningBackendReport::default(),
swapchain_plan: default_stage0_swapchain_plan(),
}
}
/// Replaces active surface/profile request.
pub fn set_render_request(&mut self, request: RenderRequest) {
self.report.request = request;
self.report.resize_rebuilds = self.report.resize_rebuilds.saturating_add(1);
}
/// Returns active render request policy.
#[must_use]
pub const fn render_request(&self) -> RenderRequest {
self.report.request
}
/// Replaces active swapchain plan used for frame submission planning.
pub fn set_swapchain_plan(&mut self, plan: VulkanSwapchainPlan) {
self.swapchain_plan = plan;
}
/// Returns active swapchain plan.
#[must_use]
pub const fn swapchain_plan(&self) -> &VulkanSwapchainPlan {
&self.swapchain_plan
}
/// Returns adapter state.
#[must_use]
pub const fn state(&self) -> VulkanBackendState {
self.state
}
/// Returns backend report.
#[must_use]
pub fn report(&self) -> &VulkanPlanningBackendReport {
&self.report
}
fn simulate_present(&mut self) {
self.report.presents = self.report.presents.saturating_add(1);
}
}
impl RenderBackend for VulkanPlanningBackend {
fn execute(&mut self, commands: &RenderCommandList) -> Result<FrameOutput, RenderError> {
if !matches!(
self.state,
VulkanBackendState::Ready | VulkanBackendState::Degraded
) {
return Err(RenderError::InvalidRange);
}
let capture = canonical_capture(commands)?;
let frame_plan = plan_vulkan_frame_submission(&self.swapchain_plan, commands)?;
self.report.frames_executed = self.report.frames_executed.saturating_add(1);
self.report.submissions = self.report.submissions.saturating_add(1);
self.report.last_capture_size = capture.len();
self.report.last_frame_submission = Some(frame_plan);
self.simulate_present();
Ok(FrameOutput)
}
}
fn default_stage0_swapchain_plan() -> VulkanSwapchainPlan {
VulkanSwapchainPlan {
schema: 1,
extent: (1, 1),
format: VulkanSurfaceFormat {
format: vk::Format::B8G8R8A8_SRGB.as_raw(),
color_space: vk::ColorSpaceKHR::SRGB_NONLINEAR.as_raw(),
},
present_mode: vk::PresentModeKHR::FIFO.as_raw(),
image_count: 2,
}
}
#[cfg(test)]
mod tests {
use super::*;
use fparkan_render::{
DrawCommand, DrawId, GpuMaterialId, GpuMeshId, IndexRange, RenderCommand, RenderPhase,
};
#[test]
fn backend_tracks_render_request_and_presents() -> Result<(), RenderError> {
let mut backend = VulkanPlanningBackend::new();
let request = RenderRequest::conservative();
backend.set_render_request(request);
assert_eq!(backend.render_request(), request);
assert_eq!(backend.report().resize_rebuilds, 1);
let commands = fparkan_render::RenderCommandList {
commands: vec![
RenderCommand::BeginFrame,
RenderCommand::Draw(DrawCommand {
id: DrawId(11),
phase: RenderPhase::Opaque,
object_id: None,
mesh: GpuMeshId(1),
material: GpuMaterialId(2),
transform: [1.0; 16],
range: IndexRange { start: 0, count: 3 },
stable_order: 7,
}),
RenderCommand::EndFrame,
],
};
backend.execute(&commands)?;
assert_eq!(backend.state(), VulkanBackendState::Ready);
assert_eq!(backend.report().frames_executed, 1);
assert_eq!(backend.report().submissions, 1);
assert_eq!(backend.report().presents, 1);
assert!(backend.report().last_capture_size > 0);
assert_eq!(
backend.report().last_frame_submission,
Some(VulkanFrameSubmissionPlan {
schema: 1,
frames_in_flight: 2,
command_buffers: 2,
semaphores_per_frame: 2,
fences_per_frame: 1,
draw_count: 1,
indexed_vertex_count: 3,
})
);
Ok(())
}
#[test]
fn frame_submission_plan_json_is_stable() -> Result<(), RenderError> {
let commands = fparkan_render::RenderCommandList {
commands: vec![
RenderCommand::BeginFrame,
RenderCommand::Draw(DrawCommand {
id: DrawId(11),
phase: RenderPhase::Opaque,
object_id: None,
mesh: GpuMeshId(1),
material: GpuMaterialId(2),
transform: [1.0; 16],
range: IndexRange { start: 0, count: 3 },
stable_order: 7,
}),
RenderCommand::EndFrame,
],
};
let swapchain = VulkanSwapchainPlan {
image_count: 3,
..default_stage0_swapchain_plan()
};
let plan = plan_vulkan_frame_submission(&swapchain, &commands)?;
assert_eq!(plan.frames_in_flight, 2);
assert_eq!(plan.command_buffers, 3);
assert_eq!(plan.draw_count, 1);
assert_eq!(plan.indexed_vertex_count, 3);
assert_eq!(
render_frame_submission_plan_json(&plan),
"{\"schema\":1,\"frames_in_flight\":2,\"command_buffers\":3,\"semaphores_per_frame\":2,\"fences_per_frame\":1,\"draw_count\":1,\"indexed_vertex_count\":3}"
);
Ok(())
}
#[test]
fn device_scoring_is_deterministic_and_prefers_discrete_unified_queue() {
let devices = vec![
device("SwiftShader", VulkanDeviceType::Cpu, 0, true, false),
device("Discrete", VulkanDeviceType::DiscreteGpu, 1, true, false),
device(
"Integrated",
VulkanDeviceType::IntegratedGpu,
2,
true,
false,
),
];
let report = select_physical_device(&devices).expect("selected device");
assert_eq!(report.device_name, "Discrete");
assert_eq!(report.graphics_queue_family, 1);
assert_eq!(report.present_queue_family, 1);
assert!(!report.portability_subset);
assert_eq!(report.enabled_extensions, vec![KHR_SWAPCHAIN_EXTENSION]);
}
#[test]
fn portability_subset_is_reported_and_enabled_when_exposed() {
let report = select_physical_device(&[device(
"MoltenVK",
VulkanDeviceType::IntegratedGpu,
0,
true,
true,
)])
.expect("selected device");
assert!(report.portability_subset);
assert_eq!(
report.enabled_extensions,
vec![
KHR_SWAPCHAIN_EXTENSION.to_string(),
KHR_PORTABILITY_SUBSET_EXTENSION.to_string()
]
);
}
#[test]
fn missing_loader_candidates_are_reported() {
assert_eq!(
select_physical_device(&[]),
Err(VulkanCapabilityError::NoPhysicalDevice)
);
}
#[test]
fn rejects_low_api_version() {
let mut candidate = device("Old GPU", VulkanDeviceType::DiscreteGpu, 0, true, false);
candidate.api_version = vk::API_VERSION_1_0;
assert!(matches!(
select_physical_device(&[candidate]),
Err(VulkanCapabilityError::ApiVersionTooLow { .. })
));
}
#[test]
fn rejects_missing_graphics_present_swapchain_and_format() {
let mut no_graphics = device("No graphics", VulkanDeviceType::DiscreteGpu, 0, true, false);
no_graphics.queue_families[0].graphics = false;
assert!(matches!(
select_physical_device(&[no_graphics]),
Err(VulkanCapabilityError::NoGraphicsQueue { .. })
));
let mut no_present = device("No present", VulkanDeviceType::DiscreteGpu, 0, true, false);
no_present.queue_families[0].present = false;
assert!(matches!(
select_physical_device(&[no_present]),
Err(VulkanCapabilityError::NoPresentQueue { .. })
));
let no_swapchain = device(
"No swapchain",
VulkanDeviceType::DiscreteGpu,
0,
false,
false,
);
assert!(matches!(
select_physical_device(&[no_swapchain]),
Err(VulkanCapabilityError::MissingSwapchainExtension { .. })
));
let mut no_format = device("No format", VulkanDeviceType::DiscreteGpu, 0, true, false);
no_format.surface_formats.clear();
assert!(matches!(
select_physical_device(&[no_format]),
Err(VulkanCapabilityError::MissingSurfaceFormat { .. })
));
}
#[test]
fn capability_report_json_is_stable() {
let report = select_physical_device(&[device(
"GPU \"A\"",
VulkanDeviceType::DiscreteGpu,
3,
true,
false,
)])
.expect("selected device");
assert_eq!(
render_capability_report_json(&report),
"{\"schema\":1,\"vulkan_api\":\"1.1.0\",\"device_name\":\"GPU \\\"A\\\"\",\"score\":1101,\"graphics_queue_family\":3,\"present_queue_family\":3,\"portability_subset\":false,\"enabled_extensions\":[\"VK_KHR_swapchain\"]}"
);
}
#[test]
fn loader_probe_report_json_is_stable() {
assert_eq!(
vulkan_entry_symbol_name().to_bytes(),
b"vkGetInstanceProcAddr"
);
assert_eq!(
render_loader_probe_report_json(&VulkanLoaderProbeReport {
schema: 1,
loader_available: true,
instance_api_version: vk::API_VERSION_1_2,
}),
"{\"schema\":1,\"loader_available\":true,\"instance_api\":\"1.2.0\"}"
);
}
#[test]
fn loader_error_display_is_actionable() {
assert_eq!(
VulkanLoaderError::Unavailable {
message: "dlopen failed".to_string(),
}
.to_string(),
"Vulkan loader is unavailable: dlopen failed"
);
}
#[test]
fn instance_plan_is_sorted_deduplicated_and_portability_aware() {
let plan = plan_vulkan_instance(&VulkanInstanceConfig {
application_name: "FParkan".to_string(),
required_extensions: vec![
"VK_KHR_surface".to_string(),
KHR_PORTABILITY_ENUMERATION_EXTENSION.to_string(),
"VK_KHR_surface".to_string(),
],
enable_portability_enumeration: true,
enable_validation: true,
});
assert_eq!(
render_instance_plan_json(&plan),
"{\"schema\":1,\"create_flags\":1,\"validation_requested\":true,\"enabled_extensions\":[\"VK_EXT_debug_utils\",\"VK_KHR_portability_enumeration\",\"VK_KHR_surface\"]}"
);
}
#[test]
fn instance_plan_adds_portability_extension_when_requested() {
let plan = plan_vulkan_instance(&VulkanInstanceConfig {
application_name: "FParkan".to_string(),
required_extensions: vec!["VK_KHR_surface".to_string()],
enable_portability_enumeration: true,
enable_validation: false,
});
assert_eq!(
plan.enabled_extensions,
vec![
KHR_PORTABILITY_ENUMERATION_EXTENSION.to_string(),
"VK_KHR_surface".to_string()
]
);
assert_eq!(plan.create_flags, 1);
}
#[test]
fn invalid_instance_extension_name_is_reported_before_loader_use() {
assert_eq!(
cstring_vec(&["bad\0extension".to_string()]),
Err(VulkanInstanceError::InvalidExtensionName {
extension: "bad\0extension".to_string()
})
);
}
#[test]
fn surface_plan_requires_native_handles() {
assert_eq!(
plan_vulkan_surface(None),
Err(VulkanSurfaceError::MissingNativeHandles)
);
assert_eq!(
VulkanSurfaceError::MissingNativeHandles.to_string(),
"native window/display handles are required for Vulkan surface creation"
);
}
#[test]
fn surface_plan_json_is_stable() {
assert_eq!(
render_surface_plan_json(&VulkanSurfacePlan {
schema: 1,
required_instance_extensions: vec![
"VK_KHR_surface".to_string(),
"VK_EXT_metal_surface".to_string(),
],
}),
"{\"schema\":1,\"required_instance_extensions\":[\"VK_KHR_surface\",\"VK_EXT_metal_surface\"]}"
);
}
#[test]
fn static_surface_extension_name_is_decoded() {
let name = extension_name(ash::khr::surface::NAME.as_ptr()).expect("extension name");
assert_eq!(name, "VK_KHR_surface");
}
#[test]
fn swapchain_plan_prefers_srgb_mailbox_and_clamps_extent() {
let plan = plan_vulkan_swapchain(&swapchain_request()).expect("swapchain plan");
assert_eq!(
plan.format,
VulkanSurfaceFormat {
format: vk::Format::B8G8R8A8_SRGB.as_raw(),
color_space: vk::ColorSpaceKHR::SRGB_NONLINEAR.as_raw(),
}
);
assert_eq!(plan.present_mode, vk::PresentModeKHR::MAILBOX.as_raw());
assert_eq!(plan.extent, (1024, 720));
assert_eq!(plan.image_count, 3);
}
#[test]
fn swapchain_plan_uses_fifo_and_current_extent_fallbacks() {
let mut request = swapchain_request();
request.preferred_present_mode = vk::PresentModeKHR::IMMEDIATE.as_raw();
request.present_modes = vec![vk::PresentModeKHR::FIFO.as_raw()];
request.capabilities.current_extent = Some((800, 600));
let plan = plan_vulkan_swapchain(&request).expect("swapchain plan");
assert_eq!(plan.present_mode, vk::PresentModeKHR::FIFO.as_raw());
assert_eq!(plan.extent, (800, 600));
}
#[test]
fn swapchain_plan_rejects_missing_surface_data_and_empty_extent() {
let mut request = swapchain_request();
request.formats.clear();
assert_eq!(
plan_vulkan_swapchain(&request),
Err(VulkanSwapchainError::MissingSurfaceFormat)
);
let mut request = swapchain_request();
request.present_modes.clear();
assert_eq!(
plan_vulkan_swapchain(&request),
Err(VulkanSwapchainError::MissingPresentMode)
);
let mut request = swapchain_request();
request.capabilities.current_extent = Some((0, 600));
assert_eq!(
plan_vulkan_swapchain(&request),
Err(VulkanSwapchainError::EmptyExtent)
);
}
#[test]
fn swapchain_plan_json_and_recreation_reports_are_stable() {
let plan = plan_vulkan_swapchain(&swapchain_request()).expect("swapchain plan");
assert_eq!(
render_swapchain_plan_json(&plan),
"{\"schema\":1,\"extent\":[1024,720],\"format\":50,\"color_space\":0,\"present_mode\":1,\"image_count\":3}"
);
let report = swapchain_recreation_report(
VulkanSwapchainRecreationReason::OutOfDate,
(1024, 720),
(1280, 720),
);
assert_eq!(
render_swapchain_recreation_report_json(&report),
"{\"schema\":1,\"reason\":\"out_of_date\",\"previous_extent\":[1024,720],\"next_extent\":[1280,720]}"
);
}
#[test]
fn triangle_shader_manifest_hashes_are_stable() {
let report =
validate_shader_manifest(&triangle_shader_manifest()).expect("shader manifest");
assert_eq!(report.modules.len(), 2);
assert_eq!(report.modules[0].name, "triangle.vert");
assert_eq!(report.modules[0].stage, VulkanShaderStage::Vertex);
assert_eq!(report.modules[0].word_count, 253);
assert_eq!(
report.modules[0].sha256,
"9023b1cc856c98ecd21755596c4e9d1e62cc63e1787f8c43ada2101544e8d0d1"
);
assert_eq!(
report.modules[1].sha256,
"6efe2c9716ae845c471ecbaac2c83e56a17a37dc017dd63f0a05f0d9161f44ba"
);
assert_eq!(
report.manifest_hash,
"849ffae9681f5ff2fc145d7b98f19f69b478d9ea73207efdf5f1748e8d51045c"
);
}
#[test]
fn shader_manifest_report_json_is_stable() {
let report =
validate_shader_manifest(&triangle_shader_manifest()).expect("shader manifest");
assert!(render_shader_manifest_report_json(&report).contains(SHADER_COMPILER_ID));
assert!(render_shader_manifest_report_json(&report).contains(SPIRV_VALIDATOR_ID));
}
#[test]
fn shader_manifest_rejects_invalid_spirv_containers() {
let mut module = triangle_shader_manifest().remove(0);
module.words = &[0xFFFF_FFFF, SPIRV_VERSION_1_0, 0, 1, 0];
assert_eq!(
validate_shader_manifest(&[module]),
Err(VulkanShaderManifestError::InvalidMagic {
name: "triangle.vert",
found: 0xFFFF_FFFF,
})
);
let mut module = triangle_shader_manifest().remove(0);
module.words = &[SPIRV_MAGIC, 0, 0, 1, 0];
assert_eq!(
validate_shader_manifest(&[module]),
Err(VulkanShaderManifestError::UnsupportedVersion {
name: "triangle.vert",
found: 0,
})
);
let mut module = triangle_shader_manifest().remove(0);
module.words = &[SPIRV_MAGIC, SPIRV_VERSION_1_0, 0, 0, 0];
assert_eq!(
validate_shader_manifest(&[module]),
Err(VulkanShaderManifestError::InvalidBound {
name: "triangle.vert",
})
);
}
fn device(
name: &str,
device_type: VulkanDeviceType,
queue_index: u32,
swapchain: bool,
portability_subset: bool,
) -> VulkanPhysicalDeviceRecord {
let mut extensions = Vec::new();
if swapchain {
extensions.push(KHR_SWAPCHAIN_EXTENSION.to_string());
}
if portability_subset {
extensions.push(KHR_PORTABILITY_SUBSET_EXTENSION.to_string());
}
VulkanPhysicalDeviceRecord {
name: name.to_string(),
api_version: MIN_VULKAN_API_VERSION,
device_type,
extensions,
queue_families: vec![VulkanQueueFamily {
index: queue_index,
graphics: true,
present: true,
}],
surface_formats: vec![VulkanSurfaceFormat {
format: vk::Format::B8G8R8A8_SRGB.as_raw(),
color_space: vk::ColorSpaceKHR::SRGB_NONLINEAR.as_raw(),
}],
}
}
fn swapchain_request() -> VulkanSwapchainRequest {
VulkanSwapchainRequest {
drawable_extent: (1280, 720),
formats: vec![
VulkanSurfaceFormat {
format: vk::Format::R8G8B8A8_UNORM.as_raw(),
color_space: vk::ColorSpaceKHR::SRGB_NONLINEAR.as_raw(),
},
VulkanSurfaceFormat {
format: vk::Format::B8G8R8A8_SRGB.as_raw(),
color_space: vk::ColorSpaceKHR::SRGB_NONLINEAR.as_raw(),
},
],
present_modes: vec![
vk::PresentModeKHR::FIFO.as_raw(),
vk::PresentModeKHR::MAILBOX.as_raw(),
],
capabilities: VulkanSwapchainSurfaceCapabilities {
current_extent: None,
min_extent: (320, 240),
max_extent: (1024, 768),
min_image_count: 2,
max_image_count: 3,
},
preferred_present_mode: vk::PresentModeKHR::MAILBOX.as_raw(),
}
}
}
Reference in New Issue View Git Blame Copy Permalink