Vulkane

Vulkan for Rust: complete bindings generated from the official vk.xml specification, plus a safe RAII wrapper that covers compute and graphics end-to-end — from instance creation through shadow mapping and deferred shading.

What is Vulkane?

Vulkane generates complete Vulkan API bindings from vk.xml, the official machine-readable specification maintained by Khronos. Every type, constant, struct, enum, function pointer, and dispatch table is derived at build time. Nothing is hardcoded.

To target a different Vulkan version, swap vk.xml and rebuild.

Vulkane exposes Vulkan through two complementary APIs:

• vulkane::raw — direct FFI bindings, exactly as the spec defines them. Maximum control, zero overhead.

• vulkane::safe — RAII wrappers with automatic cleanup, Result-based error handling, typed flags, and convenience helpers. Covers compute and graphics:

  • Instance / Device — Instance, PhysicalDevice, PhysicalDeviceGroup, Device, Queue, DeviceFeatures builder (1.0 / 1.1 / 1.2 / 1.3 features).
  • Memory — Buffer, Image, ImageView, Sampler, DeviceMemory, plus a VMA-style sub-allocator (Allocator) with TLSF + linear pools, custom pools, dedicated allocations, persistent mapping, defragmentation, and budget queries.
  • Convenience helpers — Buffer::new_bound, Image::new_2d_bound, Queue::upload_buffer<T>, Queue::upload_image_rgba, Queue::one_shot — collapse the 5-step allocate-bind pattern into one call.
  • Compute — ComputePipeline, PipelineLayout, DescriptorSet, ShaderModule, specialization constants, pipeline cache, push constants.
  • Graphics — RenderPass (with simple_color shortcut), Framebuffer, GraphicsPipelineBuilder (depth bias, CompareOp, InputRate, multi-attachment blend, dynamic viewport/scissor), Surface (Win32 / Wayland / Xlib / Xcb / Metal), Swapchain.
  • Synchronization — typed PipelineStage / AccessFlags (plus 64-bit PipelineStage2 / AccessFlags2 for Sync2), Fence, Semaphore (binary + timeline), ImageBarrier::color / ::depth, ClearValue, QueryPool.
  • Derive macros — #[derive(Vertex)] auto-generates vertex input layouts from #[repr(C)] structs (optional derive feature).
  • Extension ergonomics (0.8+) — curated safe wrappers for ray tracing (AccelerationStructure, RayTracingPipeline, cmd_trace_rays), external memory/semaphore interop (DeviceMemory::get_win32_handle / get_fd for CUDA / HIP / DX12 bridging), timeline semaphores, synchronization 2 (memory_barrier2 / image_barrier2 / buffer_barrier2), push descriptors, dynamic rendering (begin_rendering), descriptor buffer, subgroup size control, memory priority, and shader integer dot product properties. Every safe create-info builder now exposes a pnext extension point so any unwrapped extension struct can be layered on without dropping to raw.
  • Generated ergonomic traits (0.8+) — alongside the raw per-command DeviceExt / InstanceExt / CommandBufferRecordingExt traits, the build emits a second tier — DeviceSafeExt, InstanceSafeExt, PhysicalDeviceSafeExt, QueueSafeExt, CommandBufferRecordingSafeExt — with idiomatic signatures (slices for slice-params, Result<Vec<T>> for (count, data) enumerate pairs, references for input structs, return-by-value for single output params). 545 generated ergonomic methods cover ~70% of the extension surface mechanically.
  • Raw escape hatch — Device::dispatch() / Instance::dispatch() expose the full dispatch tables so you can drop to raw Vulkan for anything the safe wrapper doesn't cover yet.

Quick Start

[dependencies]

vulkane = { version = "0.10", features = ["fetch-spec"] }

use vulkane::safe::{
    ApiVersion, Buffer, BufferCreateInfo, BufferUsage, CommandPool,
    DeviceCreateInfo, DeviceMemory, Fence, Instance, InstanceCreateInfo,
    MemoryPropertyFlags, PipelineStage, AccessFlags, QueueCreateInfo,
    QueueFlags,
};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let instance = Instance::new(InstanceCreateInfo {
        application_name: Some("hello-vulkane"),
        api_version: ApiVersion::V1_0,
        ..Default::default()
    })?;

    let physical = instance
        .enumerate_physical_devices()?
        .into_iter()
        .find(|pd| pd.find_queue_family(QueueFlags::TRANSFER).is_some())
        .ok_or("no compatible GPU")?;
    let qf = physical.find_queue_family(QueueFlags::TRANSFER).unwrap();

    let device = physical.create_device(DeviceCreateInfo {
        queue_create_infos: &[QueueCreateInfo::single(qf)],
        ..Default::default()
    })?;
    let queue = device.get_queue(qf, 0);

    // One-call buffer allocation (no manual memory_requirements + find_type + bind).
    let (buffer, mut memory) = Buffer::new_bound(
        &device, &physical,
        BufferCreateInfo { size: 1024, usage: BufferUsage::TRANSFER_DST },
        MemoryPropertyFlags::HOST_VISIBLE | MemoryPropertyFlags::HOST_COHERENT,
    )?;

    // One-shot command recording + submit + wait.
    queue.one_shot(&device, qf, |rec| {
        rec.fill_buffer(&buffer, 0, 1024, 0xDEADBEEF);
        rec.memory_barrier(
            PipelineStage::TRANSFER, PipelineStage::HOST,
            AccessFlags::TRANSFER_WRITE, AccessFlags::HOST_READ,
        );
        Ok(())
    })?;

    let mapped = memory.map()?;
    assert_eq!(&mapped.as_slice()[..4], &0xDEADBEEFu32.to_ne_bytes());
    println!("GPU filled the buffer with 0xDEADBEEF — it works!");
    Ok(())
}

Bundled Examples

15 examples ship with the crate, from basic compute through advanced graphics techniques. All are headless (runnable in CI) except windowed_triangle.

cargo run -p vulkane --features fetch-spec --example headless_triangle

cargo run -p vulkane --features fetch-spec --example shadow_map

cargo run -p vulkane --features fetch-spec,derive --example derive_vertex

#[derive(Vertex)]

Enable the derive feature to auto-generate vertex input layouts:

vulkane = { version = "0.4", features = ["fetch-spec", "derive"] }

use vulkane::Vertex;

#[derive(Vertex, Clone, Copy)]
#[repr(C)]
struct MyVertex {
    position: [f32; 3],  // R32G32B32_SFLOAT, location 0
    normal:   [f32; 3],  // R32G32B32_SFLOAT, location 1
    uv:       [f32; 2],  // R32G32_SFLOAT,    location 2
}

// In pipeline setup:
let bindings = [MyVertex::binding(0)];
let attributes = MyVertex::attributes(0);
builder.vertex_input(&bindings, &attributes)

Strides, offsets, and Vulkan format enums are computed at compile time. Supports f32, [f32; 2..4], u32, [u32; 2..4], i32, [i32; 2..3], [u8; 4], u16, i16. For per-instance data, use MyStruct::instance_binding(n) instead of ::binding(n).

Precompiled shader registry

For applications that ship precompiled .spv artifacts (embedded with include_bytes! or shipped alongside the binary), [vulkane::safe::ShaderRegistry] gives you a small, shared abstraction for looking up shaders by name — plus an optional runtime disk override for shader developers iterating without a full rebuild.

use vulkane::safe::{ShaderRegistry, ShaderSource};

// Embedded at compile time. `include_bytes!` resolves paths relative
// to the file that invokes it, so the macro call lives in your crate.
const EMBEDDED: &[ShaderSource] = &[
    ShaderSource { name: "doubler", spv: include_bytes!("shaders/doubler.spv") },
    ShaderSource { name: "reduce",  spv: include_bytes!("shaders/reduce.spv")  },
];

fn app_shaders() -> ShaderRegistry {
    ShaderRegistry::new()
        .with_embedded(EMBEDDED)
        .with_env_override("MY_APP_SHADER_OVERRIDE_DIR")
}

// Later, when you have a Device:
let module = app_shaders().load_module(&device, "doubler")?;

Lookup order when an override var is configured:

1. $MY_APP_SHADER_OVERRIDE_DIR/doubler.spv on disk (if the directory and file both exist).
2. Fall back to the embedded table.

ShaderRegistry::load(name) returns the SPIR-V bytes, load_words(name) returns a Vec<u32> ready for [ShaderModule::from_spirv], and load_module(&device, name) wraps the whole pipeline. Lookup errors flow through ShaderLoadError into the unified Error::ShaderLoad variant.

Runtime shader compilation

Vulkane offers two optional, independent back-ends for compiling shader source to SPIR-V at runtime. Enable one, the other, or both — they are completely separate modules.

naga — pure Rust (WGSL + subset of GLSL)

Zero external build dependencies. Best choice when:

• You want a pure-Rust build (no CMake, no C++ toolchain).
• You are targeting modern GLSL or WGSL.
• WGSL's combined image-samplers fit your rendering code.

vulkane = { version = "0.4", features = ["naga"] }

use vulkane::safe::naga::compile_glsl;
use naga::ShaderStage;

let spirv = compile_glsl(
    r#"#version 450
       layout(local_size_x = 64) in;
       layout(set = 0, binding = 0, std430) buffer Data { uint v[]; };
       void main() { v[gl_GlobalInvocationID.x] *= 2; }"#,
    ShaderStage::Compute,
)?;
// Pass straight into ShaderModule::from_spirv(&device, &spirv).

shaderc — Khronos glslang (full GLSL + HLSL)

Wraps the Khronos reference compiler. Best choice when:

• You need full GLSL support (#include, GL_* extensions, older core versions, legacy sample shaders).
• You are compiling HLSL for a Vulkan target.
• You want optimization passes (OptimizationLevel::Size or Performance) or explicit macro defines / include resolution.

vulkane = { version = "0.4", features = ["shaderc"] }

use vulkane::safe::shaderc::{compile_glsl, ShaderKind};

let spirv = compile_glsl(
    r#"#version 450
       layout(local_size_x = 64) in;
       void main() {}"#,
    ShaderKind::Compute,
    "doubler.comp",   // virtual file name (used in error messages and #include resolution)
    "main",           // entry-point name
)?;

For fine-grained control — HLSL input, optimization level, macro defines, include callbacks, target Vulkan version — use compile_with_options:

use vulkane::safe::shaderc::{compile_with_options, ShaderKind, SourceLanguage};
use shaderc::OptimizationLevel;

let spirv = compile_with_options(
    hlsl_source,
    ShaderKind::Fragment,
    "shader.hlsl",
    "main",
    |opts| {
        opts.set_source_language(SourceLanguage::HLSL);
        opts.set_optimization_level(OptimizationLevel::Size);
        opts.add_macro_definition("USE_PBR", Some("1"));
    },
)?;

Build requirements for shaderc

shaderc-rs locates libshaderc in this order:

1. SHADERC_LIB_DIR env var — point to a directory containing libshaderc_combined.
2. VULKAN_SDK env var — installing the LunarG Vulkan SDK sets this automatically, and ships a prebuilt libshaderc_combined. This is the easiest path.
3. pkg-config / system libraries (typical on Linux distros that package shaderc).
4. Source build fallback — compiles glslang from C++ source. Requires CMake ≥ 3.17 (newer CMake may need CMAKE_POLICY_VERSION_MINIMUM=3.5 until shaderc-sys updates its pinned sources), Python 3, and a working C++ toolchain. First build takes 1–3 minutes.

If neither the SDK nor a system package is available and you don't want to build from source, use the naga feature instead.

When to pick which

Both features can be enabled simultaneously — pick per shader at the call site.

slang — Khronos Slang (modules, generics, autodiff)

Slang is Khronos's modern shading language. Pick it when you need:

• Modules, generics, and interfaces — real code reuse in shaders.
• Automatic differentiation — tag a function [Differentiable] and the compiler generates forward (__fwd_diff) and backward (__bwd_diff) variants. A single kernel definition yields both the forward and backward SPIR-V, which is a game-changer for ML compute on Vulkan.
• Explicit entry points — one .slang file can expose many compute / vertex / fragment entry points; compile each to its own SPIR-V blob from the same parsed module.

vulkane = { version = "0.4", features = ["slang"] }

Slang compilation is stateful — a session holds the SPIR-V target and search paths, modules are loaded by name through those paths, and each entry point is compiled on demand:

use vulkane::safe::slang::SlangSession;

// Given kernels/autodiff.slang with [Differentiable] functions and
// both `forward` and `backward` compute entry points:
let session = SlangSession::with_search_paths(&["kernels"])?;
let module  = session.load_file("autodiff")?;                // parses once
let fwd     = module.compile_entry_point("forward")?;        // Vec<u32> SPIR-V
let bwd     = module.compile_entry_point("backward")?;       // Vec<u32> SPIR-V

Or for a one-off compile:

use vulkane::safe::slang::compile_slang_file;

let spirv = compile_slang_file("kernels", "trivial", "main")?;

Build requirements for slang

shader-slang locates the Slang compiler via:

1. VULKAN_SDK env var — the LunarG Vulkan SDK ships slangc and the Slang runtime library. Easiest path (same as shaderc).
2. SLANG_DIR env var — a standalone Slang install from shader-slang/slang releases.
3. SLANG_INCLUDE_DIR + SLANG_LIB_DIR — split paths.

At runtime, slang.dll / libslang.so / libslang.dylib must be discoverable (same directory as the executable, or on the library search path).

Current limitation

shader-slang 0.1.0 on crates.io only supports loading Slang modules from disk (via search-path resolution). Inline source strings will be supported once a newer shader-slang release exposes them; until then, keep your Slang code in .slang files.

Why Vulkane over ash?

Features

Providing vk.xml

You usually do not have to. A vk.xml ships inside the published crate, so cargo add vulkane builds with no configuration, no network, and no feature flags. The rest of this section is for overriding that.

The build resolves a spec in this order and takes the first that exists:

Because route 2 is present in every published version, fetch-spec is a fallback rather than a requirement. If every route fails the build errors with all of them named, rather than with a missing-file diagnostic.

Supported Vulkan Versions

1.2.175 through the latest release. The minimum is set by the VK_MAKE_API_VERSION macros introduced in that version.

Architecture

vk.xml → vulkan_gen (roxmltree parser + codegen) → vulkane crate
                                                    ├── raw/   (generated FFI bindings)
                                                    ├── safe/  (RAII wrapper)
                                                    └── vulkane_derive (proc macros)

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in vulkane by you, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.