Vulkan Object Wrapper: another Rust renderer engine implementation

语言｜language

简体中文 | Chinglish

Usage

Add this crate to your project

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.

#[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.

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.

/// 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.

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:

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

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.