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"
}

下表详细介绍了这些内置网格。

名称描述面数
#Cone一个高为100 、直径为 的圆锥体。底面位于原点，圆锥体沿y方向向上延伸。78
#Cube一个以原点为中心的立方体，沿x、y和z方向的边长均为100 。12
#圆柱体一个以原点为中心、高和直径均为100 、沿y方向扩展的圆柱体。316
#矩形一个宽高均为100 、以原点为中心、位于xy平面上的矩形。2
#球体一个直径为100 、以原点为中心的球体。4900

自定义几何体

除了使用静态网格体外，您还可以实现一个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 对象时，模型将在烘焙灯光时生成一张光照贴图，该光照贴图随后将被持久化存储。渲染时，模型将加载并使用关联的光照贴图。默认值为null。

注意：若 要为模型生成并持久存储光照贴图，必须同时为其设置 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 。

instancingLodFactor : real [default: 0.0, since 6.12]

此属性允许手动确定特定实例化模型级别的细节级别（LOD）。

当场景中包含大型实例表的多个 LOD 级别时，需要手动选择最合适的细节级别。之所以需要这样做，是因为自动 LOD 管理无法正确计算单个实例的细节，因为其变换数据仅在 GPU 渲染阶段才会可用。

为了减少特定 LOD 级别的几何体开销，您可以手动指定instancingLodFactor 。该值越接近1.0 ，对象渲染的几何体就越少。值为0.0 表示整个几何体将以全细节级别进行卸载/渲染。

注意： 当单个实例与摄像机的距离未预先确定时，此 属性专门用于覆盖自动 LOD 计算。

该属性在 Qt 6.12 中引入。

另请参阅 levelOfDetailBias 。

instancingLodMax : real

定义了该模型实例在相机可见范围内的最大距离。用于细节等级的实现。

instancingLodMin : real

定义了该模型实例在何种距离下才会显示（以相机为基准）。用于细节等级的实现。

inverseBindPoses : List<matrix4x4>

该属性包含用于骨骼动画的一组“反向绑定姿势”矩阵。每个“反向绑定姿势”矩阵代表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 。

materials : List<QtQuick3D::Material>

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

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

morphTargets : List<QtQuick3D::MorphTarget>

该属性包含用于渲染所提供几何体的MorphTarget数组。对于变形目标，网格应至少具有以下属性之一：位置、法线、切线、副法线、纹理坐标或顶点颜色。

另请参阅 MorphTarget 。

motionVectorEnabled : bool [default: true, since 6.11]

指定该模型是否参与运动向量处理阶段。

当此属性设置为true 时，模型会将其运动信息贡献给运动向量缓冲区。这将用于基于像素级运动数据的时间抗锯齿（TAA）及其他特效。

当设置为false 时，该模型将被排除在运动向量生成之外。

该属性自 Qt 6.11 起引入。

另请参阅 Model::motionVectorScale 。

motionVectorScale : real [default: 1.0, since 6.11]

指定应用于模型生成的运动向量的缩放因子。

当值为1.0 时，将保留模型的实际运动；大于1.0 的值会放大运动向量，而小于1.0 的值则会缩小运动向量。这对于制作风格化效果，或在依赖运动向量缓冲区的特效中微调视觉行为非常有用。

该属性在 Qt 6.11 中引入。

另请参阅 Model::motionVectorEnabled 。

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 。

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

texelsPerUnit : real [default: 0.0, since 6.10]

大于零的数值表示在光照贴图烘焙过程中，该数值将覆盖此特定模型的Lightmapper::texelsPerUnit 值。

该属性在 Qt 6.10 中引入。

另请参阅 Lightmapper::texelsPerUnit 。

usedInBakedLighting : bool

当此属性设置为“true ”时，模型会参与烘焙光照（如光照贴图）的生成，例如以投射阴影或间接光的形式。此设置与控制模型光照贴图的生成相互独立，如需控制光照贴图生成，请使用“bakedLightmap ”。

默认值为false 。

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

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

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

此属性仅在烘焙光照贴图时有效。之后在渲染过程中使用生成的光照贴图时，它将不起作用。

另请参阅 Light::bakeMode 、bakedLightmap 、Lightmapper 以及《光照贴图与全局光照》。

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