https://github.com/nvpro-samples/vk_mini_samples
Collection of Vulkan samples
https://github.com/nvpro-samples/vk_mini_samples
Last synced: 4 months ago
JSON representation
Collection of Vulkan samples
- Host: GitHub
- URL: https://github.com/nvpro-samples/vk_mini_samples
- Owner: nvpro-samples
- License: apache-2.0
- Created: 2021-11-01T15:13:05.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-11-19T20:29:14.000Z (7 months ago)
- Last Synced: 2025-11-19T22:12:48.811Z (7 months ago)
- Language: CMake
- Size: 19.6 MB
- Stars: 302
- Watchers: 12
- Forks: 18
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Vulkan Samples
This repository contains numerous examples demonstrating various aspects of Vulkan, debugging techniques, and integration with other NVIDIA tools. For a comprehensive list, refer to the [Samples](#Samples) section below.
Each sample is accompanied by its own documentation detailing functionality and providing references for further information.
## Dependencies
* [nvpro_core](https://github.com/nvpro-samples/nvpro_core): A collection of Vulkan helper classes and utilities.
## Build Instructions
### Cloning Repositories
```bash
git clone --recursive --shallow-submodules https://github.com/nvpro-samples/nvpro_core.git
git clone https://github.com/nvpro-samples/vk_mini_samples.git
```
### Generating Solution
```bash
cd vk_mini_samples
mkdir build
cd build
cmake ..
```
### Additional SDKs
The Aftermath sample requires the separate download of the [Nsight Aftermath SDK](https://developer.nvidia.com/nsight-aftermath).
### Shader Language Options: GLSL, HLSL, or SLANG
By default, samples use GLSL shaders. However, many also offer equivalent shaders in [HLSL](https://learn.microsoft.com/en-us/windows/win32/direct3dhlsl/dx-graphics-hlsl) and [SLANG](https://github.com/shader-slang/slang). To switch between them, select the desired shader language and regenerate the CMake configuration. The solution will update accordingly with compatible projects and their respective shaders.
## Samples
For those new to this repository, the [solid color](samples/solid_color) and [rectangle](samples/rectangle) samples are recommended starting points to better understand the framework.
| Name | Description | Image | GLSL | HLSL | Slang |
| ------ | ------ | ---- | ---- | ---- | ---- |
| [barycentric_wireframe](samples/barycentric_wireframe) | Single-pass solid-wireframe rendering using `gl_BaryCoordNV` |  | [x] | [x] | [x] |
| [compute_multi_threaded](samples/compute_multi_threaded) | Executing a compute shader in a separate thread faster than the main thread.|  | [x] | [x] | [x] |
| [compute_only](samples/compute_only) | Basic compute and display example |  | [x] | [x] | [x] |
| [crash_aftermath](samples/crash_aftermath) | Integration of Nsight Aftermath SDK into an existing application |  | [x] | [x] | [x] |
| [gltf_raytrace](samples/gltf_raytrace) | glTF scene loading with path-tracing renderer |  | [x] | [x] | [x] |
| [gpu_monitor](samples/gpu_monitor) | GPU usage visualization |  | [x] | [x] | [x] |
| [image_ktx](samples/image_ktx) | KTX image display with tonemapping post-processing |  | [x] | [x] | [x] |
| [image_viewer](samples/image_viewer) | Image loading with zoom and pan functionality |  | [x] | [x] | [x] |
| [line_stipple](samples/line_stipple) | Dashed line rendering with stipple pattern |  | [x] | [x] | [x] |
| [memory_budget](samples/memory_budget) | Dynamic memory allocation within budget constraints |  | [x] | [x] | [x] |
| [mm_opacity](samples/mm_opacity) | Micromap opacity implementation |  | [x] | [x] | [x] |
| [msaa](samples/msaa) | Hardware Multi-Sampling Anti-Aliasing demonstration |  | [x] | [x] | [x] |
| [offscreen](samples/offscreen) | Windowless rendering with image save functionality. |  | [x] | [x] | [x] |
| [ray_query](samples/ray_query) | Inline raytracing in compute shaders |  | [x] | [x] | [x] |
| [ray_query_position_fetch](samples/ray_query_position_fetch) | Using VK_KHR_ray_tracing_position_fetch usage in ray query |  | [x] | [ ] | [x] |
| [ray_trace](samples/ray_trace) | Basic ray tracer with metallic-roughness shading, reflections, shadows, and sky shader. |  | [x] | [x] | [x] |
| [ray_trace_motion_blur](samples/ray_trace_motion_blur) | Motion blur for dynamic objects using NVIDIA raytracing extension |  | [x] | [ ] | [x] |
| [ray_tracing_position_fetch](samples/ray_tracing_position_fetch) | VK_KHR_ray_tracing_position_fetch implementation. |  | [x] | [ ] | [x] |
| [realtime_analysis](samples/realtime_analysis) | Real-time GPU information display |  | [x] | [ ] | [x] |
| [rectangle](samples/rectangle) | 2D rectangle rendering to GBuffer. |  | [x] | [x] | [x] |
| [ser_pathtrace](samples/ser_pathtrace) | Shading Execution Reordering (SER) for optimized GPU usage. |  | [x] | [x] | [x] |
| [shader_object](samples/shader_object) | Shader object and dynamic pipeline usage |  | [x] | [x] | [x] |
| [shader_printf](samples/shader_printf) | Shader debugging with printf functionality |  | [x] | [x] | [x] |
| [simple_polygons](samples/simple_polygons) | Multi-polygon object rasterization. |  | [x] | [x] | [x] |
| [solid_color](samples/solid_color) | Single-pixel texture creation and display. |  | [x] | [x] | [x] |
| [texture 3d](samples/texture_3d) | 3D texture creation and ray marching. |  | [x] | [x] | [x] |
| [tiny_shader_toy](samples/tiny_shader_toy) | Real-time shader compilation with error display and multi-stage pipelines. |  | [x] | [ ] | [ ] |
## Rendering Architecture
Those samples demonstrates an indirect rendering approach, diverging from direct swapchain image rendering. The rendering pipeline is structured as follows:
1. **Off-screen Rendering**: The sample renders its content to an off-screen image buffer rather than directly to the swapchain image.
2. **GUI Integration**: The rendered off-screen image is incorporated as an element within the GUI layout.
3. **Composite Rendering**: The `nvvkhl::Application` framework manages the final composition step. It combines the GUI elements (including the embedded rendered image) into a unified layout.
4. **Swapchain Presentation**: The composite result from step 3 is then rendered to the swapchain image for final presentation.
This architecture provides several advantages:
- Decouples the sample's rendering from the final presentation
- Allows for flexible GUI integration of rendered content
- Facilitates additional post-processing or compositing operations
Developers should note that the actual swapchain image rendering is abstracted away within the `nvvkhl::Application` class, providing a clean separation of concerns between sample-specific rendering and final frame composition.
## Application Architecture
The examples in this repository leverage various utilities from the [nvpro_core](https://github.com/nvpro-samples/nvpro_core) framework. Central to each sample's implementation is the [`Application`](https://github.com/nvpro-samples/nvpro_core/blob/master/nvvkhl/application.hpp) class, which provides core functionality for:
- Window creation and management
- User interface (UI) initialization
- Swapchain setup integrated with the ImGui framework
The `Application` class is an enhanced derivative of the Dear ImGui Vulkan example, optimized for our use cases.
### Modular Design
Samples are implemented as `Elements` and attached to the `Application` instance. This modular approach allows for:
1. Separation of concerns between core application logic and sample-specific code
2. Consistent handling of UI rendering and frame operations across different samples
### Initialization Process
The `init()` method orchestrates the following setup procedures:
1. GLFW window initialization
2. Swapchain setup through `ImplVulkanH_CreateOrResizeWindow`
### Execution Cycle
The `run()` method implements the main application loop, continuing until a termination event is triggered. Each iteration of this loop invokes the following methods on attached `Elements`, in sequence:
1. `onResize`: Handles viewport dimension changes
2. `onUIMenu`: Facilitates additions to the menu bar
3. `onUIRender`: Manages UI-related rendering tasks
4. `onRender`: Executes sample-specific rendering operations within the current frame's command buffer
Post-element processing, each frame concludes with:
- `frameRender()`: Finalizes the frame's rendering operations
- `framePresent()`: Submits the completed frame for presentation
This architecture provides a robust and flexible framework for implementing diverse Vulkan-based graphical samples while maintaining a consistent application structure.
## Shader Language Support
### SPIR-V Intermediate Representation
Vulkan utilizes SPIR-V as its intermediate shader representation, diverging from the direct consumption of human-readable shader text. This architectural decision enables support for multiple high-level shader languages, provided they can target the Vulkan SPIR-V environment.
### Configuration Options
The samples in this repository are designed to accommodate multiple shader languages. Language selection is controlled via CMake options:
- `USE_GLSL`: Enables GLSL shader compilation
- `USE_SLANG`: Enables Slang shader compilation
- `USE_HLSL`: Enables HLSL shader compilation
### Supported Languages
#### Slang
[Slang](https://github.com/shader-slang/slang) is a high-level shader language with syntax resembling C++. It is extensively used in NVIDIA research due to its versatility in targeting multiple backends:
- SPIR-V (Vulkan)
- DirectX 12
- CUDA
- C++
To specify a custom Slang compiler version, modify the `Slang_VERSION` CMakeLists.txt.
#### HLSL (High Level Shading Language)
Microsoft's HLSL, primarily associated with DirectX, has been extended to support SPIR-V code generation. Recent versions of the Vulkan SDK include the DXC compiler by default, facilitating HLSL to SPIR-V compilation.
To use a non-default `dxc` binary, modify the `Vulkan_dxc_EXECUTABLE` path in the `Vulkan` CMake configuration.
#### GLSL (Default)
GLSL (OpenGL Shading Language) serves as the default shader language when neither Slang nor HLSL is explicitly enabled. It is natively supported by the Vulkan ecosystem.
This multi-language support strategy offers developers flexibility in shader authoring while maintaining compatibility with Vulkan's SPIR-V requirements.
### Resources
#### HLSL
- HLSL to SPIR-V: [Feature Mapping Manual](https://github.com/microsoft/DirectXShaderCompiler/blob/main/docs/SPIR-V.rst)
- Ray Tracing: [HLSL](https://microsoft.github.io/DirectX-Specs/d3d/Raytracing.html)
- Porting to HLSL:
- [GLSL variables](https://learn.microsoft.com/en-us/windows/uwp/gaming/glsl-to-hlsl-reference#porting-glsl-variables-to-hlsl)
- [GLSL types](https://learn.microsoft.com/en-us/windows/uwp/gaming/glsl-to-hlsl-reference#porting-glsl-types-to-hlsl)
- [Global Variables](https://learn.microsoft.com/en-us/windows/uwp/gaming/glsl-to-hlsl-reference#porting-glsl-pre-defined-global-variables-to-hlsl)
- [Mapping between HLSL and GLSL](https://anteru.net/blog/2016/mapping-between-HLSL-and-GLSL/)
#### SLANG
- [GitHub Repository](https://github.com/shader-slang/slang)
- [Releases](https://github.com/shader-slang/slang/releases)
- [Getting Started Guide](https://shader-slang.com/getting-started.html)
- [User Guide](http://shader-slang.com/slang/user-guide/index.html)
- [Documentation](https://github.com/shader-slang/slang/tree/master/docs)
- [GLSL and SPIR-V Interoperability](https://shader-slang.com/slang/user-guide/a1-04-interop.html)
- [Standard Library Reference](https://shader-slang.com/stdlib-reference/index.html)
- [Language Specification](https://htmlpreview.github.io/?https://github.com/shader-slang/spec/blob/main/index.html#intro)
#### SPIR-V Intrinsics
- [GL_EXT_spirv_intrinsics](https://github.com/microsoft/DirectXShaderCompiler/wiki/GL_EXT_spirv_intrinsics-for-SPIR-V-code-gen)
- [KHR Extensions](https://github.com/KhronosGroup/SPIRV-Registry/tree/main/extensions/KHR)
- [JSON Specification](https://github.com/KhronosGroup/SPIRV-Headers/blob/main/include/spirv/unified1/spirv.json)
- [SPIR-V Specification](https://registry.khronos.org/SPIR-V/specs/unified1/SPIRV.html)
## LICENSE
Copyright 2024-2025 NVIDIA CORPORATION. Released under Apache License,
Version 2.0. See "LICENSE" file for details.