Overview of Qt3D 2.0 - Part 2

An Example of Rendering with Qt3D

In the previous article we learned about the requirements and high-level architecture of Qt3D 2.0. In order to put some of this into context and to give you a concrete example of how it looks to draw something in Qt3D using the QML API, we will now briefly show the important parts of one of the simple examples that will ship with Qt3D. We will start off simple and just draw a single entity (a trefoil knot) but to make it slightly more interesting we will use a custom set of shaders to implement a single-pass wireframe rendering method. This is what we will draw:

As mentioned in the previous article, the renderer aspect looks for entities that have some geometry, a material and optionally a transformation. These are all specified in the form of subclasses of QComponent which have been exported to the QML engine in the form of Mesh, Material and Transform respectively. So let's use these components to make a custom QML item in TrefoilKnot.qml

Let's break this down to see what's going on here. We start off by importing the Qt3D 2.0 module that provides the Entity type and value type helpers like Qt.vector3d(). We also import the Qt3D.Render 2.0 module that provides the components and other types picked up by the renderer aspect. If we were using components from other aspects, then we would also need to import the corresponding QML module here too.

We then use Entity as the root element of the custom QML type exposing some custom properties just as you would with any other type in QML.

Entities, Entities, Everywhere

In addition to aggregating components, Entity objects can be used to group child objects together. This is analogous to how Item is used in Qt Quick 2.

At the bottom of the TrefoilKnot.qml file we instantiate a Transform component and a Mesh component. The Mesh component is very simple. We use its source property to load in a static set of geometry (vertex positions, normal vectors, texture coordinates etc.) from a file in the Wavefront Obj format. This data was exported from the excellent and free Blender application. The Transform component specifies how the renderer should transform the geometry when it is drawn with the OpenGL pipeline. Exactly how this happens is a topic for a future article. For now, simply be happy that you are able to combine an ordered set of transformations into a single Transform component and that your shaders will have this information available to them automatically via some standard named uniform variables.

Dynamic Per-Vertex Data

In addition to the Mesh element, Qt3D also allows dynamic generation of per-vertex attribute data via some C++ hooks called by the task-based engine.

Simply instantiating components is not enough however. In order for them to imbue special behaviour on an entity, the entity must aggregate the components by means of its components property. This allows components to be shared between multiple entities very easily. In this example we have components for the transform and mesh which are contained within our custom type. The final component, of type Material is, in this case, provided by means of a property on the TrefoilKnot itself. This allows users of this type to easily customise the appearance of the entity, which we will make use of shortly.

Now that we have defined a custom entity, let's see how to use it to actually get our desired result. The code for our main.qml file looks like this:

We start off again with the same import statements as before but this time we also add in a namespaced import for the Qt Quick 2.1 module as we will need this shortly for some animations. Once again we also use Entity as the root element simply to act as a parent for its children. In this sense, Entity is much like the Item element type from Qt Quick.

Here, we will gloss over the FrameGraph component as that is worthy of an entire article on it's own. For now, it suffices to say that the contents of the ForwardRenderer type is what completely configures the renderer without touching any C++ code at all. It's pretty cool stuff but you'll have to wait for the details as this is already a long article. Similarly, please ignore the Configuration element. This is a temporary hack that is needed to have mouse control of the camera until we finish implementing that part correctly using aspects and components.

The BasicCamera element is a trivial wrapper around the built-in Camera type, that as you can probably deduce, represents a virtual camera. It has properties for things like the near and far planes, field of view, aspect ratio, projection type, position, orientation etc.

Multiple Cameras

It is trivial to use multiple cameras and choose between them using the framegraph for all or part of the scene rendering. We will cover this in a future article.

Next up we have the WireframeMaterial element. This is custom type that wraps up the built-in Material type. Qt3D has a robust and very flexible material system that allows multiple levels of customisation. This caters for different rendering approaches on different platforms or OpenGL versions; allows multiple rendering passes with different state sets; provides mechanisms for overriding of parameters at different levels; and also allows easy switching of shaders -- all from C++ or using QML property bindings. Once again, to do this topic justice would require more space than we have here so we will defer it for another time. For now, the take away point is that properties on a Material can easily be mapped through to uniform variables in a GLSL shader program that is itself specified in the referenced effect property.

Supported Shader Stages

Qt3D supports all of the OpenGL programmable rendering pipeline stages: Vertex, tessellation control, tessellation evaluation, geometry and fragment shaders. Compute shaders require a little more API work for getting data into and out of them before they are fully supported.

Instantiating the TrefoilKnot and setting our material on it is simplicity itself. Once we have done that and with the parts we have glossed over, the Qt3D engine in conjunction with the renderer aspect has enough information to finally render our mesh using the material we specified.

Of course we can go further and make things a little more interesting by making use of the animation elements provided by Qt Quick 2. When we animate properties of our custom TrefoilKnot or the Wireframematerial, the properties of its components get updated by means of the usual QML property binding mechanism. For example:

The property updates are noticed by the QNode base class and are automatically sent through to the corresponding objects in the renderer aspect. The renderer then takes care of translating the property updates through to new values for uniform variables in the GLSL shader programs. You can find the full source code for this example in the Qt 5 git repository (see below) and when you run it gives the following view of a trefoil knot with the width of the wireframe lines pulsing. All the heavy lifting is being done by the GPU of course. All the CPU has to do is the property animations and the little bit of work to translate the scenegraph and framegraph into raw OpenGL calls.

Even More Win?

In the future, even the animations will be able to be performed across multiple cores by providing a specialised animation aspect. It is also already possible to animate on the GPU via a custom shader program and material.

What Is the Status of Qt3D?

As of December 2014, most of the core framework of Qt3D is now in place. There are a few areas that we want to tidy up and extend before release to make it easier for users to extend. For the renderer aspect, most of the features for an initial release are working. We have just finished implementing the first pass of using data gathered from entities in the scenegraph to populate Uniform Buffer Objects (UBOs) that can be bound to OpenGL shader programs to make large amounts of data readily available. Typical use cases for UBOs are for sets of material or lighting parameters but they can be used for anything you can think of.

The two big things that we have yet to implement for the renderer aspect are:

• Support for instanced rendering. Instancing is a way of getting the GPU to draw many copies (instances) of a base object that varies in some way for each copy. Often, in position, orientation, colour, material properties, scale etc. Our plan is to provide an API similar to Qt Quick's Repeater element. In this case the delegate will be the base object and the model will provide the per-instance data. So whereas an entity with a Mesh component attached eventually gets transformed into a call to glDrawElements, an entity with a instanced component will be translated into a call to glDrawElementsInstanced.
• Qt Quick 2 Integration. There are a number of ways in which Qt Quick 2 could be integrated with Qt3D (or vice versa). For example, you may simply wish to embed a Qt3D scene into a custom Qt Quick 2 item to put it into your UI. Alternatively, you may want to overlay a Qt Quick 2 scene as a UI over your Qt3D scene. You may also want to be able to use Qt Quick 2 to render into a texture and then use that texture within your Qt3D scene, perhaps to apply it to some geometry such as a sign post. With a custom Qt Quick 2 item based on QQuickFramebufferObject and by making use of QQuickRenderControl all of these options should be possible.

In addition, we have yet to implement a sane set of default materials that are ready to use out of the box. The materials example that is included in the Qt3D examples shows a good selection of what some defaults may look like. They need making a little more generic and testing on other platforms, particularly OpenGL ES 2 and ES 3.

Beyond the renderer, the other aspect to be shipped when we release Qt3D 2.0 will be the keyboard and mouse input aspect. Support for keyboard input is already implemented and is usable. Mouse support will come in the New Year. For now we have the hacked together solution mentioned in the above wireframe example for controlling the camera.

Qt3D API

Please note that the Qt3D API is not yet frozen. The API will change before release, but hopefully not by much.

What Can You Do To Help Qt3D?

So far Qt3D 2.0 has been almost entirely designed and implemented by KDAB engineers. I would like to highlight the efforts of Paul Lemire, James Turner, Kevin Ottens, Giuseppe D'Angelo and Milian Wolff who have done a huge amount of work to rebuild Qt3D from the ground up. A lot of work has gone into Qt3D, much of it not visible, in the form of prototypes that were discarded and never saw the light of day, API reviews, testing, debugging, and profiling. This has resulted in over 1200 commits since we moved development onto the public Qt git repositories.

Most of the work in rewriting Qt3D has been funded by our employer, KDAB, and also in the spare time of the above people. Recently we were fortunate enough to get some external funding to help implement some of the missing functionality of Qt3D. This was a fantastic boost for us, because it allowed KDAB to have Paul Lemire focus primarily on Qt3D for an extended period without distraction in addition to facilitating an incredibly helpful API review.

Funding or Using Qt3D

If you wish to help contribute to Qt3D (or any other part of Qt), but you don't have the time or resources to write patches or if you just wish to invest in Qt3D with some R&D money you have left over, then please do consider funding us to do work in Qt3D on your behalf. Also, the best way to drive new features is to use a technology in the real world, so if you want to use Qt3D (or any other part of Qt) in your next project then please get in touch with us.

If you want to get involved directly with Qt3D or if you just want to try it out, then take a look at how to build Qt 5 from source and drop in to the #qt-3d channel on freenode. You will find a bunch of us in there most of the time. If you need help getting up to speed or if you want something to work on or need some guidance around the architecture please feel free to ping us in there or on the development mailing list. Please use the dev branch to build Qt3D.

We hope to release Qt3D 2.0 along with Qt 5.5.0 in the spring, but the more help or funding we can get with implementation, documentation, testing, and examples the better shape Qt3D will be in for everybody. So thank you to everybody that has provided help and feedback so far. We are happy with the direction Qt3D is going in and we are really looking forwards to an initial release and many more releases in the future.