Model QML Type
Te 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
- instancingLodFactor : real
(since 6.12) - 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 se pueda renderizar, necesita al menos una malla y un material.
Formato de malla y primitivas integradas
El modelo puede cargar mallas estáticas desde el almacenamiento o uno de los tipos de primitivas integradas. El formato de malla utilizado es un formato en tiempo de ejecución nativo del motor, pero se admiten formatos adicionales a través de la herramienta de importación de recursos Balsam.
Las primitivas integradas se pueden cargar estableciendo la propiedad « source » en uno de estos valores: « #Rectangle, #Sphere, #Cube, #Cylinder or #Cone ».
Model {
source: "#Sphere"
}La tabla siguiente describe las mallas integradas con más detalle.
| Nombre | Descripción | N.º de caras |
|---|---|---|
| #Cone | Un cono con una altura y un diámetro de 100. La base se encuentra en el origen y el cono apunta hacia arriba en la dirección y. | 78 |
| #Cubo | Un cubo centrado en el origen con aristas de 100 a lo largo de los ejes x, y y z. | 12 |
| #Cilindro | Un cilindro con una altura y un diámetro de 100, centrado en el origen y que se extiende a lo largo de la dirección y. | 316 |
| #Rectángulo | Un rectángulo con anchura y altur 100 es, centrado en el origen y situado en el plano xy. | 2 |
| #Esfera | Una esfera con un diámetro e 100, centrada en el origen. | 4900 |
Geometría personalizada
Además de utilizar mallas estáticas, puedes implementar un proveedor de « custom geometry » que proporcione al modelo datos de vértices personalizados en tiempo de ejecución. Consulta el ejemplo de geometría personalizada para ver cómo crear y utilizar un material personalizado con tu modelo.
Materiales
Un modelo puede estar formado por 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 las submallas, se utiliza el último material de la lista para las submallas siguientes. Esto se muestra en el ejemplo de submalla.
Puede utilizar los siguientes materiales con el elemento de modelo: PrincipledMaterial, DefaultMaterial y CustomMaterial.
Selección
La selección es el proceso de enviar un rayo a través de la escena desde una posición inicial para determinar qué modelos se cruzan con dicho rayo. En Qt Quick 3D, el rayo se envía normalmente desde la vista utilizando coordenadas 2D resultantes de un toque o de un evento del ratón. Si el rayo incide en un modelo, se devolverá un objeto ` pickResult ` con un identificador del modelo e información sobre el punto en el que el rayo incidió en él. En el caso de los modelos que utilizan ` custom geometry`, la selección es menos precisa que con los datos de malla estática, ya que solo se realiza en función de la ` bounding volume` del modelo. Si el rayo atraviesa más de un modelo, se selecciona el modelo más cercano con ` pickable `.
Ten en cuenta que, para que los modelos sean « pickable », su propiedad « pickable » debe estar establecida en « true ». Para obtener más información, consulta el ejemplo «Qt Quick 3D - Picking».
Documentación de propiedades
bakedLightmap : BakedLightmap
Cuando esta propiedad se establece en un objeto « BakedLightmap » válido y habilitado, el modelo obtendrá un mapa de luces generado al hornear la iluminación; a continuación, dicho mapa se almacena de forma persistente. Al renderizar, el modelo cargará y utilizará el mapa de luces asociado. El valor por defecto es «null».
Nota: Cuando se pretenda generar un mapa de luces almacenado de forma permanente para un modelo, deben establecerse en él tanto bakedLightmap como usedInBakedLighting, con el fin de indicar que el modelo no solo forma parte de la escena con mapa de luces, sino que también se desea que se genere y almacene un mapa de luces completo.
Para obtener más información sobre cómo hornear mapas de luz, consulta la documentación de « Lightmapper ».
Esta propiedad es relevante tanto al hornear como al utilizar mapas de luz. Es esencial que haya coherencia entre la ejecución de horneado y las ejecuciones posteriores que utilicen los datos generados. Por ejemplo, cambiar la clave del mapa de luces hará imposible cargar los datos generados previamente. Una excepción es enabled, que se puede utilizar para activar o desactivar dinámicamente el uso de mapas de luces (fuera de la ejecución de horneado), pero ten en cuenta que los resultados renderizados dependerán de la configuración de « bakeMode » de las luces en la escena.
Véase también usedInBakedLighting y Lightmapper.
bounds : Bounds [read-only]
Los límites del modelo describen la extensión del volumen delimitador que rodea al modelo.
Nota: Es posible quelos límites no estén disponibles de inmediato si es necesario cargar primero el modelo.
castsReflections : bool [since 6.4]
Cuando esta propiedad se establece en « true », el modelo se representa mediante sondas de reflexión y puede verse en los reflejos.
Esta propiedad se introdujo en Qt 6.4.
castsShadows : bool
Cuando esta propiedad tiene el valor « true », la geometría de este modelo se utiliza al renderizar los mapas de sombras y también se utilizan para generar sombras en la iluminación precalculada.
El valor por defecto es « true ».
depthBias : real
Almacena el sesgo de profundidad del modelo. El sesgo de profundidad se suma a la distancia del objeto respecto a la cámara a la hora de ordenar los objetos. Esto puede utilizarse para forzar el orden de renderizado entre objetos cercanos entre sí, que, de otro modo, podrían renderizarse en un orden diferente en distintos fotogramas. Los valores negativos hacen que el objeto se acerque a la cámara, mientras que los valores positivos lo alejan de ella.
geometry : Geometry
Especifica una geometría personalizada para el modelo. El archivo « Model::source » debe estar vacío cuando se utilice una geometría personalizada.
instanceRoot : QtQuick3D::Node
Esta propiedad define el origen del sistema de coordenadas de la instancia.
Consulta la documentación general para obtener una explicación detallada.
Véase también instancing y Instancing.
instancing : QtQuick3D::Instancing
Si se establece esta propiedad, el modelo no se representará de forma normal. En su lugar, se representarán varias instancias del modelo, tal y como se define en la tabla de instancias.
Véase también Instancing.
instancingLodFactor : real [default: 0.0, since 6.12]
Esta propiedad permite determinar manualmente el nivel de detalle (LOD) para niveles específicos de modelos instanciados.
En situaciones en las que una escena contiene varios niveles de LOD para tablas de instancias de gran tamaño, es necesario seleccionar manualmente el nivel de detalle más adecuado. Esto es necesario porque la gestión automática del LOD no puede calcular correctamente el detalle de las instancias individuales, ya que sus datos de transformación solo están disponibles durante la fase de renderizado de la GPU.
Para reducir la sobrecarga geométrica en niveles específicos de LOD, puedes especificar manualmente instancingLodFactor. Cuanto más se acerque el valor a 1.0, menos geometría se renderizará para el objeto. Un valor de 0.0 significa que toda la geometría se descargará o renderizará con todo el detalle.
Nota: Esta propiedad se utiliza específicamente para anular el cálculo automático del LOD cuando la proximidad de las instancias individuales a la cámara no está predeterminada.
Esta propiedad se introdujo en Qt 6.12.
Véase también levelOfDetailBias.
instancingLodMax : real
Define la distancia máxima a la que se muestra una instancia de este modelo desde la cámara. Se utiliza para la implementación del nivel de detalle.
instancingLodMin : real
Define la distancia mínima a la que se muestra una instancia de este modelo desde la cámara. Se utiliza para la implementación del nivel de detalle.
inverseBindPoses : List<matrix4x4>
Esta propiedad contiene una lista de matrices de «Inverse Bind Pose» utilizadas para la animación esquelética. Cada matriz «inverseBindPose» representa la inversa de la transformación global del « Joint::index » correspondiente en skeleton, que se utilizará inicialmente.
Nota: Esta propiedad solo se utiliza si el « Model::skeleton » es válido.
Nota: Si algunas de las matrices no están definidas, se utilizarán los valores de identidad.
Véase también « Joint::index ».
levelOfDetailBias : real [since 6.5]
Esta propiedad modifica el tamaño que debe tener el modelo al renderizarse antes de que se utilicen las mallas de nivel de detalle automáticas. Cada malla de nivel de detalle generada contiene un valor de tamaño ideal con el que debe mostrarse cada nivel, que representa la proporción de la escena renderizada que ocupará dicha malla. Un modelo que solo representa unos pocos píxeles en pantalla no necesitará toda la geometría para verse correctamente, por lo que, en este caso, se utilizará en su lugar una malla de menor nivel de detalle. Este valor es un sesgo respecto al valor ideal, de modo que un valor inferior a 1.0 requerirá un tamaño renderizado aún menor antes de pasar a un nivel de detalle inferior. Los valores superiores a 1.0 harán que se utilicen niveles de detalle más bajos antes. Un valor de 0.0 desactivará por completo el uso de los niveles de detalle.
El valor por defecto es 1.0
Nota: Esta propiedad solo surtirá efecto cuando la geometría del modelo contenga niveles de detalle.
Esta propiedad se introdujo en Qt 6.5.
Véase también Camera::levelOfDetailBias.
materials : List<QtQuick3D::Material>
Esta propiedad contiene una lista de los materiales utilizados para renderizar la geometría proporcionada. Para renderizar cualquier elemento, debe haber al menos un material. Normalmente, debería haber un material por cada submalla incluida en la geometría de origen.
Véase también «Qt Quick 3D - Ejemplo de submalla».
morphTargets : List<QtQuick3D::MorphTarget>
Esta propiedad contiene una lista de « MorphTarget» que se utilizan 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értices para los objetivos de morfo.
Véase también « MorphTarget ».
motionVectorEnabled : bool [default: true, since 6.11]
Especifica si el modelo participa en la pasada del vector de movimiento.
Cuando esta propiedad se establece en « true », el modelo aporta su información de movimiento al búfer de vectores de movimiento. Esto lo utilizan el antialiasing temporal (TAA) y otros efectos que se basan en datos de movimiento por píxel.
Cuando se establece en « false », el modelo queda excluido 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 que se aplica a los vectores de movimiento generados por el modelo.
Un valor de 1.0 conserva el movimiento real del modelo, mientras que los valores superiores a 1.0 exageran los vectores de movimiento y los valores inferiores a 1.0 los reducen. Esto puede resultar útil para crear efectos estilizados o ajustar con precisión el comportamiento visual en efectos que se basan en el 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 se puede seleccionar o no. Establece esta propiedad en « true » para que el modelo se pueda seleccionar. Por defecto, los modelos no se pueden seleccionar.
Véase también « View3D::pick ».
receivesReflections : bool
Cuando esta propiedad se establece en « true », los materiales del modelo recogen la contribución de los reflejos de una sonda de reflexión. Si el modelo se encuentra 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 se establece en « true », los materiales del modelo tienen en cuenta la contribución de las sombras de las luces que proyectan sombras.
Nota: Cuando el mapeado de luces está habilitado para este modelo, las luces totalmente horneadas con « Light::bakeMode » establecido en «Light.BakeModeAll» siempre generarán sombras (horneadas) sobre 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 tanto atributos de articulaciones como de pesos.
Nota: Si se establece esta propiedad, se habilita la animación de skinning. Esto significa que « Model » se transforma en función de « Skeleton », ignorando la transformación global del modelo.
Véase también « Model::inverseBindPoses » y «Qt Quick 3D - Ejemplo sencillo de skinning».
skin : Skin
Contiene el esqueleto del modelo. El esqueleto se utiliza para el skinning.
Nota: Las mallas del modelo deben tener tanto atributos de articulaciones como de pesos.
Nota: Si se establece esta propiedad, se habilita la animación de skinning. Esto significa que el « Model » se transformará en función de Skin::joints y se ignorará la transformación global del modelo.
Nota: Si un modelo tiene tanto un esqueleto como una piel, 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 de una de las mallas primitivas integradas que se enumeran a continuación, tal y como se describe en Mesh format and built-in primitives.
- «#Rectangle»
- «#Sphere»
- «#Cubo»
- «#Cono»
- «#Cylinder»
texelsPerUnit : real [default: 0.0, since 6.10]
Un valor superior a cero significa que este valor anulará el valor de « Lightmapper::texelsPerUnit » para este modelo concreto durante el proceso de «lightmap baking».
Esta propiedad se introdujo en Qt 6.10.
Véase también « Lightmapper::texelsPerUnit ».
usedInBakedLighting : bool
Cuando esta propiedad se establece en « true », el modelo contribuye a la iluminación precalculada, como los mapas de luz, por ejemplo, en forma de sombras proyectadas o luz indirecta. Este ajuste es independiente del control de la generación de mapas de luz para el modelo; para ello, utiliza « bakedLightmap ».
El valor por defecto es « false ».
Nota: El valor por defecto es «false», ya que los diseñadores y desarrolladores deben evaluar siempre, modelo por modelo, si el objeto es adecuado para formar parte de la iluminación precalculada.
Advertencia: 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 obtener más información sobre cómo hornear mapas de luz, consulta la documentación de Lightmapper.
Esta propiedad solo es relevante al hornear mapas de luz. No tiene ningún efecto posteriormente, cuando se utilizan los mapas de luz generados durante el renderizado.
Véase también Light::bakeMode, bakedLightmap, Lightmapper y «Lightmaps y la iluminación global».
© 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.