Qt Quick 3D - 灯光示例

演示了不同灯光类型的使用方法。

带有彩色灯光和阴影的 Qt 徽标图块，用于演示各种照明类型

本示例演示了在应用程序中使用三种不同类型的光源。

设置场景光源

定向光

定向光从位于无限远处的不可识别光源向一个方向发射光线。这类似于现实生活中的阳光。定向光的射程无限，且光强不会衰减。

我们将方向光设置为发射红色光，并使其围绕x轴进行旋转动画。

DirectionalLight {
    id: light1
    color: Qt.rgba(1.0, 0.1, 0.1, 1.0)
    ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    position: Qt.vector3d(0, 200, 0)
    rotation: Quaternion.fromEulerAngles(-135, -90, 0)
    shadowMapQuality: Light.ShadowMapQualityVeryHigh
    pcfFactor: 1
    visible: directionalLightCheckBox.checked
    castsShadow: checkBoxShadows.checked
    brightness: directionalLightSlider.value
    SequentialAnimation on rotation {
        loops: Animation.Infinite
        QuaternionAnimation {
            to: Quaternion.fromEulerAngles(-45, -90, 0)
            duration: 2000
            easing.type: Easing.InOutQuad
        }
        QuaternionAnimation {
            to: Quaternion.fromEulerAngles(-135, -90, 0)
            duration: 2000
            easing.type: Easing.InOutQuad
        }
    }
}

点光源

点光源可描述为一个球体，从光源中心向各个方向以相等的强度发射光线。这类似于灯泡发光的方式。

我们将点光源设置为发出绿色光，并对其x坐标位置进行动画效果。

PointLight {
    id: light2
    color: Qt.rgba(0.1, 1.0, 0.1, 1.0)
    ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    position: Qt.vector3d(0, 300, 0)
    shadowMapFar: 2000
    shadowMapQuality: Light.ShadowMapQualityHigh
    visible: pointLightCheckBox.checked
    castsShadow: checkBoxShadows.checked
    brightness: pointLightSlider.value
    SequentialAnimation on x {
        loops: Animation.Infinite
        NumberAnimation {
            to: 400
            duration: 2000
            easing.type: Easing.InOutQuad
        }
        NumberAnimation {
            to: 0
            duration: 2000
            easing.type: Easing.InOutQuad
        }
    }
}

聚光灯

聚光灯与点光源类似，区别在于它不是向各个方向发光，而是以锥形向一个方向发光。除了锥角之外，聚光灯与点光源具有相同的特征和属性。

我们将聚光灯设置为发出暖色光，并对其y坐标方向的旋转进行动画处理。

SpotLight {
    id: light4
    color: Qt.rgba(1.0, 0.9, 0.7, 1.0)
    ambientColor: Qt.rgba(0.0, 0.0, 0.0, 0.0)
    position: Qt.vector3d(0, 250, 0)
    eulerRotation.x: -45
    shadowMapFar: 2000
    shadowMapQuality: Light.ShadowMapQualityHigh
    visible: spotLightCheckBox.checked
    castsShadow: checkBoxShadows.checked
    brightness: spotLightSlider.value
    coneAngle: 110
    innerConeAngle: 70
    PropertyAnimation on eulerRotation.y {
        loops: Animation.Infinite
        from: 0
        to: -360
        duration: 10000
    }
}

设置场景模型

首先，我们添加两个矩形模型，作为场景中的地面和后墙。这些模型有助于观察光影效果。

Model {
    source: "#Rectangle"
    y: -200
    scale: Qt.vector3d(15, 15, 15)
    eulerRotation.x: -90
    materials: [
        PrincipledMaterial {
            baseColor: Qt.rgba(0.8, 0.6, 0.4, 1.0)
        }
    ]
}
Model {
    source: "#Rectangle"
    z: -400
    scale: Qt.vector3d(15, 15, 15)
    materials: [
         PrincipledMaterial {
            baseColor: Qt.rgba(0.8, 0.8, 0.9, 1.0)
        }
    ]
}

接着，我们添加了围绕y轴旋转的主Logo模型。

Model {
    id: logoDefault
    source: "qtlogo.mesh"
    scale: Qt.vector3d(5000, 5000, 5000)

    property variant material
    materials: [ material ]

    property bool animate: true
    NumberAnimation on eulerRotation.y {
        running: logoDefault.animate
        loops: Animation.Infinite
        duration: 5000
        from: 0
        to: -360
    }
}

我们还添加了小型立方体模型，用于演示每种光源的位置和旋转。当用户操作相关滑块时，这些立方体会放大。

Model {
    // Directional Light Marker
    property real size: directionalLightSlider.highlight ? 0.2 : 0.1
    source: "#Cube"
    position: light1.position
    rotation: light1.rotation
    scale: Qt.vector3d(size, size, size * 2)
    materials: [
        PrincipledMaterial {
            baseColor: light1.color
            lighting: PrincipledMaterial.NoLighting
        }
    ]
    castsShadows: false
    visible: directionalLightCheckBox.checked
}
Model {
    // Point Light Marker
    source: "#Sphere"
    position: light2.position
    rotation: light2.rotation
    property real size: pointLightSlider.highlight ? 0.2 : 0.1
    scale: Qt.vector3d(size, size, size)
    materials: [
        PrincipledMaterial {
            baseColor: light2.color
            lighting: PrincipledMaterial.NoLighting
        }
    ]
    castsShadows: false
    visible: pointLightCheckBox.checked
}
Node {
    // Spot Light Marker
    position: light4.position
    rotation: light4.rotation
    property real size: spotLightSlider.highlight ? 0.2 : 0.1
    scale: Qt.vector3d(size, size, size)
    Model {
        source: "#Cone"
        castsShadows: false
        eulerRotation.x: 90
        materials: PrincipledMaterial {
            baseColor: light4.color
            lighting: PrincipledMaterial.NoLighting
        }
    }
    visible: spotLightCheckBox.checked
}

用户可通过设置面板启用阴影，并分别控制每盏灯的可见性和亮度。

示例项目 @ code.qt.io

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