# Vulkan Object Wrapper: another Rust renderer engine implementation
## 语言｜language
## Usage
### Add this crate to your project
```cmd
cargo add vkobject-rs
```
## Rendering strategy
1. Create the `VulkanContext`
- If you want to use **vkobject-rs** with GLFW, the simplest way is to use `create_vulkan_context()` with your GLFW window.
2. Build pipelines for you to draw.
- A pipeline is an object that gathers all of the data from all of your buffers into a shader, runs the shader, and then wires the output to the render target attachments.
- To build a pipeline, you will have to create these things:
1. Mesh. A mesh describes the polygon you want to render.
2. Shaders. The shaders define how to process polygons to make pixels and put the pixels into which target attachments.
3. The data for the shader's inputs. A uniform buffer, storage buffer, push constants, textures, or texel buffers could do this.
3. Draw with the pipeline.
- See the implementation of `pub fn draw()` in the **Example code** section.
4. Resource clean-ups were done automatically when your objects go out of scope, appreciated by the RAII rule of the Rust language.
## The mainly used objects
### Buffers: to hold your polygons, draw instances, draw commands, and shader storages
There are some kinds of buffers in this crate:
- `BufferWithType<T>`: A wrapper for `Buffer`, mainly for the data that won't be modified frequently, so its staging buffer could be discarded.
- `BufferVec<T>`: A wrapper for `Buffer`, provides an interface that is like a `Vec<T>`, call `flush()` could upload data to GPU with a command buffer.
- The `flush()` will only upload the modified part of the data to the GPU. The data updation is incremental, minimizing the bandwidth usage of CPU-GPU data transfer.
- The staging buffer of this buffer is not discardable.
- `UniformBuffer<T>`: A wrapper for `Buffer`, whose data on the CPU side could be dereferenced into a structure, and you can modify the structure members freely.
- The `flush()` will upload the whole structure to the GPU side.
- This buffer is commonly used for shader inputs.
- `GenericUniformBuffer`: A wrapper for `UniformBuffer<T>` that erases the generic type `<T>`.
- `StorageBuffer<T>`: A wrapper for `Buffer` and the usage is the same as `UniformBuffer<T>` except it's for the shader's storage buffer inputs.
- The shaders could modify the storage buffers freely, while they can't modify uniform buffers.
- `GenericStorageBuffer`: A wrapper for `StorageBuffer<T>` that erases the generic type `<T>`.
- `StagingBuffer`: The staging buffer that's totally transparent to your CPU, you can have its data pointer and modify the data for it to upload to the GPU.
- Safety: You should have to know how to manipulate raw pointers correctly.
- `Buffer`: The buffer that's transparent to the GPU, and has its own staging buffer for uploading data to the GPU.
- Transfer data to its staging buffer, then call `upload_staging_buffer()` to enqueue an upload command into a command buffer.
- After the upload command is executed, the data is transferred into the GPU, then you call `discard_staging_buffer()` to save some system memory if you wish.
- This thing is raw; you don't want to use this.
- `VulkanBuffer`: The most low-level buffer wrapping object, the `Buffer` and `StagingBuffer` are implemented by using this object.
- This thing is super raw; you don't want to use this.
### Mesh: to hold your polygons, draw instances, draw commands
A mesh has 4 buffers. According to the usage, they are:
- vertex buffer
- index buffer (optional)
- instance buffer (optional)
- indirect draw command buffer (optional)
The buffers for a mesh have two types:
- For static draw usage, there is `BufferWithType<T>`
- The data in the buffer is once initialized, and then never changes.
- For dynamic update usage, there is `BufferVec<T>`
- You can modify its data frequently like a `Vec<T>`, then call `flush()` to apply changes to the GPU buffer.
```rust
#[derive(Debug, Clone)]
pub struct Mesh<BV, V, BE, E, BI, I, BC, C>
where
BV: BufferForDraw<V>,
BE: BufferForDraw<E>,
BI: BufferForDraw<I>,
BC: BufferForDraw<C>,
V: BufferVecStructItem,
E: BufferVecItem + 'static,
I: BufferVecStructItem,
C: BufferVecStructItem {
pub primitive_type: VkPrimitiveTopology,
pub vertices: BV,
pub indices: Option<BE>,
pub instances: Option<BI>,
pub commands: Option<BC>,
vertex_type: V,
element_type: E,
instance_type: I,
command_type: C,
}
/// If a buffer you don't need, use this for your buffer item type
#[derive(Default, Debug, Clone, Copy, Iterable)]
pub struct UnusedBufferItem {}
/// If a buffer you don't need, use this for your buffer type
pub type UnusedBufferType = BufferWithType<UnusedBufferItem>;
/// Use this function to create an unused buffer type
pub fn buffer_unused() -> Option<UnusedBufferType> {
None
}
impl<BV, V, BE, E, BI, I, BC, C> Mesh<BV, V, BE, E, BI, I, BC, C>
where
BV: BufferForDraw<V>,
BE: BufferForDraw<E>,
BI: BufferForDraw<I>,
BC: BufferForDraw<C>,
V: BufferVecStructItem,
E: BufferVecItem + 'static,
I: BufferVecStructItem,
C: BufferVecStructItem {
/// Create the mesh from the buffers
pub fn new(primitive_type: VkPrimitiveTopology, vertices: BV, indices: Option<BE>, instances: Option<BI>, commands: Option<BC>) -> Self {
Self {
primitive_type,
vertices,
indices,
instances,
commands,
vertex_type: V::default(),
element_type: E::default(),
instance_type: I::default(),
command_type: C::default(),
}
}
/// Upload staging buffers to GPU
pub fn flush(&mut self, cmdbuf: VkCommandBuffer) -> Result<(), VulkanError> {
filter_no_staging_buffer(self.vertices.flush(cmdbuf))?;
if let Some(ref mut indices) = self.indices {filter_no_staging_buffer(indices.flush(cmdbuf))?;}
if let Some(ref mut instances) = self.instances {filter_no_staging_buffer(instances.flush(cmdbuf))?;}
if let Some(ref mut commands) = self.commands {filter_no_staging_buffer(commands.flush(cmdbuf))?;}
Ok(())
}
/// Discard staging buffers if the data will never be modified.
pub fn discard_staging_buffers(&mut self) {
self.vertices.discard_staging_buffer();
if let Some(ref mut indices) = self.indices {indices.discard_staging_buffer();}
if let Some(ref mut instances) = self.instances {instances.discard_staging_buffer();}
if let Some(ref mut commands) = self.commands {commands.discard_staging_buffer();}
}
}
```
### Shaders
The shaders in this crate can compile GLSL or HLSL code to SPIR-V intermediate language. Also, they could be loaded from a binary file instead of the source code.
```rust
let draw_shaders = Arc::new(DrawShaders::new(
Arc::new(VulkanShader::new_from_source_file_or_cache(device.clone(), ShaderSourcePath::VertexShader(PathBuf::from("shaders/test.vsh")), false, "main", OptimizationLevel::Performance, false)?),
None,
None,
None,
Arc::new(VulkanShader::new_from_source_file_or_cache(device.clone(), ShaderSourcePath::FragmentShader(PathBuf::from("shaders/test.fsh")), false, "main", OptimizationLevel::Performance, false)?),
));
```
### Texture
The `VulkanTexture` is the wrapper for you to use textures.
### DescriptorProps
The descriptor properties are for the shader inputs; they define which descriptor set and binding has a uniform buffer, or texture, samplers, etc.
- The shader inputs were made as `Vec<T>` since this could help to provide data for array-type inputs of the shaders.
- For a single variable input, simply providing one element of the array could work.
```rust
/// The properties for the descriptor set
#[derive(Debug)]
pub enum DescriptorProp {
/// The props for the samplers
Samplers(Vec<Arc<VulkanSampler>>),
/// The props for the image
Images(Vec<TextureForSample>),
/// The props for the storage buffer
StorageBuffers(Vec<Arc<dyn GenericStorageBuffer>>),
/// The props for the uniform buffers
UniformBuffers(Vec<Arc<dyn GenericUniformBuffer>>),
/// The props for the storage texel buffer
StorageTexelBuffers(Vec<VulkanBufferView>),
/// The props for the uniform texel buffers
UniformTexelBuffers(Vec<VulkanBufferView>),
}
/// The descriptor set properties
#[derive(Default, Debug, Clone)]
pub struct DescriptorProps {
/// The descriptor sets
pub sets: HashMap<u32 /* set */, HashMap<u32 /* binding */, Arc<DescriptorProp>>>,
}
```
### Pipeline
The pipeline wires mesh, texture, uniform buffers, storage buffers, shaders, output images, all together, and defines all of the rendering options.
```rust
let pipeline = ctx.create_pipeline_builder(mesh, draw_shaders, desc_props.clone())?
.set_cull_mode(VkCullModeFlagBits::VK_CULL_MODE_NONE as VkCullModeFlags)
.set_depth_test(false)
.set_depth_write(false)
.build()?;
```
On draw:
```rust
let scene = ctx.begin_scene(0, None)?;
scene.set_viewport_swapchain(0.0, 1.0)?;
scene.set_scissor_swapchain()?;
scene.begin_renderpass(Vec4::new(0.0, 0.0, 0.2, 1.0), 1.0, 0)?;
pipeline.draw(scene.get_cmdbuf())?;
scene.end_renderpass()?;
scene.finish();
```
## Example code
```rust
use glfw::*;
use crate::prelude::*;
use std::{
collections::HashMap,
ffi::CStr,
path::PathBuf,
slice::from_raw_parts_mut,
sync::{
Arc,
Mutex,
RwLock,
atomic::{
AtomicBool,
Ordering,
}
},
thread,
time::Duration,
};
const TEST_TIME: f64 = 10.0;
#[derive(Debug)]
pub struct AppInstance {
pub ctx: Arc<RwLock<VulkanContext>>,
pub window: PWindow,
pub events: GlfwReceiver<(f64, WindowEvent)>,
pub glfw: Glfw,
}
impl AppInstance {
pub fn new(width: u32, height: u32, title: &str, window_mode: glfw::WindowMode) -> Result<Self, VulkanError> {
static GLFW_LOCK: Mutex<u32> = Mutex::new(0);
let glfw_lock = GLFW_LOCK.lock().unwrap();
let mut glfw = glfw::init(glfw::fail_on_errors).unwrap();
glfw.window_hint(WindowHint::ClientApi(ClientApiHint::NoApi));
let (mut window, events) = glfw.create_window(width, height, title, window_mode).expect("Failed to create GLFW window.");
drop(glfw_lock);
window.set_key_polling(true);
let device_requirement = DeviceRequirement {
can_graphics: true,
can_compute: false,
name_subtring: "",
};
let ctx = Arc::new(RwLock::new(create_vulkan_context(&window, device_requirement, PresentInterval::VSync, 1, false)?));
let ctx_lock = ctx.read().unwrap();
for gpu in VulkanGpuInfo::get_gpu_info(&ctx_lock.vkcore)?.iter() {
println!("Found GPU: {}", unsafe{CStr::from_ptr(gpu.properties.deviceName.as_ptr())}.to_str().unwrap());
}
println!("Chosen GPU name: {}", unsafe{CStr::from_ptr(ctx_lock.device.get_gpu().properties.deviceName.as_ptr())}.to_str().unwrap());
println!("Chosen GPU type: {:?}", ctx_lock.device.get_gpu().properties.deviceType);
drop(ctx_lock);
Ok(Self {
glfw,
window,
events,
ctx,
})
}
pub fn get_time(&self) -> f64 {
glfw_get_time()
}
pub fn set_time(&self, time: f64) {
glfw_set_time(time)
}
pub fn run(&mut self,
test_time: Option<f64>,
mut on_render: impl FnMut(&mut VulkanContext, f64) -> Result<(), VulkanError> + Send + 'static
) -> Result<(), VulkanError> {
let exit_flag = Arc::new(AtomicBool::new(false));
let exit_flag_cloned = exit_flag.clone();
let start_time = self.glfw.get_time();
let ctx = self.ctx.clone();
let renderer_thread = thread::spawn(move || {
let mut num_frames = 0;
let mut time_in_sec: u64 = 0;
let mut num_frames_prev: u64 = 0;
while !exit_flag_cloned.load(Ordering::Relaxed) {
let cur_frame_time = glfw_get_time();
let run_time = cur_frame_time - start_time;
on_render(&mut ctx.write().unwrap(), run_time).unwrap();
num_frames += 1;
let new_time_in_sec = run_time.floor() as u64;
if new_time_in_sec > time_in_sec {
let fps = num_frames - num_frames_prev;
println!("FPS: {fps}\tat {new_time_in_sec}s");
time_in_sec = new_time_in_sec;
num_frames_prev = num_frames;
}
}
});
while !self.window.should_close() {
let run_time = glfw_get_time() - start_time;
thread::sleep(Duration::from_millis(1));
self.glfw.poll_events();
for (_, event) in glfw::flush_messages(&self.events) {
match event {
glfw::WindowEvent::Key(Key::Escape, _, Action::Press, _) => {
self.window.set_should_close(true);
}
_ => {}
}
}
if let Some(test_time) = test_time {
if run_time >= test_time {
self.window.set_should_close(true);
}
}
}
exit_flag.store(true, Ordering::Relaxed);
renderer_thread.join().unwrap();
println!("End of the test");
Ok(())
}
}
unsafe impl Send for AppInstance {}
unsafe impl Sync for AppInstance {}
fn main() {
derive_vertex_type! {
pub struct VertexType {
pub position: Vec2,
}
}
derive_uniform_buffer_type! {
pub struct UniformInput {
resolution: Vec3,
time: f32,
}
}
struct Resources {
uniform_input: Arc<dyn GenericUniformBuffer>,
pipeline: Pipeline,
}
impl Resources {
pub fn new(ctx: &mut VulkanContext) -> Result<Self, VulkanError> {
let device = ctx.device.clone();
let draw_shaders = Arc::new(DrawShaders::new(
Arc::new(VulkanShader::new_from_source_file_or_cache(device.clone(), ShaderSourcePath::VertexShader(PathBuf::from("shaders/test.vsh")), false, "main", OptimizationLevel::Performance, false)?),
None,
None,
None,
Arc::new(VulkanShader::new_from_source_file_or_cache(device.clone(), ShaderSourcePath::FragmentShader(PathBuf::from("shaders/test.fsh")), false, "main", OptimizationLevel::Performance, false)?),
));
let uniform_input: Arc<dyn GenericUniformBuffer> = Arc::new(UniformBuffer::<UniformInput>::new(device.clone())?);
let desc_props = Arc::new(DescriptorProps::default());
desc_props.new_uniform_buffer(0, 0, uniform_input.clone());
let pool_in_use = ctx.cmdpools[0].use_pool(None)?;
let vertices_data = vec![
VertexType {
position: Vec2::new(-1.0, -1.0),
},
VertexType {
position: Vec2::new( 1.0, -1.0),
},
VertexType {
position: Vec2::new(-1.0, 1.0),
},
VertexType {
position: Vec2::new( 1.0, 1.0),
},
];
let vertices = Arc::new(RwLock::new(BufferWithType::new(device.clone(), &vertices_data, pool_in_use.cmdbuf, VkBufferUsageFlagBits::VK_BUFFER_USAGE_VERTEX_BUFFER_BIT as VkBufferUsageFlags)?));
let mesh = Arc::new(GenericMeshWithMaterial::new(Arc::new(Mesh::new(VkPrimitiveTopology::VK_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP, vertices, buffer_unused(), buffer_unused(), buffer_unused())), "", None));
mesh.geometry.flush(pool_in_use.cmdbuf)?;
drop(pool_in_use);
ctx.cmdpools[0].wait_for_submit(u64::MAX)?;
mesh.geometry.discard_staging_buffers();
let pipeline = ctx.create_pipeline_builder(mesh, draw_shaders, desc_props)?
.set_cull_mode(VkCullModeFlagBits::VK_CULL_MODE_NONE as VkCullModeFlags)
.set_depth_test(false)
.set_depth_write(false)
.build()?;
Ok(Self {
uniform_input,
pipeline,
})
}
pub fn draw(&self, ctx: &mut VulkanContext, run_time: f64) -> Result<(), VulkanError> {
let scene = ctx.begin_scene(0, None)?;
let cmdbuf = scene.get_cmdbuf();
let extent = scene.get_rendertarget_extent();
let ui_data = unsafe {from_raw_parts_mut(self.uniform_input.get_staging_buffer_address()? as *mut UniformInput, 1)};
ui_data[0] = UniformInput {
resolution: Vec3::new(extent.width as f32, extent.height as f32, 1.0),
time: run_time as f32,
};
self.uniform_input.flush(cmdbuf)?;
scene.set_viewport_swapchain(0.0, 1.0)?;
scene.set_scissor_swapchain()?;
scene.begin_renderpass(Vec4::new(0.0, 0.0, 0.2, 1.0), 1.0, 0)?;
self.pipeline.draw(cmdbuf)?;
scene.end_renderpass()?;
scene.finish();
Ok(())
}
}
let mut inst = Box::new(AppInstance::new(1024, 768, "Vulkan test", glfw::WindowMode::Windowed).unwrap());
let resources = Resources::new(&mut inst.ctx.write().unwrap()).unwrap();
inst.run(Some(TEST_TIME),
move |ctx: &mut VulkanContext, run_time: f64| -> Result<(), VulkanError> {
resources.draw(ctx, run_time)
}).unwrap();
}
```
## FAQ
### Question: When building the dependent `shaderc`, it fails and shows the following information:
```
warning: shaderc-sys@0.10.1: shaderc: requested to build from source
error: failed to run custom build command for `shaderc-sys v0.10.1`
Caused by:
process didn't exit successfully: `C:\your\path\to\your\crate\target\release\build\shaderc-sys-03dfa106721f22d5\build-script-build` (exit code: 101)
--- stdout
cargo:warning=shaderc: requested to build from source
--- stderr
thread 'main' panicked at C:\Users\your_name\.cargo\registry\src\index.crates.io-1949cf8c6b5b557f\shaderc-sys-0.10.1\build\cmd_finder.rs:55:13:
couldn't find required command: "ninja"
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
warning: build failed, waiting for other jobs to finish...
```
* Answer: Install ninja, then build it again.
* For Windows: run `winget install Ninja-build.Ninja`
* For Debian/Ubuntu: run `sudo apt install ninja-build`
* For Fedora/RHEL: run `sudo dnf install ninja-build`
* For MacOS: run `brew install ninja`
See: https://github.com/ninja-build/ninja/releases`
### Question: When the `validation_layer` feature was enabled, it failed to run. The error information says:
```
called `Result::unwrap()` on an `Err` value: VkError(VkErrorLayerNotPresent("vkCreateInstance"))
```
* Answer: This is because your GPU driver doesn't support the Vulkan validation layer. You can only debug your Vulkan code without it.
* Buying an NVIDIA GPU device could resolve this problem, as its driver supports the Vulkan validation layer.