Back to Qt.io
Contact Us Blog Download Qt

SpotLight QML Type

定义场景中的聚光灯。更多

Import Statement: import QtQuick3D
Inherits:

Light

属性

详细说明

聚光灯朝一个方向发射光，呈锥形，由coneAngle 定义。光强在接近coneAngle 时减弱。光强开始减弱的角度由innerConeAngle 定义。这两个角度的单位都是度。

在innerConeAngle 内，点光源的行为与点光源类似。在那里，光强按照反平方定律减弱。不过，淡入淡出（和范围）可以通过constantFade 、linearFade 和quadraticFade 属性进行控制。光衰减的计算公式如下 constantFade +distance * (linearFade * 0.01) +distance * (quadraticFade * 0.0001)^2

我们来看一个简单的例子。这里的聚光灯位于 Z 轴 300 处，即摄像机和场景中心的中间位置。默认情况下，光线是沿着 Z 轴方向发射的。brightness 增加到 10，使其看起来更像典型的聚光灯。

import QtQuick
import QtQuick3D
View3D {
    anchors.fill: parent

    PerspectiveCamera { z: 600 }

    SpotLight {
        z: 300
        brightness: 10
        ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    }

    Model {
        source: "#Rectangle"
        scale: Qt.vector3d(10, 10, 10)
        z: -100
        materials: PrincipledMaterial { }
    }

    Model {
        source: "#Sphere"
        scale: Qt.vector3d(2, 2, 2)
        materials: PrincipledMaterial {
            baseColor: "#40c060"
            roughness: 0.1
        }
    }
}

旋转的情况与DirectionalLight 类似。在这里，我们希望灯光更多地向右方发射，因此围绕 Y 轴旋转 -20 度。我们将coneAngle 设置为 30，而不是默认的 40，从而减小了锥度。我们还将innerConeAngle 改为 10，使强度开始减弱的时间提前。

SpotLight {
    z: 300
    brightness: 10
    ambientColor: Qt.rgba(0.1, 0.1, 0.1, 1.0)
    eulerRotation.y: -20
    coneAngle: 30
    innerConeAngle: 10
}

更多使用示例，请参见Qt Quick 3D - 灯光示例。

另请参阅 DirectionalLight,PointLight, 和阴影贴图。

属性文档

coneAngle : real

该属性定义了光线不影响场景的截止角度（从边缘到边缘）。定义单位为0 和180 之间的度数。默认值为40 。

注： 当锥角接近180 度时，阴影质量将开始下降。因此建议使用170 以下的值。


constantFade : real

该属性是光线衰减项的常数因子。默认值为 1.0。


innerConeAngle : real

该属性定义了光线强度在接近coneAngle 时开始逐渐减弱的角度（从边缘到边缘）。定义单位为 0 至 180 度。如果设置的值大于coneAngle ，其行为将与coneAngle 相同。默认值为 30。


linearFade : real

该属性可提高灯光效果根据与灯光的距离成比例地使灯光变暗的速度。默认值为0.0 ，这意味着灯光没有线性衰减。此处使用的值会先乘以0.01 ，然后再用于计算光衰减。


quadraticFade : real

该属性根据平方反比定律增加灯光效果的光线衰减速度。默认值为 1.0，这意味着点光源的衰减完全遵循平方反比定律，即当距离物体的距离增加一倍时，光照强度减弱为原来的四分之一。这里使用的值会乘以0.0001 ，然后用于计算光衰减。


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