DOCSEARCHbyAlgolia
Submit Docs

VulkanSceneGraph (VSG)

repository·master·Indexed 23 days ago

https://github.com/vsg-dev/vulkanscenegraph

A high-performance, cross-platform C++17 scene graph library built on top of the Vulkan API, designed for modern graphics and compute applications. It provides a framework for encapsulating Vulkan command buffer calls through a compilable command system, including support for vertex/index buffer binding, image blitting, and attachment clearing.

Tokens
11K
Snippets
12
Records
75
Agent score
82%

What's inside VulkanSceneGraph

  1. Overview of VulkanSceneGraph

    master
    VulkanSceneGraph (VSG) is a modern, cross-platform, high-performance scene graph library built on the Vulkan graphics/compute API. It is written in C++17 and follows CppCoreGuidelines and FOSS Best Practices. The library is licensed under the MIT License (except for vulkan.h which uses Apache License 2.0).

  2. Explore VulkanSceneGraph companion projects

    master

    The VSG ecosystem includes several companion libraries for extended functionality:

    • vsgXchange: Reading/writing 3rd party images, 3D models, and HTTP support.
    • vsgExamples: Tests and examples.
    • osg2vsg: Integration for converting OpenSceneGraph (OSG) to VSG.
    • vsgImGui: ImGui integration for UI in graphics windows.
    • vsgQt: Qt integration.
    • vsgPoints: 3D point cloud loading and rendering (supports billions of points).
    • vsgUnity: Unity plugin for exporting to native VSG formats.
    • MyFirstVsgApplication: A standalone application template.
    • vsgFramework: A CMake template project using FetchContent to pull in all main libraries and dependencies.

  3. Prerequisites for building VulkanSceneGraph

    master

    To build VSG, ensure you meet the following requirements:

    Required:

    • C++17 compliant compiler (e.g., g++ 7.3+, Clang 6.0+, or Visual Studio 2017+)
    • CMake 3.7 or later
    • Vulkan 1.1 or later

    Optional:

    • glslang 14.0 or later (only required if runtime shader compilation is needed)

    Note on Vulkan SDK: For the latest versions, it is recommended to use the VulkanSDK provided by LunarG. After unpacking the SDK, set the VULKAN_SDK environment variable to the include/lib directory within it.

  4. Build VulkanSceneGraph on Unix (Linux/macOS)

    master

    1. Install Dependencies

    Ubuntu family:

    sudo apt-get install cmake-curses-gui g++ git libvulkan-dev glslang-dev glslang-tools

    Fedora:

    dnf install git cmake ninja-build gcc-c++ libxcb-devel vulkan-loader-devel glslc glslang-devel

    Gentoo:

    emerge dev-util/vulkan-tools

    macOS (via Homebrew):

    brew cmake
brew glslang
brew clang-format

    2. Build Instructions

    Static Library (.a) build:

    git clone https://github.com/vsg-dev/VulkanSceneGraph.git
cd VulkanSceneGraph
cmake .
cmake --build . -j 16 -t install

    Shared Library (.so) build:

    git clone https://github.com/vsg-dev/VulkanSceneGraph.git
mkdir vsg-shared-build
cd vsg-shared-build
cmake ../VulkanSceneGraph -DBUILD_SHARED_LIBS=ON
cmake --build . -j 16 -t install

    macOS Note: Use standard Makefiles rather than building directly in Xcode to avoid issues with code signing settings.

  5. Use VulkanSceneGraph in your CMake project

    master

    To use VSG in your own project, ensure you are using CMake. When VSG is installed, it provides a CMake package configuration file in lib/cmake/vsg.

    Basic Integration

    Add the following to your CMakeLists.txt:

    cmake_minimum_required(VERSION 3.10)
find_package(vsg REQUIRED)

add_executable(myapp "myapp.cpp")
target_link_libraries(myapp vsg::vsg)

    Linking to vsg::vsg automatically handles:

    • Include paths.
    • Libraries.
    • Necessary definitions (like VSG_SHARED_LIBRARY on Windows).
    • Setting the minimum C++ standard to 17.

  6. Build VulkanSceneGraph for Android

    master

    Requires Android NDK 18 and CMake 3.13.

    Run the following CMake command (replace /location/of/Android/sdk/ndk-bundle with your actual path):

    cmake ./ \
-DCMAKE_BUILD_TYPE="Debug" \
-DCMAKE_SYSTEM_NAME="Android" \
-DCMAKE_SYSTEM_VERSION=24 \
-DCMAKE_ANDROID_STL_TYPE="c++_static" \
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \
-DCMAKE_ANDROID_NDK=/location/of/Android/sdk/ndk-bundle \
-DCMAKE_INSTALL_PREFIX=/usr/local/android

make -j 8
make install

  7. Build VulkanSceneGraph on Windows

    master

    1. Setup Vulkan SDK

    Download and install the Vulkan SDK (1.2.162.0 or later) from LunarG. Ensure the installer adds VK_SDK_PATH and VULKAN_SDK to your environment variables.

    2. Build via Visual Studio (GUI)

    1. Clone the repository and enter the directory.
    2. Run CMake to generate the solution:
      cmake . -G "Visual Studio 15 2017 Win64"
      (Note: You can also use Visual Studio 2019 or 2022 with appropriate -G flags).
    3. Open the generated VSG.sln file.
    4. Build the All target.
    5. Run the install target. Note: If installing to Program Files, you must run Visual Studio as an Administrator.

    3. Build via Command Line

    git clone https://github.com/vsg-dev/VulkanSceneGraph.git
cd VulkanSceneGraph
mkdir build && cd build
cmake .. -G "Visual Studio 15 2017 Win64"
cmake --build .
cmake --install .

    To specify a different installation directory via CLI, use --prefix Path\To\Another\Directory with the install command.

    4. Integration

    Add the VSG install path to your CMAKE_PREFIX_PATH environment variable so other projects can find it: CMAKE_PREFIX_PATH = C:\Program Files\VSG

  8. Build VSG for macOS using MoltenVK

    master

    Since macOS does not natively support Vulkan, you must use MoltenVK to translate Vulkan calls to Metal.

    1. Install MoltenVK: Download the Vulkan SDK from LunarG, unpack it, and note the path to the macOS subfolder.
    2. Configure Environment: Set the VULKAN_SDK environment variable and related MoltenVK variables so CMake can locate the SDK. You can verify the setup by running the vulkaninfo executable found in vulkansdk/macOS/bin.
    3. Build VSG: Use CMake to generate an Xcode project, then build the install target within Xcode.
    4. Integration: Set CMAKE_PREFIX_PATH to point to your VSG installation so other CMake projects can find it.

    Note for Xcode Users: Xcode often ignores system environment variables. If your application fails to run within Xcode, manually add the required environment variables (like VULKAN_SDK, VK_LAYER_PATH, etc.) to the Product > Scheme > Edit Scheme > Arguments section.

    # 1. Set up environment variables (e.g., in .bash_profile)
export VULKAN_SDK="/path/to/your/vulkansdk/macOS"
export VK_LAYER_PATH="$VULKAN_SDK/etc/vulkan/explicit_layer.d"
export VK_ICD_FILENAMES="$VULKAN_SDK/etc/vulkan/icd.d/MoltenVK_icd.json"
export PATH="$VULKAN_SDK:$VULKAN_SDK/bin:$PATH"
export DYLD_LIBRARY_PATH="$VULKAN_SDK/lib:$DYLD_LIBRARY_PATH"

# 2. Build VSG
git clone https://github.com/vsg-dev/VulkanSceneGraph.git
cd VulkanSceneGraph
cmake . -G "Xcode"

# 3. After installing VSG, set prefix for other projects
export CMAKE_PREFIX_PATH="/usr/local/lib/cmake/vsg"

  9. Build and install the static libvsg library

    master

    Use the following commands to clone the repository and build/install the static libvsg library (.a/.lib) directly in the source directory.

    git clone https://github.com/vsg-dev/VulkanSceneGraph.git
cd VulkanSceneGraph
cmake .
cmake --build . -j 16 -t install

  10. Build VSG for Android

    master

    To build VulkanSceneGraph for Android, you need Android NDK 18 and CMake 3.13.

    1. Install NDK: Use Android Studio's SDK Manager. Ensure at least Android API level 24 is installed, then install the NDK via the 'SDK Tools' tab. Note your 'Android SDK Location'.
    2. Generate Build Files: Use CMake to generate make files. You must specify the NDK path and an installation prefix to separate the Android build from your native OS build.
    3. Build and Install: Run make to compile and make install to place headers and libraries in your specified prefix.
    git clone https://github.com/vsg-dev/VulkanSceneGraph.git
cd VulkanSceneGraph
cmake ./ \
-DCMAKE_BUILD_TYPE="Debug" \
-DCMAKE_SYSTEM_NAME="Android" \
-DCMAKE_SYSTEM_VERSION=24 \
-DCMAKE_ANDROID_STL_TYPE="c++_static" \
-DCMAKE_ANDROID_ARCH_ABI=armeabi-v7a \
-DCMAKE_ANDROID_NDK=/location/of/Android/sdk/ndk-bundle \
-DCMAKE_INSTALL_PREFIX=/usr/local/android

make -j 8
make install

  11. Prerequisites for VulkanSceneGraph

    master

    To build or use VulkanSceneGraph, ensure your environment meets the following requirements:

    • C++17 compliant compiler: e.g., g++ 7.3+, Clang 6.0+, or Visual Studio 2017+.
    • Vulkan: Version 1.1 or later (libs and headers via repository or VulkanSDK).
    • CMake: Version 3.10 or later.
    • glslang (Optional): Version 14.0 or later is required if your application needs runtime shader compilation.

  12. Use vsg::Commands to manage multiple commands

    master
    The vsg::Commands class acts as a container for multiple vsg::Command objects. It is functionally equivalent to vsg::Group but optimized for performance by reducing CPU overhead when applying the state stack prior to command calls. You can use it to group related commands together, which will then be traversed and executed as a single unit during the command recording process.