Crate vulkanic

Source
Expand description

§vulkanic - Vulkan API adapter

Vulkan Specs

Ultra-thin wrapper sitting on top of vk-sys.

§Examples

GLFW:

let ep: EntryPoints = vk::EntryPoints::load(|procname| {
    glfw_window.get_instance_proc_address(0, procname.to_str().unwrap())
}).into();

// let instance_info = ...

let instance = unsafe { ep.create_instance(&instance_info) }?;

let ip: InstancePointers = vk::InstancePointers::load(|procname| {
    glfw_window.get_instance_proc_address(instance, procname.to_str().unwrap())
}).into();
let dp: DevicePointers = vk::DevicePointers::load(|procname| {
    glfw_window.get_instance_proc_address(instance, procname.to_str().unwrap())
}).into();

for physical_device in ip.enumerate_physical_devices(instance)? {
    // ...
}

// ...

// use pointers directly, if wrapper implementation is missing
// unsafe { dp.InvalidateMappedMemoryRanges(..) }

§Crate conventions

  • same partitioning like vk-sys with EntryPoints, InstancePointers and DevicePointers
  • Rust naming conventions are met
    • function names e.g. CreateDevice renamed to create_device
    • parameter names e.g. physicalDevice renamed to physical_device
    • C type prefixes are omitted e.g. pCreateInfo to create_info
  • type mapping
    • vk::Bool32 to bool
    • pointers pCreateInfo: *const DeviceCreateInfo to borrows create_info: &DeviceCreateInfo
    • API calls having array parameters e.g. fenceCount: u32, pFences: *const Fence will be presented as Rust slices e.g. fences: &[vk::Fence].
  • return values
    • std::result::Result<T, vk::Result> if API call has a result
    • T if API call has no result
    • API calls with a result, will return Ok(..) only for vk::SUCCESS

§Missing parts

  • many Vulkan API calls are still not yet implemented
  • API calls like vkAcquireNextImageKHR can return non-error results which are currently handled as error. It’s not clear (even from the specs) if out-parameter are valid in this case.

§Safety

  • many Vulkan API calls are safe Rust regarding they may fail, but will not have undefined behaviour
  • all Vulkan API calls with structs containing pointers like pNext: *const c_void have to be considered unsafe, because caller has to make sure they are valid.
  • using Vec or slices as ffi pointers is safe, because all vk-sys structs are #[repr(C)], which ensures correct alignment without padding.

Structs§

Type Aliases§

  • Result
    Result type for most Vulkan API calls, if they support them. Currently non-error return values are handled as Err(..) (also see Missing parts on top).