Back to Qt.io
Contact Us Blog Download Qt

Model QML Type

用于加载 3D 模型数据。更多

Import Statement: import QtQuick3D
Inherits:

Node

Inherited By:

XrHandModel

属性

详细说明

模型项可以加载网格，并通过添加材质来修改网格的着色方式。要渲染一个模型，至少需要一个网格和一个材质。

网格格式和内置基元

模型可以从存储空间中加载静态网格，也可以从内置基元类型中加载静态网格。所使用的网格格式是引擎原生的运行时格式，但通过资产导入工具Balsam 可以支持其他格式。

可通过将source 属性设置为以下值之一来加载内置基元：#Rectangle, #Sphere, #Cube, #Cylinder or #Cone 。

Model {
    source: "#Sphere"
}

自定义几何体

除了使用静态网格外，您还可以实现custom geometry 提供程序，在运行时为模型提供自定义顶点数据。有关如何在模型中创建和使用自定义材质的示例，请参阅自定义几何体示例。

材料

一个模型可以由多个子网格组成，每个子网格都可以有自己的材质。子网格使用materials 列表中与其索引相对应的材料。如果材料的数量少于子网格的数量，则列表中的最后一种材料将用于后续的子网格。子网格示例对此进行了演示。

您可以在模型项中使用以下材料：PrincipledMaterial,DefaultMaterial, 和CustomMaterial 。

拣选

选取是指从某个起始位置发送一条射线穿过场景，找出与射线相交的模型的过程。在Qt Quick 3D 中，射线通常使用触摸或鼠标事件产生的 2D 坐标从视图中发出。如果有模型被射线击中，pickResult ，并返回模型句柄和射线击中模型的位置信息。对于使用custom geometry 的模型，拾取的准确性不如静态网格数据，因为拾取只针对模型的bounding volume 。如果射线穿过不止一个模型，则会选择最接近的pickable 模型。

请注意，要使模型pickable ，其pickable 属性必须设置为true 。更多信息，请参阅Qt Quick 3D - 挑选示例。

属性文档

bakedLightmap : BakedLightmap

当此属性设置为一个有效的、已启用的BakedLightmap 对象时，模型将在烘焙光照时获得一个光照贴图，该光照贴图将被持久存储。渲染时，模型将加载并使用相关的光图。默认值为空。

注意： 如果要为模型生成持久存储的光照贴图，则必须同时设置烘焙光照贴图（bakedLightmap）和usedInBakedLighting ，以表明该模型不仅参与了光照贴图场景，还希望烘焙并存储完整的光照贴图。

有关如何烘焙光贴图的详细信息，请参阅Lightmapper 文档。

该属性在烘焙和使用光贴图时都很重要。烘焙运行和使用生成数据的后续运行之间保持一致的状态至关重要。例如，更改光贴图键将导致无法加载之前生成的数据。enabled 是一个例外，它可用于动态切换光照贴图的使用（在烘焙运行之外），但要注意渲染结果将取决于场景中光照的bakeMode 设置。

另请参阅 usedInBakedLighting 和Lightmapper 。


bounds : Bounds [read-only]

模型的边界描述了模型周围的边界体的范围。

注意： 如果需要先加载模型，则边界可能无法立即使用。


castsReflections : bool [since 6.4]

当此属性设置为true 时，模型将通过反射探针渲染，并可在反射中看到。

此属性在 Qt 6.4 中引入。


castsShadows : bool

当此属性为true 时，该模型的几何体将用于渲染阴影贴图，并在烘焙照明中生成阴影。

默认值为true 。


depthBias : real

保存模型的深度偏置。在对物体进行排序时，深度偏差会被添加到物体与摄像机的距离中。这可以用来强制相邻物体之间的渲染顺序，否则这些物体在不同帧中的渲染顺序可能会不同。负值会使排序值更靠近摄像机，而正值则会使排序值离摄像机更远。


geometry : Geometry

为模型指定自定义几何体。使用自定义几何体时，Model::source 必须为空。


instanceRoot : QtQuick3D::Node

该属性定义了实例坐标系的原点。

详细说明请参阅概述文档。

另请参阅 instancing 和Instancing 。


instancing : QtQuick3D::Instancing

如果设置了该属性，模型将无法正常渲染。相反，将按照实例表的定义渲染模型的多个实例。

另请参阅 Instancing 。


instancingLodMax : real

定义显示该模型实例时与摄像机的最大距离。用于实现细节层次。


instancingLodMin : real

定义显示此模型实例时与摄像机的最小距离。用于实现细节级别。


inverseBindPoses : List<matrix4x4>

该属性包含骨骼动画中使用的反向绑定姿势矩阵列表。每个 inverseBindPose 矩阵指的是skeleton 中相关Joint::index 全局变换的逆矩阵，最初将使用该矩阵。

注： 该属性仅在Model::skeleton 有效时使用。

注： 如果未设置某些矩阵，则将使用同一值。

另请参阅 Joint::index 。


levelOfDetailBias : real [since 6.5]

此属性可更改模型在渲染时需要的尺寸，然后才会使用自动细节网格。每个生成的细节层次网格都包含每个层次应显示的理想尺寸值，该值是渲染场景中该网格所占比例。在屏幕上只显示几个像素的模型不需要完整的几何图形就能看起来正确，因此在这种情况下会使用较低的细节网格。该值是理想值的一个偏差，如果该值小于1.0 ，则需要更小的渲染尺寸才能切换到较低的细节级别。高于1.0 的值将导致更快地使用较低级别的细节。如果值为0.0 ，则会完全禁止使用细节级别。

默认值为1.0

注意： 只有当模型的几何体包含细节级别时，此属性才会生效。

此属性在 Qt 6.5 中引入。

另请参阅 Camera::levelOfDetailBias 。


lightmapBaseResolution : int

定义此模型的光贴图的大致大小。默认值为 1024，表示基本尺寸为 1024x1024。光贴图纹理的实际大小可能会有所不同，通常会更大，这取决于网格。

对于较简单、较小的网格，或已知没有必要使用较大的光贴图时，可将该值设置为较小的值，例如 512 或 256。

最小值为 128。

该设置既适用于持久存储的光贴图，也适用于中间的部分光贴图。在制作光照贴图时，所有已启用usedInBakedLighting 的模型都是路径追踪场景的一部分。因此，所有这些模型都需要执行光照贴图 UV 解包和光栅化步骤，以计算直接光照，然后将其考虑到场景中的间接光反弹。不过，对于只贡献而不存储光照贴图的模型来说，默认值通常已经足够。对于存储并使用生成的光照贴图的模型来说，微调更为重要。

该属性只在制作光贴图时才有意义。之后，在渲染过程中使用生成的光贴图时，它不会产生任何影响。

在资产导入时已预先生成光贴图 UV 数据（如通过香脂工具）的模型将忽略此属性，因为光贴图 UV 展开和光贴图尺寸提示评估已经完成，在光贴图烘焙过程中不会再次执行。


materials : List<QtQuick3D::Material>

该属性包含用于渲染所提供几何体的材质列表。要渲染任何物体，必须至少有一种材质。通常情况下，源几何体中的每个子网格都应有一个材质。

另请参阅 Qt Quick 3D - 子网格示例。


morphTargets : List<QtQuick3D::MorphTarget>

此属性包含用于渲染所提供几何体的MorphTargets 列表。网格应在变形目标的位置、法线、切线、二轨迹、纹理坐标和顶点颜色中至少有一个属性。

另请参阅 MorphTarget 。


pickable : bool

此属性控制模型是否可拾取。将此属性设置为true 可使模型可拾取。默认情况下模型不可拾取。

另请参阅 View3D::pick 。


receivesReflections : bool

当此属性设置为true 时，模型的材料会从反射探针获得反射贡献。如果模型同时位于多个反射探针内，则会考虑最近的反射探针。


receivesShadows : bool

当此属性设置为true 时，模型的材质会考虑阴影投射灯的阴影贡献。

注： 当此模型启用光贴图时，无论此属性的值如何，Light::bakeMode 设置为 Light.BakeModeAll 的完全烘焙灯光将始终在模型上生成（烘焙）阴影。

默认值为true 。


skeleton : Skeleton

包含模型的骨架。骨架与inverseBindPoses 一起用于绘制皮肤。

注： 模型的网格必须同时具有关节和权重属性。

注： 如果设置了此属性，将启用蒙皮动画。这意味着Model 会根据Skeleton 进行变换，而忽略模型的全局变换。

另请参阅 Model::inverseBindPoses 和Qt Quick 3D - 简单蒙皮示例。


skin : Skin

包含模型的骨架。骨架用于蒙皮。

注： 模型的网格必须同时具有关节和权重属性。

注： 如果设置了该属性，将启用蒙皮动画。这意味着Model 将根据Skin::joints 进行变换，而模型的全局变换将被忽略。

注： 如果模型既有骨骼又有皮肤，则将使用皮肤。

另请参见 Qt Quick 3D - Simple Skinning Example.


source : url

此属性定义了包含此模型几何图形的网格文件的位置，或下面列出的内置原始网格之一，如Mesh format and built-in primitives 中所述。

  • "#矩形
  • "#Sphere
  • "#Cube
  • "#Cone" （#圆锥体
  • "#圆柱体

usedInBakedLighting : bool

当此属性设置为true 时，模型将以投射阴影或间接光等形式为烘焙光照（如光贴图）做出贡献。此设置与控制模型的光贴图生成无关，请使用bakedLightmap 。

默认值为false 。

注： 默认值为 false，因为设计人员和开发人员必须始终根据每个模型来评估对象是否适合参与烘焙光照。

警告： 具有动态变化属性（如动画位置、旋转或其他属性）的模型不适合参与烘焙光照。

有关如何烘焙光照贴图的更多信息，请参阅Lightmapper 文档。

该属性仅在烘焙光照贴图时有效。之后，在渲染过程中使用生成的光贴图时，它不会产生任何影响。

另请参阅 Light::bakeMode,bakedLightmap,Lightmapper 以及光贴图和全局光照。


© 2025 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.