How vsg-dev/vulkanscenegraph works
Purpose and Build Surface
VulkanSceneGraph (VSG) is a C++17, cross-platform scene-graph library for Vulkan graphics and compute; this repository builds the libvsg library, not an application. CMake is the build/install entry point: CMakeLists.txt, src/vsg/CMakeLists.txt, and generated package metadata src/vsg/vsgConfig.cmake.in. Public API is organized under include/vsg/, with aggregate inclusion at include/vsg/all.h.
Core Object and Scene Model
Intrusive-reference-counted objects, typed data/arrays, visitors, and memory facilities form the common object model. Scene content is a hierarchy of Node subclasses, traversed for update, compilation, culling, and recording. State-bearing groups attach graphics state to subtrees, while transform, LOD, instancing, and geometry nodes express renderable structure.
Paths: include/vsg/core/Object.h, include/vsg/core/Visitor.h, include/vsg/nodes/Node.h, include/vsg/nodes/StateGroup.h, src/vsg/nodes/Geometry.cpp.
Vulkan Abstraction and GPU Resources
The vk layer owns Vulkan-facing wrappers for instance/device selection, surfaces, queues, synchronization, command buffers, memory, render passes, and swapchains. The state layer describes buffers, images, descriptors, shaders, and graphics/compute pipelines; compilation translates scene/state objects into device-specific Vulkan resources.
Paths: include/vsg/vk/Device.h, include/vsg/vk/Swapchain.h, include/vsg/state/GraphicsPipeline.h, src/vsg/vk/Context.cpp, src/vsg/state/ShaderModule.cpp.
Frame Rendering Pipeline
Applications create windows/presentations and a Viewer, attach camera/view and render/command graphs, then run frame work. Update operations mutate dynamic scene data; compile traversals realize pending GPU resources; record traversals convert graph contents to Vulkan command buffers; record/submit and transfer tasks synchronize queue submission and presentation.
Paths: include/vsg/app/Viewer.h, include/vsg/app/RenderGraph.h, include/vsg/app/CompileTraversal.h, include/vsg/app/RecordAndSubmitTask.h, src/vsg/app/Presentation.cpp.
Commands, Traversals, and Advanced Rendering
Command objects encapsulate Vulkan draw, dispatch, copy, barriers, queries, and secondary-command execution. Scene traversal selects and records these commands under state. Optional subsystems integrate mesh shader draws and Vulkan ray tracing acceleration structures/pipelines into the same command/state model.
Paths: include/vsg/commands/Command.h, include/vsg/commands/DrawIndexed.h, include/vsg/raytracing/BuildAccelerationStructureTraversal.h, include/vsg/raytracing/RayTracingPipeline.h, src/vsg/meshshaders/DrawMeshTasks.cpp.
Input, Assets, and Background Work
Platform window adapters translate native events into VSG UI events; camera handlers consume them for interaction. I/O provides VSG ASCII/binary serialization, reader/writer extensibility, paths/options, and database paging for streamed scene tiles/LOD. Threading primitives and operation threads support asynchronous compilation, loading, and deferred destruction.
Paths: include/vsg/ui/CollectEvents.h, include/vsg/app/Trackball.h, include/vsg/io/ReaderWriter.h, include/vsg/io/DatabasePager.h, include/vsg/threading/OperationThreads.h.
Platform and External Boundaries
Vulkan 1.1+ is required; optional glslang enables runtime shader compilation. Native window implementations cover Android, Harmony, iOS/macOS (Objective-C++), Win32, and XCB; Apple targets use MoltenVK per project documentation. Companion repositories supply model/image import, HTTP, UI, Qt/SDL, and examples rather than being embedded here.
Paths: src/vsg/platform/android/Android_Window.cpp, src/vsg/platform/macos/MacOS_Window.mm, src/vsg/platform/win32/Win32_Window.cpp, include/vsg/utils/ShaderCompiler.h.
Main entry points: Viewer.h Viewer · Node.h Scene node hierarchy · Device.h Vulkan device · Context.cpp Compilation context
Components 22
Build Surface
- CMake build and package · Builds and installs libvsg.
CMakeLists.txt - Public API aggregate
include/vsg/all.h
Scene Model
- Object and visitor model · Intrusive objects, typed data, visitors, and memory facilities.
include/vsg/core/Object.h - Scene node hierarchy · Nodes represent traversable scene content.
include/vsg/nodes/Node.h - State-bearing subtrees · Attaches graphics state to scene subtrees.
include/vsg/nodes/StateGroup.h - Geometry nodes
src/vsg/nodes/Geometry.cpp
Vulkan and State
- Vulkan device · Owns device-facing Vulkan resources and queues.
include/vsg/vk/Device.h - Swapchain
include/vsg/vk/Swapchain.h - Compilation context · Creates device-specific resources during compilation.
src/vsg/vk/Context.cpp - Pipelines and shaders · Descriptors, shaders, buffers, images, and graphics or compute pipelines.
include/vsg/state/GraphicsPipeline.h
Frame Pipeline
- Render commands · Draw, dispatch, copy, barrier, query, and secondary commands.
include/vsg/commands/Command.h - Viewer · Coordinates windows, views, render graphs, and frame work.
include/vsg/app/Viewer.h - Render graph
include/vsg/app/RenderGraph.h - Compile traversal · Compiles pending scene and state resources.
include/vsg/app/CompileTraversal.h - Record and submit · Records command buffers, submits queues, and synchronizes presentation.
include/vsg/app/RecordAndSubmitTask.h - Presentation
src/vsg/app/Presentation.cpp
I/O, Input, Background
- Input and camera control · Native events drive camera handlers.
include/vsg/ui/CollectEvents.h - Assets and database paging · Reader/writer extensibility and streamed scene loading.
include/vsg/io/DatabasePager.h - Operation threads · Supports asynchronous loading, compilation, and deferred destruction.
include/vsg/threading/OperationThreads.h
Platform Boundaries
- Native window adapters · Android, Apple, Win32, and XCB implementations.
src/vsg/platform/win32/Win32_Window.cpp - Vulkan 1.1+
- Optional glslang compiler · Enables runtime shader compilation.
include/vsg/utils/ShaderCompiler.h
Connections 23
- CMake build and package → Public API aggregate: packages
- Public API aggregate → Object and visitor model: exports
- Object and visitor model → Scene node hierarchy: base objects and visitors
- Scene node hierarchy → State-bearing subtrees: specializes
- Scene node hierarchy → Geometry nodes: specializes
- State-bearing subtrees → Pipelines and shaders: binds
- Geometry nodes → Render commands: records draw work
- Pipelines and shaders → Compilation context: compiled by
- Compilation context → Vulkan device: realizes on
- Vulkan device → Vulkan 1.1+: wraps
- Vulkan device → Swapchain: owns presentation resources
- Viewer → Render graph: drives
- Viewer → Compile traversal: runs
- Viewer → Record and submit: runs
- Render graph → Render commands: traverses and records
- Compile traversal → Compilation context: uses
- Record and submit → Swapchain: presents via
- Presentation → Swapchain: creates
- Native window adapters → Presentation: provides native surface
- Input and camera control → Viewer: feeds events
- Assets and database paging → Operation threads: schedules loading
- Operation threads → Compile traversal: supports async compilation
- Optional glslang compiler → Pipelines and shaders: compiles shaders at runtime