Porting to Qt 6 - Qt Quick 3D

Qt 6 is a result of the conscious effort to make the framework more efficient and easy to use.

We try to maintain binary and source compatibility for all the public APIs in each release. But some changes were inevitable in an effort to make Qt a better framework. Parts of the Qt Quick 3D API have been substantially modified.

In this topic we summarize those changes in Qt Quick 3D, and provide guidance to handle them.

RHI

The biggest change is the introduction of the Rendering Hardware Interface, which allows Qt Quick 3D to run on Direct3D, Metal and Vulkan in addition to OpenGL and OpenGL ES. This means that all shader code needs to be updated, and that inline shaders are no longer supported. All shader properties are now URLs referring to binary shader files.

See the RHI porting guide for detailed information.

Other API changes

QML import version

Starting with Qt 6.0, the version number for QML import statements is the same as the Qt version number. It is now also possible to import a module without specifying a version: this will import the latest version of the module.

Lighting

Light brightness now represents an energy multiplier defaulting to 1.0, where Qt 5 would use a percentage value defaulting to 100. In practice this means that all brightness values should be divided by 100.

SceneEnvironment.probeBrightness is renamed to probeExposure and is also redefined to be a multiplier with a default value of 1.0. That is, all probeBrightness values should be renamed to probeExposure and divided by 100.

AreaLight has been removed for performance reasons. In many cases it can be replaced with SpotLight, which was added in Qt Quick 5.15.

Custom Materials

The custom materials API has been completely reworked in 6.0. This means any existing custom materials will have to be substantially rewritten. See the CustomMaterial documentation for details of the new API.

Principled Material

The PrincipledMaterial QML type has been greatly improved in Qt Quick 6.0, and now more closely follows the principles of Physically Based Rendering. Imported models should now render correctly without changing properties of the materials. Existing materials will need to be changed to undo any compensations for previous inaccuracies.

Predefined materials

There are no predefined materials included in QtQuick3D 6.0. Any materials added in future releases will probably not be compatible with the old ones. The Materials import does not exist. (The CustomMaterial type is moved to the base QtQuick3D import.)

These are the material QML types that have been removed in Qt 6.0:

  • AluminumAnodizedEmissiveMaterial
  • AluminumAnodizedMaterial
  • AluminumBrushedMaterial
  • AluminumEmissiveMaterial
  • AluminumMaterial
  • CopperMaterial
  • FrostedGlassMaterial
  • FrostedGlassSinglePassMaterial
  • GlassMaterial
  • GlassRefractiveMaterial
  • PaperArtisticMaterial
  • PaperOfficeMaterial
  • PlasticStructuredRedEmissiveMaterial
  • PlasticStructuredRedMaterial
  • SteelMilledConcentricMaterial

Tesselation and displacement maps

Model tesselation mode is gone due to increased focus on supporting embedded hardware. In addition, as a result, displacement map support has been removed from materials. Similar effects can be achieved with a custom material.