Ash

A very lightweight wrapper around Vulkan

Stable yet?

I don't expect any big changes anymore. The library will still remain < 1.0 until I had time to use it in a real project. If you encounter any problems, feel free to open an Issue.

Breaking changes:

• 0.15.8 -> 0.16.0: map_memory now returns a void ptr. ash::util::Align is a helper struct that can write to aligned memory.

Why Ash?

• Lightweight Vulkan wrapper
• Low overhead
• Additional type safety
• Trait based, version specific loader

What does it do?

Explicit returns with Result

Functions return a type VkResult<T> = Result<T, vk::Result> instead of an error code. No mutable references for the output are required.

// 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");

Always returns a Vec<T> for functions that output multiple values.

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

Slices

Ash always uses slices in functions.

// C
void vkCmdPipelineBarrier(
    VkCommandBuffer                             commandBuffer,
    VkPipelineStageFlags                        srcStageMask,
    VkPipelineStageFlags                        dstStageMask,
    VkDependencyFlags                           dependencyFlags,
    uint32_t                                    memoryBarrierCount,
    const VkMemoryBarrier*                      pMemoryBarriers,
    uint32_t                                    bufferMemoryBarrierCount,
    const VkBufferMemoryBarrier*                pBufferMemoryBarriers,
    uint32_t                                    imageMemoryBarrierCount,
    const VkImageMemoryBarrier*                 pImageMemoryBarriers);

// Rust
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]);

device.cmd_pipeline_barrier(setup_command_buffer,
                            vk::PIPELINE_STAGE_TOP_OF_PIPE_BIT,
                            vk::PIPELINE_STAGE_TOP_OF_PIPE_BIT,
                            vk::DependencyFlags::empty(),
                            &[],
                            &[],
                            &[layout_transition_barrier]);

Type safety

Ash still uses raw Vulkan structs. The only difference is type safety. Everything that can be an enum is an enum like vk::StructureType, flags are implemented similar to the Bitflags crate. Ash also follows the Rust style guide. The reason that Ash uses raw Vulkan structs is to be extensible, just like the Vulkan spec.

let pool_create_info = vk::CommandPoolCreateInfo {
    s_type: vk::StructureType::CommandPoolCreateInfo,
    p_next: ptr::null(),
    flags: vk::COMMAND_POOL_CREATE_RESET_COMMAND_BUFFER_BIT,
    queue_family_index: queue_family_index,
};
let pool = device.create_command_pool(&pool_create_info, None).unwrap();

Additionally pointers like Instance, Device, Queue etc are hidden behind a type. Those pointers can only be constructed from within Ash which eliminates some invalid API usage and has the benefit of making some functions in Vulkan safe.

Function pointer loading

Ash also takes care of loading the function pointers. Function pointers are split into 3 categories, Entry, Instance and Device. The reason for not loading it into a global is that in Vulkan you can have multiple devices and each device will load its own function pointers to achieve better performance. Click here for more information.

Ash also manages multiple versions of Vulkan without any breakage. You will never run into any runtime error because you tried to access a function pointer that failed to load. Function pointers either load successfully or fail and return an error.

use ash::{Device, Instance};
// Specifies the version that you want to load
use ash::version::V1_0;
// Those traits implement the version specific functions
use ash::version::{InstanceV1_0, DeviceV1_0, EntryV1_0};
let entry = Entry::<V1_0>::new().unwrap();
let instance = entry.create_instance(...).expect("Instance creation error.");
let device = instance.create_device(...).expect("Device creation error.");

A V1_X struct is used to indicate the version.

// Define your types
type YourDevice = Device<V1_0>;
type YourInstance = Instance<V1_0>;

You can upgrade to a future version without any breakage.

// For example, switching from V1_0 to V1_3 will not cause any breakage.
type YourDevice = Device<V1_3>;
type YourInstance = Instance<V1_3>;

A newer version can always be converted to an older version.

let newer_device: Device<V1_5> = ...;
let older_device: Device<V1_0> = newer_device.into();

Or specify the minimum version that you require with a trait.

fn do_something_with_a_device<Device: DeviceV1_0>(device: &Device){}

Extension loading

Additionally, every Vulkan extension has to be loaded explicitly. You can find all extensions under ash::extensions. You still have to tell Vulkan which instance or device extensions you want to load.

use ash::extensions::Swapchain;
let swapchain_loader = Swapchain::new(&instance, &device).expect("Unable to load swapchain");
let swapchain = swapchain_loader.create_swapchain_khr(&swapchain_create_info).unwrap();

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

You don't have to pass an Instance or Device handle anymore, this is done implicitly for you. This makes sure that you will always use the most optimal implementation for your Device.

// C
VkResult vkCreateCommandPool(
    VkDevice                                    device,
    const VkCommandPoolCreateInfo*              pCreateInfo,
    const VkAllocationCallbacks*                pAllocator,
    VkCommandPool*                              pCommandPool);

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

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

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.

Triangle

Displays a triangle with vertex colors.

cd examples
cargo run --bin triangle

Texture

Displays a texture on a quad.

cd examples
cargo run --bin texture

Roadmap

Extensions

• Swapchain
• Surface
• XlibSurface
• DebugReport
• Win32Surface
• MirSurface
• XcbSurface
• AndroidSurface
• WaylandSurface
• Display

In progress

• Wrapping the complete spec
• Version specific loader

A thanks to

• Api with no secrets
• Vulkan tutorial
• Vulkan examples
• Vulkan tutorial
• Vulkano
• vk-rs