Qt6 QML Book/Qt Quick 3D/基础知识

The Basics

基础知识

In this section we will walk through the basics of Qt Quick 3D. This includes working with the built in shapes (meshes), using lights, and transformations in 3D.

在本节中，我们将介绍Qt Quick 3D的基础知识。这包括使用内置形状（网格）、使用灯光和三维变换。

A Basic Scene

基本场景

A 3D scene consists of a few standard elements:

3D场景由几个标准元素组成：

• View3D, which is the top level QML element representing the entire 3D scene.
• View3D，它是表示整个3D场景的顶级QML元素。
• SceneEnvironment, controls how the scene is rendered, including how the background, or sky box, is rendered.
• 场景环境（SceneEnvironment）控制场景的渲染方式，包括背景或天空框的渲染方式。
• PerspectiveCamera, the camera in the scene. Can also be a OrthographicCamera, or even a custom camera with a custom projection matrix.
• 透视摄像机，场景中的摄像机。也可以是正交摄像机，甚至可以是具有自定义投影矩阵的自定义摄像机。

In addition to this, the scene usually contains Model instances representing objects in the 3D space, and lights.

除此之外，场景通常包含表示三维空间中对象的模型实例和灯光。

We will look at how these elements interact by creating the scene shown below.

我们将通过创建如下所示的场景来了解这些元素是如何相互作用的。

 

First of all, the QML code is setup with a View3D as the main element, filling the window. We also import the QtQuick3D module.

首先，QML代码以View3D作为主要元素进行设置，填充窗口。我们还导入了QtQuick3D模块。

The View3D element can be seen as any other Qt Quick element, just that inside of it, the 3D contents will be rendered.

View3D元素可以被视为任何其他Qt Quick元素，只是在其中，3D内容将被渲染。

import QtQuick
import QtQuick3D

Window {
    width: 640
    height: 480
    visible: true
    title: qsTr("Basic Scene")

    View3D {
        anchors.fill: parent

        // ...
    
    }
}

Then we setup the SceneEnvironment with a solid background colour. This is done inside the View3D element.

然后我们用纯色背景设置场景环境。这是在View3D元素内完成的。

environment: SceneEnvironment {
    clearColor: "#222222"
    backgroundMode: SceneEnvironment.Color
}

The SceneEnvironment can be used to control a lot more rendering parameters, but for now, we only use it to set a solid background colour.

SceneEnvironment可以用来控制更多的渲染参数，但目前，我们只使用它来设置纯色背景。

The next step is to add meshes to the scene. A mesh represents an object in 3D space. Each mesh is created using a Model QML element.

下一步是将网格添加到场景中。网格表示三维空间中的对象。每个网格都是使用Model QML元素创建的。

A model can be used to load 3D assets, but there are a few built-in meshes allowing us to get started without involving the complexity of 3D assets management. In the code below, we create a #Cone and a #Sphere.

可以使用模型加载三维资产，但有一些内置网格允许我们在不涉及三维资产管理复杂性的情况下开始。在下面的代码中，我们创建了一个#圆锥体和一个#球体。

In addition to the shape of the mesh, we position them in 3D space and provide them with a material with a simple, diffuse base colour. We will discuss materials more in the [Materials and Light]("Materials and Lights") section

除了网格的形状外，我们还将其放置在3D空间中，并为其提供具有简单漫反射基色的材质。我们将在[materials and Light]（“materials and Lights”）一节中详细讨论材料

When positioning elements in 3D space, coordinates are expressed as Qt.vector3d(x, y, z) where the x axis controls the horizontal movement, y is the vertical movement, and z the how close or far away something is.

在三维空间中定位元素时，坐标表示为Qt.vector3d(x, y, z)，其中x轴控制水平运动，y是垂直运动，z是距离物体的距离。

By default, the positive direction of the x axis is to the right, positive y points upwards, and positive z out of the screen. I say default, because this depends on the projection matrix of the camera.

默认情况下，x轴的正方向向右，正y向上，正z出屏幕。我说默认值，因为这取决于摄像机的投影矩阵。

Model {
    position: Qt.vector3d(0, 0, 0)
    scale: Qt.vector3d(1, 1.25, 1)
    source: "#Cone"
    materials: [ PrincipledMaterial { baseColor: "yellow"; } ]
}

Model {
    position: Qt.vector3d(80, 0, 50)
    source: "#Sphere"
    materials: [ PrincipledMaterial { baseColor: "green"; } ]
}

Once we have lights in the scene we add a DirectionalLight, which is a light that works much like the sun. It adds an even light in a pre-determined direction. The direction is controlled using the eulerRotation property where we can rotate the light direction around the various axes.

一旦我们在场景中有了灯光，我们就添加了一个DirectionalLight，这是一种工作原理很像太阳的灯光。它在预先确定的方向上添加均匀光。方向是使用eulerRotation属性控制的，在该属性中，我们可以围绕各种轴旋转灯光方向。

By setting the castsShadow property to true we ensure that the light generates shadows as can be seen on cone, where the shadow from the sphere is visible.

通过将castsShadow属性设置为true，我们可以确保灯光生成可以在圆锥体上看到的阴影，在圆锥体上可以看到来自球体的阴影。

DirectionalLight {
    eulerRotation.x: -20
    eulerRotation.y: 110

    castsShadow: true
}

The last piece of the puzzle is to add a camera to the scene. There are various cameras for various perspectives, but for a realistic projection, the ProjectionCamera is the one to use.

最后一个难题是在场景中添加一个摄像机。有各种各样的摄像机用于不同的视角，但对于真实的投影，可以使用ProjectionCamera。

In the code, we place the camera using the position property. It is then possible to direct the camera using the eulerRotation property, but instead we call the lookAt method from the Component.onCompleted signal handler. This rotates the camera to look at a specific direction once it has been created and initialized.

在代码中，我们使用位置position属性放置相机。然后可以使用eulerRotation属性引导摄像机，但我们从Component.onCompleted信号处理器中调用lookAt方法。一旦相机被创建和初始化，它就会旋转相机以查看特定方向。

PerspectiveCamera {
    position: Qt.vector3d(0, 200, 300)
    Component.onCompleted: lookAt(Qt.vector3d(0, 0, 0))
}

The resulting scene can be seen below.

由此产生的场景如下所示。

 So, all in all, a minimal scene consists of a View3D with an SceneEnvironment, something to look at, e.g. a Model with a mesh, a light source, e.g. a DirectionalLight, and something to look with, e.g. a PerspectiveCamera.

因此，总而言之，一个最小的场景包括一个具有场景环境的View3D，一个可以观看的物体，例如一个带有网格的模型，一个光源，例如定向光，以及一个可以观看的物体，例如透视相机。

The Built-in Meshes

内置网格

In the previous example, we used the built-in cone and sphere. Qt Quick 3D comes with the following built in meshes:

在上一个示例中，我们使用了内置的圆锥体和球体。Qt Quick 3D附带以下内置网格：

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

These are all shown in the illustration below. (top-left: Cube, top-right: Cone, center: Sphere, bottom-left: Cylinder, bottom-right: Rectangle)

这些都显示在下图中。（左上：立方体，右上：圆锥体，中心：球体，左下：圆柱体，右下：矩形）

 

Tip

注

One caveat is that the #Rectangle is one-sided. That means that it is only visible from one direction. This means that the eulerRotation property is important.

When working with real scenes, the meshes are exported from a design tool and then imported into the Qt Quick 3D scene. We look at this in more detail in the Working with Assets section.

​
需要注意的是#矩形是单面的。这意味着它只能从一个方向看到。这意味着eulerRotation属性很重要。
使用真实场景时，网格从设计工具导出，然后导入到Qt Quick 3D场景中。我们将在“使用资产”一节中详细介绍这一点。
​

Lights

​​​​​​​灯光

Just as with meshes, Qt Quick 3D comes with a number of pre-defined light sources. These are used to light the scene in different ways.

与网格一样，Qt Quick 3D也提供了许多预定义的光源。这些用于以不同的方式照亮场景。

The first one, DirectionalLight, should be familiar from our previous example. It works much as the sun, and casts light uniformly over the scene in a given direction. If the castsShadow property is set to true, the light will cast shadows, as shown in the illustration below. This property is available for all the light sources.

第一个是DirectionalLight，应该与我们前面的示例很熟悉。它的工作原理类似于太阳，并以给定的方向在场景上均匀投射灯光。如果castsShadow属性设置为true，则灯光将投射阴影，如下图所示。此属性适用于所有光源。

 

DirectionalLight {
    eulerRotation.x: 210
    eulerRotation.y: 20

    castsShadow: true
}

The next light source is the PointLight. It is a light that eminates from a given point in space and then falls off towards darkness based on the values of the constantFade, linearFade, and quadraticFace properties, where the light is calculated as constantFade + distance * (linearFade * 0.01) + distance^2 * (quadraticFade * 0.0001). The default values are 1.0 constant and quadratic fade, and 0.0 for the linear fade, meaning that the light falls off according to the inverse square law.

下一个光源是点光源。它是一种灯光，从空间中的给定点突出，然后根据constantFade、linearFade和SquadicFace属性的值向黑暗方向下降，其中灯光计算为constantFade+距离*（linearFade*0.01）+距离平方*（SquadicFade*0.0001）。默认值为1.0常数和二次衰减，线性衰减为0.0，这意味着灯光根据平方反比定律衰减。

 

PointLight {
    position: Qt.vector3d(100, 100, 150)

    castsShadow: true
}

The last of the light sources is the SpotLight which emits a cone of light in a given direction, much like a real world spotlight. The cone consists of an inner and an outer cone. The width of these is controlled by the innerConeAngle and coneAngle, specified in degrees between zero and 180 degrees.

最后一个光源是聚光灯，它在给定方向上发射一个光锥，很像真实世界的聚光灯。锥由内锥和外锥组成。其宽度由内锥角和锥角控制，以0到180度之间的角度指定。

The light in the inner cone behaves much like a PointLight and can be controlled using the constantFade, linearFade, and quadraticFace properties. In addition to this, the light fades towards darkness as it approaches the outer cone, controlled by the coneAngle.

内锥中的灯光的行为很像点光源，可以使用constantFade、linearFade和SquadicFace属性进行控制。除此之外，当光线接近由锥角控制的外锥时，光线会逐渐变暗。

 

SpotLight {
    position: Qt.vector3d(50, 200, 50)
    eulerRotation.x: -90

    brightness: 5
    ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)

    castsShadow: true
}

In addition to the castsShadow property, all lights also has the commonly used properties color and brightness which control the color and intensity of the light emitted. The lights also has an ambientColor property defining a base color to be applied to materials, before they are lit by the light source. This property is set to black by default, but can be used to provide a base lighting in a scene.

除了castsShadow属性外，所有灯光还具有常用的属性颜色和亮度，用于控制发射光的颜色和强度。灯光还具有ambientColor属性，定义了在光源照亮之前应用于材质的基色。默认情况下，该属性设置为黑色，但可用于在场景中提供基础照明。

In the examples this far, we've only used one light source at a time, but it is of course possible to combine multiple light sources in a single scene.

在到目前为止的示例中，我们一次只使用一个光源，但当然可以在单个场景中组合多个光源。