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 - 灯光示例。
另请参阅 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, 以及Lightmaps and Global Illumination。
brightness : real |
该属性定义了该灯光效果的总乘数。默认值为 1。
castsShadow : bool |
启用此属性后，灯光将投射（实时）阴影。默认值为 false。
注意： 当bakeMode 设置为 Light.BakeModeAll 时，此属性将不起作用。完全烘焙的灯光总是有烘焙阴影，但它永远不会参与实时阴影贴图。
color : color |
此属性定义了应用于受此灯光照射的模型的颜色。默认值为白色（rgb(255, 255, 255)）。
pcfFactor : real |
该属性控制 PCF（百分比近似滤波）因子。该值试图接近世界空间中 PCF 滤波的半径。
注意： 需要在softShadowQuality 中设置 PCF，该属性才能生效。
默认值：2.0
此属性在 Qt 6.8 中引入。
另请参阅 Light::softShadowQuality 。
scope : Node |
该属性允许在场景中选择一个节点。只有该节点及其子节点受此灯光影响。默认值为空，表示未选择作用域。
注意： 作用域灯光无法投射实时阴影，这意味着设置了作用域的灯光不应将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 |
该属性控制柔和阴影的质量。
| 常数 | 说明 |
|---|---|
Light.Hard | 无柔和阴影。 |
Light.PCF4 | 使用 4 个采样点进行百分比更接近过滤的柔和阴影。 |
Light.PCF8 | 以 8 个采样点的百分比近似过滤柔光阴影。 |
Light.PCF16 | 以 16 个采样点的百分比渐近滤波柔和阴影。 |
Light.PCF32 | 百分比渐近滤波 32 个采样点的柔和阴影。 |
Light.PCF64 | 用 64 个采样点近似百分比过滤柔光阴影。 |
默认值：Light.PCF4
此属性在 Qt 6.8 中引入。
另请参阅 Light::pcfFactor 和Light::shadowFilter 。
use32BitShadowmap : bool |
© 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.
