[−][src]Crate nobs_vk
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 and might force you into design decisions you would normally try to avoid. This library 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
Namespaces
Name prefixes of the C-types, enums and 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
Entry points to vulkan commands are placed in objects containing funcion pointes. After loading the function pointers contain the address to the respective vulkan API call. 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).
Objects with function pointes define all commands that are listed the vulkan reference. In case a specific feature level is selected as well as platform or hardware vendor specific extensions the definitions for the functions or methods are not removed. However calling such a function, that is not supported will always cause a panic.
Instance and device wrapper
This library introduces exactly one feature for more convenience while using the API: the traits InstanceWrapper and DeviceWrapper.
With these two traits we divide vulkan commands into functions, that need a valid device and those that do not. Vulkan commands are then attached to an object as methods of the respective trait. Such a richer wrapper around a vulkan instance or device can be easily implemented by only providing a single method for the trait.
Vulkan reference
For documentation of the defined enums, structs and funcions see the vulkan reference.
Macros
| make_version | Create a version number from a major, minor and patch as it is defined in vulkan version numbers and semantics |
| version_major | Extract major number from version, created with make_version or retrieved from vulkan |
| version_minor | Extract minor number from version, created with make_version or retrieved from vulkan |
| version_patch | Extract patch number from version, created with make_version or retrieved from vulkan |
Structs
| Core | Vulkan core commands |
| DeviceExtensions | Vulkan device extensions |
| InstanceExtensions | Vulkan instance extensions |
Constants
| VERSION_1_0 | |
| VERSION_1_1 |
Traits
| DeviceWrapper | Trait with default pass-through implementations for vulkan commands associated with a device |
| InstanceWrapper | Trait with default pass-through implementations for vulkan commands associated with an instance |