Skip to content

Getting Started With KUESA 3D 2.0

Components

Kuesa 3D is divided into three main libraries: Kuesa Core, Kuesa Qt3D and Kuesa Serenity.

Kuesa Core

The Kuesa Core library handles glTF 2 imports / exports. You can use it with either Kuesa Qt3D or Kuesa Serenity.

Kuesa Qt3D

  • Provides wrappers to easily integrate with Qt and Qt 3D
  • A QML plugin for integration with QtQuick
  • The gltfViewer tool to preview glTF 2.0 files, including selecting cameras and animations

Kuesa Serenity

Kuesa Serenity provides wrappers to easily integrate with Kuesa Studio's 3D Renderer (Serenity) using Vulkan.

Prerequisites

Please make sure to remove all former Kuesa and Serenity installations from your system. Otherwise Cmake may find it which may result in configure or build errors.

  • System wide Kuesa and Serenity installations
  • Kuesa installations inside any Qt versions

Windows

  • Microsoft Visual Studio C++ 2019 compiler (or later)
  • git
  • CMake, make sure it is in your PATH

For the Kuesa Studio Renderer (Serenity) you'll need:

  • Vulkan SDK
  • Make sure to install the additional debug libraries when prompted during the install process
  • Make sure VULKAN_SDK is set accordingly in your environment
  • vcpkg

Linux

  • C++17 compiler (GCC / Clang)
  • git
  • CMake

For the Kuesa Studio Renderer (Serenity) you'll need:

  • Vulkan SDK
  • Make sure VULKAN_SDK is set accordingly in your environment
  • Note: We recommend installing the Vulkan SDK directly from LunarG rather than relying on your distribution packages as those might not provide the shaderc library which Serenity relies on.

Hardware

Desktop

Anything with OpenGL 3.2 support (or more recent) is adequate.

Currently supported operating systems are:

  • Linux
  • Windows
  • Mac OS

Embedded

Here's a list of Chipsets/Devices Kuesa has successfully been tested on:

  • Apple iPad 5 (PowerVR GT7600)
  • Apple iPhone 7
  • OnePlus 3T (Android, Qualcolmm Snapdragon 821/Adreno 430)
  • NVidia Tegra K1 (embedded Linux)
  • iMX8 (embedded Linux)

Kuesa Runtime supports anything with OpenGL ES 3.2 or above.

OpenGL ES 3.1 or lower is supported but with a limited feature set depending on available OpenGL extensions.

  • For HDR support, GL_OES_texture_half_float is required
  • For anti aliasing, ARB_texture_multisample and GL_EXT_color_buffer_half_float are required

Dependencies

Most dependencies will be automatically fetched and downloaded during the configuration process.

Qt

Kuesa Runtime 2.0's optional Qt integration requires Qt 3D from Qt 5.15 or Qt 6 to be built.

The Kuesa Qt 3D integration library will be automatically enabled if Qt5 or Qt6 is found. You might have to specify the path to the Qt install with CMAKE_PREFIX_PATH

Note: Latest Qt 3D sources for 5.15 can be freely obtained from here

Serenity

For the Kuesa Studio Renderer (Serenity) you'll need Freetype to be installed for its rmlUI overlay and support.

The recommended way to install Freetype on Windows is to use vcpkg and do

1
vcpkg install freetype

Optional dependencies

Draco Compression

Kuesa supports the KHR_draco_mesh_compression glTF extension as defined here. Draco can be used to dramatically decrease the size of glTF files.

Kuesa comes with its own embedded version of the Draco library but by default, Kuesa will check if a system Draco mesh compression library is found and enable Draco support accordingly.

To build Kuesa with its own embedded version of the Draco library, run cmake like this:

1
cmake -DKUESA_FETCH_DRACO=ON ...

Note that Kuesa has last been tested with Draco 1.5.2

The glTF Inspector, provided with Kuesa Studio, is able to compress existing glTF 2.0 assets with Draco.

Documentation

If you wish to build the documentation locally, you'll need to install the following dependencies

Building & Installation

Kuesa builds with CMake. Unpack the Kuesa sources in the directory of your choosing.

Building Using Qt3D

The Kuesa Qt 3D integration library will be automatically enabled if Qt5 or Qt6 is found. You need to specify the path to the Qt install with CMAKE_PREFIX_PATH as shown below.

1
2
3
4
5
mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=<your qt path>\msvc2019_64 -DKUESA_BUILD_EXAMPLES=ON ..
cmake --build . --config Release
cmake --install .

Note: The configure step might take some time as missing dependencies will be fetched online.

Note: If you want to run the examples, you'll need to make sure your environment is properly set up. <your qt path>\msvc2019_64\bin and the Kuesa install path (e. g. C:/Program Files (x86)/Kuesa/bin) need to be in PATH and QML_IMPORT_PATH needs to be set (e. g. C:/Program Files (x86)/Kuesa/qml) accordingly.

Building Using Serenity

Similarly, the Kuesa Serenity integration library will be enabled if the Serenity package is found by Cmake. This can be done by setting the CMAKE_PREFIX_PATH variable. Alternatively, if you have been provided the Serenity source package as an archive, you can use the SERENITY_TARBALL option as follows:

1
2
3
4
5
mkdir build
cd build
cmake -DSERENITY_TARBALL=<your serenity.zip> -DKUESA_BUILD_EXAMPLES=ON ..
cmake --build . --config Release
cmake --install .

Note: The configure step might take some time as missing dependencies will be fetched online.

Linux

1
2
3
4
5
mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX=/path/to/where/kuesa/will/be/installed -DCMAKE_PREFIX_PATH=/path/to/Qt -DKUESA_BUILD_EXAMPLES=ON -DKUESA_FETCH_DRACO=ON -DSERENITY_TARBALL=/path/to/serenity.zip ..
cmake --build . --config Release
cmake --install .

Windows

1
2
3
4
5
mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH=/path/to/Qt -DKUESA_BUILD_EXAMPLES=ON -DKUESA_FETCH_DRACO=ON -DSERENITY_TARBALL=/path/to/serenity.zip ..
cmake --build . --config Release
cmake --install .

If you have used vcpkg to install Freetype, you can set -DCMAKE_TOOLCHAIN_FILE to and -DVCPKG_TARGET_TRIPLET

1
cmake -DCMAKE_PREFIX_PATH=/path/to/Qt -DCMAKE_TOOLCHAIN_FILE=path/to/vcpkg/scripts/buildsystems/vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows -DKUESA_BUILD_EXAMPLES=ON -DKUESA_FETCH_DRACO=ON -DSERENITY_TARBALL=/path/to/serenity.zip ..

Note: You might need to run your console as administrator in order to successfully install Kuesa to its default location.

CMake Options

  • KUESA_BUILD_EXAMPLES=ON to enable building of the examples
  • KUESA_BUILD_TESTS=ON to enable building of the examples
  • KUESA_FETCH_DRACO=ON to fetch the Draco library
  • SERENITY_TARBALL=/path/to/serenity.zip to enable building Serenity and the Kuesa Serenity library
  • KUESA_DOCS=ON to build the documentation
  • CMAKE_INSTALL_PREFIX=/path/to/install to override the default installation path

Deployment

Using Kuesa in your project

Kuesa gets installed as a CMake package. The simplest way to use Kuesa in a project is therefore to write a CMakeList.txt file and build your project with cmake.

Using the Kuesa Qt3D backend

1
2
3
4
5
6
7
find_package(Kuesa REQUIRED)
find_package(Qt NAMES Qt6 Qt5 COMPONENT Gui REQUIRED)

qt_add_executable(${PROJECT_NAME} MANUAL_FINALIZATION <source_files ...>)

target_link_libraries(${PROJECT_NAME} PUBLIC Qt::Gui Kuesa::Kuesa Kuesa::KuesaQt3D Kuesa::KuesaQt3DUtils)
target_compile_definitions(${PROJECT_NAME} PRIVATE ASSETS_DIR="${CMAKE_CURRENT_SOURCE_DIR}/assets" ABSOLUTE)

Using the Kuesa Serenity backend

1
2
3
4
5
6
7
find_package(Kuesa REQUIRED)
find_package(Serenity REQUIRED)

add_executable(${PROJECT_NAME} <source_files ...>)

target_link_libraries(${PROJECT_NAME} PUBLIC Kuesa::Kuesa Kuesa::Serenity)
target_compile_definitions(${PROJECT_NAME} PRIVATE ASSETS_DIR="${CMAKE_CURRENT_SOURCE_DIR}/assets" ABSOLUTE)
Note:

CMake will looks for a file names KuesaConfig.cmake. This fill is located in /lib/cmake/Kuesa.
If Kuesa was installed into a user defined location, you might have to set the CMAKE_PREFIX_PATH variable to contain the Kuesa intall path: 

1
cmake -DCMAKE_PREFIX_PATH=<kuesa_install_dir>.

In case cmake is unable to locate the Kuesa Cmake package, you could try to set CMAKE_FIND_DEBUG_MODE=ON to get more insight about where CMake is looking for. 

1
cmake -DCMAKE_PREFIX_PATH=<kuesa_install_dir> -DCMAKE_FIND_DEBUG_MODE=ON

Kuesa Qt 3D

Binaries build against the KuesaQt3D library will require: - Qt dlls to be in the PATH (Windows) / LD_LIBRARY_PATH (Linux) - The KuesaQt3D QML module to be in the qml import path, it can be set with the QML_IMPORT_PATH environment variable

1
QML_IMPORT_PATH=/path/to/Kuesa/install/qml
  • Troubleshooting QML imports can be done by setting the environnement variable QML_IMPORT_TRACE=1
Clearing Stale Caches

If you've updated Kuesa or have used Kuesa previously, it is recommended to clear the Qt 3D cached shader files.

These cache is located at Qt::TempLocation which is usually "C:/Users//AppData/Local/Temp" on Windows and "/tmp" on Linux.

Remove all the .qt3d files present at that location to ensure Kuesa rebuilds all the shaders with all the updates.

Documentation

The reference documentation is available at: https://kdab.github.io/kuesa/

3rd-Party

Kuesa Qt3D uses the following 3rd-party software:

  • Qt 5.15 or later, licensed under LGPLv3: Qt

  • Draco, licensed under Apache License 2.0 and authored by Google Inc.: Draco

  • MikkTSpace, licensed under a custom license and authored by Morten S. Mikkelsen: MikkTSpace

Python Binding

A Python binding is available based on PySide 2. Please check the build instructions in src/python and the sample application in examples/kuesa/python.

Support

Please report issues here

KDAB will happily accept external contributions; however, all contributions will require a signed Contributor License Agreement.