Top Related Projects
Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2
C++ examples for the Vulkan graphics API
Ray tracing examples and tutorials using VK_KHR_ray_tracing
A beginner-friendly Vulkan path tracing tutorial in under 300 lines of C++.
Cross-platform, graphics API agnostic, "Bring Your Own Engine/Framework" style rendering library.
Quick Overview
Vulkan-Samples is a comprehensive collection of open-source samples and tutorials for the Vulkan graphics API. Maintained by the Khronos Group, this repository serves as a valuable resource for developers learning Vulkan or seeking to implement advanced graphics techniques using the API.
Pros
- Extensive collection of samples covering various Vulkan features and techniques
- Well-documented code with detailed explanations and comments
- Regular updates and contributions from the Vulkan community
- Cross-platform support for Windows, Linux, Android, and macOS (MoltenVK)
Cons
- Steep learning curve for beginners due to Vulkan's complexity
- Some samples may require powerful hardware to run efficiently
- Limited coverage of certain advanced topics or niche use cases
- Occasional inconsistencies in coding style across different samples
Code Examples
Here are a few short code examples from the Vulkan-Samples repository:
- Creating a Vulkan instance:
vk::ApplicationInfo app_info("Example", 1, "Example", 1, VK_API_VERSION_1_0);
vk::InstanceCreateInfo instance_info({}, &app_info);
vk::Instance instance = vk::createInstance(instance_info);
- Creating a Vulkan device:
vk::DeviceQueueCreateInfo queue_info({}, queue_family_index, 1, &queue_priority);
vk::DeviceCreateInfo device_info({}, 1, &queue_info);
vk::Device device = physical_device.createDevice(device_info);
- Creating a Vulkan command buffer:
vk::CommandPoolCreateInfo pool_info(vk::CommandPoolCreateFlagBits::eResetCommandBuffer, queue_family_index);
vk::CommandPool command_pool = device.createCommandPool(pool_info);
vk::CommandBufferAllocateInfo alloc_info(command_pool, vk::CommandBufferLevel::ePrimary, 1);
std::vector<vk::CommandBuffer> command_buffers = device.allocateCommandBuffers(alloc_info);
Getting Started
To get started with Vulkan-Samples:
-
Clone the repository:
git clone https://github.com/KhronosGroup/Vulkan-Samples.git
-
Install the required dependencies (Vulkan SDK, CMake, etc.)
-
Build the project:
cd Vulkan-Samples cmake -G "<generator>" . cmake --build .
-
Run a sample:
./bin/vulkan_samples sample_name
For more detailed instructions, refer to the repository's README and documentation.
Competitor Comparisons
Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2
Pros of Filament
- Cross-platform rendering engine with support for multiple APIs (OpenGL, Vulkan, Metal)
- Comprehensive material system with physically-based rendering (PBR) support
- Extensive documentation and examples for various use cases
Cons of Filament
- Steeper learning curve due to its comprehensive feature set
- Larger codebase and potentially higher overhead for simple projects
- Less focused on Vulkan-specific optimizations and best practices
Code Comparison
Filament (C++):
FilamentApp& app = FilamentApp::get();
Engine* engine = app.getEngine();
Scene* scene = engine->createScene();
Vulkan-Samples (C++):
vkb::PlatformUniquePtr platform = vkb::platform::create_unique_platform();
vkb::WindowUniquePtr window = platform->create_window("Vulkan Sample");
vkb::Context context(std::move(platform), std::move(window));
Summary
Filament offers a more comprehensive rendering solution with cross-platform support, while Vulkan-Samples focuses specifically on Vulkan best practices and optimizations. Filament provides a higher-level abstraction, which can be beneficial for complex projects but may introduce overhead for simpler ones. Vulkan-Samples, on the other hand, offers a more direct approach to Vulkan development, making it ideal for learning and implementing Vulkan-specific techniques.
C++ examples for the Vulkan graphics API
Pros of Vulkan
- More extensive collection of samples covering a wider range of Vulkan features and techniques
- Includes advanced rendering techniques and compute shader examples
- Samples are well-documented with detailed explanations and comments
Cons of Vulkan
- Less frequently updated compared to Vulkan-Samples
- May not always reflect the latest Vulkan best practices or features
- Some samples might be more complex for beginners to understand
Code Comparison
Vulkan:
void VulkanExample::buildCommandBuffers()
{
VkCommandBufferBeginInfo cmdBufInfo = vks::initializers::commandBufferBeginInfo();
for (int32_t i = 0; i < drawCmdBuffers.size(); ++i)
{
VK_CHECK_RESULT(vkBeginCommandBuffer(drawCmdBuffers[i], &cmdBufInfo));
// ... (rendering commands)
VK_CHECK_RESULT(vkEndCommandBuffer(drawCmdBuffers[i]));
}
}
Vulkan-Samples:
void VulkanSample::build_command_buffers()
{
VkCommandBufferBeginInfo begin_info = vkb::initializers::command_buffer_begin_info();
for (auto &cmd_buf : command_buffers)
{
VK_CHECK(vkBeginCommandBuffer(cmd_buf, &begin_info));
// ... (rendering commands)
VK_CHECK(vkEndCommandBuffer(cmd_buf));
}
}
Both repositories provide similar command buffer creation patterns, but Vulkan-Samples uses more modern naming conventions and error checking macros.
Ray tracing examples and tutorials using VK_KHR_ray_tracing
Pros of vk_raytracing_tutorial_KHR
- Focused specifically on ray tracing, providing in-depth examples and tutorials
- Includes NVIDIA-specific optimizations and best practices
- Smaller, more manageable codebase for those primarily interested in ray tracing
Cons of vk_raytracing_tutorial_KHR
- Limited scope compared to Vulkan-Samples, which covers a broader range of Vulkan features
- May not be as frequently updated or maintained as the official Khronos Group repository
- Potentially less portable across different hardware vendors
Code Comparison
vk_raytracing_tutorial_KHR:
void HelloVulkan::createBottomLevelAS()
{
// ... (BLAS creation code)
m_rtBuilder.buildBlas(m_blas, VK_BUILD_ACCELERATION_STRUCTURE_PREFER_FAST_TRACE_BIT_KHR);
}
Vulkan-Samples:
void VulkanSample::create_acceleration_structure()
{
// ... (Acceleration structure creation code)
vkCreateAccelerationStructureKHR(get_device().get_handle(), &as_info, nullptr, &acceleration_structure);
}
The vk_raytracing_tutorial_KHR example uses a higher-level abstraction (m_rtBuilder) for building acceleration structures, while Vulkan-Samples demonstrates a more low-level approach using direct Vulkan API calls.
A beginner-friendly Vulkan path tracing tutorial in under 300 lines of C++.
Pros of vk_mini_path_tracer
- Focused specifically on path tracing, providing a deep dive into this advanced rendering technique
- Compact and streamlined codebase, making it easier to understand the core concepts
- Includes NVIDIA-specific optimizations, potentially offering better performance on supported hardware
Cons of vk_mini_path_tracer
- Limited in scope compared to Vulkan-Samples, which covers a broader range of Vulkan features and techniques
- Less comprehensive documentation and fewer explanatory comments in the code
- May not be as portable or widely applicable as Vulkan-Samples due to its focus on NVIDIA hardware
Code Comparison
Vulkan-Samples (initialization):
VkApplicationInfo app_info{};
app_info.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
app_info.pApplicationName = "Vulkan Sample";
app_info.applicationVersion = VK_MAKE_VERSION(1, 0, 0);
app_info.pEngineName = "No Engine";
app_info.engineVersion = VK_MAKE_VERSION(1, 0, 0);
vk_mini_path_tracer (initialization):
VkApplicationInfo app_info = {};
app_info.sType = VK_STRUCTURE_TYPE_APPLICATION_INFO;
app_info.pApplicationName = "vk_mini_path_tracer";
app_info.applicationVersion = 1;
app_info.pEngineName = "vk_mini_path_tracer";
app_info.engineVersion = 1;
Both repositories provide valuable resources for learning Vulkan, with Vulkan-Samples offering a broader scope and vk_mini_path_tracer focusing on advanced path tracing techniques.
Cross-platform, graphics API agnostic, "Bring Your Own Engine/Framework" style rendering library.
Pros of bgfx
- Cross-platform support for multiple rendering APIs (OpenGL, Direct3D, Vulkan, etc.)
- Lightweight and performance-focused design
- Extensive set of examples and tools for various rendering techniques
Cons of bgfx
- Steeper learning curve due to its lower-level API
- Less focus on Vulkan-specific features and optimizations
- Smaller community and less frequent updates compared to Vulkan-Samples
Code Comparison
bgfx:
bgfx::init(bgfx::RendererType::Vulkan);
bgfx::setViewClear(0, BGFX_CLEAR_COLOR | BGFX_CLEAR_DEPTH, 0x303030ff, 1.0f, 0);
bgfx::setViewRect(0, 0, 0, uint16_t(width), uint16_t(height));
Vulkan-Samples:
vkb::Instance instance{};
vkb::PhysicalDevice physical_device = instance.get_suitable_physical_device();
vkb::Device device = physical_device.create_device({});
vkb::Swapchain swapchain{device, window.get_surface(), window.get_extent()};
The bgfx code demonstrates its abstraction layer for multiple rendering APIs, while Vulkan-Samples focuses specifically on Vulkan setup and usage.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
////
- Copyright (c) 2019-2024, Arm Limited and Contributors
- SPDX-License-Identifier: Apache-2.0
- Licensed under the Apache License, Version 2.0 the "License";
- you may not use this file except in compliance with the License.
- You may obtain a copy of the License at
-
http://www.apache.org/licenses/LICENSE-2.0
- Unless required by applicable law or agreed to in writing, software
- distributed under the License is distributed on an "AS IS" BASIS,
- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- See the License for the specific language governing permissions and
- limitations under the License.
//// = Vulkan Samples // omit in toc :pp: {plus}{plus} ifndef::site-gen-antora[] :toc: endif::[]
image::banner.jpg[Vulkan Samples banner]
ifndef::site-gen-antora[] == Vulkan Documentation Site
Documentation for the samples is best viewed at the new link:https://docs.vulkan.org/samples/latest/README.html[Vulkan Documentation Site]. The documentation uses AsciiDoc which isn't fully supported by github.
endif::[]
== Introduction
The Vulkan Samples is collection of resources to help you develop optimized Vulkan applications.
If you are new to Vulkan the xref:samples/api/README.adoc[API samples] are the right place to start. Additionally you may find the following links useful:
ifdef::site-gen-antora[]
- xref:guide:ROOT:index.adoc[Vulkan Guide]
- xref:tutorial:ROOT:00_Introduction.adoc[Get Started in Vulkan] endif::[]
ifndef::site-gen-antora[]
- https://github.com/KhronosGroup/Vulkan-Guide[Vulkan Guide]
- https://vulkan-tutorial.com/[Get Started in Vulkan] endif::[]
xref:samples/performance/README.adoc[Performance samples] show the recommended best practice together with real-time profiling information. They are more advanced but also contain a detailed tutorial with more in-detail explanations.
=== Goals
- Create a collection of resources that demonstrate best-practice recommendations in Vulkan
- Create tutorials that explain the implementation of best-practices and include performance analysis guides
- Create a xref:framework/README.adoc[framework] that can be used as reference material and also as a sandbox for advanced experimentation with Vulkan
== Samples
- xref:./samples/README.adoc[Listing of all samples available in this repository]
== General information
- Project Basics ** xref:./docs/misc.adoc#controls[Controls] ** xref:./docs/misc.adoc#debug-window[Debug window] ** xref:./scripts/README.adoc[Create a Sample]
- Vulkan Essentials ** xref:./samples/vulkan_basics.adoc[How does Vulkan compare to OpenGL ES? What should you expect when targeting Vulkan?]
- Misc ** xref:./docs/misc.adoc#driver-version[Driver version] ** xref:./docs/memory_limits.adoc[Memory limits]
== Setup
Prerequisites: https://git-scm.com/downloads[git] with https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage[git large file storage (git-lfs)].
Clone the repo with submodules using the following command:
git clone --recurse-submodules https://github.com/KhronosGroup/Vulkan-Samples.git cd Vulkan-Samples
Follow build instructions for your platform below.
== Build
=== Supported Platforms
- Windows - xref:./docs/build.adoc#windows[Build Guide]
- Linux - xref:./docs/build.adoc#linux[Build Guide]
- macOS - xref:./docs/build.adoc#macos[Build Guide]
- Android - xref:./docs/build.adoc#android[Build Guide]
== Usage
The following shows some example command line usage on how to configure and run the Vulkan Samples.
Make sure that you are running the samples from the root directory of the repository. Otherwise the samples will not be able to find the assets. ./build/app/bin/
/ /vulkan_samples
For the entire usage use
vulkan_samples --help
For subcommand usage use
vulkan_samples <sub_command> --help
Run Swapchain Images sample
vulkan_samples sample swapchain_images
Run AFBC sample in benchmark mode for 5000 frames
vulkan_samples sample afbc --benchmark --stop-after-frame 5000
Run bonza test offscreen
vulkan_samples test bonza --headless
Run all the performance samples for 10 seconds in each configuration
vulkan_samples batch --category performance --duration 10
Run Swapchain Images sample on an Android device
adb shell am start-activity -n com.khronos.vulkan_samples/com.khronos.vulkan_samples.SampleLauncherActivity -e sample swapchain_images
== Tests
- System Test - xref:docs/testing.adoc#system-test[Usage Guide]
- Generate Sample - xref:docs/testing.adoc#generate-sample-test[Usage Guide]
== License
See link:LICENSE[LICENSE].
This project has some third-party dependencies, each of which may have independent licensing:
- https://github.com/ARM-software/astc-encoder[astc-encoder]: ASTC Evaluation Codec
- https://github.com/vit-vit/CTPL[CTPL]: Thread Pool Library
- https://github.com/docopt/docopt.cpp[docopt]: A C{pp}11 port of the Python argument parsing library
- https://github.com/glfw/glfw[glfw]: A multi-platform library for OpenGL, OpenGL ES, Vulkan, window and input
- https://github.com/g-truc/glm[glm]: OpenGL Mathematics
- https://github.com/KhronosGroup/glslang[glslang]: Shader front end and validator
- https://github.com/ocornut/imgui[dear imgui]: Immediate Mode Graphical User Interface
- https://github.com/ARM-software/HWCPipe[HWCPipe]: Interface to mobile Hardware Counters
- https://github.com/KhronosGroup/KTX-Software[KTX-Software]: Khronos Texture Library and Tools
- https://github.com/gabime/spdlog[spdlog]: Fast C{pp} logging library
- https://github.com/KhronosGroup/SPIRV-Cross[SPIRV-Cross]: Parses and converts SPIR-V to other shader languages
- https://github.com/nothings/stb[stb]: Single-file public domain (or MIT licensed) libraries
- https://github.com/syoyo/tinygltf[tinygltf]: Header only C{pp}11 glTF 2.0 file parser
- https://github.com/nlohmann/json[nlohmann json]: C{pp} JSON Library (included by https://github.com/syoyo/tinygltf[tinygltf])
- https://github.com/GPUOpen-LibrariesAndSDKs/VulkanMemoryAllocator[vma]: Vulkan Memory Allocator
- https://github.com/zeux/volk[volk]: Meta loader for Vulkan API
- https://github.com/KhronosGroup/Vulkan-Docs[vulkan]: Sources for the formal documentation of the Vulkan API
This project uses assets from https://github.com/KhronosGroup/Vulkan-Samples-Assets[vulkan-samples-assets]. Each one has its own license.
=== Trademarks
Vulkan is a registered trademark of the Khronos Group Inc.
== Contributions
Donated to Khronos by Arm, with further contributions by Sascha Willems and Adam Sawicki. See xref:CONTRIBUTORS.adoc[CONTRIBUTORS] for the full contributor list.
Also see xref:CONTRIBUTING.adoc[CONTRIBUTING] for contribution guidelines.
== Related resources
- https://developer.arm.com/documentation/101897/latest/[Mali GPU Best Practices]: A document with recommendations for efficient API usage
Top Related Projects
Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2
C++ examples for the Vulkan graphics API
Ray tracing examples and tutorials using VK_KHR_ray_tracing
A beginner-friendly Vulkan path tracing tutorial in under 300 lines of C++.
Cross-platform, graphics API agnostic, "Bring Your Own Engine/Framework" style rendering library.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot