- Qt 6.11
- Qt Quick 3D
- C++ Classes
- QQuick3DInstancing
- Qt Quick 3D | Commercial or GPLv3

# QQuick3DInstancing Class

Base class for defining instance tables. More...

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

- List of all members, including inherited members

## Properties

depthSortingEnabled : bool hasTransparency : bool instanceCountOverride : int | `(since 6.9)` shadowBoundsMaximum : QVector3D `(since 6.9)` shadowBoundsMinimum : QVector3D

## 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

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()

### `[since 6.9]` shadowBoundsMaximum : QVector3D

Sets the maximum bounds used when calculating the shadow map bounds of the models in the instance table.

Default value: `(-1, -1, -1)`

Note: This property is only enabled when the respective components of shadowBoundsMinimum are smaller than those in shadowBoundsMaximum. Otherwise the bounds are calculated automatically.

This property was introduced in Qt 6.9.

Access functions:

QVector3D | shadowBoundsMaximum() const
void | setShadowBoundsMaximum(const QVector3D &newShadowBoundsMinimum)

Notifier signal:

void | shadowBoundsMaximumChanged()

See also shadowBoundsMinimum.

### `[since 6.9]` shadowBoundsMinimum : QVector3D

Sets the minimum bounds used when calculating the shadow map bounds of the models in the instance table.

Default value: `(1, 1, 1)`

Note: This property is only enabled when the respective components of shadowBoundsMinimum are smaller than those in shadowBoundsMaximum. Otherwise the bounds are calculated automatically.

This property was introduced in Qt 6.9.

Access functions:

QVector3D | shadowBoundsMinimum() const
void | setShadowBoundsMinimum(const QVector3D &newShadowBoundsMinimum)

Notifier signal:

void | shadowBoundsMinimumChanged()

See also shadowBoundsMaximum.

## 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.