Skip to content

ReadMe.md

Latest commit

 

History

History
294 lines (211 loc) · 6.9 KB

ReadMe.md

File metadata and controls

294 lines (211 loc) · 6.9 KB

VulkanGFX

Windows Linux macOS

A cross-platform, Vulkan-based modular graphics engine.

Goals

  • Basic 3D/2D rendering capabilities
  • Cross-platform support (Windows, Linux, macOS)
  • 2D UI system with DOM controls (separate project)
  • Toolkit launcher
  • Binary builds for integration into C# frontends

Important Notes

  • macOS: Uses MoltenVK for Vulkan support
  • vcpkg: All dependencies are managed via vcpkg submodule

Getting Started

Prerequisites

All platforms require:

  • CMake 3.21 or higher
  • Git (with submodule support)
  • C++17 compatible compiler

Clone the Repository

git clone --recursive https://github.com/jaibeer72/VulkanGFX.git
cd VulkanGFX

If you forgot --recursive:

git submodule update --init --recursive

Platform-Specific Requirements

🐧 Linux

Required packages:

# Arch Linux
sudo pacman -S base-devel cmake ninja curl zip unzip tar git

# Ubuntu/Debian
sudo apt-get install build-essential cmake ninja-build curl zip unzip tar git \
    libxinerama-dev libxcursor-dev xorg-dev libglu1-mesa-dev pkg-config \
    libgl1-mesa-dev libvulkan-dev mesa-vulkan-drivers vulkan-tools

# Fedora
sudo dnf install @development-tools cmake ninja-build curl zip unzip tar git \
    libXinerama-devel libXcursor-devel libXrandr-devel libXi-devel mesa-libGL-devel

Supported Generators:

  • linux-ninja (recommended) - Ninja build system

Bootstrap vcpkg:

bash vcpkg/bootstrap-vcpkg.sh

🪟 Windows

Required tools:

  • Visual Studio 2022 (or 2019) with C++ Desktop Development workload
  • CMake (included with Visual Studio or standalone)

Supported Generators:

  • VisualStudio - Visual Studio 2022
  • MinGW - MinGW Makefiles

Bootstrap vcpkg:

.\vcpkg\bootstrap-vcpkg.bat

🍎 macOS

Required tools:

brew install cmake ninja pkg-config

Optional Vulkan runtime helpers (recommended for local debugging):

brew install vulkan-tools
  • vulkan-loader is not required for this project build, because Vulkan is provided through vcpkg (find_package(Vulkan REQUIRED)).
  • vulkan-tools provides the mock ICD JSON on macOS, which is useful if your local Vulkan runtime setup is incomplete.

Supported Generators:

  • osx-xcode - Xcode project generation

Bootstrap vcpkg:

bash vcpkg/bootstrap-vcpkg.sh

Building the Project

Using CMake Presets (Recommended)

The project includes CMake presets for all platforms:

Linux:

cmake --preset linux-ninja
cmake --build --preset linux-ninja:Debug

Windows (Visual Studio):

cmake --preset VisualStudio
cmake --build --preset VisualStudio:Debug

Windows (MinGW):

cmake --preset MinGW
cmake --build --preset MinGW:Debug

macOS:

cmake --preset osx-xcode
cmake --build --preset osx-xcode:Debug

Manual Build

If you prefer not to use presets:

# Configure
cmake -B build -S . \
  -DCMAKE_BUILD_TYPE=Debug \
  -DCMAKE_TOOLCHAIN_FILE=./vcpkg/scripts/buildsystems/vcpkg.cmake

# Build
cmake --build build

Available Build Presets

  • VulkanGFX:Debug - Default debug configuration
  • linux-ninja:Debug - Linux with Ninja
  • VisualStudio:Debug - Windows with Visual Studio
  • MinGW:Debug - Windows with MinGW
  • osx-xcode:Debug - macOS with Xcode

Running the Application

After building, the executable will be located at:

  • Linux/Mac: out/build/<preset-name>/VulkanGFX
  • Windows: out/build/<preset-name>/Debug/VulkanGFX.exe

Dependencies

All dependencies are automatically managed by vcpkg:

  • GLFW 3.4 - Window and input handling
  • GLM 1.0.2 - Mathematics library
  • Vulkan SDK 1.4.328 - Graphics API

Documentation

Development

Debugging with VSCode

Required Extension: lldb-dap (for macOS/Linux) or ms-vscode.cpptools (for all platforms)

Example launch.json configuration (macOS with lldb-dap):

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Debug Vulkan App",
            "type": "lldb-dap",
            "request": "launch",
            "program": "${workspaceFolder}/out/build/osx-xcode/Debug/VulkanGFX",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "environment": [],
            "internalConsoleOptions": "openOnSessionStart",
            "miDebuggerPath": "/Applications/Xcode.app/Contents/Developer/Toolchains/XcodeDefault.xctoolchain/usr/bin/lldb"
        }
    ]
}

For Linux:

{
    "name": "Debug Vulkan App (Linux)",
    "type": "cppdbg",
    "request": "launch",
    "program": "${workspaceFolder}/out/build/linux-ninja/VulkanGFX",
    "args": [],
    "cwd": "${workspaceFolder}",
    "environment": [],
    "externalConsole": false,
    "MIMode": "gdb",
    "setupCommands": [
        {
            "description": "Enable pretty-printing for gdb",
            "text": "-enable-pretty-printing",
            "ignoreFailures": true
        }
    ]
}

For Windows:

{
    "name": "Debug Vulkan App (Windows)",
    "type": "cppvsdbg",
    "request": "launch",
    "program": "${workspaceFolder}/out/build/VisualStudio/Debug/VulkanGFX.exe",
    "args": [],
    "cwd": "${workspaceFolder}",
    "environment": [],
    "console": "integratedTerminal"
}

Troubleshooting

Linux: Permission denied when running executables

If your workspace is on a separate partition mounted with noexec, remount it:

sudo mount -o remount,exec /path/to/workspace

To make it permanent, edit /etc/fstab and add exec to the mount options.

vcpkg bootstrap fails

Ensure you have all required tools installed for your platform (see Platform-Specific Requirements above).

Missing Vulkan drivers

  • Linux: Install your GPU vendor's Vulkan drivers (mesa-vulkan-drivers, nvidia-utils, etc.)
  • Windows: Update your GPU drivers from manufacturer's website
  • macOS: MoltenVK is included via vcpkg

License

See LICENSE.txt for licensing information.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md if available, or open an issue to discuss proposed changes.