class QQuick3DInstancing¶

Base class for defining instance tables. More…

Synopsis¶

Properties¶

depthSortingEnabledᅟ
hasTransparencyᅟ
instanceCountOverrideᅟ

Methods¶

def __init__()
def depthSortingEnabled()
def hasTransparency()
def instanceBuffer()
def instanceColor()
def instanceCountOverride()
def instanceCustomData()
def instancePosition()
def instanceRotation()
def instanceScale()
def markDirty()

Virtual methods¶

def getInstanceBuffer()

Signals¶

def depthSortingEnabledChanged()
def hasTransparencyChanged()
def instanceCountOverrideChanged()
def instanceNodeDirty()
def instanceTableChanged()

Static functions¶

def calculateTableEntry()
def calculateTableEntryFromQuaternion()

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

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

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property 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:

depthSortingEnabled()
setDepthSortingEnabled()
Signal depthSortingEnabledChanged()

property 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:

hasTransparency()
setHasTransparency()
Signal hasTransparencyChanged()

property 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:

instanceCountOverride()
setInstanceCountOverride()
Signal instanceCountOverrideChanged()

__init__([parent=None])¶

Parameters:: parent – QQuick3DObject

static calculateTableEntry(position, scale, eulerRotation, color[, customData={}])¶

Parameters:

position – QVector3D
scale – QVector3D
eulerRotation – QVector3D
color – QColor
customData – QVector4D

Return type:

InstanceTableEntry

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 calculateTableEntryFromQuaternion(position, scale, rotation, color[, customData={}])¶

Parameters:

position – QVector3D
scale – QVector3D
rotation – QQuaternion
color – QColor
customData – QVector4D

Return type:

InstanceTableEntry

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.

depthSortingEnabled()¶

Return type:: bool

See also

setDepthSortingEnabled()

Getter of property depthSortingEnabledᅟ .

depthSortingEnabledChanged()¶

Notification signal of property depthSortingEnabledᅟ .

abstract getInstanceBuffer(instanceCount)¶

Parameters:: instanceCount – int
Return type:: QByteArray

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

hasTransparency()¶

Return type:: bool

See also

setHasTransparency()

Getter of property hasTransparencyᅟ .

hasTransparencyChanged()¶

Notification signal of property hasTransparencyᅟ .

instanceBuffer(instanceCount)¶

Parameters:: instanceCount – int
Return type:: QByteArray

instanceColor(index)¶

Parameters:: index – int
Return type:: QColor

instanceCountOverride()¶

Return type:: int

See also

setInstanceCountOverride()

Getter of property instanceCountOverrideᅟ .

instanceCountOverrideChanged()¶

Notification signal of property instanceCountOverrideᅟ .

instanceCustomData(index)¶

Parameters:: index – int
Return type:: QVector4D

instanceNodeDirty()¶

instancePosition(index)¶

Parameters:: index – int
Return type:: QVector3D

instanceRotation(index)¶

Parameters:: index – int
Return type:: QQuaternion

instanceScale(index)¶

Parameters:: index – int
Return type:: QVector3D

instanceTableChanged()¶

markDirty()¶

Mark that the instance data has changed and must be uploaded again.

See also

getInstanceBuffer instanceCountOverride

setDepthSortingEnabled(enabled)¶

Parameters:: enabled – bool

See also

depthSortingEnabled()

Setter of property depthSortingEnabledᅟ .

setHasTransparency(hasTransparency)¶

Parameters:: hasTransparency – bool

See also

hasTransparency()

Setter of property hasTransparencyᅟ .

setInstanceCountOverride(instanceCountOverride)¶

Parameters:: instanceCountOverride – int

See also

instanceCountOverride()

Setter of property instanceCountOverrideᅟ .