volcanic

Rust bindings for Vulkan 1.4.362, covering core Vulkan 1.0 through 1.4, Vulkan extensions, and Vulkan Video definitions from that registry release. The exact upstream sources and checksums are recorded in spec/source.toml.

Cargo features select the API surface you compile. The registry version describes the bindings; the Vulkan versions and extensions available at runtime depend on your loader and device.

Run a small example

With Rust and a Vulkan loader installed, run this from the repository root:

cargo run -p volcanic --example version --features loader,core_1_1

The example loads Vulkan and prints the maximum instance API version supported by the loader. It requires no window or instance. If the Vulkan 1.1 version-query command is unavailable, it reports Vulkan 1.0.

The complete example:

use std::error::Error;
use volcanic::{loader::CmdsGlobal, *};

fn main() -> Result<(), Box<dyn Error>> {
    let default_library = if cfg!(target_os = "windows") {
        "vulkan-1.dll"
    } else if cfg!(target_os = "macos") {
        "libvulkan.1.dylib"
    } else {
        "libvulkan.so.1"
    };
    let path = std::env::args_os()
        .nth(1)
        .unwrap_or_else(|| default_library.into());

    let library = unsafe { libloading::Library::new(path)? };
    let global = unsafe { CmdsGlobal::load(&library)? };
    let mut version = VK_API_VERSION_1_0;
    if let Some(enumerate_version) = global.vkEnumerateInstanceVersion {
        let result = unsafe { enumerate_version(&mut version) };
        if result != VkResult::Success {
            return Err(format!("vkEnumerateInstanceVersion failed: {result:?}").into());
        }
    }

    println!(
        "Supported instance API: Vulkan {}.{}.{}",
        VK_API_VERSION_MAJOR(version),
        VK_API_VERSION_MINOR(version),
        VK_API_VERSION_PATCH(version),
    );
    Ok(())
}

The library stays loaded until after the last Vulkan call. On macOS, install a Vulkan loader separately. You can pass an explicit loader path on any platform:

cargo run -p volcanic --example version --features loader,core_1_1 -- /path/to/vulkan-loader

The printed version comes from your system and can differ from the bindings' version. Individual devices can support a different API version.

Use it in your project

For a local checkout, add these dependencies to your application's Cargo.toml, adjusting the path relative to that file:

[dependencies]
volcanic = { path = "../volcanic/volcanic", features = ["loader", "core_1_1"] }
libloading = "0.9"

The example above can be copied directly into src/main.rs.

No features are enabled by default. Extension prerequisites must also be enabled; missing prerequisites produce compile errors. Cargo features do not enable extensions at runtime: query support and enable the extensions when creating your Vulkan instance or device.

These are raw FFI bindings. Calls are unsafe, and callers manage Vulkan object lifetimes. Command-table fields are Option function pointers so you can check whether a command was loaded; convenience methods panic when their command is missing. Vulkan enums are transparent integer wrappers with named constants and from_raw/as_raw methods. Flags use the reexported bitflags crate, and callbacks use nullable function pointers.

Regenerate the bindings

The generator reads the checked-in registry files in spec/:

cargo run -p codegen
cargo run -p codegen -- --check

The first command updates the bindings, loader, and Cargo features. The second checks that generated files are current without modifying them.

AI maintenance disclaimer

This project is developed and maintained with AI assistance. The generator was originally AI-written. Despite automated tests and ABI checks, errors may remain; review and test the bindings for your use case before relying on them.