Light QML Type
一个适用于所有光源的、不可创建的抽象基类。更多...
| Import Statement: | import QtQuick3D |
| Inherits: | |
| Inherited By: |
属性
- ambientColor : color
- bakeMode : enumeration
- brightness : real
- castsShadow : bool
- color : color
- pcfFactor : real
(since 6.8) - scope : Node
- shadowBias : real
- shadowFactor : real
- shadowMapFar : real
- shadowMapQuality : enumeration
- softShadowQuality : enumeration
(since 6.8) - use32BitShadowmap : bool
(since 6.9)
详细说明
“光”本身是所有其子类型的不可创建的基础。这些子类型提供了多种选项，用于确定光的样式。
使用示例请参见Qt Quick 3D - Lights Example。
另请参阅 DirectionalLight 和PointLight 。
属性文档
ambientColor : color
该属性定义了在该光源照亮材质之前，应用于材质的基础颜色。默认值为黑色，即 rgb(0, 0, 0)。
bakeMode : enumeration
该属性控制光源在烘焙照明（例如生成光照贴图时）中是否处于活动状态。
| 常量 | 描述 |
|---|---|
Light.BakeModeDisabled | 该光源在烘焙照明中不被使用。 |
Light.BakeModeIndirect | 此光源的间接照明贡献（用于全局照明）已烘焙。直接照明（漫反射、镜面反射、实时阴影映射）在运行时按常规方式计算。 在运行时，如果不在烘焙模式下，渲染器将尝试采样光照贴图以获取间接光照数据，并将其与实时计算的结果相结合。 |
Light.BakeModeAll | 此光源的直接（漫反射、阴影）和间接照明均已烘焙。该光源不会产生镜面反射，也不会生成实时阴影贴图，但始终具有烘焙阴影。 在运行时，如果未处于烘焙模式，渲染器将尝试采样光照贴图，以代替对漫反射光照和阴影映射的标准实时计算。 |
默认值为Light.BakeModeDisabled
注意： 与Model::usedInBakedLighting一样， 设计师和开发人员必须始终针对每盏灯进行评估，以确定该灯是否适合参与烘焙照明。
警告： 属性会动态变化的光源 （例如，位置、旋转或其他属性会随动画变化），不适合参与烘焙照明。
此属性在烘焙和使用光照贴图时均适用。烘焙运行与后续使用生成的数据的运行之间保持一致的状态至关重要。更改为其他值不会改变光照贴图中先前生成并持久存储的数据，但引擎的渲染行为将遵循该属性的当前值。
有关如何烘焙光照贴图的更多信息，请参阅《光照贴图与全局光照》。
另请参阅 Model::usedInBakedLighting 、Model::bakedLightmap 、Lightmapper 以及《光照贴图与全局光照》。
brightness : real
此属性定义了该光源效果的总体倍数。默认值为 1。
castsShadow : bool
启用此属性后，光源将投射（实时）阴影。默认值为 false。
注意：当“ bakeMode ” 设置为“Light.BakeModeAll”时， 此属性将不起作用。完全烘焙的光源始终具有烘焙阴影，但绝不会参与实时阴影映射。
color : color
此属性定义了应用于受该光源照射的模型的颜色。默认值为白色，即 rgb(255, 255, 255)。
pcfFactor : real [since 6.8]
该属性用于控制 PCF（百分比邻近过滤）因子。该值旨在近似表示世界坐标系中 PCF 过滤的半径。
注意： 必须在softShadowQuality 中设置PCF ，该属性才能生效。
默认值：2.0
该属性自 Qt 6.8 起引入。
另请参阅 Light::softShadowQuality 。
scope : Node
该属性允许选择场景中的一个节点。只有该节点及其子节点会受到此光源的影响。默认值为 null，表示未选择任何作用域。
注意：具有作用域 的光源无法投射实时阴影，这意味着设置了作用域的光源不应将castsShadow 设为true。不过，当bakeMode 设置为Light.BakeModeAll时，它们仍可生成烘焙阴影。
shadowBias : real
此属性用于调整物体在自身上投射阴影时的阴影效果。该值旨在近似表示世界坐标系中的偏移量，因此需要根据场景的大小进行调整。
默认值为10
shadowFactor : real
此属性用于确定投射阴影的深浅程度。取值范围为 [0, 100]，其中 0 表示无阴影，100 表示光线被完全遮蔽。
默认值为75 。
shadowMapFar : real
该属性决定了阴影贴图的最大距离。数值越小，贴图的精度和效果越好。默认值为 5000。单位为本地坐标系中的点。
shadowMapQuality : enumeration
该属性用于设置为阴影渲染生成的阴影贴图的质量。较低的质量会消耗较少的资源，但生成的阴影质量较低；而较高的质量会消耗更多的资源，但生成的阴影质量更高。
支持的质量值包括：
| 常量 | 描述 |
|---|---|
Light.ShadowMapQualityLow | 使用 256x256 纹理渲染阴影贴图。 |
Light.ShadowMapQualityMedium | 使用 512x512 纹理渲染阴影贴图。 |
Light.ShadowMapQualityHigh | 使用 1024x1024 纹理渲染阴影贴图。 |
Light.ShadowMapQualityVeryHigh | 使用 2048x2048 纹理渲染阴影贴图。 |
Light.ShadowMapQualityUltra | 使用 4096x4096 的纹理渲染阴影贴图。 |
默认值为Light.ShadowMapQualityLow
softShadowQuality : enumeration [since 6.8]
该属性指定了启用阴影时应使用的柔和阴影效果。渲染阴影时实际使用的采样数量，由材质所用光源中设置的最高质量级别决定。
| 常量 | 描述 |
|---|---|
Light.Hard | 不生成柔和阴影。 |
Light.PCF4 | 使用 4 个采样点对柔和阴影进行“百分比更近”过滤。 |
Light.PCF8 | 使用 8 个采样点，对柔和阴影进行百分比更近滤波。 |
Light.PCF16 | 使用 16 个采样点对柔和阴影进行百分比更近滤波。 |
Light.PCF32 | 使用 32 个采样点进行百分比更近过滤的柔和阴影。 |
Light.PCF64 | 使用 64 个采样点对柔和阴影进行百分比更近滤波。 |
默认值：Light.PCF4
注意：目前， 大于 16 个采样的值将被视为 16 个采样。
该属性自 Qt 6.8 起引入。
另请参阅 Light::pcfFactor 和Light::shadowFilter 。
use32BitShadowmap : bool [since 6.9]
该属性控制是否应为该光源使用 32 位阴影贴图深度缓冲区。
默认值：false
该属性自 Qt 6.9 起引入。
另请参阅 Light::castsShadow 。
© 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.
