Lets you load a 3D model data. 更多...
| import 语句： | import QtQuick3D |
| 继承： | Node |
The Model item makes it possible to load a mesh and modify how its shaded, by adding materials to it. For a model to be renderable, it needs at least a mesh and a material.
The model can load static meshes from storage or one of the built-in primitive types. The mesh format used is a run-time format that's native to the engine, but additional formats are supported through the asset import tool Balsam .
The built-in primitives can be loaded by setting the
source
property to one of these values:
#Rectangle, #Sphere, #Cube, #Cylinder or #Cone
.
Model { source: "#Sphere" }
In addition to using static meshes, it is possible to implement a custom geometry provider that provides the model with custom vertex data at run-time. See the Custom Geometry Example for an example on how to create and use a custom material with your model.
A model can consist of several sub-meshes, each of which can have its own material. The sub-mesh uses a material from the materials list, corresponding to its index. If the number of materials is less than the sub-meshes, the last material in the list is used for subsequent sub-meshes. This is demonstrated in the Sub-mesh example .
There are currently three different materials that can be used with the model item, the PrincipledMaterial ， DefaultMaterial ，和 CustomMaterial .
Picking is the process of sending a ray through the scene from some starting position to find which model(s) intersects with the ray. In QtQuick3D the ray is normally sent from the view using 2D coordinates resulting from a touch or mouse event. If a model was hit by the ray a PickResult will be returned with a handle to the model and information about where the ray hit the model. For models that use custom geometry the picking is less accurate then for static mesh data, as picking is only done against the models bounding volume . If the ray goes through more then one model, the closest pickable model is selected.
Note that models are not pickable by default, so to be able to pick a model in the scene, the model will need to make it self discoverable by setting the pickable property to true. Visit the Qt Quick 3D - 拾取范例 to see how picking can be enabled.
|
bakedLightmap : BakedLightmap |
When this property is set to a valid, enabled BakedLightmap object, the model will get a lightmap generated when baking lighting, the lightmap is then stored persistently. When rendering, the model will load and use the associated lightmap. The default value is null.
注意： When the intention is to generate a persistently stored lightmap for a Model, both bakedLightmap and usedInBakedLighting must be set on it, in order to indicate that the Model not only participates in the lightmapped scene, but also wants a full lightmap to be baked and stored.
For more information on how to bake lightmaps, see the Lightmapper 文档编制。
This property is relevant both when baking and when using lightmaps. A consistent state between the baking run and the subsequent runs that use the generated data is essential. For example, changing the lightmap key will make it impossible to load the previously generated data. An exception is enabled , which can be used to dynamically toggle the usage of lightmaps (outside of the baking run), but be aware that the rendered results will depend on the Lights' bakeMode settings in the scene.
另请参阅 usedInBakedLighting and Lightmapper .
|
[read-only] bounds : Bounds |
The bounds of the model descibes the extents of the bounding volume around the model.
注意： The bounds might not be immediately available if the model needs to be loaded first.
|
[since 6.4] castsReflections : bool |
当此特性被设为
true
, the model is rendered by reflection probes and can be seen in the reflections.
该特性在 Qt 6.4 引入。
|
castsShadows : bool |
When this property is
true
, the geometry of this model is used when rendering to the shadow maps, and is also generating shadows in baked lighting.
默认值为
true
.
|
depthBias : real |
Holds the depth bias of the model. Depth bias is added to the object distance from camera when sorting objects. This can be used to force rendering order between objects close to each other, that might otherwise be rendered in different order in different frames. Negative values cause the sorting value to move closer to the camera while positive values move it further from the camera.
|
geometry : 几何体 |
Specify a custom geometry for the model. The Model::source must be empty when custom geometry is used.
|
instanceRoot : QtQuick3D::Node |
This property defines the origin of the instance’s coordinate system.
见 overview documentation for a detailed explanation.
另请参阅 instancing and Instancing .
|
instancing : QtQuick3D::Instancing |
If this property is set, the model will not be rendered normally. Instead, a number of instances of the model will be rendered, as defined by the instance table.
另请参阅 Instancing .
|
instancingLodMax : real |
Defines the maximum distance from camera that an instance of this model is shown. Used for a level of detail implementation.
|
instancingLodMin : real |
Defines the minimum distance from camera that an instance of this model is shown. Used for a level of detail implementation.
|
inverseBindPoses : List < matrix4x4 > |
This property contains a list of Inverse Bind Pose matrixes used for the skeletal animation. Each inverseBindPose matrix means the inverse of the global transform of the repective Joint::index in skeleton , which will be used initially.
注意： This property is only used if the Model::skeleton is valid.
注意： If some of the matrices are not set, identity values will be used.
另请参阅 Joint::index .
|
[since 6.5] levelOfDetailBias : real |
This property changes the size the model needs to be when rendered before the automatic level of detail meshes are used. Each generated level of detail mesh contains an ideal size value that each level should be shown, which is a ratio of how much of the rendered scene will be that mesh. A model that represents only a few pixels on screen will not require the full geometry to look correct, so a lower level of detail mesh will be used instead in this case. This value is a bias to the ideal value such that a value smaller than
1.0
will require an even smaller rendered size before switching to a lesser level of detail. Values above
1.0
will lead to lower levels of detail being used sooner. A value of
0.0
will disable the usage of levels of detail completely.
默认值为
1.0
注意： This property will only have an effect when the Model's geometry contains levels of detail.
该特性在 Qt 6.5 引入。
另请参阅 Camera::levelOfDetailBias .
|
lightmapBaseResolution : int |
Defines the approximate size of the lightmap for this model. The default value is 1024, indicating 1024x1024 as the base size. The actual size of the lightmap texture is likely to be different, often bigger, depending on the mesh.
For simpler, smaller meshes, or when it is known that using a bigger lightmap is unnecessary, the value can be set to something smaller, for example, 512 or 256.
The minimum value is 128.
This setting applies both to persistently stored and for intermediate, partial lightmaps. When baking lightmaps, all models that have usedInBakedLighting enabled are part of the path-traced scene. Thus all of them need to have lightmap UV unwrapping performed and the rasterization steps necessary to compute direct lighting which then can be taken into account for indirect light bounces in the scene. However, for models that just contribute to, but do not store a lightmap the default value is often sufficient. Fine-tuning is more relevant for models that store and then use the generated lightmaps.
This property is relevant only when baking lightmaps. It has no effect afterwards, when using the generated lightmaps during rendering.
Models that have lightmap UV data pre-generated during asset import time (e.g. via the balsam tool) will ignore this property because the lightmap UV unwrapping and the lightmap size hint evaluation have already been done, and will not be performed again during lightmap baking.
|
materials : List < QtQuick3D::Material > |
This property contains a list of materials used to render the provided geometry. To render anything, there must be at least one material. Normally there should be one material for each sub-mesh included in the source geometry.
另请参阅 Qt Quick 3D - 子网格范例 .
|
morphTargets : List < QtQuick3D::MorphTarget > |
This property contains a list of MorphTarget s used to render the provided geometry. Meshes should have at least one attribute among positions, normals, tangent, bitangent for the morph targets. Quick3D supports maximum 8 morph targets and remains will be ignored.
注意： First 2 morph targets can have maximum 4 attributes among position, normal, tangent, and binormal.
注意： 3rd and 4th morph targets can have maximum 2 attributes among position, and normal.
注意： Remaining morph targets can have only the position attribute.
注意： This property is not used when the model is shaded by CustomMaterial .
另请参阅 MorphTarget .
|
pickable : bool |
This property controls whether the model is pickable or not. Set this property to
true
to make the model pickable. Models are not pickable by default.
另请参阅 View3D::pick .
|
receivesReflections : bool |
当此特性被设为
true
, the model's materials take reflections contribution from a reflection probe. If the model is inside more than one reflection probe at the same time, the nearest reflection probe is taken into account.
|
receivesShadows : bool |
当此特性被设为
true
, the model's materials take shadow contribution from shadow casting lights into account.
注意： When lightmapping is enabled for this model, fully baked lights with Light::bakeMode set to Light.BakeModeAll will always generate (baked) shadows on the model, regardless of the value of this property.
默认值为
true
.
|
skeleton : Skeleton |
Contains the skeleton for the model. The Skeleton is used together with inverseBindPoses for skinning .
注意： Meshes of the model must have both joints and weights attributes.
注意： If this property is set, skinning animation is enabled. It means that Model is transformed based on Skeleton ignoring Model's global transformation.
另请参阅 Model::inverseBindPoses and Qt Quick 3D - 简单蒙皮范例 .
|
skin : Skin |
Contains the skeleton for the model. The Skeleton is used for skinning .
注意： Meshes of the model must have both joints and weights attributes.
注意： If this property is set, skinning animation is enabled. This means the Model will be transformed based on Skin::joints and the Model's global transformation will be ignored.
注意： If a model has both a skeleton and a skin, then the skin will be used.
另请参阅 Qt Quick 3D - 简单蒙皮范例 .
|
source : url |
This property defines the location of the mesh file containing the geometry of this Model or one of the built-in primitive meshes listed below as described in Mesh format and built-in primitives .
|
usedInBakedLighting : bool |
当此特性被设为
true
, the model contributes to baked lighting, such as lightmaps, for example in form of casting shadows or indirect light. This setting is independent of controlling lightmap generation for the model, use
bakedLightmap
for that.
默认值为
false
.
注意： The default value is false, because designers and developers must always evaluate on a per-model basis if the object is suitable to take part in baked lighting.
警告： Models with dynamically changing properties, for example, animated position, rotation, or other properties, are not suitable for participating in baked lighting.
For more information on how to bake lightmaps, see the Lightmapper 文档编制。
This property is relevant only when baking lightmaps. It has no effect afterwards, when using the generated lightmaps during rendering.
另请参阅 Light::bakeMode , bakedLightmap , Lightmapper ，和 Lightmaps and Global Illumination .
