Vulkan tutorial written in Rust using Ash
Vulkan tutorials written in Rust using Ash. The extended branch contains a few more
chapters that I won’t merge on that branch since I want it to stay close to the original tutorial.
Please check it out :). If you wan’t to run it on android see the android branch.
This repository will follow the structure of the original tutorial. Each
commit will correspond to one page or on section of the page for
long chapters.
Sometimes an ‘extra’ commit will be added with some refactoring, commenting or feature.
All chapters of the original tutorial are now covered. The code compiles on windows, linux
and macos and runs on windows, and linux. It should also run on macos but I haven’t been
able to test yet. I’ll update this statement when I (or someone else) can try.
You need to have a Vulkan SDK installed and glslangValidator executable in your PATH.
This should be the case when installing the Vulkan SDK.
If for some reason you want to skip the shader compilation when buiding the project you can set
the SKIP_SHADER_COMPILATION environment variable to true. Though you will need to provide the
compiled shaders for the program to run.
This section contains the summary of the project commits. Follow 
to go to the related
tutorial page.
Application setup. We don’t setup the window system now as it’s done in
the original tutorial.
Create and destroy the Vulkan instance with required surface extensions.
Add VK_LAYER_LUNARG_standard_validation at instance creation and creates
a debug report callback function after checking that it is available.
Since we are using the log crate, we log the message with the proper log level.
The callback is detroyed at application termination.
Find a physical device with at least a queue family supporting graphics.
Create the logical device interfacing with the physical device. Then create
the graphics queue from the device.
Create the window, the window surface and the presentation queue.
Update the physical device creation to get a device with presentation support.
At that point, the code will only work on Windows.
Checks for swapchain support and enable device extension for swapchain. Then
query the swapchain details and choose the right settings. Then create the
swapchain and retrieve the swapchain images.
Create the image views to the swapchain images.
Add SwapchainProperties to hold the format, present mode and extent of our swapchain.
Add a method to build the best properties to SwapchainSupportDetails.
Move these two struct into the swapchain module.
Create the vertex and fragment shaders GLSL source and add a compile.bat script
to compile it into SPIR-V bytecode using glslangValidator.
Load the compiled SPIR-V and create a ShaderModule from it.
In this section I forgot to create the shader stage create info structures. It’s ok
they will be created in 1.3.5: Graphics pipeline.
This one is huge so it will be split across several commits.
Create the vertex input and input assembly info for the pipeline.
Create the viewport and scissor info for the pipeline.
Create the rasterizer info for the pipeline.
Create the multisampling info for the pipeline.
Create color blend attachment and color blend info for the pipeline.
Create the pipeline layout info.
Create the render pass.
Create the PipelineShaderStageCreateInfo that we forgot in 1.3.2: Shader module.
Create the grahics pipeline.
Until now we compiled the shaders with a compile.bat script that we have to run
manually before running the application. In this section, we will compite them
when building the application using Cargo‘s build scripts.
The build script scan the content of the shaders directory and generates a compiled
SPIR-V shader for each file it founds. The files are generated in a the same directory
as the GLSL shaders and with the same name appended with .spv.
Create one framebuffer for each image of the swapchain.
Create a command pool and allocate one command buffer per swapchain image.
Then we register all the commands required to render.
This section is also split across multiple commits.
Setup the main loop.
Create a semphore to signal that an image has been acquired and another one
to signal that the rendering to the image is finished.
Acquire the next image from the swapchain, submit the command buffer and
present the rendered image.
Limit the number of frames that can be renderer simultaneously using fences.
QueueFamilyIndices structure and return it at physical device creationSyncObjects containing the semaphores and fence for one frame.InFlightFrames containing all SyncObjects and the current frame index.Iterator for InFlightFrames so we just need to call next() toHandle swapchain recreation when resizing the window or when the swapchain is suboptimal
or out of date.
Remove hard coded vertices from the vertex shader source and create vertices on the cpu.
Update the pipeline with the vertex binding and attributes description.
Create and fill the vertex buffer and bind it before rendering.
Create a staging buffer for the vertex data and copy the vertex data from this buffer’s
memory to the memory of the device local buffer.
The tutorial also suggests that we allocate command buffers used for memory copy from
a command pool dedicated to short-lived command buffers, so we did that too.
Use index buffer to reuse vertice when drawing a rectangle.
In the original tutorial the create_index_buffer is the same as create_vertex_buffer
but with the vertex data replaced with the index data. To limit duplication we’ve added
a method that creates and fill a buffer and fill it with the passed data. This method is
called from create_vertex_buffer and create_index_buffer.
Create a UniformBufferObject structure containing transformation matrices and create the
descriptor layout and buffers used to make it accessible from the vertex shader.
Also add a math module containing a perspective function that creates a prespective matrix
that is working with Vulkan’s NDC.
Create a descriptor pool and allocate a descriptor set for each descriptor buffer.
This section is split too.
Load an image from a file.
Create an host visible staging buffer for image data and create a device local
image. At this point the image is empty, we will copy the buffer data in a later
section.
Copy the image data store in the host visible buffer to the device local image.
Create the image view and sampler. Also enable the sampler anisotropy feature.
Update the descriptor set, add texture coordinates to Vertex and update the
shaders to read texture coordinates and sample the texture.
Update Vertex to make the position 3d. Update the vertex shader to take the
new dimension into account. Add a new quad to render. And setup depth buffer
so the new quad is renderer correctly relatively to the other. Recreate the
depth buffer resources when the swapchain is recreated.
Add Texture struct which will hold the resources required by mutable image,
(image, memory, view and optionnally a sampler).
Add VkContext that will hold the instance, debug callback, physical and logical
devices, and surface.
Overall refactoring of the code with some Rust specific code smell fixes.
Load a 3D model from an wavefront obj file and render it. We skip the deduplication
step because the crate we use to load obj files already does it.
Since 3.1: Descriptor layout and buffer, our rendered geometry has been spinning
infinitely around its local z axis. In this chapter we change this behaviour and
implement an orbital camera controlled with the mouse.
You can scroll the mouse wheel to get closer or further away from the global origin.
And you can left click and move the mouse to move around the global origin.
Generate mipmaps for the model texture and update the sampler to make use of them.
Add multisampling anti-aliasing.
With validation layers:
RUST_LOG=vulkan_tutorial_ash=debug cargo run
The RUST_LOG level will affect the log level of the validation layers too.
or without:
cargo run --release
Thanks to Alexander Overvoorde for this amazing tutorials.