Expand description
nobs-vk
no bullshit vulkan bindings.
This crate is auto generated by python scripts and provides types, constants and functions for vulkan.
Existential questions
Why does nobs-vk exists? nobs-vk…
- is used how the vulkan api is documented
- is auto generated from a python script that sources the vk.xml from the vulkan registry
- gives you the freedom to do as you please in your design decisions (but therefore doesn’t protect you from your own stupidity)
- is not a full blown window creating bloat library in the back, just to execute some small compute shader with a headless vulkan build
While more involved wrappers for vulkan do exist they also strife to completely hide the vulkan api behind another layer of rust code. nobs-vk tries to be as simple as possible and just exposes callable functions to vulkan.
Examples
Vulkan core initialisation
This is a simple example that retrieves the version of vulkan that is installed on the system
#[macro_use] extern crate nobs_vk as vk;
//...
// loads vulkan core
let _vk_lib = vk::Core::new();
// good to go from here, we can use any vulkan function that is supported by this system
// make sure _vk_lib lives throughout the time that vulkan is used and is dropped afterwards
// global vulkan version
let mut inst_ver: u32 = 0;
if vk::EnumerateInstanceVersion(&mut inst_ver) != vk::SUCCESS {
panic!("something went terribly wrong");
}
assert_eq!(1, version_major!(inst_ver));
assert_eq!(1, version_minor!(inst_ver));
assert_eq!(0, version_patch!(inst_ver));Instance extension loading
After we created a vulkan instance we can load extensions
#[macro_use] extern crate nobs_vk as vk;
use std::ffi::CString;
use std::ffi::CStr;
use std::ptr;
use std::os::raw::c_char;
// ...
let _vk_lib = vk::Core::new();
// Define some extensions and convert them to c-strings
let ext_names = vec![vk::KHR_SURFACE_EXTENSION_NAME, vk::KHR_XLIB_SURFACE_EXTENSION_NAME];
let ext_names_cstr = ext_names
.iter()
.map(|e| CString::new(*e).unwrap())
.collect::<Vec<CString>>();
let ext_names_ptr = ext_names_cstr
.iter()
.map(|e| e.as_ptr())
.collect::<Vec<*const c_char>>();
// create the instance
let appinfo = vk::InstanceCreateInfo {
sType: vk::STRUCTURE_TYPE_INSTANCE_CREATE_INFO,
pNext: ptr::null(),
flags: 0,
pApplicationInfo: ptr::null(),
enabledLayerCount: 0,
ppEnabledLayerNames: ptr::null(),
enabledExtensionCount: ext_names.len() as u32, // <- extension names go here
ppEnabledExtensionNames: ext_names_ptr.as_ptr(), // <-
};
let mut inst = vk::NULL_HANDLE;
vk::CreateInstance(&appinfo, ptr::null(), &mut inst);
// not an extension, so we can call it no matter what
let mut num_devices: u32 = 0;
vk::EnumeratePhysicalDevices(inst, &mut num_devices, ptr::null_mut());
println!("num devices: {}", num_devices);
// load extensions
// note that only extensions are loaded, that have been specified in ext_names
let ie = vk::InstanceExtensions::new(inst);
// we can now use instence extensions, e.g.:
// ie.CreateXlibSurfaceKHR(...)
// don't forget to clean up
vk::DestroyInstance(inst, ptr::null());Details
Vulkan commands are either core or extension. We provide two different mechanisms to load function pointers.
Core commands are loaded with nobs_vk::Core::new or
nobs_vk::Core::with_version. The returned object
holds entry points to core vulkan commands and defines member function to call them.
Additionaly global functions in the nobs_vk namespace are defined that may be called as
long as a valid instance of nobs_vk::Core exists. Warning: do not create multiple instances
of nobs_vk::Core.
Instance and device extensions are loaded with
nobs_vk::[InstanceExtensions|DeviceExtensions]. The two types hold entry points to vulkan
extensions and define member functions to call them. Only those extension are loaded, that have
been specified during instance/device creation (enabledExtensionCount and
ppEnabledExtensionNames fields of fields of
VkInstanceCreateInfo
and VkDeviceCreateInfo).
Namespaces
Name prefixes of the C-types, enums and (core) functions are removed in favor of the module namespace.
For example VK_Result becomes vk::Result, VK_SUCCESS becomes vk::SUCCESS, vkCreateInstance() becomes vk::CreateInstance().
Function pointers
nobs-vk defines functions for all extensions that have been specified in the generate.py. This all its required types,
function pointers and methods in nobs_vk::[InstanceExtensions|DeviceExtensions] are
generated. In case a system does not support an extension the function pointer will not be
loaded, and calling its respectiove method causes a panic.
Traits for rich instance and device wrapper
nobs-vk provides the traits InstanceWreapper and InstanceWreapper. Both are intended to be used in a implementation a rich wrapper around a vulkan instance or device. They extend an object that can provide a InstanceExtension or DeviceExtension with methods to call vulkan commands directly on the object. The provided methods are simple pass through to the actual function pointer.
Vulkan reference
For documentation of the defined enums, structs and funcions see the vulkan reference.