模型 QML 类型

允许加载 3D 模型数据。 更多...

导入语句import QtQuick3D
继承了

Node

属性

详细描述

Model 项目允许通过添加材料来加载网格并修改其着色方式。为了使模型可渲染，它至少需要一个网格和一个材料。

网格格式和内置原语

模型可以从存储或内置的原始类型中加载静态网格。使用的网格格式是引擎的原生运行时格式，但可以通过资产导入工具Balsam支持额外的格式。

内置原始类型可以通过将source属性设置为以下值之一来加载： #Rectangle, #Sphere, #Cube, #Cylinder 或 #Cone。

Model {
    source: "#Sphere"
}

自定义几何形状

除了使用静态网格外，你还可以实现一个自定义几何体提供者，在运行时为模型提供自定义顶点数据。请参阅自定义几何体示例，了解如何创建和使用自定义材质。

材质

模型可以由多个子网格组成，每个子网格都可以有自己的材质。子网格使用材质列表中的一个材质，对应其索引。如果材质数量少于子网格数量，则使用列表中的最后一个材质。在子网格示例中演示了这一点。

你可以使用以下材质与模型项一起使用：PrincipledMaterial，DefaultMaterial，和CustomMaterial。

拾取

拾取是指从一个起始位置通过场景发送射线，以找到哪些模型与射线相交的过程。在Qt Quick 3D中，射线通常使用触摸或鼠标事件产生的2D坐标从视图发送。如果模型被射线击中，将返回包含模型句柄和射线击中模型位置信息的PickResult。对于使用自定义几何体的模型，由于拾取仅针对模型的边界体积执行，因此其拾取精度不如静态网格数据。如果射线穿过多个模型，则选择最接近的可拾取模型。

请注意，要使模型可拾取，其可拾取属性必须设置为true。有关更多信息，请参阅Qt Quick 3D - 拾取示例。

属性文档

bakedLightmap : BakedLightmap

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

注意：如果打算为模型生成持久存储的光图，则必须在其中设置bakedLightmap和usedInBakedLighting，以便指示模型不仅参与光图场景，还希望完全烘焙并存储光图。

有关生成光图的更多信息，请参阅Lightmapper文档。

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

另请参阅：usedInBakedLighting和Lightmapper。


bounds : Bounds [只读]

模型的边界描述了围绕模型的边界体积的延伸。

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


castsReflections : bool [自 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>

此属性包含用于骨骼动画的逆绑定姿势矩阵列表。每个逆绑定姿势矩阵表示在skeleton中的相应Joint::index的全局变换的逆，最初将被使用。

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

注意： 如果某些矩阵没有设置，将使用单位值。

另请参阅 Joint::index。


levelOfDetailBias : real [自 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 数据的模型（例如，通过 balsam 工具）将忽略此属性，因为照明图 UV 展平和照明图大小提示评估已经完成，并且不会在照明图烘焙期间再次执行。


materials : List<QtQuick3D::Material>

此属性包含用于渲染提供几何形状的材料的列表。为了渲染任何内容，至少必须有一个材料。通常对于每个包含在源几何体中的子网格都应该有一个材料。

参见 Qt Quick 3D - 子网格示例。


morphTargets : List<QtQuick3D::MorphTarget>

此属性包含用于渲染提供几何形状的 MorphTarget 列表。网格应该至少包含位置、法线、切线、双法线、纹理坐标和顶点颜色中的至少一个属性以供形态目标使用。

参见 MorphTarget。


pickable : bool

此属性控制模型是否可选择。将此属性设置为 true 以使模型可选择。模型默认不可选择。

参见 View3D::pick。


receivesReflections : bool

当此属性设置为 true 时，模型的材料从反射探针取反光贡献。如果模型同时包含多个反射探针，则考虑最近的反射探针。


receivesShadows : bool

当此属性设置为 true 时，模型的材料考虑从投射阴影的光源处的阴影贡献。

注意： 当启用此模型的光照贴图时，将使用 Light::bakeMode 设置为 Light.BakeModeAll 的完全烘焙的光以产生（烘焙）阴影，无论此属性的值如何。

默认值是true。


skeleton : Skeleton

包含模型的骨骼。骨骼与 inverseBindPoses 一起用于 皮肤变形。

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

注意： 如果设置此属性，则启用皮肤变形动画。这意味着 Model 基于骨架进行转换，忽略模型的全局转换。

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


skin : Skin

包含模型的骨骼。骨骼用于 皮肤变形。

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

注意： 如果设置此属性，则启用皮肤变形动画。这意味着将根据 Skin::joints 和模型的全局转换对 Model 进行转换，忽略模型的全局转换。

注意： 如果有骨骼和皮肤，则使用皮肤。

另请参阅 Qt Quick 3D - 简单皮肤变形示例。


source : url

此属性定义了包含此模型或以下列出的内建原始网格（如描述所述 网格格式和内建原始网格）几何形状的网格文件的地址。

  • "#Rectangle"
  • "#Sphere"
  • "#Cube"
  • "#Cone"
  • "#Cylinder"

usedInBakedLighting : bool

当此属性设置为 true 时，模型对烘焙光照的贡献，例如光照贴图，例如通过投射阴影或间接光照。此设置独立于控制模型光照贴图生成的控制，请使用 bakedLightmap 进行设置。

默认值为 false。

注意： 默认值为 false，因为设计师和开发者必须始终根据模型评估是否适合参与烘焙光照。

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

有关生成光图的更多信息，请参阅Lightmapper文档。

仅当烘焙照明图时，此属性才相关。在渲染时使用生成的照明图之后，它没有作用。

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


© 2024 Qt 公司有限。此处包括的文档贡献是相应所有者的版权。此处提供的文档根据自由软件基金会发布的 GNU 自由文档许可版本 1.3 的条款进行许可。Qt 和相应的标志是芬兰以及/或其他国家/地区的 Qt 公司的商标。所有其他商标都是其所有者财产。