# 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](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:

```sh
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](volcanic/examples/version.rs):

```rust
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:

```sh
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:

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

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

| Feature | Enables |
| --- | --- |
| `core_1_0` through `core_1_4` | The selected core version and all earlier core versions |
| `vk_khr_surface`, `vk_khr_swapchain`, etc. | Individual Vulkan extensions |
| `vulkan_video_codec_h264std`, etc. | Individual Vulkan Video definitions |
| `loader` | Global, instance, and device command tables loaded through `libloading` |
| `everything` | All generated core, extension, and video features; add `loader` separately |

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/`:

```sh
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.