Vulkan Samples

A comprehensive collection of Vulkan examples demonstrating various aspects of modern graphics programming, debugging techniques, and integration with NVIDIA tools. This repository serves as both a learning resource and a reference implementation for Vulkan development.

Quick Start

Prerequisites

• nvpro_core2: Vulkan helper classes and utilities
• Vulkan 1.4+ compatible GPU and drivers
• CMake 3.18+

Build Instructions

# Clone repositories
git clone https://github.com/nvpro-samples/nvpro_core2.git
git clone https://github.com/nvpro-samples/vk_mini_samples.git

# Build
cd vk_mini_samples
cmake -B build -S .
cmake --build build -j 8

Compiled files will be under the _bin directory.

Learning Path

For Beginners

Start with these foundational samples to understand the framework:

Sample	Description	Image	GLSL	Slang
solid_color	Single-pixel texture creation and display		-	-
rectangle	2D rectangle rendering to GBuffer		✅	✅

Sample Catalog

Graphics & Rendering

Sample	Description	Image	GLSL	Slang
barycentric_wireframe	Single-pass solid-wireframe rendering using gl_BaryCoordNV		✅	✅
descriptor_heap	VK_EXT_descriptor_heap with per-draw and bindless rendering modes		✅	✅
gltf_raytrace	glTF path tracer, fully bindless with VK_EXT_descriptor_heap		❌	✅
image_ktx	KTX image display with tonemapping post-processing		✅	✅
image_viewer	Image loading with zoom and pan functionality		✅	✅
line_stipple	Dashed line rendering with stipple pattern		✅	✅
mesh_shaders	Basic mesh shaders without task shader (baseline)		✅	✅
mesh_task_shaders	Mesh and task shaders with GPU-driven frustum culling		✅	✅
mm_opacity	Micromap opacity implementation		✅	✅
msaa	Hardware Multi-Sampling Anti-Aliasing demonstration		✅	✅
offscreen	Windowless rendering with image save functionality		✅	✅
rectangle	2D rectangle rendering to GBuffer		✅	✅
simple_polygons	Multi-polygon rasterization; VK_EXT_descriptor_heap on a classic pipeline		✅	✅
solid_color	Single-pixel texture creation and display		✅	✅
texture_3d	3D texture creation and ray marching; bindless VK_EXT_descriptor_heap		✅	✅

Ray Tracing & Advanced Graphics

Sample	Description	Image	GLSL	Slang
ray_query	Inline raytracing in compute shaders		✅	✅
ray_query_position_fetch	Using VK_KHR_ray_tracing_position_fetch in ray query		✅	✅
ray_trace	Basic ray tracer; VK_EXT_descriptor_heap on a ray-tracing pipeline		❌	✅
ray_trace_clusters	Cluster acceleration structures (VK_NV_cluster_acceleration_structure) with per-cluster coloring and LOD		✅	✅

More raytracing examples can be found in the vk_raytracing_tutorial_KHR.

Compute & Performance

Sample	Description	Image	GLSL	Slang
compute_multi_threaded	Executing compute shaders in separate threads		✅	✅
compute_only	Basic compute and display; bindless VK_EXT_descriptor_heap		✅	✅
memory_budget	Dynamic memory allocation within budget constraints		✅	✅
realtime_analysis	Real-time GPU information display		✅	❌

Development & Debugging

Sample	Description	Image	GLSL	Slang
crash_aftermath	Integration of Nsight Aftermath SDK		✅	✅
gpu_monitor	GPU usage visualization		✅	✅
shader_object	Shader object and dynamic pipeline usage		✅	✅
shader_printf	Shader debugging with printf functionality		✅	✅
tiny_shader_toy	Real-time shader compilation with error display		✅	✅

Architecture

Rendering Pipeline

The samples demonstrate an indirect rendering approach with the following structure:

1. Off-screen Rendering → Sample renders to off-screen buffer
2. GUI Integration → Rendered content embedded in GUI layout
3. Composite Rendering → nvapp::Application combines GUI elements
4. Swapchain Presentation → Final composition presented to screen

Application Architecture

The examples in this repository leverage various utilities from the nvpro_core2 framework. Central to each sample's implementation is the Application 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

Application Lifecycle

The following diagram illustrates the complete application lifecycle, from initialization through the main rendering loop:

flowchart LR
    subgraph s1["Application Element"]
        O["onAttach: Initialize"]
        P["onUIMenu: Menu Items"]
        Q["onUIRender: UI Widgets"]
        R["onPreRender: Pre-frame Setup"]
        S["onRender: GPU Commands"]
        T["onPostRender: Post-frame Setup"]
        U["onDetach: Cleanup"]
    end
    
    A["Constructor"] --> B["init: Setup Window, Vulkan, ImGui"]
    B --> C["run: Main Loop"]
    C --> D["Frame Setup: Events, ImGui, Viewport"]
    D --> E{"prepareFrameResources"}
    E -- Success --> F["beginCommandRecording"]
    E -- Fail --> C
    F --> I["drawFrame: Element Processing"]
    I --> J["renderToSwapchain: ImGui"]
    J --> L["endFrame: Submit Commands"]
    L --> M["presentFrame"]
    M --> N["advanceFrame"]
    N --> C
    
    B -. addElement .-> O
    D -. Menu Bar .-> P
    I -. UI Phase .-> Q
    I -. "Pre-Render" .-> R
    I -. Render Phase .-> S
    I -. "Post-Render" .-> T
    
    C -->|Exit Event| V["shutdown()"]
    V -. onDetach .-> U
    
    style O fill:#f1f8e9
    style P fill:#f1f8e9
    style Q fill:#f1f8e9
    style R fill:#f1f8e9
    style S fill:#f1f8e9
    style T fill:#f1f8e9
    style U fill:#f1f8e9
    style A fill:#e1f5fe
    style C fill:#f3e5f5
    style I fill:#FFE0B2
    style M fill:#FFE0B2
    style V fill:#ffebee

Loading

Initialization Process

The init() method orchestrates the following setup procedures:

1. GLFW Initialization: glfwInit() sets up the windowing system
2. Vulkan Context: nvvk::Context::init() creates the Vulkan instance, device, and queues
3. Window Creation: ImGui_ImplVulkanH_CreateOrResizeWindow() creates the window and swapchain
4. ImGui Setup: ImGui_ImplVulkan_Init() initializes the ImGui Vulkan backend
5. Swapchain: Manages presentation images

During initialization, core Vulkan resources are provided by the framework:

• VkInstance: Connection between application and Vulkan library
• VkPysicalDevice: Representation of the physical GPU
• VkDevice: Logical representation of the physical GPU
• VkQueue: Command submission queue for GPU operations

Execution Cycle

The run() method implements the main application loop, continuing until a termination event is triggered. Each iteration follows this sequence:

Frame Preparation

1. Frame Setup: Process events, update ImGui, handle viewport changes
2. Resource Management: prepareFrameResources() acquires swapchain image
3. Cleanup: freeResourcesQueue() releases previous frame resources
4. Synchronization: prepareFrameToSignal() sets up frame synchronization

Command Recording

5. Command Buffer: beginCommandRecording() starts recording GPU commands
6. Element Processing: drawFrame() invokes element callbacks in sequence:
   • onUIRender: UI widget rendering
   • onPreRender: Pre-frame setup operations
   • onRender: Sample-specific GPU commands
   • onPostRender: Post-frame cleanup operations

Frame Completion

7. ImGui Rendering: renderToSwapchain() renders UI to swapchain image
8. Synchronization: addSwapchainSemaphores() sets up presentation synchronization
9. Submission: endFrame() submits command buffers to GPU
10. Presentation: presentFrame() presents the completed frame
11. Advancement: advanceFrame() moves to next frame resources

Element Lifecycle

Elements attached to the application follow a well-defined lifecycle:

• onAttach: Called during addElement(), used for initialization
• onUIMenu: Called during frame setup, adds menu items to the menu bar
• onUIRender: Called during UI phase, renders ImGui widgets
• onPreRender: Called before main rendering, handles pre-frame setup
• onRender: Called during render phase, records GPU commands
• onPostRender: Called after main rendering, handles post-frame cleanup
• onDetach: Called during shutdown, used for cleanup and resource deallocation

Shader Language Support

SPIR-V Intermediate Representation

Vulkan uses SPIR-V as its intermediate shader representation, enabling support for multiple high-level shader languages.

Supported Languages

Slang (Default)

Slang - High-level shader language with C++-like syntax

• Targets: SPIR-V (Vulkan), DirectX 12, CUDA, C++
• Usage: Set USE_SLANG=1 in CMakeLists.txt

GLSL

OpenGL Shading Language - Native Vulkan ecosystem support

• Usage: Set USE_SLANG=0 in CMakeLists.txt

Additional Dependencies

Required SDKs

• Nsight Aftermath SDK: Required for the crash_aftermath sample
  • Download from NVIDIA Developer

Resources

Shader Language Resources

• Slang Documentation
• SPIR-V Specification
• GL_EXT_spirv_intrinsics

Related Projects

• nvpro_core2: Core framework and utilities
• vk_raytracing_tutorial_KHR: Original KHR ray tracing tutorial

License

Copyright 2024-2026 NVIDIA CORPORATION. Released under Apache License, Version 2.0. See LICENSE file for details.