Model QML Type
Permite cargar los datos de un modelo 3D. Más...
| Import Statement: | import QtQuick3D |
| Inherits: | |
| Inherited By: |
Propiedades
- bakedLightmap : BakedLightmap
- bounds : Bounds
- castsReflections : bool
(since 6.4) - castsShadows : bool
- depthBias : real
- geometry : Geometry
- instanceRoot : QtQuick3D::Node
- instancing : QtQuick3D::Instancing
- instancingLodMax : real
- instancingLodMin : real
- inverseBindPoses : List<matrix4x4>
- levelOfDetailBias : real
(since 6.5) - materials : List<QtQuick3D::Material>
- morphTargets : List<QtQuick3D::MorphTarget>
- motionVectorEnabled : bool
(since 6.11) - motionVectorScale : real
(since 6.11) - pickable : bool
- receivesReflections : bool
- receivesShadows : bool
- skeleton : Skeleton
- skin : Skin
- source : url
- texelsPerUnit : real
(since 6.10) - usedInBakedLighting : bool
Descripción detallada
El elemento Modelo permite cargar una malla y modificar su sombreado, añadiéndole materiales. Para que un modelo sea renderizable, necesita al menos una malla y un material.
Formato de malla y primitivas incorporadas
El modelo puede cargar mallas estáticas almacenadas o una de las primitivas incorporadas. El formato de malla utilizado es un formato de tiempo de ejecución nativo del motor, pero se admiten formatos adicionales a través de la herramienta de importación de activos Balsam.
Las primitivas incorporadas pueden cargarse estableciendo la propiedad source en uno de estos valores: #Rectangle, #Sphere, #Cube, #Cylinder or #Cone.
Model { source: "#Sphere" }
La siguiente tabla describe las mallas incorporadas con más detalle.
| Nombre | Descripción | Número de caras |
|---|---|---|
| #Cono | Un cono con una altura y un diámetro de 100. La base está en el origen y el cono apunta hacia arriba en la dirección y. | 78 |
| #Cubo | Un cubo centrado en el origen con 100 lados largos a lo largo de x, y y z. | 12 |
| #Cilindro | Un cilindro con 100 altura y diámetro centrado en el origen expandiéndose a lo largo de la dirección y. | 316 |
| #Rectángulo | Un rectángulo con 100 anchura y altura centrado en el origen en el plano xy. | 2 |
| #Esfera | Esfera de diámetro 100 centrada en el origen. | 4900 |
Geometría personalizada
Además de utilizar mallas estáticas, puedes implementar un proveedor custom geometry que proporcione al modelo datos de vértices personalizados en tiempo de ejecución. Consulte el ejemplo de geometría personalizada para ver un ejemplo sobre cómo crear y utilizar un material personalizado con su modelo.
Materiales
Un modelo puede constar de varias submallas, cada una de las cuales puede tener su propio material. La submalla utiliza un material de la lista materials, correspondiente a su índice. Si el número de materiales es inferior al de submallas, el último material de la lista se utiliza para las submallas siguientes. Esto se demuestra en el ejemplo Submalla.
Puede utilizar los siguientes materiales con el elemento del modelo: PrincipledMaterial, DefaultMaterial, y CustomMaterial.
Picking
Laselección es el proceso de enviar un rayo a través de la escena desde una posición inicial para encontrar los modelos que se cruzan con el rayo. En Qt Quick 3D, el rayo se envía normalmente desde la vista usando coordenadas 2D resultantes de un evento táctil o del ratón. Si un modelo es alcanzado por el rayo, pickResult será devuelto con un "handle" del modelo e información sobre dónde el rayo alcanzó al modelo. Para los modelos que utilizan custom geometry, la selección es menos precisa que para los datos de malla estáticos, ya que la selección sólo se realiza contra el modelo bounding volume. Si el rayo atraviesa más de un modelo, se selecciona el modelo pickable más cercano.
Tenga en cuenta que para que los modelos sean pickable, su propiedad pickable debe ser true. Para más información, consulte Qt Quick 3D - Ejemplo de selección.
Documentación de propiedades
bakedLightmap : BakedLightmap
Cuando esta propiedad se establece en un objeto BakedLightmap válido y habilitado, el modelo obtendrá un lightmap generado al bakear la iluminación, el lightmap se almacena de forma persistente. Al renderizar, el modelo cargará y utilizará el lightmap asociado. El valor por defecto es null.
Nota: Cuando la intención es generar un lightmap almacenado persistentemente para un Modelo, ambos bakedLightmap y usedInBakedLighting deben ser establecidos en él, con el fin de indicar que el Modelo no sólo participa en la escena lightmapped, sino que también quiere que un lightmap completo sea bakeado y almacenado.
Para más información sobre como bakear lightmaps, ver la documentación de Lightmapper.
Esta propiedad es relevante tanto cuando se bakea como cuando se usan lightmaps. Un estado consistente entre la ejecución de baking y las subsiguientes ejecuciones que utilicen los datos generados es esencial. Por ejemplo, cambiar la clave del lightmap hará imposible cargar los datos generados previamente. Una excepción es enabled, que puede usarse para cambiar dinámicamente el uso de lightmaps (fuera de la ejecución de baking), pero ten en cuenta que los resultados renderizados dependerán de los ajustes de Lights' bakeMode en la escena.
Ver también usedInBakedLighting y Lightmapper.
bounds : Bounds [read-only]
Los límites del modelo describen la extensión del volumen alrededor del modelo.
Nota: Los límites pueden no estar disponibles inmediatamente si el modelo necesita ser cargado primero.
castsReflections : bool [since 6.4]
Cuando esta propiedad se establece en true, el modelo se renderiza mediante sondas de reflexión y puede verse en las reflexiones.
Esta propiedad se introdujo en Qt 6.4.
castsShadows : bool
Cuando esta propiedad es true, la geometría de este modelo se utiliza cuando se renderiza a los mapas de sombras, y también está generando sombras en la iluminación baked.
El valor por defecto es true.
depthBias : real
Contiene el sesgo de profundidad del modelo. El sesgo de profundidad se añade a la distancia del objeto desde la cámara cuando se ordenan los objetos. Esto se puede utilizar para forzar el orden de renderizado entre objetos cercanos entre sí, que de otro modo podrían ser renderizados en diferente orden en diferentes fotogramas. Los valores negativos hacen que el valor de ordenación se mueva más cerca de la cámara mientras que los valores positivos lo mueven más lejos de la cámara.
geometry : Geometry
Especifique una geometría personalizada para el modelo. El Model::source debe estar vacío cuando se utiliza geometría personalizada.
instanceRoot : QtQuick3D::Node
Esta propiedad define el origen del sistema de coordenadas de la instancia.
Véase la documentación general para una explicación detallada.
Véase también instancing y Instancing.
instancing : QtQuick3D::Instancing
Si se establece esta propiedad, el modelo no se renderizará normalmente. En su lugar, se mostrarán un número de instancias del modelo, tal y como se define en la tabla de instancias.
Véase también Instancing.
instancingLodMax : real
Define la distancia máxima desde la cámara a la que se muestra una instancia de este modelo. Se utiliza para una implementación de nivel de detalle.
instancingLodMin : real
Define la distancia mínima desde la cámara a la que se muestra una instancia de este modelo. Se utiliza para una implementación de nivel de detalle.
inverseBindPoses : List<matrix4x4>
Esta propiedad contiene una lista de matrices Inverse Bind Pose utilizadas para la animación del esqueleto. Cada matriz inverseBindPose significa la inversa de la transformada global de la repective Joint::index en skeleton, que será utilizada inicialmente.
Nota: Esta propiedad sólo se utiliza si Model::skeleton es válida.
Nota: Si algunas de las matrices no están establecidas, se utilizarán valores de identidad.
Véase también Joint::index.
levelOfDetailBias : real [since 6.5]
Esta propiedad cambia el tamaño que debe tener el modelo cuando se renderiza antes de que se utilicen las mallas automáticas de nivel de detalle. Cada malla de nivel de detalle generada contiene un valor de tamaño ideal que cada nivel debe mostrar, que es una proporción de cuánto de la escena renderizada será esa malla. Un modelo que represente sólo unos pocos píxeles en pantalla no necesitará toda la geometría para verse correctamente, por lo que en este caso se utilizará una malla de menor nivel de detalle. Este valor es un sesgo hacia el valor ideal, de forma que un valor inferior a 1.0 requerirá un tamaño de renderizado aún menor antes de cambiar a un nivel de detalle menor. Los valores superiores a 1.0 harán que se utilicen antes niveles de detalle inferiores. Un valor de 0.0 desactivará completamente el uso de niveles de detalle.
El valor por defecto es 1.0
Nota: Esta propiedad sólo tendrá efecto cuando la geometría del Modelo contenga niveles de detalle.
Esta propiedad se introdujo en Qt 6.5.
Ver también Camera::levelOfDetailBias.
materials : List<QtQuick3D::Material>
Esta propiedad contiene una lista de materiales utilizados para renderizar la geometría proporcionada. Para renderizar cualquier cosa, debe haber al menos un material. Normalmente debe haber un material por cada submalla incluida en la geometría fuente.
Véase también Qt Quick 3D - Ejemplo de submalla.
morphTargets : List<QtQuick3D::MorphTarget>
Esta propiedad contiene una lista de MorphTargets utilizados para renderizar la geometría proporcionada. Las mallas deben tener al menos un atributo entre posiciones, normales, tangentes, binormales, coordenadas de textura y colores de vértice para los objetivos morph.
Véase también MorphTarget.
motionVectorEnabled : bool [default: true, since 6.11]
Especifica si el modelo participa en el pase del vector de movimiento.
Cuando esta propiedad se establece en true, el modelo contribuye con su información de movimiento al búfer del vector de movimiento. Esto es utilizado por el antialiasing temporal (TAA) y otros efectos que dependen de los datos de movimiento por píxel.
Cuando se establece en false, el modelo se excluye de la generación de vectores de movimiento.
Esta propiedad se introdujo en Qt 6.11.
Véase también Model::motionVectorScale.
motionVectorScale : real [default: 1.0, since 6.11]
Especifica un factor de escala aplicado a los vectores de movimiento generados por el modelo.
Un valor de 1.0 conserva el movimiento real del modelo, mientras que valores superiores a 1.0 exageran los vectores de movimiento y valores inferiores a 1.0 los reducen. Esto puede ser útil para efectos estilizados o para ajustar el comportamiento visual en efectos que dependen del búfer de vectores de movimiento.
Esta propiedad se introdujo en Qt 6.11.
Véase también Model::motionVectorEnabled.
pickable : bool
Esta propiedad controla si el modelo es seleccionable o no. Establezca esta propiedad a true para que el modelo sea seleccionable. Los modelos no son seleccionables por defecto.
Véase también View3D::pick.
receivesReflections : bool
Cuando esta propiedad está establecida en true, los materiales del modelo toman la contribución de reflexión de una sonda de reflexión. Si el modelo está dentro de más de una sonda de reflexión al mismo tiempo, se tiene en cuenta la sonda de reflexión más cercana.
receivesShadows : bool
Cuando esta propiedad está establecida a true, los materiales del modelo tienen en cuenta la contribución de sombras de las luces que proyectan sombras.
Nota: Cuando lightmapping está activado para este modelo, las luces totalmente bakeadas con Light::bakeMode establecido a Light.BakeModeAll siempre generarán sombras (bakeadas) en el modelo, independientemente del valor de esta propiedad.
El valor por defecto es true.
skeleton : Skeleton
Contiene el esqueleto del modelo. El esqueleto se utiliza junto con inverseBindPoses para el skinning.
Nota: Las mallas del modelo deben tener atributos de articulaciones y pesos.
Nota: Si esta propiedad esta establecida, la animación de skinning esta habilitada. Esto significa que Model es transformado basado en Skeleton ignorando la transformación global del modelo.
Ver también Model::inverseBindPoses y Qt Quick 3D - Ejemplo Simple de Skinning.
skin : Skin
Contiene el esqueleto del modelo. El esqueleto se utiliza para el skinning.
Nota: Las mallas del modelo deben tener atributos de articulaciones y pesos.
Nota: Si esta propiedad esta establecida, la animación de skinning esta habilitada. Esto significa que el Model será transformado basado en Skin::joints y la transformación global del Modelo será ignorada.
Nota: Si un modelo tiene tanto un esqueleto como una piel, entonces se utilizará la piel.
Véase también Qt Quick 3D - Simple Skinning Example.
source : url
Esta propiedad define la ubicación del archivo de malla que contiene la geometría de este Modelo o una de las mallas primitivas incorporadas que se enumeran a continuación como se describe en Mesh format and built-in primitives.
- "#Rectángulo"
- "Esfera
- "#Cubo"
- "Cono
- "Cilindro
texelsPerUnit : real [default: 0.0, since 6.10]
Un valor mayor que cero significa que este valor anulará el valor Lightmapper::texelsPerUnit para este modelo específico durante la cocción del lightmap.
Esta propiedad se introdujo en Qt 6.10.
Véase también Lightmapper::texelsPerUnit.
usedInBakedLighting : bool
Cuando esta propiedad está establecida a true, el modelo contribuye a la iluminación baked, como lightmaps, por ejemplo en forma de sombras proyectadas o luz indirecta. Este ajuste es independiente del control de la generación de lightmaps para el modelo, utilice bakedLightmap para ello.
El valor por defecto es false.
Nota: El valor por defecto es false, porque los diseñadores y desarrolladores siempre deben evaluar en cada modelo si el objeto es adecuado para participar en la iluminación baked.
Atención: Los modelos con propiedades que cambian dinámicamente, por ejemplo, posición animada, rotación u otras propiedades, no son adecuados para participar en la iluminación horneada.
Para más información sobre cómo bakear lightmaps, consulte la documentación de Lightmapper.
Esta propiedad sólo es relevante al bakear lightmaps. No tiene efecto después, cuando se utilizan los lightmaps generados durante el renderizado.
Ver también Light::bakeMode, bakedLightmap, Lightmapper, y Lightmaps and Global Illumination.
© 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.
