Sur cette page

QQuick3DInstancing Class

Classe de base permettant de définir des tables d'instances. En savoir plus...

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'instances personnalisée pour un modèle dans la scène 3D d'Qt Quick.

Cette classe est abstraite : pour l'utiliser, créez une sous-classe et implémentez la méthode ` getInstanceBuffer()`.

Documentation des propriétés

depthSortingEnabled : bool

Contient la valeur indiquant si le tri en profondeur est activé pour la table d’instances. Lorsque cette option est activée, les instances sont triées et rendues de la plus éloignée de la caméra à la plus proche, c’est-à-dire de l’arrière vers l’avant. Si elle est désactivée (ce qui est le cas par défaut), les instances sont rendues dans l’ordre où elles sont spécifiées dans la table d’instances.

Remarque : les instances sont uniquement triées les unes par rapport aux autres. Elles 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

Définissez cette propriété sur « true » si la table d'instanciation contient des valeurs alpha qui doivent être utilisées lors du rendu du modèle. Cette propriété n'a d'incidence que si le modèle est opaque : si le modèle présente une transparence material ou une opacity inférieure à un, la valeur alpha de la table sera utilisée dans tous les cas.

Remarque : l’activation du mélange alpha peut entraîner des problèmes de rendu lorsque des instances se chevauchent. Consultez la documentation sur le mélange alpha 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

Définissez cette propriété pour limiter le nombre d'instances sans avoir à régénérer ni à réimporter la table des instances. Cela permet de modifier de manière très peu coûteuse le nombre d'instances affichées.

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 pour calculer les limites de la carte d'ombres des modèles de la table d'instances.

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

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

Cette énumération a été introduite dans Qt 6.9.

Fonctions d'accès :

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

Signal de notification :

void shadowBoundsMaximumChanged()

Voir aussi shadowBoundsMinimum.

[since 6.9] shadowBoundsMinimum : QVector3D

Définit les limites minimales utilisées pour calculer les limites de la carte d'ombres des modèles de la table d'instances.

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

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

Cette énumération a été introduite dans Qt 6.9.

Fonctions d’accès :

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

Signal de notification :

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 formats position, scale, eulerRotation, color et customData au format de table d'instances attendu par les shaders de sommets standard. Exemple 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 également calculateTableEntryFromQuaternion.

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

Convertit les fonctions position, scale, rotation, color et customData au format de table d'instances attendu par les shaders de sommets standard.

Cette fonction est identique à calculateTableEntry(), à l’exception de l’utilisation d’un quaternion pour spécifier la rotation.

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

Implémentez cette fonction pour renvoyer le contenu de la table des instances. Le nombre d'instances doit être renvoyé dans ` instanceCount`. La sous-classe est chargée de mettre le résultat en cache si nécessaire. Si la table des instances change, la sous-classe doit appeler la fonction ` markDirty()`.

[protected] void QQuick3DInstancing::markDirty()

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