Back to Qt.io
Contact Us Blog Download Qt

QQuick3DInstancing Class

Base class for defining instance tables. More...

Header: #include <QQuick3DInstancing>
Since: Qt 6.2
In QML: Instancing
Inherits: QQuick3DObject

Properties

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.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.