vulkano-rs / vulkano

Safe and rich Rust wrapper around the Vulkan API

Vulkano

Vulkano is a Rust wrapper around the Vulkan graphics API. It follows the Rust philosophy, which is that as long as you don't use unsafe code you shouldn't be able to trigger any undefined behavior. In the case of Vulkan, this means that non-unsafe code should always conform to valid API usage.

What does vulkano do?

• Provides a low-levelish API around Vulkan. It doesn't hide what it does but provides some comfort types.
• Plans to prevent all invalid API usages, even the most obscure ones. The purpose of Vulkano is not to simply let you draw a teapot, but to cover all possible usages of Vulkan and detect all the possible problems in order to write robust programs. Invalid API usage is prevented thanks to both compile-time checks and runtime checks.
• Can handle synchronization on the GPU side for you (unless you choose to do that yourself), as this aspect of Vulkan is both annoying to handle and error-prone. Dependencies between submissions are automatically detected, and semaphores are managed automatically. The behavior of the library can be customized thanks to unsafe trait implementations.
• Tries to be convenient to use. Nobody is going to use a library that requires you to browse the documentation for hours for every single operation.

Comparison

Comparison to other well-known Graphics APIs in Rust ecosystem.

Name	Open-sourced Since	API Level	Notable Features
Vulkano	March, 2016	High-level Rust API wrapping Vulkan APIs.	Type-safe compile-time shaders. Transparent interoperability with glsl and spir-v shader code types in Rust code. Automatically generated types for shader's Layout.
Wgpu	May, 2019	High-level Rust API with multiple backends.	Supports multiple backends: Vulkan, Metal, DirectX, WebGPU, and other. Follows WebGPU specification. With async/await API.
Miniquad	March, 2020	High-level minimalistic Rust API with multiple backends.	Relatively minimalistic API well suited for small to medium graphics projects. Supports multiple backends, including browser target.
Sierra	March, 2021	High-level Rust API for Vulkan/Metal APIs.	Layouts, Descriptors and shader Types construction in Rust code through the macro system. Built on top of Erupt. Supports Ray Tracing Pipeline.
Glium	October, 2014	High-level Rust API wrapping OpenGL	OpenGL only.
Ash	August, 2016	Low-level API for Vulkan.	Unsafe Vulkan API bindings.
Erupt	April, 2020	Low-level API for Vulkan.	Unsafe Vulkan API bindings.

Please note that by the current date none of the known projects in the ecosystem(including Vulkano) reached stable release versions and the final design goals, their APIs are changing from time to time in a breakable way too, and there could be bugs and unfinished features too.

However, most of the projects mentioned above are already established definitive structures, all feature breaking changes will likely be straightforward to fix in user code, and most of them are maintained. As such we can recommend using any of them in the 3rd party code. The choice depends on the end project's goals and requirements, and we recommend examining their actual set of features and API capabilities beforehand.

Projects using Vulkano

We started collecting this list just recently and it would be appreciated if you help us by contributing(opening a PR) into README.md.

Project Name	Description
Basalt	GUI framework for Desktop applications
Ferret	Doom-compatible game engine
Sandbox	2D Pixel Physics Simulator
Egui Winit Vulkano	Vulkano integration with Egui
VideowindoW	Uses Vulkano under the hood to enable asynchronous video stream compositing
Korangar	A Vulkan based Ragnarok Online client
Krnl	Safe, portable, high performance compute (GPGPU) kernels.
Vera	Animation engine scripted in Rust.

We would love to help you keep your project in sync with the most recent changes in Vulkano if you give us feedback by adding your project to this list.

Thanks in advance!

Documentation and Resources

To get started you are encouraged to use the following resources:

• The examples folder in this repository.
• docs.rs - Full Vulkano API documentation
• The guide on vulkano.rs - Starts with trivial compute examples (~50 lines of code) and then works up to rendering triangles and mandelbrots. The guide is currently outdated a little. We are planning to update it in the future, but it's a good place to start understanding the base building blocks of Vulkano API.
• Github Issues - Raise a topic, ask a question or report a bug. The new topics there are watched regularly by maintainers and other community users.
• Gitter Chat - Another place to raise a question. However, the chat is not maintained regularly at this moment. Better use Github Issues for this purpose.

Contributing

Contributions are very welcome! Feel free to submit pull requests, to open questions and topics in the Issues section.

The project was initially developed by Pierre Krieger(Tomaka), who established Vulkano's base design goals, and the code structure. In the meantime, development is driven by Vulkano community members.

New Pull Requests are usually scheduled for review by the end of each week. The older PRs that are already in review have priority over the new ones. We are trying to push development forward as quick as possible, but the review process sometimes takes time, please be patient as the maintainers need time to check everything properly.

If something needs to get promoted urgently, please ping current Vulkano maintainer(@Eliah-Lakhin) in the PR's or Issue's comments.

If your change adds, removes or modifies a trait or a function, please specify changelog entries in the Pull Request description(not in the changelog file directly). They will be transferred to the changelog right after the PR merge.

Every PR must pass tests in order to be merged to master.

Minor releases are usually happening between 1 to 3 months averagely depending on grow of unreleased and breaking changes in master

Repository Structure

This repository contains four libraries:

• vulkano is the main one.
• vulkano-shaders provides the shader! macro for compiling glsl shaders.
• vulkano-util provides a variety of utility functions to streamline certain common operations such as device and swapchain creation.
• vulkano-win provides a safe link between vulkano and the winit library which can create a window to render to.

In order to run tests, run cargo test --all at the root of the repository. Make sure your Vulkan driver is up to date before doing so.

Hall of Fame

We would love to mention some members, who put significant contributions to this project:

• Pierre Krieger. The initial developer. Patreon page.
• Lucas Kent. Maintainer. Patreon page.
• Austin Johnson. Maintainer. Patreon page.
• Rua. An active developer, who put a lot of effort to improve Vulkano and constantly keeping it up to date.
• You! Thanks to your help, contributions, improvements, bug reports and user experience to make this project one of the major Rust graphics API library in Rust!

Setup and Troubleshooting

Vulkano uses shaderc-rs for shader compilation. Refer to shaderc-rs documentation to provide a pre-built libshaderc for faster build times.

Note that in general vulkano does not require you to install the official Vulkan SDK. This is not something specific to vulkano (you don't need the SDK to write programs that use Vulkan, even without vulkano), but many people are unaware of that and install the SDK thinking that it is required. However, macOS and iOS platforms do require a little more Vulkan setup since it is not natively supported. See below for more details.

Unless you provide libshaderc, in order to build libshaderc with the shaderc-sys crate, the following tools must be installed and available on PATH:

• CMake
• Ninja Is optional except when building with MSVC. It may speed up build time for libshaderc.
• Python (works with both Python 2.x and 3.x, on windows the executable must be named python.exe)

These requirements can be either installed with your favourite package manager or with installers from the projects' websites. Below are some examples of ways to set up.

windows-msvc Specific Setup

1. rustup default stable-x86_64-pc-windows-msvc
2. Install Build Tools for Visual Studio 2017. If you have already been using this toolchain then its probably already installed.
3. Install msys2, following ALL of the instructions.
4. Then in the msys2 terminal run: pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-python2 mingw-w64-x86_64-ninja
5. Add the msys2 mingw64 binary path to the PATH environment variable.

Windows-gnu Specific Setup

windows-gnu toolchain is not supported but you can instead cross-compile to windows-gnu from windows-msvc

Steps 1 and 2 are to workaround rust-lang/rust#49078 by using the same mingw that rust uses.

1. Download and extract https://s3-us-west-1.amazonaws.com/rust-lang-ci2/rust-ci-mirror/x86_64-6.3.0-release-posix-seh-rt_v5-rev2.7z
2. Add the absolute path to mingw64\bin to your PATH environment variable. (This path needs to be before the msys2 path)
3. Run the command: rustup default stable-x86_64-pc-windows-msvc
4. Run the command: rustup target install x86_64-pc-windows-gnu
5. Install Build Tools for Visual Studio 2017. If you have already been using this toolchain then it's probably already installed.
6. Install msys2, following ALL of the instructions.
7. Then in the msys2 terminal run: pacman --noconfirm -Syu mingw64/mingw-w64-x86_64-pkg-config mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-make mingw-w64-x86_64-python2 mingw-w64-x86_64-ninja
8. Add the msys2 mingw64 binary path to the PATH environment variable.
9. Any cargo command that builds the project needs to include --target x86_64-pc-windows-gnu e.g. to run: cargo run --target x86_64-pc-windows-gnu

Linux Specific Setup

Use your package manager to install the required dev-tools and Vulkan drivers

For example on ubuntu:

sudo apt-get install build-essential git python cmake libvulkan-dev vulkan-tools

On arch based system

sudo pacman -Sy base-devel git python cmake vulkan-devel --noconfirm

macOS and iOS Specific Setup

Vulkan is not natively supported by macOS and iOS. However, there exists MoltenVK an open-source Vulkan implementation on top of Apple's Metal API. This allows vulkano to build and run on macOS and iOS platforms.

The easiest way to get vulkano up and running with MoltenVK is to install the Vulkan SDK for macOS. There are installation instructions on the LunarG website.

On iOS, vulkano links directly to the MoltenVK framework. There is nothing else to do besides installing it. Note that the Vulkan SDK for macOS also comes with the iOS framework.

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

vulkano's Issues

Enum renamed

VK_COLORSPACE_SRGB_NONLINEAR_KHR was renamed to VK_COLOR_SPACE_SRGB_NONLINEAR_KHR in the specs.

The value remains in the same.

Obtuse runtime panic when Vulkan is not installed

thread '<main>' panicked at 'called `Result::unwrap()` on an `Err` value: "The specified module could not be found. (os error 126)"', ../src/libcore\result.rs:688
Process didn't exit successfully: `target\debug\vulkano-test.exe` (exit code: 101)

This error message could be a little clearer, such as "Vulcan not installed".

This is totally to help end users and not idiotic coders who may or may not have forgot to check whether Vulkan was actually supported on his system.

Allow creating a debug callback at instance creation

Since this is now allowed by the specs.

Building on linux

Ok, so I ran into several problems when building on linux, one of which is easily solved:

1. KhronosGroup/glslang does not compile on linux with your included version. This issue was fixed by KhronosGroup/glslang#172 , so you should update that.
2. There is an error when building winit. I'm using multirust so I'm not really sure if this happens with a normal rust install. This is the output:

Compiling winit v0.4.8 (https://github.com/tomaka/winit#b4d4fee8)
/home/kokxx/.multirust/toolchains/nightly/cargo/git/checkouts/winit-a80c9921f4b7860e/master/src/api/x11/ffi.rs:14:5: 14:60 error: environment variable `OUT_DIR` not defined
/home/kokxx/.multirust/toolchains/nightly/cargo/git/checkouts/winit-a80c9921f4b7860e/master/src/api/x11/ffi.rs:14     include!(concat!(env!("OUT_DIR"), "/glx_bindings.rs"));
                                                                                                                      ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/kokxx/.multirust/toolchains/nightly/cargo/git/checkouts/winit-a80c9921f4b7860e/master/src/api/x11/ffi.rs:14:5: 14:60 error: couldn't read "/home/kokxx/.multirust/toolchains/nightly/cargo/git/checkouts/winit-a80c9921f4b7860e/master/src/api/x11/0/glx_bindings.rs": No such file or directory (os error 2)
/home/kokxx/.multirust/toolchains/nightly/cargo/git/checkouts/winit-a80c9921f4b7860e/master/src/api/x11/ffi.rs:14     include!(concat!(env!("OUT_DIR"), "/glx_bindings.rs"));
                                                                                                                      ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Could not compile `winit`.

To learn more, run the command again with --verbose.

Check the status of VK_KHR_sampler_mirror_clamp_to_edge

I'm not sure if that thing is core or an extension or something else.

dst/dest inconsistency

Some parts of the library (eg. struct members or function names) use dst and some others use dest as a shorthand for "destination".

I suggest that they should just all be renamed to "destination", and "src" renamed to "source".

Consider google/shaderc for shader compilation.

Compiling libshaderc google/shaderc might work for better integration.

Let buffers and images manage pipeline barriers manually

Basically I'm unsatisfied with the Image and Buffer traits and their "block" system.

Instead of using blocks, these traits should return some kind of CommandBufferBuildState object that contains the logic of managing barriers.
While we're at it, they should also return some kind of SubmissionSync object that the command buffer invokes to determine the dependencies and transitions.

Need to finish #33 before doing this.

Add an easy way to generate mipmaps

Add a trait in the image module that is implemented on command buffer builders:

pub fn trait CommandBufferImageExt {
    fn generate_mipmaps<I>(self, image: &Arc<I>) -> Self where I: Image;
}

impl CommandBufferImageExt for CommandBufferBuilder {
    ...
}

So that users can easily do this operation without using a for loop.

Rename CommandBufferPool to CommandPool?

CommandBufferPool is named "Command Pool" in the spec. I think vulkano should use the same names as the spec when there isn't a good reason not to.

Why Lifetimes?

I'm trying to build a struct that has fields for both the vulkano Instance and the PhysicalDevice I am using. In the new function, I first create an Instance, then I create a PhysicalDevice from it and then I create and return the instance of the struct that contains both:

// ...
pub struct Renderer<'a> {
    instance: std::sync::Arc<vk::instance::Instance>,
    physical_device: vk::instance::PhysicalDevice<'a>,
}

impl<'a> Renderer<'a> {
    pub fn new() -> Renderer<'a> {
        // ...
        let instance = vk::instance::Instance::new(Some(&app_info), &extensions, &[]).unwrap(); // TODO: deal with errors
        let physical_device = vk::instance::PhysicalDevice::enumerate(&instance).next().unwrap(); // TODO: choose correct device

        Renderer {
            instance: instance,
            physical_device: physical_device,
        }
    }
}

I get the following error:

renderer.rs:28:72: 28:80 error: `instance` does not live long enough
renderer.rs:28         let physical_device = vk::instance::PhysicalDevice::enumerate(&instance).next().unwrap(); // TODO: choose correct device
                                                                                      ^~~~~~~~
renderer.rs:14:34: 34:6 note: reference must be valid for the lifetime 'a as defined on the block at 14:33...
renderer.rs:14     pub fn new() -> Renderer<'a> {
renderer.rs:15         let app_info = vk::instance::ApplicationInfo {
renderer.rs:16             application_name: "vulkano-test",
renderer.rs:17             application_version: 1,
renderer.rs:18             engine_name: "vulkano-test",
renderer.rs:19             engine_version: 1,
               ...
renderer.rs:27:96: 34:6 note: ...but borrowed value is only valid for the block suffix following statement 2 at 27:95
renderer.rs:27         let instance = vk::instance::Instance::new(Some(&app_info), &extensions, &[]).unwrap(); // TODO: deal with errors
renderer.rs:28         let physical_device = vk::instance::PhysicalDevice::enumerate(&instance).next().unwrap(); // TODO: choose correct device
renderer.rs:29
renderer.rs:30         Renderer {
renderer.rs:31             instance: instance,
renderer.rs:32             physical_device: physical_device,
               ...
error: aborting due to previous error
error: Could not compile `vulkano-test`.

If I understand this correctly, I would have to pass a reference to the Renderer's instance to PhysicalDevice::enumerate in order for Rust to understand that the Instance doesn't disappear after the function has finished. But then I would have to create the Renderer before the PhysicalDevice, which would mean that it can't contain the PhysicalDevice. (I may be misunderstanding things as I'm new to Rust.)

I don't think PhysicalDevice needs to use a lifetime, though, as the lifetime is just for a reference to an Arc. But Arc already makes sure that the Instance won't be destroyed before the PhysicalDevice, right? So I think that

pub struct PhysicalDevice<'a> {
    instance: &'a Arc<Instance>,
    device: usize,
}

could be replaced by

pub struct PhysicalDevice {
    instance: Arc<Instance>,
    device: usize,
}

and enumerate and from_index could just clone the Arc instead of saving a reference to it.
Again, I'm new to Rust and may be misunderstanding things. I'm sorry if I'm wasting your time with my confusion. ;)

Optimize the memory pool

Using a memory pool to manage memory is encouraged in Vulkan.
Not only it is encouraged, but since the number of simultaneous allocations is limited in Vulkan it can also be mandatory on some systems if you don't want to run into OOM errors.

Handle optimalBufferCopy limits

These limits are optional and represent an additional alignment for when you want optimal buffer copy performances.

There should be a way in vulkano to request this when creating a buffer.

Failing to run examples

Hi there, I have Windows Insider with 364.51 NVIDIA Drivers. and Im using rust 1.7 mscv from https://static.rust-lang.org/dist/rust-1.7.0-x86_64-pc-windows-msvc.msi and with VS2015 community.

Do I need nightly or something? I dont think because cargo build ends with a lot of warnings but 0 errors.

And I get

cargo run --example buffers_copy
   Compiling vulkano v0.1.0 (file:///Z:/tyoc/Documentos/GitHub/vulkano/vulkano)
examples\buffers_copy.rs:8:20: 8:70 error: this function takes 3 parameters but 2 parameters were supplied [E0061]
examples\buffers_copy.rs:8     let instance = vulkano::instance::Instance::new(Some(&app), None).expect("failed to create instance");
                                              ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
examples\buffers_copy.rs:8:20: 8:70 help: run `rustc --explain E0061` to see a detailed explanation
examples\buffers_copy.rs:18:28: 19:93 error: this function takes 5 parameters but 4 parameters were supplied [E0061]
examples\buffers_copy.rs:18     let (device, queues) = vulkano::device::Device::new(&physical, physical.supported_features(),
examples\buffers_copy.rs:19                                                         [(queue, 0.5)].iter().cloned(), &[])
examples\buffers_copy.rs:18:28: 19:93 help: run `rustc --explain E0061` to see a detailed explanation
examples\buffers_copy.rs:40:83: 40:89 error: no method named `lock` found for type `alloc::arc::Arc<vulkano::device::Queue>` in the current scope
examples\buffers_copy.rs:40     let cb_pool = vulkano::command_buffer::CommandBufferPool::new(&device, &queue.lock().unwrap().family())
                                                                                                              ^~~~~~
examples\buffers_copy.rs:48:31: 48:37 error: no method named `lock` found for type `alloc::arc::Arc<vulkano::device::Queue>` in the current scope
examples\buffers_copy.rs:48         let mut queue = queue.lock().unwrap();
                                                          ^~~~~~
examples\buffers_copy.rs:49:24: 49:42 error: no method named `submit` found for type `alloc::arc::Arc<vulkano::command_buffer::outer::PrimaryCommandBuffer>` in the current scope
examples\buffers_copy.rs:49         command_buffer.submit(&mut queue).unwrap();
                                                   ^~~~~~~~~~~~~~~~~~
error: aborting due to 5 previous errors

And

cargo run --example image
   Compiling vulkano v0.1.0 (file:///Z:/tyoc/Documentos/GitHub/vulkano/vulkano)
examples\image.rs:28:65: 28:68 error: mismatched types:
 expected `&vulkano::instance::extensions::InstanceExtensions`,
    found `&[_; 0]`
(expected struct `vulkano::instance::extensions::InstanceExtensions`,
    found array of 0 elements) [E0308]
examples\image.rs:28     let instance = vulkano::instance::Instance::new(Some(&app), &[], &extensions).expect("failed to create instance");
                                                                                     ^~~
examples\image.rs:28:65: 28:68 help: run `rustc --explain E0308` to see a detailed explanation
examples\image.rs:28:20: 28:52 error: the trait `core::iter::Iterator` is not implemented for the type `&vulkano::instance::extensions::InstanceExtensions` [E0277]
examples\image.rs:28     let instance = vulkano::instance::Instance::new(Some(&app), &[], &extensions).expect("failed to create instance");
                                        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
examples\image.rs:28:20: 28:52 help: run `rustc --explain E0277` to see a detailed explanation
examples\image.rs:28:20: 28:52 note: `&vulkano::instance::extensions::InstanceExtensions` is not an iterator; maybe try calling `.iter()` or a similar method
examples\image.rs:28:20: 28:52 note: required by `vulkano::instance::instance::Instance::new`
examples\image.rs:41:28: 42:93 error: this function takes 5 parameters but 4 parameters were supplied [E0061]
examples\image.rs:41     let (device, queues) = vulkano::device::Device::new(&physical, physical.supported_features(),
examples\image.rs:42                                                         [(queue, 0.5)].iter().cloned(), &[])
examples\image.rs:41:28: 42:93 help: run `rustc --explain E0061` to see a detailed explanation
examples\image.rs:203:9: 205:99 error: this function takes 11 parameters but 10 parameters were supplied [E0061]
examples\image.rs:203         vulkano::pipeline::GraphicsPipeline::new(&device, &vs.main_entry_point(), &ia, &viewports,
examples\image.rs:204                                                  &raster, &ms, &blend, &fs.main_entry_point(),
examples\image.rs:205                                                  &pipeline_layout, renderpass.subpass(0).unwrap())
examples\image.rs:203:9: 205:99 help: run `rustc --explain E0061` to see a detailed explanation
examples\image.rs:205:79: 205:89 error: no method named `subpass` found for type `alloc::arc::Arc<vulkano::framebuffer::RenderPass<main::renderpass::Layout>>` in the current scope
examples\image.rs:205                                                  &pipeline_layout, renderpass.subpass(0).unwrap())
                                                                                                    ^~~~~~~~~~
examples\image.rs:226:36: 226:50 error: no method named `submit` found for type `alloc::arc::Arc<vulkano::command_buffer::outer::PrimaryCommandBuffer>` in the current scope
examples\image.rs:226         command_buffers[image_num].submit(&queue).unwrap();
                                                         ^~~~~~~~~~~~~~
error: aborting due to 6 previous errorsZ

And here is a different one

cargo run --example teapot
   Compiling vulkano v0.1.0 (file:///Z:/tyoc/Documentos/GitHub/vulkano/vulkano)
examples\teapot.rs:13:5: 13:20 warning: unused import, #[warn(unused_imports)] on by default
examples\teapot.rs:13 use std::ffi::OsStr;
                          ^~~~~~~~~~~~~~~
examples\teapot.rs:14:5: 14:36 warning: unused import, #[warn(unused_imports)] on by default
examples\teapot.rs:14 use std::os::windows::ffi::OsStrExt;
                          ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
examples\teapot.rs:15:5: 15:13 warning: unused import, #[warn(unused_imports)] on by default
examples\teapot.rs:15 use std::mem;
                          ^~~~~~~~
Z:\tyoc\Documentos\GitHub\vulkano\vulkano\target\debug\build\vulkano-fcfdb4e00fb9d264\out/shaders/examples/teapot_fs.glsl:50:45: 50:52 warning: unused variable: `layouts`, #[warn(unused_variables)] on by default
Z:\tyoc\Documentos\GitHub\vulkano\vulkano\target\debug\build\vulkano-fcfdb4e00fb9d264\out/shaders/examples/teapot_fs.glsl:50     fn decode_descriptor_set_layouts(&self, layouts: Self::DescriptorSetLayouts)
                                                                                                                                                                         ^~~~~~~
examples\teapot.rs:19:10: 19:80 note: in this expansion of include!
Z:\tyoc\Documentos\GitHub\vulkano\vulkano\target\debug\build\vulkano-fcfdb4e00fb9d264\out/shaders/examples/teapot_fs.glsl:58:38: 58:42 warning: unused variable: `sets`, #[warn(unused_variables)] on by default
Z:\tyoc\Documentos\GitHub\vulkano\vulkano\target\debug\build\vulkano-fcfdb4e00fb9d264\out/shaders/examples/teapot_fs.glsl:58     fn decode_descriptor_sets(&self, sets: Self::DescriptorSets)
                                                                                                                                                                  ^~~~
examples\teapot.rs:19:10: 19:80 note: in this expansion of include!
     Running `target\debug\examples\teapot.exe`
thread '<main>' panicked at 'failed to create instance: LayerNotPresent', ../src/libcore\result.rs:709
Process didn't exit successfully: `target\debug\examples\teapot.exe` (exit code: 101)

And

cargo run --example triangle
   Compiling vulkano v0.1.0 (file:///Z:/tyoc/Documentos/GitHub/vulkano/vulkano)
examples\triangle.rs:24:65: 24:96 error: mismatched types:
 expected `&vulkano::instance::extensions::InstanceExtensions`,
    found `&[&str; 1]`
(expected struct `vulkano::instance::extensions::InstanceExtensions`,
    found array of 1 elements) [E0308]
examples\triangle.rs:24     let instance = vulkano::instance::Instance::new(Some(&app), &["VK_LAYER_LUNARG_draw_state"], &extensions).expect("failed to create instance");
                                                                                        ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
examples\triangle.rs:24:65: 24:96 help: run `rustc --explain E0308` to see a detailed explanation
examples\triangle.rs:24:20: 24:52 error: the trait `core::iter::Iterator` is not implemented for the type `&vulkano::instance::extensions::InstanceExtensions` [E0277]
examples\triangle.rs:24     let instance = vulkano::instance::Instance::new(Some(&app), &["VK_LAYER_LUNARG_draw_state"], &extensions).expect("failed to create instance");
                                           ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
examples\triangle.rs:24:20: 24:52 help: run `rustc --explain E0277` to see a detailed explanation
examples\triangle.rs:24:20: 24:52 note: `&vulkano::instance::extensions::InstanceExtensions` is not an iterator; maybe try calling `.iter()` or a similar method                                                                                examples\triangle.rs:24:20: 24:52 note: required by `vulkano::instance::instance::Instance::new`
examples\triangle.rs:68:28: 70:89 error: this function takes 5 parameters but 4 parameters were supplied [E0061]        examples\triangle.rs:68     let (device, queues) = vulkano::device::Device::new(&physical, physical.supported_features(),
examples\triangle.rs:69                                                         [(queue, 0.5)].iter().cloned(),
examples\triangle.rs:70                                                         &["VK_LAYER_LUNARG_draw_state"])
examples\triangle.rs:68:28: 70:89 help: run `rustc --explain E0061` to see a detailed explanation
examples\triangle.rs:204:9: 207:81 error: this function takes 11 parameters but 10 parameters were supplied [E0061]
examples\triangle.rs:204         vulkano::pipeline::GraphicsPipeline::new(&device, &vs.main_entry_point(), &ia, &viewports,
examples\triangle.rs:205                                                  &raster, &ms, &blend, &fs.main_entry_point(),
examples\triangle.rs:206                                                  &vulkano::descriptor_set::PipelineLayout::new(&device, vulkano::descriptor_set::EmptyPipelineDesc, ()).unwrap(),
examples\triangle.rs:207                                                  renderpass.subpass(0).unwrap()).unwrap()
examples\triangle.rs:204:9: 207:81 help: run `rustc --explain E0061` to see a detailed explanation
examples\triangle.rs:207:61: 207:71 error: no method named `subpass` found for type `alloc::arc::Arc<vulkano::framebuffer::RenderPass<main::renderpass::Layout>>` in the current scope
examples\triangle.rs:207                                                  renderpass.subpass(0).unwrap()).unwrap()
                                                                                     ^~~~~~~~~~
error: aborting due to 5 previous errors

Spelling issue in triangle example

"Only", not "Onle".

Use the ImageClearValue trait when clearing at the start of a render pass

Instead of directly FormatDesc::ClearValue.

Consider an `Aligned` wrapper around types in generated struct definitions

Example GLSL code:

struct Foo {
    vec3 a;
    f32 b;
}

This is the Rust code that is currently generated:

#[repr(C)]
#[derive(Default)]
struct Foo  {
    a: [f32; 3],
    _dummy: [u8; 4],
    b: f32,
}

But this could be an alternative solution:

#[repr(C)]
struct Foo  {
    a: Aligned<[f32; 3], Align16>,
    b: f32,
}

Both have their advantages and drawbacks.

Synchronization clarifications in the specs

Version 1.0.18 changed many things in regard to synchronization.

Basically, everything you submit to a single queue is executed in order (both order of submission and order of the command buffers within a batch) with the exception that the GPU can change the order of commands between pipeline barriers, semaphore waits/signals and fence signals.

In other words, pipeline barriers, semaphores and fences apply to the entire queue (including anything that was submitted before) and not just the current command buffer or the current batch.

Sparse operations are not concerned by this and must be explicitly protected by a semaphore.

Notes from the GDC sessions

Some "good practices" taken from the GDC sessions:

• Use one command buffer/descriptor pool per thread, don't synchronize them.
• Don't try to be smarter than the driver with host allocation by just wrapping malloc().
• Allocate pools of memory, don't allocate one memory per object. (#14)
• Allocate multiple command buffers at once.
• Don't overuse semaphores and fences.
• Submit relatively large batches of command buffers at once.
• Tell the truth about Load/Store/DontCare when creating a render pass.
• Always use the BY_REGION bit in subpass dependencies if possible.
• Create the framebuffer with the renderpass that it's going to be used with.
• Don't create über framebuffers. Specialize.
• Only use vkQueueWaitIdle/vkDeviceWaitIdle at shutdown.

Vulkano should make it easy to use the good practices by default.

Not on crates.io

The readme says you can use Vulkano with vulkano = "0.1", but Vulkano is not on crates.io, so that doesn't work. You can use it with vulkano = { git = "https://github.com/tomaka/vulkano" }.

libvulkan.so: cannot open shared object file: No such file or directory

Vulkano tries to load the vulkan system library on unix by looking up libvulkan.so. This library does not exist on Ubuntu (after installing vulkan-utils) or in the steam runtime. The library is called libvulkan.so.1 (which is a symlink to libvulkan.so.1.0.8. ). One could create a symlink libvulkan.so -> libvulkan.so.1 but I think there is no reason not to just load libvulkan.so.1

see #164

Magic values in pipeline_layout macro

I am trying to use this macro to produce descriptors for a compute shader that should use the storage image type, but it appears the pre-implemented image types all set 'sampled=true'.

Is there a way to specify the values I'd like to use in each struct (DescriptorImageDesc in this case)? Or would it be acceptable for me to add the missing implementation - although I see how the permutation of options could bloat the API quickly.

Missing?:
vulkano::descriptor::pipeline_layout::custom_pipeline_macro::StorageImage;

Thanks for this awesome library!

Automatically generate structs of the SPIR-V parser from the JSON specs

https://github.com/KhronosGroup/SPIRV-Headers/blob/master/include/spirv/1.0/spirv.core.grammar.json

Write a build script that parses this file and generates Rust structs and enums.

About OomError

Most functions in Vulkan can return VK_ERROR_OUT_OF_HOST_MEMORY and VK_ERROR_OUT_OF_DEVICE_MEMORY. In fact most functions can only return one of these two errors.

This is reflected in vulkano by the fact that a lot of functions can return OomError.

However in practice it is very unlikely that an out-of-memory error actually happens, with the exception of vkAllocateMemory.

The API would be much more convenient to use if an out of memory error returned by Vulkan resulted in a panic instead of returning an error, like it's the case for the core Rust.
Again, with the exception of DeviceMemory which would still return OomError.

Executing a secondary CB invalidates the CB state

Creating an uninitialized CPU-accessible buffer or image should be unsafe

Asking on IRC, it seems that uninitialized memory really is unsafe. It is an undefined behavior to read from it, and the only reason why things work today is that the compiler doesn't realize it's uninitialized.

glslang_validator not copied during build correctly

I'm on linux, and trying to compile the examples is failing because glslang_validator is not generating the output file it is supposed to. It turns out that my
...vulkano/examples/target/debug/build/glsl-to-spirv-11036aceadb12936/out/glslang_validator application is 0 bytes. It returns success when you run (apparently), but it doesn't do anything.

If I manually copy ...vulkano/examples/target/debug/build/glsl-to-spirv-11036aceadb12936/out/bin/glslangValidator to ...vulkano/examples/target/debug/build/glsl-to-spirv-11036aceadb12936/out/glslang_validator then it builds.

I assume that is what this code in glsl-to-spirv/build/build.rs is supposed to do:

    if let Err(_) = fs::hard_link(&path, &out_file) {
        fs::copy(&path, &out_file).expect("failed to copy executable");
    }

However I was unable to figure out how to debug that code. (My attempts to print out paths didn't add any output to cargo build).

Obtuse runtime panic when struct field name doesn't match shader attribute name

When a vertex struct field name doesn't match its respective shader attribute name, you get a runtime panic which is hard to decipher.

---

Original, uninformed issue:

If a struct's field is named col and it is used as a vertex, the program will crash at runtime with an error like this:

thread '<main>' panicked at 'missing vertex attrib', src/libcore/optio
n.rs:704                                                             
note: Run with `RUST_BACKTRACE=1` for a backtrace.
error: Process didn't exit successfully: `target/debug/triangle` (exit code: 101)

To reproduce, just s/position/col in the triangle example.

This caused me a great deal of frustration when I was trying to modify the triangle example to accept a buffer of vertex colours. Changing the name of the field wasn't something I thought to try for a long time.

Extensions API

There are already some new layers and extensions, like the steam overlay, that aren't covered in the Vulkan spec. They should be useable with Vulkano, but they shouldn't all be included in the Vulkano crate.

I propose an extensions API that makes it possible to implement 3rd-party extension. Standard extensions like the WSI extensions would also use that API, but would still be implemented in the Vulkano crate.

I will create a pull request with an example of how that might look. If you're okay with it, I'll continue to implement it and create the missing comments.

Resources management suggestion

This is mostly a post-it so that I don't forget this idea.

It should be possible to transition resources between states encoded in the type system, like this:

struct Buffer {
    ...
}

struct FenceLockedBuffer {
    ...
}

struct LockedBuffer {
    ...
}

You could only modify a Buffer. When executing a command, the user could choose between creating a fence or not. If creating a fence, the Buffer would turn into a FenceLockedBuffer. If not creating a fence, the Buffer would turn into a LockedBuffer.

A FenceLockedBuffer could be turned back into a Buffer by blocking. Both FenceLockedBuffer and LockedBuffer could be used when executing commands.

However this system doesn't say how to handle the relationship between buffers/textures and command buffers.

Consider using Version for app/engine version

Using the type Version for application_version and engine_version in ApplicationInfo and providing an easy way to convert the crate version into a Version would be convenient.

Can't run teapot or image example

Both vulkano and the examples build just fine. The triangle example runs correctly. I can build and run the C++ Vulkan examples from LunarG/VulkanSamples. But when I try to run either the image or teapot example I get an error like this:

~/c/v/examples> cargo run --bin image
     Running `target/debug/image`
thread '<main>' panicked at 'failed to create instance: ExtensionNotPresent', ../src/libcore/result.rs:746
note: Run with `RUST_BACKTRACE=1` for a backtrace.
Process didn't exit successfully: `target/debug/image` (exit code: 101)

I'm on Arch Linux, and I installed the Vulkan development packages via pacman.

~/c/v/examples> pacman -Ss vulkan
extra/spirv-tools 1.0.3-1 (vulkan-devel) [installed]
    API and commands for processing SPIR-V modules
extra/vulkan-headers 1:1.0.12-1 (vulkan-devel) [installed]
    Vulkan header files
extra/vulkan-icd-loader 1.0.8.0-1 [installed]
    Vulkan Installable Client Driver (ICD) Loader
extra/vulkan-intel 0.0.3+3713+ga998e49-1 [installed]
    Intel's Vulkan mesa driver
extra/vulkan-man-pages 1:1.0.12-1 (vulkan-devel) [installed]
    Vulkan man pages
extra/vulkan-validation-layers 1.0.8.0-1 (vulkan-devel) [installed]
    Vulkan Software Development Kit

Forbid creating multiple swapchains from the same surface

Functions that return the wrong error

A list of functions that return the wrong error right now: (not complete)

• Swapchain::new
• Suface::is_supported
• Suface::get_capabilities
• Event::signaled
• command_buffer::inner::submit
• Fence::ready

vk-sys should be autogenerated from vk.xml

Instead of hand-coding all the definitions, they should be parsed from the same XML definitions that are used to create vulkan.h. This should also add support for the recent extensions for free. I have some WIP code that parses it and generates something that at least seems like rust, I'll try and beat it into shape so it can autogenerate vk-sys/lib.rs.

Handle bufferImageGranularity correctly

Section 11.6

There is an implementation-dependent limit, bufferImageGranularity, which specifies a page-like granularity at which buffer, linear image and optimal image resources must be placed in adjacent memory locations to avoid aliasing. Two resources which do not satisfy this granularity requirement are said to alias. Linear image resource are images created with VK_IMAGE_TILING_LINEAR and optimal image resources are those created with VK_IMAGE_TILING_OPTIMAL. bufferImageGranularity is specified in bytes, and must be a power of two. Implementations which do not require such an additional granularity may report a value of one.

MissingExtension VK_KHR_xlib_surface

When I try to run the examples on Ubuntu 16.04 I get the following error:

thread '

' panicked at 'called Result::unwrap() on an Err value: SurfaceCreationError(MissingExtension { name: "VK_KHR_xlib_surface" })', ../src/libcore/result.rs:746

The vulkan samples from SaschaWillems all run fine, so I think its not a problem of the vulkan install.

I’m running vulkano on Ubuntu 16.04 x64 with an AMD R9 380X with AMDGPU-Pro 16.30.3.

Add StagingImage

Add a StagingImage wrapper around images with linear layouts.
This allows users to directly write the pixel data in the image, then copy it to another image.

InstanceExtensions::platform_surface()

A function InstanceExtensions::target_surface() that returns InstanceExtensions with khr_surface and khr_(target)_surface (depending on compilation target) set to true would make multiplatform programming easier.

Vulkan bools should maybe not map to Rust bool

Rust supposes that bools always contain either 0 or 1. A GPU might not write the value 1 when you write true, although this needs to be checked from the specs.

Provide a way to query supported instance extensions

The Vulkan spec lists the function vkEnumerateInstanceExtensionProperties with which you can query for supported extensions. A function like InstanceExtensions::supported() which returns supported extensions would be useful. Should I implement it?

Add a description to the repo to make it easier to find

What the title says. Give it a Github description.

Doesn't build

Since 6ba0a6e, vulkano requires smallvec = { git = "https://github.com/tomaka/rust-smallvec", branch = "patch-1" } instead of smallvec = "0.1.6", but there is no branch "patch-1" for smallvec, so vulkano fails to build.

Keep Samplers alive in the Device

A cache of the samplers should be stored in the Device struct (with weak pointers to avoid a cyclic dependency). Creating a sampler should look in this cache first in order to avoid duplicates.

Implement RenderPassAttachmentsList<Arc<T>> on render passes with only one attachment

So that instead of:

Framebuffer::new(&device, [1024, 768, 1], render_pass::AList { color: &img })

You can write:

Framebuffer::new(&device, [1024, 768, 1], &img)

Change "panicks" to "panics"

Problem with triangle example

let pipeline = GraphicsPipeline::new(&device, GraphicsPipelineParams {
        // We need to indicate the layout of the vertices.
        // The type `SingleBufferDefinition` actually contains a template parameter corresponding
        // to the type of each vertex. But in this code it is automatically inferred.
        vertex_input: SingleBufferDefinition::new(),

I'm getting this error when trying to compile:

error: unable to infer enough type information about `_`; type annotations or generic parameter binding required [E0282]
      vertex_input: SingleBufferDefinition::new(),
                    ^~~~~~~~~~~~~~~~~~~~~~~~~~~

I'm using Rust 1.9 and Vulkano straight from this repo.

Memory leak in command pools

#125 introduces a memory leak. When a thread gets destroyed, the corresponding element in per_thread isn't destroyed.

Show warnings generated by glslang

Once rust-lang/cargo#2630 lands

Add support for EXT_debug_marker

https://github.com/KhronosGroup/Vulkan-Docs/tree/1.0-VK_EXT_debug_marker