En esta página

QQuick3DInstancing Class

Clase base para definir tablas de instancia. 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 ser heredada para especificar una tabla de instancias personalizada para un Modelo en la escena 3D de Qt Quick.

Esta clase es abstracta: Para utilizarla, cree una subclase e implemente getInstanceBuffer().

Documentación de Propiedades

depthSortingEnabled : bool

Contiene el valor de ordenación de profundidad habilitado para la tabla de instancias. Cuando está activado, las instancias se ordenan y renderizan desde la instancia más alejada de la cámara a la más cercana, es decir, de atrás hacia delante. Si está deshabilitado, que es el valor por defecto, las instancias se renderizan en el orden en que se especifican en la tabla de instancias.

Nota: Las instancias sólo se ordenan entre sí. Las instancias no se ordenan con respecto a otros objetos de la escena.

Nota: La ordenación aumenta el tiempo de preparación de los fotogramas, especialmente cuando el número de instancias es elevado.

Funciones de acceso:

bool depthSortingEnabled() const
void setDepthSortingEnabled(bool enabled)

Señal notificadora:

void depthSortingEnabledChanged()

hasTransparency : bool

Establezca esta propiedad a true si la tabla de instanciación contiene valores alfa que deberían utilizarse al renderizar el modelo. Esta propiedad sólo supone una diferencia si el modelo es opaco: Si el modelo tiene un material transparente, o un opacity menor que uno, se utilizará el valor alfa de la tabla.

Nota: Activar la mezcla alfa puede causar problemas de renderizado cuando las instancias se solapan. Consulte la documentación sobre mezcla alfa e instanciación para más detalles.

Funciones de acceso:

bool hasTransparency() const
void setHasTransparency(bool hasTransparency)

Señal del notificador:

void hasTransparencyChanged()

instanceCountOverride : int

Establezca esta propiedad para limitar el número de instancias sin regenerar o volver a cargar la tabla de instancias. Esto permite una animación muy económica del número de instancias renderizadas.

Funciones de acceso:

int instanceCountOverride() const
void setInstanceCountOverride(int instanceCountOverride)

Señal de aviso:

void instanceCountOverrideChanged()

[since 6.9] shadowBoundsMaximum : QVector3D

Establece los límites máximos utilizados 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 sólo se activa cuando los componentes respectivos de shadowBoundsMinimum son menores que los de shadowBoundsMaximum. En caso contrario, los límites se calculan automáticamente.

Esta propiedad 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 utilizados 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 sólo se activa cuando los respectivos componentes de shadowBoundsMinimum son menores que los de shadowBoundsMaximum. En caso contrario, los límites se calculan automáticamente.

Esta propiedad se introdujo en Qt 6.9.

Funciones de acceso:

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

Notifier signal:

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 esperado por 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 esperado por los sombreadores de vértices estándar.

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

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

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

[protected] void QQuick3DInstancing::markDirty()

Marca que los datos de la instancia han cambiado y deben cargarse de nuevo.

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.