kdab/kuesa

Professional 3D asset creation and integration workflow for Qt

DEPRECATED

Kuesa Runtime 1.* is deprecated. It has been replaced by Kuesa Runtime 2 available here.

Kuesa Runtime module for Qt 3D

Note: The master branch contains the last stable release. The dev branch contain the upcoming release. dev might be in an unstable or even broken state during development. Please use [releases][github-release] or master to get a stable version.

Kuesa Runtime is a module for Qt 3D which provides:

• Support for glTF 2 importing
• Helpers for accessing and manipulating loaded content
• PBR and custom material support
• Custom forward renderer for adding effects
• A Qt Creator template for quickly creating new Kuesa based projects

It is the developer facing part of the Kuesa 3D design and integration workflow.

Kuesa Studio is the designer facing part of Kuesa.

It provides:

• glTF2 exporters and Kuesa specific glTF extensions for major 3D design softwares:
  • Kuesa for Blender
  • Kuesa for 3ds Max
  • Kuesa for Maya (coming soon)
• A library of real time materials that can be exported to glTF and previewed in Blender
• Tooling around asset conditioning to decrease asset size and optimize for embedded use cases.

More information about Kuesa Studio can be found here.

Requirements

Note: this repository requires git-lfs support.

Kuesa Runtime 1.4 requires Qt 3D from Qt 5.15 or Qt 6.0.

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

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

Optional Dependencies

Kuesa can optionally use the Draco mesh compression library, either through an embedded version, or a version present on the system. Draco can be used to dramatically decrease the size of glTF files.

Kuesa supports the KHR_draco_mesh_compression glTF extension as defined here.

By default, Kuesa will build with its own embedded version of the Draco library. This can be enforced with:

qmake kuesa.pro -- --draco=qt

To build Kuesa without any support for Draco, run qmake like this:

qmake kuesa.pro -- --draco=no

To build Kuesa with an external version of Draco, run qmake like this:

qmake kuesa.pro -- --draco=system

If Draco is not installed in the default location on your system, you can set the DRACOSDK environment variable to point to where Draco is installed. Use the DRACOSDK_LIBS environment variable to point to the folder containing the Draco libraries.

Note that Kuesa has last been tested with Draco at commit 8833cf878e6fd43c5a3fd6e4231212e25e25e632.

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

Components

Kuesa Runtime is composed of:

• A Qt module with core classes
• A QML plugin
• The gltfViewer tool to preview glTF 2.0 files, including selecting cameras and animations

Installation

Kuesa builds as a Qt module and will be installed alongside Qt. The main advantage is that once installed, using Kuesa in your projects is as easy as adding QT += kuesa to your project file. The down side is that building Kuesa from source can be a little more complicated if you're not used to building Qt itself already.

Note: you DO NOT have to build Qt from source, building Kuesa against a pre-installed version of Qt should work fine.

But building a module means that Kuesa has dependencies that are similar to those that apply when building Qt from source (Instructions on how to build Qt from source can be found here). In particular:

• perl must be installed and included in the PATH
• if you have downloaded Kuesa as an archive from github, you must create an empty .git folder at the root of the kuesa source directory.

Once these are installed, syncqt will be able to generate the module headers at build time. Simply run:

qmake
make
make install

Should examples not be built, try:

make sub-examples
cd examples
make install

To install the Qt Creator template, copy the entire kuesa folder from tools/qtc_templates to the templates/wizards folder inside the Qt Creator install location.

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 uses the following 3rd-party software:

• Qt 5.15 or later, licensed under LGPLv3 www.qt.io

• Draco, licensed under Apache License 2.0 and authored by Google Inc. https://github.com/google/draco

• MikkTSpace, licensed under a custom license and authored by Morten S. Mikkelsen http://mmikkelsen3d.blogspot.com/

Python Binding

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

Support

Please file issues here

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

About KDAB

Kuesa is maintained by Klarälvdalens Datakonsult AB (KDAB).

The KDAB Group is the global No.1 software consultancy for Qt, C++ and OpenGL applications across desktop, embedded and mobile platforms.

The KDAB Group provides consulting and mentoring for developing Qt applications from scratch and in porting from all popular and legacy frameworks to Qt. We continue to help develop parts of Qt and are one of the major contributors to the Qt Project. We can give advanced or standard trainings anywhere around the globe on Qt as well as C++, OpenGL, 3D and more.

Please visit https://www.kdab.com to meet the people who write code like this.

kuesa's Issues

forward renderer has not any surface

hi
tnx for your project .
in any example that exist in source tree and other project that powered by kuesa for load gltf files there is a problem at forwardRenderer.
when start application and try to create forwardRenderer there is no window in "currentSurface" variable and application pring qCWarning that say "unexpected surface size".
and finally cannot show any 3d item.

1 Kuesa::ForwardRenderer::currentSurfaceSize forwardrenderer.cpp 1321 0x7fffcd52f7fd
2 Kuesa::ForwardRenderer::reconfigureFrameGraph forwardrenderer.cpp 1109 0x7fffcd52e842
3 Kuesa::ForwardRenderer::rebuildFGTree forwardrenderer.cpp 1338 0x7fffcd52f973
4 Kuesa::ForwardRenderer::ForwardRenderer forwardrenderer.cpp 620 0x7fffcd52d0b9
5 QQmlPrivate::QQmlElementKuesa::ForwardRenderer::QQmlElement qqmlprivate.h 103 0x7fffcd9378eb
6 QQmlPrivate::createIntoKuesa::ForwardRenderer qqmlprivate.h 124 0x7fffcd937926
7 QQmlType::create(QObject * *, void * *, unsigned long) const 0x7ffff6accbf3
8 QQmlObjectCreator::createInstance(int, QObject *, bool) 0x7ffff6b300ee

Where is the Qt3D shader graph/node editor?

According to https://www.kdab.com/wp-content/uploads/stories/qt3d_node_editor_and_shader_generator.pdf the node editor to edit shader graph files should be part of kuesa but I can't find it (neither as a QtCreator plugin). Could you point me to where it's located? Editing shader graph files by hand is rather tedious ;)

Thanks in advance.

compilation error, PCH files missing

c1plus: error: one or more PCH files were found, but they were invalid
cc1plus: error: use -Winvalid-pch for more information
cc1plus: fatal error: .pch/Kuesa: No such file or directory
compilation terminated.
make[2]: *** [Makefile:9215: .obj/sceneentity.o] Error 1
make[2]: Leaving directory '/root/Downloads/build-kuesa-Desktop_Qt_5_12_5_GCC_64bit- Debug/src/core'
make[1]: *** [Makefile:61: sub-core-install_subtargets] Error 2
make[1]: Leaving directory '/root/Downloads/build-kuesa-Desktop_Qt_5_12_5_GCC_64bit-Debug/src'
make: *** [Makefile:62: sub-src-install_subtargets] Error 2

Duck Example doesn'ts show duck.

Hello,

I am running many duck gltf Example. I did fetch gltf using LFS (so gltf is fine - it loads in 3D viewer).
Gltf assets are parsed correctly but nothing is displayed on Window / app.
I also tried loading Duck.gltf using kusea gltfeditor, still it is white screen and assets are not rendered.
What could be wrong...

Best
Nikhil.

make & make install error

Some of the required modules (qtHaveModule(3drender):qtHaveModule(3danimation)) are not available. Skipped

different between qt5.12.9 qt5.14.2

hi
tnx for kuesa project that help perfectly work at 3d application
there is a undetermined issue in kuesa application that compiled by qt5.12.9 and qt5.14.2
a simple blender project export to gltf and show at simple application
when i compile application with qt5.12.9 material and object color is like solid mode render at blender and
when i compile application with qt5.14.2 material and object color is like full mode render at blender just like uploaded picture
the test application and gltf is same at two application

and i want a fully render mode(that show at 5.14.2) view at a application that compiled by 5.12.9

build error

Hi, I have the building errors as following. Please how to figure out.

`Configure summary:

Kuesa Runtime:
Draco .................................. yes
System Draco ........................... no
System LibKTX .......................... no
Kuesa:
Tools .................................. yes

Qt is now configured for building. Just run 'make'.
Once everything is built, you must run 'make install'.
Qt will be installed into '/Users/lihuaiguang/QT/6.1.1/clang_64'.

Prior to reconfiguration, make sure you remove any leftovers from
the previous build.

lhg@MBP2 kuesa % make
Some of the required modules (qtHaveModule(3drender):qtHaveModule(3danimation)) are not available.
Skipped.`

Kuesa's AnimationPlayer working in QML but not working in C++

Here are implementations of AnimationPlayer, in qml and c++.
The animation in qml works, the rendering works in c++, but not the animation, although these are the same implementation for the same animation with different languages.

The animation is not running in c++.

I suspect the use of Scene3D, in qml, having a scene3D for 3D rendering is mandatory.

I did not implement Scene3D in c++, I could not find It in c++.

Rename assetpipelineeditor

The name of the tool is misleading (for the time being...), and gives us poor SEO.

Suggestion:

• rename APE into gltfViewer or gltf2Viewer
• rename gltfViewer into gltfViewerMinimal (or so)

build error, header file include path problem

In file included from sceneentity.cpp:29:0:
sceneentity.h:33:43: fatal error: Kuesa/animationclipcollection.h: No such file or directory
compilation terminated.
Makefile:4979: recipe for target '.obj/sceneentity.o' failed
make[2]: *** [.obj/sceneentity.o] Error 1

in the sceneenitity.h file , it includes "Kuesa/other.h", but there is none Kuesa directory

Error when executing one the examples

I downloaded the kuesa git repository, I run
qmake
make
make install,
everything went fine, I opened this directory using Qt Creator, and tried to execute one of the examples, then I get these errors:

Qt3D.Renderer.OpenGL.Backend: Unable to find suitable Texture Unit
Qt3D.Renderer.OpenGL.Backend: FBO incomplete 

When I checked my OpenGL version, I get: OpenGL version string: 3.1 Mesa 18.2.8
Maybe the problem comes from the OpenGL version because 3.2 version or above is required, but I don't know how to upgrade it, I tried for several hours to change the version but I couldn't.

while running make amd make install

Invisible car on car-scene application

The car-scene application is loaded correctly but the car is not visibile.

Environment: Kubuntu 18.04 x86_64, Qt5.12, nvidia 396.54, NO draco installed.

I have added a couple of qDebug prints and it seems that the gltf file cannot be loaded.

Kuesa: GLTF2Parser::parse() ":/DodgeViper.gltf"
Kuesa: File is not a valid json document. Base path: ":/"

The assetspipelineeditor too, is unable to load the DodgeViper.gltf file:

Kuesa: File is not a valid json document

How can I retrieve more debug information?

Full log:

QML debugging is enabled. Only use this in a safe environment.
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: Undefined clip or mapper in AnimationPlayer
ClipAnimators need a clip and a mapper to be played
ClipAnimators need a clip and a mapper to be played
<Unknown File>: QML QQuickAnchors: Binding loop detected for property "margins"
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: Undefined clip or mapper in AnimationPlayer
Kuesa: GLTF2Parser::parse() ":/DodgeViper.gltf"
Kuesa: File is not a valid json document. Base path: ":/"
[Qt3DRender::GLTexture] No QTextureData generated from Texture Generator yet. Texture will be invalid for this frame
[Qt3DRender::GLTexture] No QTextureData generated from Texture Generator yet. Texture will be invalid for this frame
[Qt3DRender::GLTexture] No QTextureData generated from Texture Generator yet. Texture will be invalid for this frame
[Qt3DRender::GLTexture] No QTextureData generated from Texture Generator yet. Texture will be invalid for this frame
qml: Triggered
ClipAnimators need a clip and a mapper to be played
ClipAnimators need a clip and a mapper to be played
ClipAnimators need a clip and a mapper to be played
ClipAnimators need a clip and a mapper to be played
ClipAnimators need a clip and a mapper to be played

negative playbackRate on c++ QClock and animationPlayer

hello
there is a problem in animationPlayer clock when using c++ API to instantiate animationPlayer and set the clock to them.
for positive playebackRate animation play correctly but in negative playbackRate animation not work.

in qml api usage negative an positive animation is ok.

sample code :

`

auto player = new Kuesa::AnimationPlayer(m_sceneEntity);
player->setSceneEntity(m_sceneEntity);
player->setClip(clipName);
if (player->status() == Kuesa::AnimationPlayer::Ready) {
player->setClock(m_clock);
m_clock->setPlaybackRate(reverse ? -1.0 : 1.0);
player->start();
}
`

PBR shaders + normals on the car-example yield visual artifacts

Even MSAA enabled, the car scene still exhibits an enormous amount of aliasing. This is a problem with the model and/or the shaders, as this aliasing appears within faces of the same sub-mesh (e.g. the hood). Either there's normals spiking around some edge, or the shaders are not mipping correctly, or similar.

Note how MSAA is enabled for the ground plane (in the top left corner). However the jagged lines are all around the air intake, including the bottom right part.

Here is even more noticeable, not sure if caused by the same effect:

Looks like there's no filtering on the env map samples or something like that.

Adding Kuesa runtime to an already available Qt3D editor

I'm sorry if it sounds like a stupid question 😕 😅

I'm confused about how Kuesa runtime would help a 3D editor application.

For example, consider this app:

https://github.com/qt-labs/qt3d-editor

What would I gain by replacing some parts of this app with Kuesa runtime? How Kuesa runtime can help to improve it? What would be the benefits?

Terrible framerate on MacOS

When I load Sponza (from glTF-Sample-Models repo) into the AssetPipelineEditor, it runs at an unusable 2FPS. I've also experienced very slow framerates with the kuesa's car example. Loading the same scene into Blender 2.8 using Eevee, its an a reasonable framerate. I'm currently running on 2018 Mac Book Pro with Radean Pro 560X.

Make error, required modules missing

root@aras:~/Downloads/kuesa-dev# qmake

Running configuration tests...
Done running configuration tests.

Configure summary:

Kuesa Runtime:
Draco .................................. yes
System Draco ........................... no
Kuesa:
Tools .................................. yes

Qt is now configured for building. Just run 'make'.
Once everything is built, you must run 'make install'.
Qt will be installed into '/usr'.

Prior to reconfiguration, make sure you remove any leftovers from
the previous build.

root@aras:~/Downloads/kuesa-dev# make
Some of the required modules (qtHaveModule(3drender):qtHaveModule(3danimation)) are not available.
Skipped.