Sur cette page

QQuick3DInstancing Class

Classe de base pour la définition des tables d'instance. Plus d'informations...

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

Propriétés

Fonctions publiques

bool depthSortingEnabled() const
bool hasTransparency() const
int instanceCountOverride() const
QVector3D shadowBoundsMaximum() const
QVector3D shadowBoundsMinimum() const

Emplacements publics

void setDepthSortingEnabled(bool enabled)
void setHasTransparency(bool hasTransparency)
void setInstanceCountOverride(int instanceCountOverride)
void setShadowBoundsMaximum(const QVector3D &newShadowBoundsMinimum)
void setShadowBoundsMinimum(const QVector3D &newShadowBoundsMinimum)

Signaux

Fonctions protégées

virtual QByteArray getInstanceBuffer(int *instanceCount) = 0
void markDirty()

Membres statiques protégés

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 = {})

Description détaillée

La classe QQuick3DInstancing peut être héritée pour spécifier une table d'instance personnalisée pour un modèle dans la scène 3D de Qt Quick.

Cette classe est abstraite : pour l'utiliser, il faut créer une sous-classe et implémenter getInstanceBuffer().

Documentation sur les propriétés

depthSortingEnabled : bool

Contient la valeur d'activation du tri en profondeur pour la table d'instances. Lorsque cette valeur est activée, les instances sont triées et rendues de l'instance la plus éloignée de la caméra à la plus proche, c'est-à-dire de l'arrière vers l'avant. S'il est désactivé, ce qui est la valeur par défaut, les instances sont rendues dans l'ordre où elles sont spécifiées dans la table d'instances.

Remarque : les instances ne sont triées que les unes par rapport aux autres. Les instances ne sont pas triées par rapport aux autres objets de la scène.

Remarque : le tri augmente le temps de préparation des images, en particulier lorsque le nombre d'instances est élevé.

Fonctions d'accès :

bool depthSortingEnabled() const
void setDepthSortingEnabled(bool enabled)

Signal de notification :

void depthSortingEnabledChanged()

hasTransparency : bool

Attribuer la valeur true à cette propriété si la table d'instanciation contient des valeurs alpha qui doivent être utilisées lors du rendu du modèle. Cette propriété ne fait une différence que si le modèle est opaque : Si le modèle est transparent ( material) ou si l'adresse opacity est inférieure à un, la valeur alpha de la table sera utilisée de toute façon.

Remarque : l'activation de l'alpha blending peut entraîner des problèmes de rendu lorsque les instances se chevauchent. Voir la documentation sur l 'alpha blending et l'instanciation pour plus de détails.

Fonctions d'accès :

bool hasTransparency() const
void setHasTransparency(bool hasTransparency)

Signal de notification :

void hasTransparencyChanged()

instanceCountOverride : int

Cette propriété permet de limiter le nombre d'instances sans régénérer ou recharger la table des instances. Cela permet une animation très peu coûteuse du nombre d'instances rendues.

Fonctions d'accès :

int instanceCountOverride() const
void setInstanceCountOverride(int instanceCountOverride)

Signal de notification :

void instanceCountOverrideChanged()

[since 6.9] shadowBoundsMaximum : QVector3D

Définit les limites maximales utilisées lors du calcul des limites de la carte des ombres des modèles dans la table d'instance.

Valeur par défaut : (-1, -1, -1)

Remarque : cette propriété n'est activée que si les composantes respectives de shadowBoundsMinimum sont inférieures à celles de shadowBoundsMaximum. Dans le cas contraire, les limites sont calculées automatiquement.

Cette propriété a été introduite dans Qt 6.9.

Fonctions d'accès :

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

Signal Notifier :

void shadowBoundsMaximumChanged()

Voir aussi shadowBoundsMinimum.

[since 6.9] shadowBoundsMinimum : QVector3D

Définit les limites minimales utilisées lors du calcul des limites de la carte des ombres des modèles dans la table d'instance.

Valeur par défaut : (1, 1, 1)

Note : Cette propriété n'est activée que lorsque les composantes respectives de shadowBoundsMinimum sont plus petites que celles de shadowBoundsMaximum. Dans le cas contraire, les limites sont calculées automatiquement.

Cette propriété a été introduite dans Qt 6.9.

Fonctions d'accès :

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

Signal Notifier :

void shadowBoundsMinimumChanged()

Voir également shadowBoundsMaximum.

Documentation des fonctions membres

[static protected] QQuick3DInstancing::InstanceTableEntry QQuick3DInstancing::calculateTableEntry(const QVector3D &position, const QVector3D &scale, const QVector3D &eulerRotation, const QColor &color, const QVector4D &customData = {})

Convertit les fichiers position scale eulerRotation color et customData au format de table d'instance attendu par les vertex shaders standard. Modèle typique :

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

Voir aussi calculateTableEntryFromQuaternion.

[static protected] QQuick3DInstancing::InstanceTableEntry QQuick3DInstancing::calculateTableEntryFromQuaternion(const QVector3D &position, const QVector3D &scale, const QQuaternion &rotation, const QColor &color, const QVector4D &customData = {})

Convertit les fichiers position scale rotation color et customData au format de table d'instance attendu par les vertex shaders standard.

C'est la même chose que calculateTableEntry(), à l'exception de l'utilisation d'un quaternion pour spécifier la rotation.

[pure virtual protected] QByteArray QQuick3DInstancing::getInstanceBuffer(int *instanceCount)

Cette fonction est mise en œuvre pour renvoyer le contenu de la table des instances. Le nombre d'instances doit être renvoyé à l'adresse instanceCount. La sous-classe est responsable de la mise en cache du résultat si nécessaire. Si la table d'instances change, la sous-classe doit appeler markDirty().

[protected] void QQuick3DInstancing::markDirty()

Indique que les données de l'instance ont changé et doivent être téléchargées à nouveau.

Voir également getInstanceBuffer et instanceCountOverride.

© 2026 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.