QQuick3DInstancing Class
Base class for defining instance tables. More...
| Header: | #include <QQuick3DInstancing> |
| Since: | Qt 6.2 |
| In QML: | Instancing |
| Inherits: | QQuick3DObject |
Properties
- depthSortingEnabled : bool
- hasTransparency : bool
- instanceCountOverride : int
Public Functions
| bool | depthSortingEnabled() const |
| bool | hasTransparency() const |
| int | instanceCountOverride() const |
| QVector3D | shadowBoundsMaximum() const |
| QVector3D | shadowBoundsMinimum() const |
Public Slots
| void | setDepthSortingEnabled(bool enabled) |
| void | setHasTransparency(bool hasTransparency) |
| void | setInstanceCountOverride(int instanceCountOverride) |
| void | setShadowBoundsMaximum(const QVector3D &newShadowBoundsMinimum) |
| void | setShadowBoundsMinimum(const QVector3D &newShadowBoundsMinimum) |
Signals
| void | depthSortingEnabledChanged() |
| void | hasTransparencyChanged() |
| void | instanceCountOverrideChanged() |
| void | shadowBoundsMaximumChanged() |
| void | shadowBoundsMinimumChanged() |
Protected Functions
| void | markDirty() |
Static Protected Members
| QQuick3DInstancing::InstanceTableEntry | calculateTableEntry(const QVector3D &position, const QVector3D &scale, const QVector3D &eulerRotation, const QColor &color, const QVector4D &customData = {}) |
| QQuick3DInstancing::InstanceTableEntry | calculateTableEntryFromQuaternion(const QVector3D &position, const QVector3D &scale, const QQuaternion &rotation, const QColor &color, const QVector4D &customData = {}) |
Detailed Description
The QQuick3DInstancing class can be inherited to specify a custom instance table for a Model in the Qt Quick 3D scene.
This class is abstract: To use it, create a subclass and implement getInstanceBuffer().
Property Documentation
depthSortingEnabled : bool
Holds the depth sorting enabled value for the instance table. When enabled, instances are sorted and rendered from the furthest instance from the camera to the nearest i.e. back-to-front. If disabled, which is the default, instances are rendered in the order they are specified in the instance table.
Note: The instances are only sorted against each other. Instances are not sorted against other objects in the scene.
Note: The sorting increases the frame preparation time especially with large instance counts.
Access functions:
| bool | depthSortingEnabled() const |
| void | setDepthSortingEnabled(bool enabled) |
Notifier signal:
| void | depthSortingEnabledChanged() |
hasTransparency : bool
Set this property to true if the instancing table contains alpha values that should be used when rendering the model. This property only makes a difference if the model is opaque: If the model has a transparent material, or an opacity less than one, the alpha value from the table will be used regardless.
Note: Enabling alpha blending may cause rendering issues when instances overlap. See the alpha blending and instancing documentation for details.
Access functions:
| bool | hasTransparency() const |
| void | setHasTransparency(bool hasTransparency) |
Notifier signal:
| void | hasTransparencyChanged() |
instanceCountOverride : int
Set this property to limit the number of instances without regenerating or re-uploading the instance table. This allows very inexpensive animation of the number of instances rendered.
Access functions:
| int | instanceCountOverride() const |
| void | setInstanceCountOverride(int instanceCountOverride) |
Notifier signal:
| void | instanceCountOverrideChanged() |
Member Function Documentation
[static protected] QQuick3DInstancing::InstanceTableEntry QQuick3DInstancing::calculateTableEntry(const QVector3D &position, const QVector3D &scale, const QVector3D &eulerRotation, const QColor &color, const QVector4D &customData = {})
Converts the position scale eulerRotation color and customData to the instance table format expected by the standard vertex shaders. Typical pattern:
QByteArray MyInstanceTable::getInstanceBuffer(int *instanceCount) { QByteArray instanceData; ... auto entry = calculateTableEntry({xPos, yPos, zPos}, {xScale, yScale, zScale}, {xRot, yRot, zRot}, color, {}); instanceData.append(reinterpret_cast<const char *>(&entry), sizeof(entry));
See also calculateTableEntryFromQuaternion.
[static protected] QQuick3DInstancing::InstanceTableEntry QQuick3DInstancing::calculateTableEntryFromQuaternion(const QVector3D &position, const QVector3D &scale, const QQuaternion &rotation, const QColor &color, const QVector4D &customData = {})
Converts the position scale rotation color and customData to the instance table format expected by the standard vertex shaders.
This is the same as calculateTableEntry(), except for using a quaternion to specify the rotation.
[protected] void QQuick3DInstancing::markDirty()
Mark that the instance data has changed and must be uploaded again.
See also getInstanceBuffer and instanceCountOverride.