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
| void | depthSortingEnabledChanged() |
| void | hasTransparencyChanged() |
| void | instanceCountOverrideChanged() |
| void | shadowBoundsMaximumChanged() |
| void | shadowBoundsMinimumChanged() |
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.