Model QML Type | Qt Quick 3D 6.1.3

- Qt 6.1
- Qt Quick 3D
- QML Types
- Model QML Type
- Qt 6.1.3 Reference Documentation

# Model QML Type

Lets you load a 3D model data. More...

Import Statement: | import QtQuick3D .
Inherits: | Node

- List of all members, including inherited members

## Properties

- bounds : Bounds
- castsShadows : bool
- geometry : Geometry
- instanceRoot : QtQuick3D::Node
- instancing : QtQuick3D::Instancing
- inverseBindPoses : List<matrix4x4>
- materials : List<QtQuick3D::Material>
- morphTargets : List<QtQuick3D::MorphTarget>
- pickable : bool
- receivesShadows : bool
- skeleton : Skeleton
- source : url

## Detailed Description

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.

## Mesh format and built-in primitives

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

### Custom geometry

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.

## Materials

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, the DefaultMaterial, and the CustomMaterial.

## Picking

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 - Picking example to see how picking can be enabled.

## Property Documentation

[read-only] bounds : Bounds

The bounds of the model descibes the extents of the bounding volume around the model.

Note: The bounds might not be immediately available if the model needs to be loaded first.

castsShadows : bool

When this property is `true`, the geometry of this model is used when rendering to the shadow maps.

geometry : 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.

See the overview documentation for a detailed explanation.

See also 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.

See also Instancing.

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.

Note: This property is only used if the Model::skeleton is valid.

Note: If some of the matrices are not set, identity values will be used.

See also Joint::index.

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.

See also Qt Quick 3D - Sub-mesh Example.

morphTargets : List<QtQuick3D::MorphTarget>

This property contains a list of MorphTargets 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.

Note: First 2 morph targets can have maximum 4 attributes among position, normal, tangent, and binormal.

Note: 3rd and 4th morph targets can have maximum 2 attributes among position, and normal.

Note: Remaining morph targets can have only the position attribute.

Note: This property is not used when the model is shaded by CustomMaterial.

See also 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.

See also View3D::pick.

receivesShadows : bool

When this property is set to `true`, the model's materials take shadow contribution from shadow casting lights into account.

skeleton : Skeleton

Contains the skeleton for the model. The Skeleton is used together with inverseBindPoses for skinning.

Note: Meshes of the model must have both joints and weights attributes.

Note: If this property is set, skinning animation is enabled. It means that Model is transformed based on Skeleton ignoring Model's global transformation.

See also Model::inverseBindPoses and Qt Quick 3D - Simple Skinning Example.

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.

- "#Rectangle"
- "#Sphere"
- "#Cube"
- "#Cone"
- "#Cylinder"