Go to file
Marijn Suijten 92084df65f
generator: Wrap _as_c_str() getter for possibly-pointers in Option (#860)
While this function is already marked `unsafe` to represent cases where
an invalid pointer might be dereferenced, it should at least be obvious
to the caller that there is a real chance for `NULL` pointers in these
`CStr` getters, which will now be returned as `None`.  This function
won't be used in `Debug` now as the dereference operation is still
`unsafe`.

The `_as_c_str()` getters for static arrays is left untouched, as the
data is read directly from the known-valid struct here.
2024-01-12 00:08:38 +01:00
.github Switch to safe CStr::from_bytes_until_nul on sized c_char array wrapper (#746) 2023-12-02 20:04:57 +01:00
analysis rewrite: Absolute basics (#713) 2023-03-13 22:06:38 +01:00
ash generator: Wrap _as_c_str() getter for possibly-pointers in Option (#860) 2024-01-12 00:08:38 +01:00
ash-examples Clean up unused std::XXX:: qualifications in examples and extensions (#852) 2023-12-24 00:36:21 +01:00
ash-rewrite Switch to safe CStr::from_bytes_until_nul on sized c_char array wrapper (#746) 2023-12-02 20:04:57 +01:00
ash-window Switch to safe CStr::from_bytes_until_nul on sized c_char array wrapper (#746) 2023-12-02 20:04:57 +01:00
generator generator: Wrap _as_c_str() getter for possibly-pointers in Option (#860) 2024-01-12 00:08:38 +01:00
generator-rewrite Rename examples to ash-examples (#820) 2023-11-17 17:27:28 +01:00
.gitignore pin vk-parse to crates.io 2018-08-17 12:26:32 -07:00
.gitmodules gitmodules: Disable update to prevent cloning on cargo checkout (#808) 2023-10-30 12:20:28 +01:00
bors.toml Add github actions (#244) 2019-10-20 17:41:13 +02:00
Cargo.toml cargo: Set resolver = "2" and avoid warning 2023-11-21 11:14:32 +01:00
Changelog.md generator: Apply must_use attributes to all Vulkan structs (#845) 2023-12-05 22:09:44 +01:00
LICENSE-APACHE init 2016-08-14 01:13:39 +02:00
LICENSE-MIT init 2016-08-14 01:13:39 +02:00
README.md Switch to safe CStr::from_bytes_until_nul on sized c_char array wrapper (#746) 2023-12-02 20:04:57 +01:00

Ash

A very lightweight wrapper around Vulkan

Crates.io Version Documentation Build Status LICENSE LICENSE Join the chat at https://gitter.im/MaikKlein/ash MSRV

Overview

  • A true Vulkan API without compromises
  • Convenience features without limiting functionality
  • Additional type safety
  • Device local function pointer loading
  • No validation, everything is unsafe
  • Generated from vk.xml
  • Support for Vulkan 1.1, 1.2, 1.3

⚠️ Semver compatibility warning

The Vulkan Video bindings are experimental and still seeing breaking changes in their upstream specification, and are only provided by Ash for early adopters. All related functions and types are semver-exempt 1 (we allow breaking API changes while releasing Ash with non-breaking semver bumps).

Features

Explicit returns with Result

// function signature
pub fn create_instance(&self,
                       create_info: &vk::InstanceCreateInfo<'_>,
                       allocation_callbacks: Option<&vk::AllocationCallbacks<'_>>)
                       -> Result<Instance, InstanceError> { .. }
let instance = entry.create_instance(&create_info, None)
    .expect("Instance creation error");

Vec<T> instead of mutable slices

pub fn get_swapchain_images(&self,
                            swapchain: vk::SwapchainKHR)
                            -> VkResult<Vec<vk::Image>>;
let present_images = swapchain_loader.get_swapchain_images_khr(swapchain).unwrap();

Note: Functions don't return Vec<T> if this would limit the functionality. See p_next.

Slices

pub fn cmd_pipeline_barrier(&self,
                            command_buffer: vk::CommandBuffer,
                            src_stage_mask: vk::PipelineStageFlags,
                            dst_stage_mask: vk::PipelineStageFlags,
                            dependency_flags: vk::DependencyFlags,
                            memory_barriers: &[vk::MemoryBarrier<'_>],
                            buffer_memory_barriers: &[vk::BufferMemoryBarrier<'_>],
                            image_memory_barriers: &[vk::ImageMemoryBarrier<'_>]);

Strongly typed handles

Each Vulkan handle type is exposed as a newtyped struct for improved type safety. Null handles can be constructed with T::null(), and handles may be freely converted to and from u64 with Handle::from_raw and Handle::as_raw for interop with non-Ash Vulkan code.

Builder pattern

let queue_info = [vk::DeviceQueueCreateInfo::default()
    .queue_family_index(queue_family_index)
    .queue_priorities(&priorities)];

let device_create_info = vk::DeviceCreateInfo::default()
    .queue_create_infos(&queue_info)
    .enabled_extension_names(&device_extension_names_raw)
    .enabled_features(&features);

let device: Device = instance
    .create_device(pdevice, &device_create_info, None)
    .unwrap();

Pointer chains

Use base.push_next(ext) to insert ext at the front of the pointer chain attached to base.

let mut variable_pointers = vk::PhysicalDeviceVariablePointerFeatures::default();
let mut corner = vk::PhysicalDeviceCornerSampledImageFeaturesNV::default();

let mut device_create_info = vk::DeviceCreateInfo::default()
    .push_next(&mut corner)
    .push_next(&mut variable_pointers);

The generic argument of .push_next() only allows valid structs to extend a given struct (known as structextends in the Vulkan registry, mapped to Extends* traits). Only structs that are listed one or more times in any structextends will implement a .push_next().

Flags and constants as associated constants

// Bitflag
vk::AccessFlags::COLOR_ATTACHMENT_READ | vk::AccessFlags::COLOR_ATTACHMENT_WRITE
// Constant
vk::PipelineBindPoint::GRAPHICS,

Debug/Display for Flags

let flag = vk::AccessFlags::COLOR_ATTACHMENT_READ
        | vk::AccessFlags::COLOR_ATTACHMENT_WRITE;
println!("Debug: {:?}", flag);
println!("Display: {}", flag);
// Prints:
// Debug: AccessFlags(110000000)
// Display: COLOR_ATTACHMENT_READ | COLOR_ATTACHMENT_WRITE

Function pointer loading

Ash also takes care of loading the function pointers. Function pointers are split into 3 categories.

  • Entry: Loads the Vulkan library. Needs to outlive Instance and Device.
  • Instance: Loads instance level functions. Needs to outlive the Devices it has created.
  • Device: Loads device local functions.

The loader is just one possible implementation:

  • Device level functions are retrieved on a per device basis.
  • Everything is loaded by default, functions that failed to load are initialized to a function that always panics.
  • Do not call Vulkan 1.1 functions if you have created a 1.0 instance. Doing so will result in a panic.

Custom loaders can be implemented.

Extension loading

Additionally, every Vulkan extension has to be loaded explicitly. You can find all extensions under ash::extensions.

use ash::extensions::khr::Swapchain;
let swapchain_loader = Swapchain::new(&instance, &device);
let swapchain = swapchain_loader.create_swapchain(&swapchain_create_info).unwrap();

Raw function pointers

Raw function pointers are available, if something hasn't been exposed yet in the higher level API. Please open an issue if anything is missing.

device.fp_v1_0().destroy_device(...);

Support for extension names

use ash::extensions::{Swapchain, XlibSurface, Surface, DebugReport};
#[cfg(all(unix, not(target_os = "android")))]
fn extension_names() -> Vec<*const i8> {
    vec![
        Surface::NAME.as_ptr(),
        XlibSurface::NAME.as_ptr(),
        DebugReport::NAME.as_ptr()
    ]
}

Implicit handles

Handles from Instance or Device are passed implicitly.

pub fn create_command_pool(&self,
                           create_info: &vk::CommandPoolCreateInfo<'_>)
                           -> VkResult<vk::CommandPool>;

let pool = device.create_command_pool(&pool_create_info).unwrap();

Optional linking

The default loaded cargo feature will dynamically load the default Vulkan library for the current platform with Entry::load, meaning that the build environment does not have to have Vulkan development packages installed.

If, on the other hand, your application cannot handle Vulkan being missing at runtime, you can instead enable the linked feature, which will link your binary with the Vulkan loader directly and expose the infallible Entry::linked.

Example

You can find the examples here. All examples currently require: the LunarG Validation layers and a Vulkan library that is visible in your PATH. An easy way to get started is to use the LunarG Vulkan SDK

Windows

Make sure that you have a Vulkan ready driver and install the LunarG Vulkan SDK.

Linux

Make sure that you have a Vulkan ready driver and install the LunarG Vulkan SDK. You also have to add the library and layers to your path. Have a look at my post if you are unsure how to do that.

macOS

Install the LunarG Vulkan SDK. The installer puts the SDK in $HOME/VulkanSDK/<version> by default. You will need to set the following environment variables when running cargo:

VULKAN_SDK=$HOME/VulkanSDK/<version>/macOS \
DYLD_FALLBACK_LIBRARY_PATH=$VULKAN_SDK/lib \
VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json \
VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d \
cargo run ...

Triangle

Displays a triangle with vertex colors.

cargo run -p ash-examples --bin triangle

screenshot

Texture

Displays a texture on a quad.

cargo run -p ash-examples --bin texture

texture

Useful resources

Examples

Utility libraries

  • vk-sync - Simplified Vulkan synchronization logic, written in rust.
  • vk-mem-rs - This crate provides an FFI layer and idiomatic rust wrappers for the excellent AMD Vulkan Memory Allocator (VMA) C/C++ library.
  • gpu-allocator - GPU Memory allocator written in pure Rust for Vulkan and DirectX 12.
  • lahar - Tools for asynchronously uploading data to a Vulkan device.

Libraries that use ash

  • gfx-rs - gfx-rs is a low-level, cross-platform graphics abstraction library in Rust.

A thanks to


  1. generator complexity makes it so that we cannot easily hide these bindings behind a non-default feature flag, and they are widespread across the generated codebase. ↩︎