Lava: a Rust wrapper for the Vulkan API

Wrapper to manipulate the Vulkan API more conveniently than with bindings:

• removes the need to specify the structure type when sending structures to Vulkan
• takes care of making double Vulkan calls when necessary (e.g when retrieving a list of Vulkan objects)
• returns objects retrieved by Vulkan in a Result<T, VkResult> instead of returning them via a pointer
• allows to manipulate references, slices and options instead of pointers
• exposes the API in an object-oriented way (e.g instance.enumerate_physical_devices() instead of enumerate_physical_devices(&instance))
• removes the extension suffix from function and data-structure names
• puts all data-structures with the same extension in a dedicated module
• bit flags are exposed as structures instead of integers
• all structures have a default value, allowing to "auto-complete" large structure with optional fields using ..Default::default()
• manages the calls to vkGetInstanceProcAddr to manipulate functions that are not exposed statically
• provides a generic create_surface method to create surfaces

It comes with the following restrictions (that should be lifted in the future):

• no way to provide allocator callbacks
• no way to set the pNext field of structures (always set to NULL)
• debug report callbacks only forward the message to the Rust user-provided function (other pieces of information are unavailable)
• no exposed constants for validation layer names or extension names

Lava works by letting the developer manipulate "wrapped" data structures, which it converts to "raw" data-structures expected by Vulkan (and the other way around when retrieving objects from Vulkan). It means that there is a small overhead in each API call.

Examples

This code display the name of each of the physical GPUs of the machine:

```rust let instance = Vk::createinstance(&VkInstanceCreateInfo { flags: VkInstanceCreateFlags::none(), applicationinfo: Some(&VkApplicationInfo { applicationname: Some("lava-example"), applicationversion: 1, enginename: None, engineversion: 1, apiversion: VkVersion(1, 0, 0), }), enabledlayernames: &["VKLAYERLUNARGstandardvalidation"], enabledextensionnames: &["VKEXTdebugreport"] }).expect("Failed to create instance");

let debugreportcallback = instance.createdebugreport_callback(&VkDebugReportCallbackCreateInfo { flags: VkDebugReportFlags { warning: true, error: true, ..VkDebugReportFlags::none() }, callback: |msg : String| println!("{}", msg) }).expect("Faield to create debug callback");

let physicaldevices = instance.enumeratephysical_devices().expect("Failed to retrieve physical devices");

for physicaldevice in &physicaldevices { let properties = physicaldevice.getproperties();

println!("{}", properties.device_name);

}

debugreportcallback.destroy(); instance.destroy(); ```

This snippet shows how to create a surface from a GLFW window:

``rust // We assume thatwindow` is a pointer to a GLFWwindow, as described here: //http://www.glfw.org/docs/latest/group__vulkan.html#ga1a24536bec3f80b08ead18e28e6ae965

let surface = vkinstance.createsurface( |handle, allocator, surface| unsafe { glfwCreateWindowSurface(handle, self._window, allocator, surface) } ).expect("Failed to create window surface"); ```

Manual build

The content of the src/vk/ folder is generated from the vulkan_core.h and vk.xml files of the Vulkan documentation repository. This repository is up to date with the master branch.

If you wish to generate the wrapper for a specific version (requires Node.js):

• npm install
• node generate.js --tag <version>

Where <version> is a branch or tag name of the Vulkan-Docs repository (e.g "v1.1.80"). The script will download the appropriate files in the download/ folder and generates the new source files in src/vk/.

License

MIT