第13章：3D集成

3D场景（Scene3D）、模型加载、材质与光照、相机控制、与2D混合

本章概述

Qt Quick 3D模块为QML开发者打通了2D UI与3D内容的壁垒，无需复杂的3D引擎知识，就能在传统2D界面中无缝嵌入3D元素。本章将带你从零开始掌握3D场景搭建、模型材质配置、光照系统设计、相机交互控制，最终实现2D与3D的完美融合，打造现代沉浸式交互界面。

核心概念详解

1. Scene3D - 2D与3D的桥梁

Scene3D是连接2D QML界面与3D世界的核心容器，它本质是一个普通QML元素，能像Button、Rectangle一样被放置、调整大小、做变换，相当于在2D界面上开了一个“窗口”，专门用来渲染3D内容。

核心作用：定义3D内容的渲染视口，让3D世界能在2D界面中展示。

关键属性：

importsScene：指向以Node为根节点的3D场景；
camera：指定观察3D场景的相机；
renderMode：设置渲染模式（在线实时渲染/离线渲染）。

基础示例：

import QtQuick3D 6.5

Scene3D {
    id: scene3d
    anchors.fill: parent // 占满父容器
    focus: true // 接收交互事件
    camera: mainCamera // 指定相机

    // 3D场景根节点，所有3D元素都放在这里
    Node {
        // 平行光做主光源
        DirectionalLight { 
            eulerRotation.x: -30 // 调整光照角度
            intensity: 1.2
        }
        // 透视相机，模拟人眼视角
        PerspectiveCamera {
            id: mainCamera
            position: Qt.vector3d(0, 200, 300) // 相机位置（x,y,z）
        }
        // 加载3D模型并设置红色材质
        Model {
            source: "meshes/robot.mesh" // 模型路径
            materials: [ DefaultMaterial { diffuseColor: "red" } ]
        }
    }
}

2. 模型加载与材质配置

用Model元素就能轻松加载外部3D模型，再通过Material定义模型的表面外观，让3D物体更真实。

支持模型格式：.obj、.fbx、.glTF等，其中glTF是Qt推荐格式，支持材质、动画等完整信息，兼容性更好。

常用材质类型：

DefaultMaterial：基础PBR（基于物理的渲染）材质，满足大部分场景需求；
PrincipledMaterial：高级PBR材质，能更精细控制金属质感、粗糙度等参数；
CustomMaterial：自定义着色器材质，可实现特殊视觉效果（如透明、发光）。

实战示例：

Model {
    source: "qrc:/assets/spaceship.gltf" // 资源文件路径
    position: Qt.vector3d(0, 0, 0) // 模型位置
    scale: Qt.vector3d(2, 2, 2) // 放大2倍
    eulerRotation: Qt.vector3d(0, 45, 0) // 绕Y轴旋转45度

    materials: [
        PrincipledMaterial {
            baseColor: "#FFAA00" // 基础颜色（金黄）
            metalness: 0.8 // 金属质感（0=非金属，1=纯金属）
            roughness: 0.2 // 表面粗糙度（0=镜面，1=哑光）
            specularAmount: 1.0 // 高光强度
        }
    ]
}

3. 光照系统：让3D场景更真实

光照是3D场景的灵魂，Qt Quick 3D提供了4种常用光源，模拟不同的真实光照效果：

平行光（DirectionalLight）：光线方向统一，类似太阳光，适合室外场景全局照明；
点光源（PointLight）：从一点向四周均匀发光，可模拟灯泡、蜡烛等局部照明；
聚光灯（SpotLight）：呈锥形光束，有内外锥角，适合手电筒、舞台灯等重点照明；
区域光（AreaLight）：从矩形区域发射光线，能实现柔和的室内灯板照明。

最佳实践：场景至少搭配一个平行光做主光源，再辅以1-2个点光源或聚光灯补充细节，增强物体立体感与场景氛围。

4. 相机控制：打造交互式视角

相机决定了用户观察3D场景的角度，灵活的相机控制是沉浸式体验的核心。

常用相机类型：

PerspectiveCamera：透视相机，模拟人眼视角，有近大远小的效果，适合大部分3D场景；
OrthographicCamera：正交相机，无透视变形，常用于CAD、2.5D界面。

基础相机配置：

PerspectiveCamera {
    id: camera
    position: Qt.vector3d(0, 50, 500) // 相机位置
    eulerRotation.x: -10 // 向下俯视10度
    fieldOfView: 60 // 视野角度（越大看到的范围越广）
    clipNear: 1.0 // 最近可见距离
    clipFar: 10000.0 // 最远可见距离
}

交互控制示例（鼠标操作）：

MouseArea {
    anchors.fill: parent
    property point lastPos: Qt.point(0,0)

    // 鼠标拖动控制相机旋转
    onPressed: lastPos = Qt.point(mouseX, mouseY)
    onPositionChanged: {
        var dx = mouseX - lastPos.x
        var dy = mouseY - lastPos.y
        camera.eulerRotation.y += dx * 0.5 // 绕Y轴旋转（左右转）
        camera.eulerRotation.x += dy * 0.5 // 绕X轴旋转（上下转）
        lastPos = Qt.point(mouseX, mouseY)
    }

    // 滚轮控制相机推拉（缩放）
    onWheel: {
        camera.position.z += wheel.angleDelta.y * 0.1
        // 可添加范围限制，避免相机过近/过远
        camera.position.z = Math.max(100, Math.min(1000, camera.position.z))
    }
}

5. 3D与2D混合：无缝融合的UI体验

Qt Quick的优势在于能让2D与3D内容无缝共存，打造层次丰富的界面：

2D控件叠加：将Button、Slider等2D控件放在Scene3D之上，用于控制3D场景（如调整模型旋转、重置视角）；
3D作为背景：把3D场景设为应用动态背景，前景放置2D信息面板，提升界面质感；
混合特效：用Layer或ShaderEffect实现2D与3D的视觉融合，比如给3D场景加模糊效果，让2D控件更突出。

实战示例：3D场景上叠加2D控制面板

Item {
    width: 800; height: 600

    // 3D场景作为底层
    Scene3D {
        id: my3dScene
        anchors.fill: parent
        // 此处省略3D场景内容（相机、模型、光源）
    }

    // 半透明2D控制面板（悬浮在3D场景上）
    Rectangle {
        x: 20; y: 20
        width: 200; height: 150
        color: "#AAFFFFFF" // 半透明白色
        radius: 10 // 圆角
        border { color: "#4A90E2"; width: 2 }

        Column {
            anchors.centerIn: parent
            spacing: 10
            Text { text: "3D控制器"; font.bold: true }
            // 滑块控制模型绕Y轴旋转
            Slider {
                width: 180
                from: 0; to: 360
                onValueChanged: my3dModel.eulerRotation.y = value
            }
            // 按钮重置相机位置
            Button {
                text: "重置视角"
                onClicked: camera.position = Qt.vector3d(0, 200, 500)
            }
        }
    }
}

综合示例架构

一个完整的Qt Quick 3D应用通常分为三层：

Main.qml（2D根窗口）
├── Scene3D（3D渲染容器）
│   ├── 3D世界层
│   │   ├── 相机（PerspectiveCamera）
│   │   ├── 模型（Model）
│   │   ├── 光源（DirectionalLight/PointLight等）
│   └── 交互逻辑（鼠标/触摸控制）
└── 2D UI层
    ├── 按钮、滑块（控制3D场景）
    ├── 文本、数据面板（展示信息）

本章总结

通过本章学习，你已掌握Qt Quick 3D集成的核心技能：

用Scene3D搭建2D与3D的连接桥梁；
加载外部3D模型并配置PBR材质，让物体更真实；
搭配多种光源，提升场景立体感与氛围；
实现相机的交互式控制，让用户自由探索3D世界；
无缝混合2D与3D元素，打造沉浸式UI。

进阶提示：可进一步探索Qt Quick 3D的高级特性，比如粒子系统（ParticleSystem3D）、自定义着色器（CustomMaterial），或使用Qt 3D Studio制作复杂3D动画并集成到QML中。