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 |
Public Slots
| void | setDepthSortingEnabled(bool enabled) |
| void | setHasTransparency(bool hasTransparency) |
| void | setInstanceCountOverride(int instanceCountOverride) |
Signals
| void | depthSortingEnabledChanged() |
| void | hasTransparencyChanged() |
| void | instanceCountOverrideChanged() |
Protected Functions
| virtual QByteArray | getInstanceBuffer(int *instanceCount) = 0 |
| 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.
[pure virtual protected] QByteArray QQuick3DInstancing::getInstanceBuffer(int *instanceCount)
Implement this function to return the contents of the instance table. The number of instances should be returned in instanceCount. The subclass is responsible for caching the result if necessary. If the instance table changes, the subclass should call markDirty().
[protected] void QQuick3DInstancing::markDirty()
Mark that the instance data has changed and must be uploaded again.
See also getInstanceBuffer and instanceCountOverride.