- Qt 6.9
- Qt Quick 3D
- QML Types
- Instancing
- Qt Quick 3D | Commercial or GPLv3

# Instancing QML Type

Base type for instance tables. More...

Import Statement: | `import QtQuick3D`
Since: | Qt 6.2
Inherits: | Object3D
Inherited By: | FileInstancing, InstanceList, and RandomInstancing

- List of all members, including inherited members

## Properties

- depthSortingEnabled : bool
- hasTransparency : bool
- instanceCountOverride : int
- shadowBoundsMaximum : vector3d
- shadowBoundsMinimum : vector3d

## Methods

- color instanceColor(int index) `(since 6.3)`
- vector3d instanceCustomData(int index) `(since 6.3)`
- vector3d instancePosition(int index) `(since 6.3)`
- quaternion instanceRotation(int index) `(since 6.3)`
- vector3d instanceScale(int index) `(since 6.3)`

## Detailed Description

Instanced rendering allows duplicating a model with variations.

The Instancing type defines a table that specifies how each instance is modified relative to the base model. The table has an entry for each index, containing a transform matrix, a color, and generic data for use by custom materials. To use instancing, set a model's instancing property to reference an Instancing object.

An application can define an Instancing object in C++ by subclassing QQuick3DInstancing, or it can use one of the pre-defined QML types: InstanceList FileInstancing, or RandomInstancing. In addition, it is possible to use a particle system to define an instancing table by using the ModelParticle3D.instanceTable property.

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

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.

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.

shadowBoundsMaximum : vector3d

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 Instancing::shadowBoundsMinimum are smaller than those in Instancing::shadowBoundsMaximum. Otherwise the bounds are calculated automatically.

See also shadowBoundsMinimum.

shadowBoundsMinimum : vector3d

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 Instancing::shadowBoundsMinimum are smaller than those in Instancing::shadowBoundsMaximum. Otherwise the bounds are calculated automatically.

See also shadowBoundsMaximum.

## Method Documentation

`[since 6.3]` color instanceColor(int index)

Returns the color of the instance at index

This method was introduced in Qt 6.3.

See also instancePosition, instanceScale, instanceRotation, instanceColor, and instanceCustomData.

`[since 6.3]` vector3d instanceCustomData(int index)

Returns the custom data for the instance at index

This method was introduced in Qt 6.3.

See also instancePosition, instanceScale, instanceRotation, instanceColor, and instanceCustomData.

`[since 6.3]` vector3d instancePosition(int index)

Returns the position of the instance at index

This method was introduced in Qt 6.3.

See also instanceScale, instanceRotation, instanceColor, and instanceCustomData.

`[since 6.3]` quaternion instanceRotation(int index)

Returns a quaternion representing the rotation of the instance at index

This method was introduced in Qt 6.3.

See also instancePosition, instanceScale, instanceRotation, instanceColor, and instanceCustomData.

`[since 6.3]` vector3d instanceScale(int index)

Returns the scale of the instance at index

This method was introduced in Qt 6.3.

See also instancePosition, instanceScale, instanceRotation, instanceColor, and instanceCustomData.