1<img align="left" alt="" src="logo.png" height="150" /> 2 3# [Vulkano](https://vulkano.rs) 4 5[](https://github.com/vulkano-rs/vulkano/actions?query=workflow%3ARust) 6[](https://discord.gg/bncB9W2VDV) 7[](https://vulkano.rs/) 8<br/> 9[](https://crates.io/crates/vulkano) 10[](https://crates.io/crates/vulkano-shaders) 11[](https://crates.io/crates/vulkano-util) 12[](https://crates.io/crates/vulkano-win) 13<br/> 14[](https://docs.rs/vulkano) 15[](https://docs.rs/vulkano-shaders) 16[](https://docs.rs/vulkano-util) 17[](https://docs.rs/vulkano-win) 18 19Vulkano is a Rust wrapper around [the Vulkan graphics API](https://www.khronos.org/vulkan/). 20It follows the Rust philosophy, which is that as long as you don't use unsafe code you shouldn't 21be able to trigger any undefined behavior. In the case of Vulkan, this means that non-unsafe code 22should always conform to valid API usage. 23 24What does vulkano do? 25 26- Provides a low-levelish API around Vulkan. It doesn't hide what it does but provides some 27 comfort types. 28- Plans to prevent all invalid API usages, even the most obscure ones. The purpose of Vulkano 29 is not to simply let you draw a teapot, but to cover all possible usages of Vulkan and detect all 30 the possible problems in order to write robust programs. Invalid API usage is prevented thanks to 31 both compile-time checks and runtime checks. 32- Can handle synchronization on the GPU side for you (unless you choose to do that yourself), as this 33 aspect of Vulkan is both annoying to handle and error-prone. Dependencies between submissions are 34 automatically detected, and semaphores are managed automatically. The behavior of the library can 35 be customized thanks to unsafe trait implementations. 36- Tries to be convenient to use. Nobody is going to use a library that requires you to browse 37 the documentation for hours for every single operation. 38 39### Comparison 40 41Comparison to other well-known Graphics APIs in Rust ecosystem. 42 43| Name | Open-sourced Since | API Level | Notable Features | 44| ---- | ------------------ | --------- | ------------- | 45| 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. | 46| [Wgpu](https://github.com/gfx-rs/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. | 47| [Miniquad](https://github.com/not-fl3/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. | 48| [Sierra](https://github.com/zakarumych/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](https://gitlab.com/Friz64/erupt). Supports Ray Tracing Pipeline. | 49| [Glium](https://github.com/glium/glium) | October, 2014 | High-level Rust API wrapping OpenGL | OpenGL only. | 50| [Ash](https://github.com/MaikKlein/ash) | August, 2016 | Low-level API for Vulkan. | Unsafe Vulkan API bindings. | 51| [Erupt](https://gitlab.com/Friz64/erupt) | April, 2020 | Low-level API for Vulkan. | Unsafe Vulkan API bindings. | 52 53Please note that by the current date none of the known projects in the ecosystem(including Vulkano) 54reached stable release versions and the final design goals, their APIs are changing from time 55to time in a breakable way too, and there could be bugs and unfinished features too. 56 57However, most of the projects mentioned above are already established definitive structures, all 58feature breaking changes will likely be straightforward to fix in user code, and most of them 59are maintained. As such we can recommend using any of them in the 3rd party code. 60The choice depends on the end project's goals and requirements, and we recommend examining 61their actual set of features and API capabilities beforehand. 62 63### Projects using Vulkano 64 65We started collecting this list just recently and it would be appreciated if you help us by 66contributing(opening a PR) into [README.md](https://github.com/vulkano-rs/vulkano/blob/master/README.md). 67 68| Project Name | Description | 69| ------------ | ----------- | 70| [Basalt](https://github.com/AustinJ235/basalt) | GUI framework for Desktop applications | 71| [Ferret](https://github.com/Rua/ferret) | Doom-compatible game engine | 72| [Sandbox](https://github.com/hakolao/sandbox) | 2D Pixel Physics Simulator | 73| [Egui Winit Vulkano](https://github.com/hakolao/egui_winit_vulkano) | Vulkano integration with Egui | 74| [VideowindoW](https://www.videowindow.eu/) | Uses Vulkano under the hood to enable asynchronous video stream compositing | 75| [Korangar](https://github.com/vE5li/korangar) | A Vulkan based Ragnarok Online client | 76 77We would love to help you keep your project in sync with the most recent changes in Vulkano 78if you give us feedback by adding your project to this list. 79 80Thanks in advance! 81 82## Documentation and Resources 83 84To get started you are encouraged to use the following resources: 85 86- The [examples](https://github.com/vulkano-rs/vulkano/tree/master/examples) folder in this repository. 87 - [docs.rs](https://docs.rs/vulkano) - Full Vulkano API documentation 88 - The guide on [vulkano.rs](https://vulkano.rs/guide/introduction) - Starts with trivial compute 89 examples (~50 lines of code) and then works up to rendering triangles and mandelbrots. 90 The guide is currently outdated a little. We are planning to update it in the future, but it's 91 a good place to start understanding the base building blocks of Vulkano API. 92 - Github [Issues](https://github.com/vulkano-rs/vulkano/issues) - Raise a topic, ask a question 93 or report a bug. The new topics there are watched regularly by maintainers and other 94 community users. 95 - Gitter [Chat](https://gitter.im/vulkano-rs/Lobby) - Another place to raise a question. However, 96 the chat is not maintained regularly at this moment. Better use Github Issues for this purpose. 97 98## Contributing 99 100Contributions are very welcome! Feel free to submit pull requests, to open questions and topics 101in the [Issues](https://github.com/vulkano-rs/vulkano/issues) section. 102 103The project was initially developed by Pierre Krieger(Tomaka), who established Vulkano's base 104design goals, and the code structure. In the meantime, development is driven by Vulkano 105community members. 106 107**New Pull Requests are usually scheduled for review by the end of each week.** 108The older PRs that are already in review have priority over the new ones. We are trying to push 109development forward as quick as possible, but the review process sometimes takes time, 110please be patient as the maintainers need time to check everything properly. 111 112If something needs to get promoted urgently, please ping current Vulkano 113maintainer([@Eliah-Lakhin](https://github.com/Eliah-Lakhin/)) in the PR's 114or Issue's comments. 115 116If your change adds, removes or modifies a trait or a function, please 117specify changelog entries **in the Pull Request description**(not in the changelog file directly). 118They will be transferred to the changelog right after the PR merge. 119 120Every PR must pass tests in order to be merged to `master`. 121 122Minor releases are usually happening between 1 to 3 months averagely depending on grow 123of unreleased and breaking changes in `master` 124 125### Repository Structure 126 127This repository contains four libraries: 128 129- `vulkano` is the main one. 130- `vulkano-shaders` provides the `shader!` macro for compiling glsl shaders. 131- `vulkano-util` provides a variety of utility functions to streamline certain common operations such as device and swapchain creation. 132- `vulkano-win` provides a safe link between vulkano and the `winit` library which can create 133 a window to render to. 134 135In order to run tests, run `cargo test --all` at the root of the repository. Make sure your Vulkan 136driver is up to date before doing so. 137 138### Hall of Fame 139 140We would love to mention some members, who put significant contributions to this project: 141- Pierre Krieger. The initial developer. [Patreon page](https://www.patreon.com/tomaka). 142- Lucas Kent. Maintainer. [Patreon page](https://www.patreon.com/rukai). 143- Austin Johnson. Maintainer. [Patreon page](https://www.patreon.com/austinj235). 144- Rua. An active developer, who put a lot of effort to improve Vulkano and constantly keeping it up to date. 145- **You!** Thanks to your help, contributions, improvements, bug reports and user experience 146 to make this project one of the major Rust graphics API library in Rust! 147 148## Setup and Troubleshooting 149 150Vulkano uses [shaderc-rs](https://github.com/google/shaderc-rs) for shader compilation. Refer to shaderc-rs documentation to provide a pre-built libshaderc for faster build times. 151 152Note that in general vulkano does **not** require you to install the official Vulkan SDK. This is 153not something specific to vulkano (you don't need the SDK to write programs that use Vulkan, even 154without vulkano), but many people are unaware of that and install the SDK thinking that it is 155required. However, macOS and iOS platforms do require a little more Vulkan setup since it is not 156natively supported. See below for more details. 157 158Unless you provide libshaderc, in order to build libshaderc with the shaderc-sys crate, the following tools must be installed and available on `PATH`: 159- [CMake](https://cmake.org/) 160- [Ninja](https://ninja-build.org/) Is optional except when building with MSVC. It may speed up build time for libshaderc. 161- [Python](https://www.python.org/) (works with both Python 2.x and 3.x, on windows the executable must be named `python.exe`) 162 163These requirements can be either installed with your favourite package manager or with installers 164from the projects' websites. Below are some examples of ways to set up. 165 166### windows-msvc Specific Setup 167 1681. `rustup default stable-x86_64-pc-windows-msvc` 1692. Install [Build Tools for Visual Studio 2017](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017). If you have already been using this toolchain then its probably already installed. 1703. Install [msys2](https://www.msys2.org/), following ALL of the instructions. 1714. Then in the msys2 terminal run: `pacman --noconfirm -Syu mingw-w64-x86_64-cmake mingw-w64-x86_64-python2 mingw-w64-x86_64-ninja` 1725. Add the msys2 mingw64 binary path to the PATH environment variable. 173 174### Windows-gnu Specific Setup 175 176windows-gnu toolchain is not supported but you can instead cross-compile to windows-gnu from windows-msvc 177 178Steps 1 and 2 are to workaround https://github.com/rust-lang/rust/issues/49078 by using the same mingw that rust uses. 179 1801. 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 1812. Add the absolute path to mingw64\bin to your PATH environment variable. (This path needs to be before the msys2 path) 1823. Run the command: `rustup default stable-x86_64-pc-windows-msvc` 1834. Run the command: `rustup target install x86_64-pc-windows-gnu` 1845. Install [Build Tools for Visual Studio 2017](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2017). If you have already been using this toolchain then it's probably already installed. 1856. Install [msys2](https://www.msys2.org/), following ALL of the instructions. 1867. 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` 1878. Add the msys2 mingw64 binary path to the PATH environment variable. 1889. 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` 189 190### Linux Specific Setup 191 192Use your package manager to install the required dev-tools and Vulkan drivers 193 194For example on ubuntu: 195``` 196sudo apt-get install build-essential git python cmake libvulkan-dev vulkan-utils 197``` 198On arch based system 199``` 200sudo pacman -Sy base-devel git python cmake vulkan-devel --noconfirm 201``` 202 203### macOS and iOS Specific Setup 204 205Vulkan is not natively supported by macOS and iOS. However, there exists [MoltenVK](https://github.com/KhronosGroup/MoltenVK) 206an open-source Vulkan implementation on top of Apple's Metal API. This allows vulkano to build and run on macOS 207and iOS platforms. 208 209The easiest way to get vulkano up and running with MoltenVK is to install the 210[Vulkan SDK for macOS](https://vulkan.lunarg.com/sdk/home). There are [installation instructions](https://vulkan.lunarg.com/doc/sdk/latest/mac/getting_started.html) on the LunarG website. 211 212On iOS, vulkano links directly to the MoltenVK framework. There is nothing else to do besides 213installing it. Note that the Vulkan SDK for macOS also comes with the iOS framework. 214 215## License 216 217Licensed under either of 218 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) 219 * MIT license ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) 220at your option. 221 222### Contribution 223 224Unless you explicitly state otherwise, any contribution intentionally submitted 225for inclusion in the work by you shall be dual licensed as above, without any 226additional terms or conditions. 227
){kind=link}
){kind=link}