Crate erupt

Expand description

Vulkan API bindings

Take a look at the erupt user guide.

§MAINTENANCE MODE NOTICE

It is not recommended to use erupt for new projects, use ash instead. There is work underway to rewrite ash using ideas from the erupt project, for updates see https://github.com/ash-rs/ash/issues/344. Simple patches to erupt will still be merged, but no large changes are to be expected.

§Features

Full Vulkan API coverage
First-class support for all extensions
High quality auto-generated function wrappers
A utility module aiding your use of this crate
- VulkanResult: Idiomatic wrapper around a Vulkan Result
- surface: Create a SurfaceKHR using a RawWindowHandle (adapted from ash-window)
Generated code distributed into multiple modules
Function loading (EntryLoader, InstanceLoader, DeviceLoader)
Separate Flags and FlagBits types
A high level Builder for every struct
Type-safe pointer chain support
Default and Debug implementation for every type
Confirmed support for Linux, Windows, macOS and Android
Complete auto-generation of everything except utils

§Example: Instance Creation

use erupt::{vk, EntryLoader, InstanceLoader};

let entry = EntryLoader::new()?;

let app_info = vk::ApplicationInfoBuilder::new()
    .api_version(vk::API_VERSION_1_1);
let instance_info = vk::InstanceCreateInfoBuilder::new()
    .application_info(&app_info);
let instance = InstanceLoader::new(&entry, &instance_info)?;

// ...

instance.destroy_instance(None);

§Additional examples

§Cargo Features

surface (enabled by default): Enables the surface module, adds raw-window-handle dependency
loading (enabled by default): Enables the EntryLoader::new function, adds libloading dependency
bytemuck: Implements Pod for some hand-picked structs (*IndirectCommand, etc.), adds bytemuck dependency

§FAQ

§Q: What’s the difference between this, ash and vulkano?

A: Vulkano is special because it provides hand-written Vulkan wrappers, which means that for example it has a special hand-written wrapper around a Vulkan PhysicalDevice. On the other hand ash and erupt both provide Vulkan API bindings too, but not exposing such fancy wrappers and instead focusing on having good bindings to the raw Vulkan API.

The big selling points of erupt is that it has better documentation, high level function support for all extensions (which is only really relevant if you use those extensions), being fully generated and some more smaller improvements. On the other hand ash has a bigger existing community.

§Q: What does the number at the end of the version mean?

A: It represents the Vulkan Header version this version of erupt was generated against and is purely informational.

§Ecosystem

§Initialization

erupt-bootstrap: Vulkan Bootstrapping library, inspired by vk-bootstrap

§Memory Allocation

gpu-alloc: Rust-native, used internally by wgpu
vk-alloc: Rust-native
vk-mem-erupt: Bindings to the C++ Vulkan Memory Allocator (VMA) library

§Minimum Supported Rust Version (MSRV)

Rust 1.48 or higher.

§Thank you

ash for helping inspiring and making this crate
libloading for providing symbol loading
ash-window for providing a base for the surface module
bitflags for providing a perfect bitflag macro
The Vulkan Community ❤️
The Rust Community ❤️

§Licensing

The logo is the Volcano Emoji of Twemoji (License). The name “erupt” was added on top of it.

This project is licensed under the zlib License.

Re-exports§

pub use utils::loading::EntryLoader;

Modules§

extensions: Provides Vulkan extension items.
external: Provides external library items.
utils: Utilities to aid your usage of this crate.
vk: Re-exports every Vulkan item.
vk1_0: Provides Vulkan feature items.
vk1_1: Provides Vulkan feature items.
vk1_2: Provides Vulkan feature items.
vk1_3: Provides Vulkan feature items.

Macros§

cstr: Construct a *const std::os::raw::c_char from a string.
try_vk: Like try!, but for utils::VulkanResult.

Structs§

CustomEntryLoader: Loader for entry commands.
DeviceEnabled: A list of requirements enabled in the device loader.
DeviceLoader: Loader for device commands.
DeviceLoaderBuilder: Builder for an device loader.
EntryEnabled: A list of requirements enabled in the entry loader.
InstanceEnabled: A list of requirements enabled in the instance loader.
InstanceLoader: Loader for instance commands.
InstanceLoaderBuilder: Builder for an instance loader.

Enums§

LoaderError: An error which can occur while initializing a loader.

Traits§

ExtendableFrom: Provides type-safe pointer chain support.
ObjectHandle: Vulkan object handles (dispatchable and non-dispatchable).

Type Aliases§

SmallVec: Allows returning small amounts of data (specifically with a length <= 8) without needlessly allocating heap memory.

Crate eruptCopy item path