Scene3D QML Type
The Scene3D type is used to integrate a Qt3D scene into a QtQuick 2 scene. More...
| Import Statement: | import QtQuick.Scene3D 2.15 |
| Inherits: |
Properties
- aspects : list<string>
- cameraAspectRatioMode : enumeration
- compositingMode : enumeration
- entity : Entity
- hoverEnabled : bool
- multisample : bool
Methods
- void setItemAreaAndDevicePixelRatio(size area, real devicePixelRatio)
Detailed Description
The Scene3D type renders a Qt3D scene, provided by an Entity, into a multisampled Framebuffer object. This object is later blitted into a non-multisampled Framebuffer object, which is then rendered with premultiplied alpha. If multisampling is not required, it can be avoided by setting the multisample property to false. In this case Scene3D will render directly into the non-multisampled Framebuffer object.
If the scene to be rendered includes non-opaque materials, you may need to modify those materials with custom blend arguments in order for them to be rendered correctly. For example, if working with a PhongAlphaMaterial and a scene with an opaque clear color, you will likely want to add:
sourceAlphaArg: BlendEquationArguments.Zero destinationAlphaArg: BlendEquationArguments.One
to that material.
It is not recommended to instantiate more than a single Scene3D instance per application. The reason for this is that a Scene3D instance instantiates the entire Qt 3D engine (memory managers, thread pool, render ...) under the scene. You should instead look into using Scene3DView instances in conjunction with a single Scene3D instance.
When using Scene3D with Scene3DViews the following conditions are expected:
- The compositingMode is set to FBO
- The Scene3D is sized to occupy the full window size
- The Scene3D instance is instantiated prior to any Scene3DView
- The Scene3D entity property is left unset
Note: Śetting the visibility of the Scene3D element to false will halt the Qt 3D simulation loop. This means that binding the visible property to an expression that depends on property updates driven by the Qt 3D simulation loop (FrameAction) will never reavaluates.
Property Documentation
The list of aspects that should be registered for the 3D scene.
For example, if the scene makes use of FrameAction, the "logic" aspect should be included in the list.
The "render" aspect is hardwired and does not need to be explicitly listed.
cameraAspectRatioMode : enumeration |
| Constant | Description |
|---|---|
Scene3D.AutomaticAspectRatio | Automatic aspect ratio. |
Scene3D.UserAspectRatio | User defined aspect ratio. |
compositingMode : enumeration |
| Constant | Description |
|---|---|
FBO | Scene is rendered into a Frame Buffer Object which can be costly on some platform and hardware but allows a greater amount of flexibility. Automatic aspect ratio. This is the compositing mode to choose if your Scene3D element shouldn't occupy the entire screen and if you optionally plan on having it resized or animated. In this mode, the position of the Scene3D in the QML file controls its stacking order with regard to the other Qt Quick elements. |
Underlay | Suitable for full screen 3D scenes where using an FBO might be too resource intensive. Scene3D behaves as a QtQuick underlay. Please note that when using this mode, the size of the Scene3D and its transformations are ignored and the rendering will occupy the whole screen. The position of the Scene3D in the QML file won't have any effect either. The Qt 3D content will be drawn prior to any Qt Quick content. Care has to be taken not to overdraw and hide the Qt 3D content by overlapping Qt Quick content. Additionally when using this mode, the window clearBeforeRendering will be set to false automatically. |
The default value is FBO.
This property was introduced in Qt 5.14.
[default] entity : Entity |
The root entity of the 3D scene to be displayed.
hoverEnabled : bool |
true if hover events are accepted.
multisample : bool |
true if a multisample render buffer is requested.
By default multisampling is enabled. If the OpenGL implementation has no support for multisample renderbuffers or framebuffer blits, the request to use multisampling is ignored.
Note: Refrain from changing the value frequently as it involves expensive and potentially slow initialization of framebuffers and other OpenGL resources.
Method Documentation
Sets the item area to area and the pixel ratio to devicePixelRatio.