En esta página

QQuick3DInstancing Class

Clase base para definir tablas de instancias. Más...

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

Propiedades

Funciones públicas

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

Ranuras públicas

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

Señales

Funciones protegidas

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

Miembros estáticos protegidos

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

Descripción detallada

La clase QQuick3DInstancing puede heredarse para especificar una tabla de instancias personalizada para un modelo en la escena 3D de Qt Quick.

Esta clase es abstracta: para utilizarla, crea una subclase e implementa el método ` getInstanceBuffer()`.

Documentación de propiedades

depthSortingEnabled : bool

Almacena el valor de la opción «Ordenar por profundidad» activada para la tabla de instancias. Cuando está activada, las instancias se ordenan y se representan desde la más lejana a la cámara hasta la más cercana, es decir, de atrás hacia delante. Si está desactivada, que es la configuración por defecto, las instancias se representan en el orden en que aparecen especificadas en la tabla de instancias.

Nota: Las instancias solo se ordenan entre sí. No se ordenan con respecto a otros objetos de la escena.

Nota: La ordenación aumenta el tiempo de preparación de fotogramas, especialmente cuando hay un gran número de instancias.

Funciones de acceso:

bool depthSortingEnabled() const
void setDepthSortingEnabled(bool enabled)

Señal de notificación:

void depthSortingEnabledChanged()

hasTransparency : bool

Establece esta propiedad en «true» si la tabla de instanciación contiene valores alfa que deben utilizarse al renderizar el modelo. Esta propiedad solo tiene efecto si el modelo es opaco: si el modelo tiene un « material » transparente o un « opacity » inferior a uno, se utilizará el valor alfa de la tabla en cualquier caso.

Nota: Activar la mezcla alfa puede provocar problemas de renderizado cuando las instancias se superponen. Consulta la documentación sobre mezcla alfa e instanciación para obtener más detalles.

Funciones de acceso:

bool hasTransparency() const
void setHasTransparency(bool hasTransparency)

Señal de notificador:

void hasTransparencyChanged()

instanceCountOverride : int

Establece esta propiedad para limitar el número de instancias sin necesidad de regenerar ni volver a cargar la tabla de instancias. Esto permite animar de forma muy económica el número de instancias renderizadas.

Funciones de acceso:

int instanceCountOverride() const
void setInstanceCountOverride(int instanceCountOverride)

Señal de notificador:

void instanceCountOverrideChanged()

[since 6.9] shadowBoundsMaximum : QVector3D

Establece los límites máximos que se utilizan al calcular los límites del mapa de sombras de los modelos de la tabla de instancias.

Valor por defecto: (-1, -1, -1)

Nota: Esta propiedad solo está habilitada cuando los componentes correspondientes de « shadowBoundsMinimum » son menores que los de «shadowBoundsMaximum». De lo contrario, los límites se calculan automáticamente.

Esta enumeración se introdujo en Qt 6.9.

Funciones de acceso:

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

Señal de notificador:

void shadowBoundsMaximumChanged()

Véase también shadowBoundsMinimum.

[since 6.9] shadowBoundsMinimum : QVector3D

Establece los límites mínimos que se utilizan al calcular los límites del mapa de sombras de los modelos de la tabla de instancias.

Valor por defecto: (1, 1, 1)

Nota: Esta propiedad solo está habilitada cuando los componentes correspondientes de `shadowBoundsMinimum` son menores que los de ` shadowBoundsMaximum`. De lo contrario, los límites se calculan automáticamente.

Esta enumeración se introdujo en Qt 6.9.

Funciones de acceso:

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

Señal de notificador:

void shadowBoundsMinimumChanged()

Véase también shadowBoundsMaximum.

Documentación de las funciones miembro

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

Convierte position, scale, eulerRotation, color y customData al formato de tabla de instancias que esperan los sombreadores de vértices estándar. Patrón típico:

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

Véase también calculateTableEntryFromQuaternion.

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

Convierte position, scale, rotation, color y customData al formato de tabla de instancias que esperan los sombreadores de vértices estándar.

Es lo mismo que calculateTableEntry(), salvo que utiliza un cuaternión para especificar la rotación.

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

Implementa esta función para devolver el contenido de la tabla de instancias. El número de instancias debe devolverse en ` instanceCount`. La subclase se encarga de almacenar el resultado en caché si es necesario. Si la tabla de instancias cambia, la subclase debe llamar a ` markDirty()`.

[protected] void QQuick3DInstancing::markDirty()

Indica que los datos de la instancia han cambiado y deben volver a cargarse.

Véase también getInstanceBuffer y 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.