DOCSEARCHbyAlgolia
Submit Docs

Vulkan-Tools

repository·main·Indexed 19 days ago

https://github.com/khronosgroup/vulkan-tools

A collection of essential utilities and demos for verifying Vulkan API implementations and inspecting system capabilities. Key components include vulkaninfo for reporting GPU and driver properties, the Vulkan Mock ICD for testing validation layers without physical hardware, and the Vkcube and Vkcube++ demo applications.

Tokens
3.5K
Snippets
12
Records
20
Agent score
66%

What's inside Vulkan-Tools

  1. Overview of Vulkan-Tools components

    main

    The vulkan-tools repository provides utilities to help developers verify the correct use of the Vulkan API. The available components include:

    • Mock ICD: A mock Installable Client Driver (ICD) for testing purposes.
    • Vkcube and Vkcube++ Demo: Demo applications used to showcase Vulkan capabilities.
    • VulkanInfo: A utility to provide information about the Vulkan implementation and capabilities on the system.
    • Windows Runtime: An installer for the Windows runtime components.

  2. What is the Vulkan Mock ICD and when to use it

    main

    The Vulkan Mock ICD is a driver designed specifically for testing Vulkan Validation Layers (LVL) in environments where actual GPU hardware is unavailable or when you want to isolate validation layer logic from rendering results.

    Core Capabilities

    • Null Driver: Provides a fixed, hard-coded device configuration. This allows validation tests to run on a consistent simulated device.
    • Entrypoint Tracking & Verification (Planned): A feature intended to store expected Vulkan function calls and parameters within the ICD, allowing a separate process to verify that validation layers are passing calls and parameters to the ICD unchanged.

    Use Cases

    • Validation Layer Testing: Testing the correctness of layers without dependency on GPU rendering.
    • Simulated Environments: Running Vulkan tests on CI/CD pipelines or systems without discrete GPUs.
    • Custom Extensions: The driver can be enhanced to mimic actual ICD behavior (e.g., simulating synchronization objects, query data, or command buffer state) or hooked up to a software renderer to act as a virtual GPU.

  3. Manage dependencies with UPDATE_DEPS

    main

    The project uses a custom process for C/C++ dependencies similar to vcpkg.

    • Enable dependency updates: Set -D UPDATE_DEPS=ON during CMake configuration. This pulls dependencies listed in scripts/known_good.json using Python and CMake scripting.
    • Default behavior: UPDATE_DEPS is OFF by default to remain friendly to system package managers.
    • Testing new dependency versions: You can test specific versions by modifying known_good.json or by setting CMAKE_PREFIX_PATH to a custom installation directory. If you change the prefix path, you must delete CMakeCache.txt (or the entire build directory) to clear cached results.
    # Example: testing a custom dependency path
rm -rf build/
cmake -S . -B build/ ... -D CMAKE_PREFIX_PATH=~/foobar/vulkan_headers_install/ ...

  4. Understand the Vulkan-Tools version tagging scheme

    main

    This repository uses a specific tagging scheme to align with Vulkan specification releases.

    • Repository Tags: Follow the format v<version> (e.g., v1.3.266). These correspond to new Vulkan specification releases.
    • SDK Tags: Note that these are different from official Vulkan SDK tags, which follow the format vulkan-sdk-<version>.<patch> (e.g., vulkan-sdk-1.3.266.0).

    Warning: Marked version releases in this repository have undergone thorough testing but do not imply the same quality level as official SDK tags.

  5. Build Vulkan-Tools on Linux

    main

    Requirements

    Install the necessary system libraries:

    sudo apt-get install git build-essential python3 cmake
# For WSI (Window System Integration) support:
sudo apt-get install libwayland-dev xorg-dev

    WSI Support Options

    By default, the build supports Xcb, Xlib, and Wayland. To disable support for a specific display server, use the option BUILD_WSI_<name>_SUPPORT=OFF (e.g., BUILD_WSI_WAYLAND_SUPPORT=OFF).

    32-bit Support

    While not officially supported on 32-bit Linux, you can attempt to build 32-bit targets on a 64-bit Ubuntu system by installing gcc-multilib, g++-multilib, and libx11-dev:i386, then setting the following environment variables:

    export ASFLAGS=--32
export CFLAGS=-m32
export CXXFLAGS=-m32
export PKG_CONFIG_LIBDIR=/usr/lib/i386-linux-gnu
    sudo apt-get install git build-essential python3 cmake
sudo apt-get install libwayland-dev xorg-dev

  6. Enable the Vulkan Mock ICD

    main

    To use the Vulkan Mock ICD for validation layer testing without actual GPU hardware, you must point the VK_ICD_FILENAMES environment variable to the mock ICD JSON configuration file. This allows the Vulkan loader to use the mock driver instead of a physical hardware driver.

    Ensure you provide the absolute or correct relative path to the VkICD_mock_icd.json file located within your build directory.

    export VK_ICD_FILENAMES={BUILD_DIR}/icd/VkICD_mock_icd.json

  7. Regenerate source code using tools_codegen

    main

    The repository contains generated source code that should not be modified directly. You can use the tools_codegen CMake target to run the generation script (scripts/generate_source.py). Note that TOOLS_CODEGEN is OFF by default.

    cmake -S . -B build -D TOOLS_CODEGEN=ON
cmake --build build --target tools_codegen
    cmake -S . -B build -D TOOLS_CODEGEN=ON
cmake --build build --target tools_codegen

  8. Build Vulkan-Tools on MacOS

    main

    Requirements

    • Xcode

    Workflow

    Use the Xcode generator to create and open an Xcode project:

    # Create the Xcode project
cmake -S . -B build -G Xcode

# Open the Xcode project
cmake --open build
    cmake -S . -B build -G Xcode
cmake --open build

  9. Run Vulkan Info to inspect GPU and driver properties

    main

    The vulkaninfo program is a utility provided in the Vulkan SDK used to output detailed information about the Vulkan environment, including:

    • Device properties of identified GPUs
    • Supported Vulkan extensions per GPU
    • Recognized layers
    • Supported image formats and format properties

    To run the tool, ensure you have installed the SDK and configured your runtime environment. By default, running vulkaninfo without arguments produces human-readable text output to the console.

    vulkaninfo

  10. Build Vulkan-Tools for Android

    main

    Requirements

    • CMake 3.22.1+
    • NDK r25+
    • Ninja 1.10+
    • Android SDK Build-Tools 34.0.0+
    • Android Studio (with SDK Platforms API 26+, Build-Tools, Platform-Tools, SDK Tools, NDK, and CMake installed via SDK Manager)

    Environment Setup

    Ensure ANDROID_SDK_ROOT and ANDROID_NDK_HOME are set, and that build tools are in your PATH.

    Building Binaries (No APK)

    To build binaries like vulkaninfo or libVkCube for a specific ABI using CMake:

    cmake -S . -B build \
  -D CMAKE_TOOLCHAIN_FILE=$ANDROID_NDK_HOME/build/cmake/android.toolchain.cmake \
  -D ANDROID_PLATFORM=26 \
  -D CMAKE_ANDROID_ARCH_ABI=arm64-v8a \
  -D CMAKE_ANDROID_STL_TYPE=c++_static \
  -D ANDROID_USE_LEGACY_TOOLCHAIN_FILE=NO \
  -D CMAKE_BUILD_TYPE=Release \
  -D UPDATE_DEPS=ON \
  -G Ninja

cmake --build build

    Alternatively, use the scripts/android.py helper script:

    # Build release binaries for arm64-v8a
python3 scripts/android.py --config Release --app-abi arm64-v8a --app-stl c++_static

# Build release binaries for all ABIs
python3 scripts/android.py --config Release --app-abi 'armeabi-v7a arm64-v8a x86 x86_64' --app-stl c++_static

    Building the VkCube APK

    Use scripts/android.py with the --apk flag to handle the complex process of wrapping CMake and Android CLI tools:

    # Build a complete APK with debug binaries for all ABIs
python3 scripts/android.py --config Debug --app-abi 'armeabi-v7a arm64-v8a x86 x86_64' --app-stl c++_shared --apk

# Build a clean APK with release binaries for arm64-v8a
python3 scripts/android.py --config Release --app-abi arm64-v8a --app-stl c++_shared --apk --clean

    Note: APKs are placed in the build-android/bin directory.

    python3 scripts/android.py --config Release --app-abi arm64-v8a --app-stl c++_static

  11. Validate vulkaninfo JSON output against Vulkan Profiles schema

    main

    The JSON output generated by vulkaninfo is designed to be compatible with the Vulkan Profiles solution. To ensure your vulkaninfo output is correctly structured, you can validate it against the official Vulkan Profiles JSON schema found at https://schema.khronos.org/vulkan/.

    Validation Steps

    1. Generate the data: Run vulkaninfo --json to generate a .json file containing the system information.
    2. Obtain the schema: Download the latest Vulkan Profiles schema from https://schema.khronos.org/vulkan/.
    3. Run validation: Use an online JSON validator tool by pasting both the downloaded schema and the generated vulkaninfo JSON data into the tool's schema and data fields respectively. Ensure the tool reports no errors.
    vulkaninfo --json

  12. Build and deploy Vulkan Info for iOS

    main

    Vulkan Info can be built for iOS using the Xcode project located in the vulkaninfo/ios directory of the repository.

    Requirements & Setup:

    • Apple Developer Program: You must be a member to deploy to physical devices.
    • MoltenVK: Vulkan Info requires MoltenVK libraries. You must manually add these libraries to your Xcode project. Refer to the LunarG macOS SDK guide for instructions.

    Accessing Output Files: When run on an iOS device, the tool generates vulkaninfo.json, portability.json, and an HTML file. To retrieve these files:

    1. Connect the device to a host computer via USB.
    2. Use the iOS application file sharing mechanism (via iTunes on Windows or Finder on macOS).
    3. Navigate to the vulkaninfo folder on the device to access the files.

    Note: There is currently no supported way to access these files from a Linux host computer.