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 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
let _vk_lib = vk::VkLib::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));§Convenience Instance and Device creation
Instance and device creation are a large portion of the boiler plate code that comes with implementing a vulkan application, so it makes sence to have a convenient way of doing this in the library (which is why you could argue that it barely does not contradicts the “no bullshit” paradigm)
#[macro_use]
extern crate nobs_vk;
use nobs_vk as vk;
use std::ffi::CStr;
fn main() {
let lib = vk::VkLib::new();
let inst = vk::instance::new()
.validate(vk::DEBUG_REPORT_ERROR_BIT_EXT | vk::DEBUG_REPORT_WARNING_BIT_EXT)
.application("awesome app", 0)
.add_extension(vk::KHR_SURFACE_EXTENSION_NAME)
.add_extension(vk::KHR_XLIB_SURFACE_EXTENSION_NAME)
.create(lib)
.unwrap();
for pd in vk::device::PhysicalDevice::enumerate_all(inst.handle) {
println!(
"instance api version: {} {} {}",
version_major!(pd.properties.apiVersion),
version_minor!(pd.properties.apiVersion),
version_patch!(pd.properties.apiVersion)
);
println!("driver version: {}", pd.properties.driverVersion);
println!("vendor id: {}", pd.properties.vendorID);
println!("device id: {}", pd.properties.deviceID);
println!("vendor: {}", unsafe {
CStr::from_ptr(&pd.properties.deviceName[0]).to_str().unwrap()
});
println!("layers: {:?}", pd.supported_layers);
println!("extensions: {:?}", pd.supported_extensions);
}
let (_pdevice, _device) = vk::device::PhysicalDevice::enumerate_all(inst.handle)
.remove(0)
.into_device()
.add_queue(vk::device::QueueProperties {
present: false,
graphics: true,
compute: true,
transfer: true,
}).create()
.unwrap();
}§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 stored in VkLib. There are also functions declared globally for every vulkan command. After creating an instance of VkLib these function redirect to the VkLib instance. This is done for convenience purposes, so that we do not have to pass on the VkLib instance. Since there is a function for every vulkan command, this also includes commands, that are not supported on the system. In this case calling the function will panic even after instance/device creation. The same will happen if the vkulan library was initialized with a feature level and the function is therefore not supported.
§Check macros
Additionally to the result integer constants that are defined by the vulkan api, the two enums Success and Error are declared. These capture the successful and unsuccessful error codes. The vk_check! converts the error code returned from vulkan with make_result and prints debug information when the command failed. vk_uncheck! will consume the result and panic on error, while vk_check! returns the Result<Success, Error>
§Instance and Device builder patterns
As the sole convenience feature this library introduces builder patterns for instance and device creation. This enables a convenient way of configuring e.g. debug layers for a vulkan instance, or extensions and properties of queues for devices. See instance::Builder and device::Builder for more details
§Vulkan reference
For documentation of the defined enums, structs and funcions see the vulkan reference.
Modules§
- Covenience device and physical device creation.
- Covenience instance creation.
Macros§
- Create a version number from a major, minor and patch as it is defined in vulkan version numbers and semantics
- Extract major number from version, created with make_version or retrieved from vulkan
- Extract minor number from version, created with make_version or retrieved from vulkan
- Extract patch number from version, created with make_version or retrieved from vulkan
- Wraps a call to a vulkan command and converts it’s returned error code with make_result.
- Same as vk_check but instead of returning the Result calls unwrap on it.
Structs§
- Vulkan library initialization struct
Enums§
- Enum type for all unsuccessful return codes in
nobs_vk::Result - Enum type for all successful return codes in
nobs_vk::Result
Constants§
Functions§
- Converts the integer error code from a vulkan command into a
Result<Success, Error>