ash/README.md

166 lines
6.8 KiB
Markdown
Raw Normal View History

2017-04-07 18:04:14 +10:00
# Ash
2016-12-10 06:33:25 +11:00
2016-12-10 09:13:58 +11:00
A very lightweight wrapper around Vulkan
2016-12-10 06:38:22 +11:00
[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE-MIT)
[![LICENSE](https://img.shields.io/badge/license-apache-blue.svg)](LICENSE-APACHE)
2016-12-10 06:49:49 +11:00
[![Documentation](https://docs.rs/ash/badge.svg)](https://docs.rs/ash)
2016-12-10 06:38:22 +11:00
[![Build Status](https://travis-ci.org/MaikKlein/ash.svg?branch=master)](https://travis-ci.org/MaikKlein/ash)
2016-12-26 12:17:56 +11:00
[![Build status](https://ci.appveyor.com/api/projects/status/ed7757as3a4ebexn/branch/master?svg=true)](https://ci.appveyor.com/project/MaikKlein/ash/branch/master)
2016-12-10 06:33:25 +11:00
[![Join the chat at https://gitter.im/MaikKlein/ash](https://badges.gitter.im/MaikKlein/ash.svg)](https://gitter.im/MaikKlein/ash?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
2016-12-10 06:45:09 +11:00
[![Crates.io Version](https://img.shields.io/crates/v/ash.svg)](https://crates.io/crates/ash)
2016-12-23 12:01:36 +11:00
[![](https://tokei.rs/b1/github/maikklein/ash)](https://github.com/MaikKlein/ash)
2016-08-14 09:13:39 +10:00
2018-11-12 04:05:03 +11:00
## Overview
2018-11-12 04:06:48 +11:00
- [x] A true Vulkan API without compromises
- [x] Convenience features that don't limit the functionality
- [x] Function pointer loading
- [x] No validation, everything is **unsafe**
- [x] Generated from `vk.xml`
2018-11-12 04:05:03 +11:00
## Features
2016-12-28 14:31:48 +11:00
### Explicit returns with `Result`
2016-12-10 05:25:48 +11:00
```Rust
2017-04-30 23:46:38 +10:00
// function signature
2016-12-29 18:06:17 +11:00
pub fn create_instance(&self,
create_info: &vk::InstanceCreateInfo,
allocation_callbacks: Option<&vk::AllocationCallbacks>)
2017-04-30 23:46:38 +10:00
-> Result<Instance, InstanceError> { .. }
2017-01-05 18:35:37 +11:00
let instance = entry.create_instance(&create_info, None)
2016-12-29 18:06:17 +11:00
.expect("Instance creation error");
2016-12-10 05:25:48 +11:00
```
2018-11-12 04:05:03 +11:00
### Returns a `Vec<T>` (*when possible*) for functions that output multiple values.
2016-12-10 05:25:48 +11:00
```Rust
2016-12-24 07:41:16 +11:00
pub fn get_swapchain_images_khr(&self,
swapchain: vk::SwapchainKHR)
-> VkResult<Vec<vk::Image>>;
2016-12-29 18:06:17 +11:00
let present_images = swapchain_loader.get_swapchain_images_khr(swapchain).unwrap();
2016-12-10 05:25:48 +11:00
```
2016-12-28 14:31:48 +11:00
2018-11-12 04:05:03 +11:00
### Slices in functions
2016-12-10 05:25:48 +11:00
```Rust
2016-12-24 07:41:16 +11:00
pub fn cmd_pipeline_barrier(&self,
command_buffer: vk::CommandBuffer,
src_stage_mask: vk::PipelineStageFlags,
dst_stage_mask: vk::PipelineStageFlags,
dependency_flags: vk::DependencyFlags,
memory_barriers: &[vk::MemoryBarrier],
buffer_memory_barriers: &[vk::BufferMemoryBarrier],
image_memory_barriers: &[vk::ImageMemoryBarrier]);
2016-12-10 05:25:48 +11:00
```
2016-12-28 14:31:48 +11:00
2018-11-12 04:05:03 +11:00
### Default implementation for all types
2016-12-10 05:25:48 +11:00
```Rust
2018-11-12 04:05:03 +11:00
// No need to manually set the structure type
let desc_alloc_info = vk::DescriptorSetAllocateInfo {
descriptor_pool: self.pool,
descriptor_set_count: self.layouts.len() as u32,
p_set_layouts: self.layouts.as_ptr(),
..Default::default()
2016-12-24 07:41:16 +11:00
};
2016-12-10 05:25:48 +11:00
```
2018-11-12 04:05:03 +11:00
### Builder pattern
2016-12-10 05:25:48 +11:00
```Rust
2018-11-12 04:05:03 +11:00
let pipeline_vertex_input_state_create_info = vk::PipelineVertexInputStateCreateInfo::builder()
.vertex_binding_descriptions(&Vertex::binding_descriptions())
.vertex_attribute_descriptions(&Vertex::attribute_descriptions()).build();
2017-01-01 18:31:13 +11:00
```
2018-11-12 04:05:03 +11:00
*Note*: No validation is done, the lifetimes only have to live as long as the builder object. It is the responsibility of the user to make sure that the pointers are valid.
### Flags and constants as associated constants
2017-01-01 18:31:13 +11:00
```Rust
2018-11-12 04:05:03 +11:00
dst_access_mask: vk::AccessFlags::COLOR_ATTACHMENT_READ
| vk::AccessFlags::COLOR_ATTACHMENT_WRITE,
2017-01-01 18:31:13 +11:00
```
```Rust
2018-11-12 04:05:03 +11:00
pipeline_bind_point: vk::PipelineBindPoint::GRAPHICS,
2017-01-01 18:31:13 +11:00
```
2018-11-12 04:05:03 +11:00
### Debug/Display for Flags
2017-01-01 18:31:13 +11:00
```Rust
2018-11-12 04:05:03 +11:00
let flag = vk::AccessFlags::COLOR_ATTACHMENT_READ
| vk::AccessFlags::COLOR_ATTACHMENT_WRITE;
println!("Debug: {:?}", flag);
println!("Display: {}", flag);
// Prints:
// Debug: AccessFlags(110000000)
// Display: COLOR_ATTACHMENT_READ | COLOR_ATTACHMENT_WRITE
2017-01-01 18:31:13 +11:00
```
2018-11-12 04:05:03 +11:00
### Interop
2017-01-01 18:31:13 +11:00
```Rust
2018-11-12 04:05:03 +11:00
PipelineBindPoint::from_raw(bindpoint);
2016-12-24 07:41:16 +11:00
```
2016-12-28 14:31:48 +11:00
2018-11-12 04:05:03 +11:00
### Function pointer loading
Ash also takes care of loading the function pointers. Function pointers are split into 3 categories, Entry, Instance and Device. The reason for not loading it into a global is that in Vulkan you can have multiple devices and each device will load its own function pointers to achieve better performance. Click [here](https://github.com/KhronosGroup/Vulkan-LoaderAndValidationLayers/blob/master/loader/LoaderAndLayerInterface.md) for more information.
2016-12-28 14:31:48 +11:00
### Extension loading
2018-11-12 04:05:03 +11:00
Additionally, every Vulkan extension has to be loaded explicitly. You can find all extensions under [ash::extensions](https://github.com/MaikKlein/ash/tree/master/ash/src/extensions).
2016-12-24 07:41:16 +11:00
```Rust
use ash::extensions::Swapchain;
2018-11-12 04:05:03 +11:00
let swapchain_loader = Swapchain::new(&instance, &device);
2016-12-24 07:41:16 +11:00
let swapchain = swapchain_loader.create_swapchain_khr(&swapchain_create_info).unwrap();
2016-12-10 05:25:48 +11:00
```
2016-12-28 14:31:48 +11:00
2017-01-01 18:31:13 +11:00
### Support for extension names
```Rust
use ash::extensions::{Swapchain, XlibSurface, Surface, DebugReport};
#[cfg(all(unix, not(target_os = "android")))]
fn extension_names() -> Vec<*const i8> {
vec![
Surface::name().as_ptr(),
XlibSurface::name().as_ptr(),
DebugReport::name().as_ptr()
]
}
```
2016-12-28 14:31:48 +11:00
### Implicit handles
2018-11-12 04:05:03 +11:00
Handles from Instance or Device are passed implicitly.
2016-12-10 05:25:48 +11:00
```Rust
2016-12-24 07:41:16 +11:00
pub fn create_command_pool(&self,
create_info: &vk::CommandPoolCreateInfo)
-> VkResult<vk::CommandPool>;
2016-12-10 05:25:48 +11:00
2016-12-24 07:41:16 +11:00
let pool = device.create_command_pool(&pool_create_info).unwrap();
2016-12-10 05:25:48 +11:00
```
2016-12-28 14:22:13 +11:00
2016-12-10 05:39:16 +11:00
## Example
You can find the examples [here](https://github.com/MaikKlein/ash/tree/master/examples).
2017-01-01 18:37:12 +11:00
All examples currently require: the LunarG Validation layers and a Vulkan library that is visible in your `PATH`. An easy way to get started is to use the [LunarG Vulkan SDK](https://lunarg.com/vulkan-sdk/)
#### Windows
Make sure that you have a Vulkan ready driver and install the [LunarG Vulkan SDK](https://lunarg.com/vulkan-sdk/).
#### Linux
Make sure that you have a Vulkan ready driver and install the [LunarG Vulkan SDK](https://lunarg.com/vulkan-sdk/). You also have to add the library and layers to your path. Have a look at my [post](http://askubuntu.com/a/803110/77183) if you are unsure how to do that.
2016-12-26 00:49:20 +11:00
### [Triangle](https://github.com/MaikKlein/ash/blob/master/examples/src/bin/triangle.rs)
2016-12-26 11:23:19 +11:00
Displays a triangle with vertex colors.
2016-12-10 07:01:44 +11:00
```
2016-12-26 00:49:20 +11:00
cd examples
cargo run --bin triangle
2016-12-10 07:01:44 +11:00
```
2016-12-10 05:39:16 +11:00
2016-12-10 05:47:29 +11:00
![screenshot](http://i.imgur.com/PQZcL6w.jpg)
2016-12-10 05:39:16 +11:00
2016-12-26 00:49:20 +11:00
### [Texture](https://github.com/MaikKlein/ash/blob/master/examples/src/bin/texture.rs)
2016-12-26 11:23:19 +11:00
Displays a texture on a quad.
2016-12-12 14:43:46 +11:00
```
2016-12-26 00:49:20 +11:00
cd examples
cargo run --bin texture
2016-12-12 14:43:46 +11:00
```
2016-12-12 14:30:01 +11:00
![texture](http://i.imgur.com/trow00H.png)
2016-12-10 07:04:31 +11:00
## A thanks to
* [Api with no secrets](https://software.intel.com/en-us/articles/api-without-secrets-introduction-to-vulkan-part-1)
* [Vulkan tutorial](http://av.dfki.de/~jhenriques/development.html)
* [Vulkan examples](https://github.com/SaschaWillems/Vulkan)
2016-12-10 07:05:19 +11:00
* [Vulkan tutorial](https://vulkan-tutorial.com/)
2016-12-10 07:04:31 +11:00
* [Vulkano](https://github.com/tomaka/vulkano/)
* [vk-rs](https://github.com/Osspial/vk-rs)