# vsg-dev/vulkanscenegraph architecture

> Architecture diagram of the GitHub repository vsg-dev/vulkanscenegraph, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vsg-dev/vulkanscenegraph
- Repository: https://github.com/vsg-dev/vulkanscenegraph

## Overview

#### 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: [`include/vsg/app/Viewer.h`](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/Viewer.h) (Viewer), [`include/vsg/nodes/Node.h`](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/nodes/Node.h) (Scene node hierarchy), [`include/vsg/vk/Device.h`](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/vk/Device.h) (Vulkan device), [`src/vsg/vk/Context.cpp`](https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/vk/Context.cpp) (Compilation context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_build["Build Surface"]
  node_cmake["CMake build and package<br/>[CMakeLists.txt]"]
  node_public_api["Public API aggregate<br/>headers<br/>[all.h]"]
end

subgraph group_scene["Scene Model"]
  node_object_model["Object and visitor model<br/>core<br/>[Object.h]"]
  node_scene_nodes["Scene node hierarchy<br/>scene graph<br/>[Node.h]"]
  node_state_groups["State-bearing subtrees<br/>scene state<br/>[StateGroup.h]"]
  node_geometry["Geometry nodes<br/>renderable scene<br/>[Geometry.cpp]"]
end

subgraph group_gpu["Vulkan and State"]
  node_device["Vulkan device<br/>Vulkan wrapper<br/>[Device.h]"]
  node_swapchain["Swapchain<br/>presentation resource<br/>[Swapchain.h]"]
  node_context["Compilation context<br/>Vulkan context<br/>[Context.cpp]"]
  node_pipeline_state["Pipelines and shaders<br/>GPU state<br/>[GraphicsPipeline.h]"]
end

subgraph group_frame["Frame Pipeline"]
  node_commands["Render commands<br/>command model<br/>[Command.h]"]
  node_viewer["Viewer<br/>application runtime<br/>[Viewer.h]"]
  node_render_graph["Render graph<br/>render traversal<br/>[RenderGraph.h]"]
  node_compile_traversal["Compile traversal<br/>GPU realization<br/>[CompileTraversal.h]"]
  node_record_submit["Record and submit<br/>frame task"]
  node_presentation["Presentation<br/>[Presentation.cpp]"]
end

subgraph group_services["I/O, Input, Background"]
  node_input_camera["Input and camera control<br/>UI interaction<br/>[CollectEvents.h]"]
  node_assets_paging["Assets and database paging<br/>I/O service<br/>[DatabasePager.h]"]
  node_operation_threads["Operation threads<br/>background work<br/>[OperationThreads.h]"]
end

subgraph group_platform["Platform Boundaries"]
  node_native_windows["Native window adapters<br/>platform adapter<br/>[Win32_Window.cpp]"]
  node_vulkan{{"Vulkan 1.1+<br/>external API"}}
  node_shader_compiler["Optional glslang compiler<br/>external integration<br/>[ShaderCompiler.h]"]
end

node_cmake -->|"packages"| node_public_api
node_public_api -->|"exports"| node_object_model
node_object_model -->|"base objects and visitors"| node_scene_nodes
node_scene_nodes -->|"specializes"| node_state_groups
node_scene_nodes -->|"specializes"| node_geometry
node_state_groups -->|"binds"| node_pipeline_state
node_geometry -->|"records draw work"| node_commands
node_pipeline_state -->|"compiled by"| node_context
node_context -->|"realizes on"| node_device
node_device -->|"wraps"| node_vulkan
node_device -->|"owns presentation resources"| node_swapchain
node_viewer -->|"drives"| node_render_graph
node_viewer -->|"runs"| node_compile_traversal
node_viewer -->|"runs"| node_record_submit
node_render_graph -->|"traverses and records"| node_commands
node_compile_traversal -->|"uses"| node_context
node_record_submit -->|"presents via"| node_swapchain
node_presentation -->|"creates"| node_swapchain
node_native_windows -->|"provides native surface"| node_presentation
node_input_camera -->|"feeds events"| node_viewer
node_assets_paging -->|"schedules loading"| node_operation_threads
node_operation_threads -.->|"supports async compilation"| node_compile_traversal
node_shader_compiler -.->|"compiles shaders at runtime"| node_pipeline_state

click node_cmake "https://github.com/vsg-dev/vulkanscenegraph/blob/master/CMakeLists.txt"
click node_public_api "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/all.h"
click node_object_model "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/core/Object.h"
click node_scene_nodes "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/nodes/Node.h"
click node_state_groups "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/nodes/StateGroup.h"
click node_geometry "https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/nodes/Geometry.cpp"
click node_device "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/vk/Device.h"
click node_swapchain "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/vk/Swapchain.h"
click node_context "https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/vk/Context.cpp"
click node_pipeline_state "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/state/GraphicsPipeline.h"
click node_commands "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/commands/Command.h"
click node_viewer "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/Viewer.h"
click node_render_graph "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/RenderGraph.h"
click node_compile_traversal "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/CompileTraversal.h"
click node_record_submit "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/RecordAndSubmitTask.h"
click node_presentation "https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/app/Presentation.cpp"
click node_input_camera "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/ui/CollectEvents.h"
click node_assets_paging "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/io/DatabasePager.h"
click node_operation_threads "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/threading/OperationThreads.h"
click node_native_windows "https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/platform/win32/Win32_Window.cpp"
click node_shader_compiler "https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/utils/ShaderCompiler.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cmake,node_public_api toneBlue
class node_object_model,node_scene_nodes,node_state_groups,node_geometry toneAmber
class node_device,node_swapchain,node_context,node_pipeline_state toneMint
class node_commands,node_viewer,node_render_graph,node_compile_traversal,node_record_submit,node_presentation toneRose
class node_input_camera,node_assets_paging,node_operation_threads toneIndigo
class node_native_windows,node_vulkan,node_shader_compiler toneTeal
```

## Components

### Build Surface

- [CMake build and package](https://github.com/vsg-dev/vulkanscenegraph/blob/master/CMakeLists.txt): build · Builds and installs libvsg. · `CMakeLists.txt`
- [Public API aggregate](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/all.h): headers · `include/vsg/all.h`

### Scene Model

- [Object and visitor model](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/core/Object.h): core · Intrusive objects, typed data, visitors, and memory facilities. · `include/vsg/core/Object.h`
- [Scene node hierarchy](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/nodes/Node.h): scene graph · Nodes represent traversable scene content. · `include/vsg/nodes/Node.h`
- [State-bearing subtrees](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/nodes/StateGroup.h): scene state · Attaches graphics state to scene subtrees. · `include/vsg/nodes/StateGroup.h`
- [Geometry nodes](https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/nodes/Geometry.cpp): renderable scene · `src/vsg/nodes/Geometry.cpp`

### Vulkan and State

- [Vulkan device](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/vk/Device.h): Vulkan wrapper · Owns device-facing Vulkan resources and queues. · `include/vsg/vk/Device.h`
- [Swapchain](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/vk/Swapchain.h): presentation resource · `include/vsg/vk/Swapchain.h`
- [Compilation context](https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/vk/Context.cpp): Vulkan context · Creates device-specific resources during compilation. · `src/vsg/vk/Context.cpp`
- [Pipelines and shaders](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/state/GraphicsPipeline.h): GPU state · Descriptors, shaders, buffers, images, and graphics or compute pipelines. · `include/vsg/state/GraphicsPipeline.h`

### Frame Pipeline

- [Render commands](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/commands/Command.h): command model · Draw, dispatch, copy, barrier, query, and secondary commands. · `include/vsg/commands/Command.h`
- [Viewer](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/Viewer.h): application runtime · Coordinates windows, views, render graphs, and frame work. · `include/vsg/app/Viewer.h`
- [Render graph](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/RenderGraph.h): render traversal · `include/vsg/app/RenderGraph.h`
- [Compile traversal](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/CompileTraversal.h): GPU realization · Compiles pending scene and state resources. · `include/vsg/app/CompileTraversal.h`
- [Record and submit](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/app/RecordAndSubmitTask.h): frame task · Records command buffers, submits queues, and synchronizes presentation. · `include/vsg/app/RecordAndSubmitTask.h`
- [Presentation](https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/app/Presentation.cpp): window presentation · `src/vsg/app/Presentation.cpp`

### I/O, Input, Background

- [Input and camera control](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/ui/CollectEvents.h): UI interaction · Native events drive camera handlers. · `include/vsg/ui/CollectEvents.h`
- [Assets and database paging](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/io/DatabasePager.h): I/O service · Reader/writer extensibility and streamed scene loading. · `include/vsg/io/DatabasePager.h`
- [Operation threads](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/threading/OperationThreads.h): background work · Supports asynchronous loading, compilation, and deferred destruction. · `include/vsg/threading/OperationThreads.h`

### Platform Boundaries

- [Native window adapters](https://github.com/vsg-dev/vulkanscenegraph/blob/master/src/vsg/platform/win32/Win32_Window.cpp): platform adapter · Android, Apple, Win32, and XCB implementations. · `src/vsg/platform/win32/Win32_Window.cpp`
- **Vulkan 1.1+**: external API
- [Optional glslang compiler](https://github.com/vsg-dev/vulkanscenegraph/blob/master/include/vsg/utils/ShaderCompiler.h): external integration · Enables runtime shader compilation. · `include/vsg/utils/ShaderCompiler.h`

## Connections

- 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
