Fog QML Type
指定场景的雾效设置。更多...
| Import Statement: | import QtQuick3D |
| Since: | Qt 6.5 |
| Inherits: |
属性
- color : color
- density : real
- depthCurve : real
- depthEnabled : bool
- depthFar : real
- depthNear : real
- enabled : bool
- heightCurve : real
- heightEnabled : bool
- leastIntenseY : real
- mostIntenseY : real
- transmitCurve : real
- transmitEnabled : bool
详细说明
当SceneEnvironment 的fog 属性被设置为一个有效的Fog对象时，这些属性将用于配置雾效的渲染。
此类型提供的简单雾效由材质实现。它并非后期处理效果，这意味着它不涉及使用View3D 的输出对纹理进行额外渲染通道的处理，而是通过片段着色器在每个可渲染对象（Model 的子网格）中，使用PrincipledMaterial 或带着色效果的CustomMaterial 来实现。
雾效通过以下若干属性进行配置：
- 常规设置：color 以及density
- 深度雾设置：depthEnabled 、depthNear 、depthFar 、depthCurve
- 高度雾设置：heightEnabled 、leastIntenseY 、mostIntenseY 、heightCurve
- 颜色透射设置：transmitEnabled ，transmitCurve
例如，以下代码片段使用默认雾参数启用了深度雾（但不启用高度雾）：
environment: SceneEnvironment {
backgroundMode: SceneEnvironment.Color
clearColor: theFog.color
fog: Fog {
id: theFog
enabled: true
depthEnabled: true
}
}除了内联定义 Fog 对象外，还可以通过id 引用一个 Fog 对象。由于ExtendedSceneEnvironment 继承了其父类SceneEnvironment 的所有特性，因此雾效果也可以与ExtendedSceneEnvironment 配合使用：
Fog {
id: theFog
enabled: true
depthEnabled: true
}
environment: ExtendedSceneEnvironment {
fog: theFog
}另请参阅 Qt Quick 3D - 简单雾效示例和Qt Quick 3D - 场景特效示例。
属性文档
color : color
雾的颜色。默认值为“#8099b3”
同一场景，颜色调整得更偏蓝一些：
另请参阅 density 。
density : real
控制雾效的强度，实际上这是一个取值范围在0到1之间的倍数。默认值为1.0。降低该值会减弱雾效的强度。仅当depthEnabled 设置为true时才生效。
屏幕上的视觉效果可能会受到“ExtendedSceneEnvironment ”中其他若干设置的影响，例如色调映射或光晕与光晕扩散。相同的密度值可能会产生不同的效果，这取决于启用了哪些其他效果以及这些效果的配置方式。
密度设置为0.95 的示例场景：
将密度降低至0.15 后的同一场景：
另请参阅 color 。
depthCurve : real
默认值为 1.0。
仅当depthEnabled 设置为 true 时才适用。
另请参阅 depthEnabled 。
depthEnabled : bool
控制远处是否出现雾。默认值为 false。
另请参阅 heightEnabled 、enabled 、depthNear 、depthFar 以及depthCurve 。
depthFar : real
距摄像机的结束距离。默认值为 1000.0。仅在将 `depthEnabled ` 设置为 `true` 时生效。
注意：场景 （包括摄像机和模型）应相应地进行设置，以便通过depthNear 和depthFar等属性定义合理的范围。请勿期望在未先调整变换的情况下，直接在包含原样导入的资源的场景中始终能启用雾效。 例如，本页面中包含Sponza模型的示例截图，是在对由balsam 工具从 glTF 源资源生成的 Sponza 组件实例，手动应用额外缩放比例(100, 100, 100) 之后生成的。这样便获得了足够的 Z 轴范围，通过调整depthNear 和 depthFar 的数值，从而得到了令人满意的效果。
另请参阅 depthNear 和depthEnabled 。
depthNear : real
与摄像机的起始距离。默认值为 10.0。仅当depthEnabled 设置为true时才适用。
以这个场景为例，首先设置较高的 depthNear 值。
降低 depthNear 的值会导致雾效实际上“向摄像机靠近”，因为此时雾效的起始距离更近：
注意：场景 （包括摄像机和模型）应相应地进行设置，以便通过 depthNear 和depthFar 等属性定义合理的范围。请不要期望在未先调整变换的情况下，直接在包含原样导入的资源的场景中始终能启用雾效。 例如，本页面中包含Sponza模型的示例截图，是在对由balsam 工具从 glTF 源资源生成的 Sponza 实例组件上，手动应用了(100, 100, 100) 的额外缩放比例后生成的。这从而提供了足够的 Z 范围，通过调整 depthNear 和depthFar 的数值，可以获得良好的视觉效果。
另请参阅 depthFar 和depthEnabled 。
enabled : bool
控制是否在场景中应用雾效。默认值为 false。
若不将此值设为 true，启用深度雾或高度雾将无效。
另请参阅 depthEnabled 和heightEnabled 。
heightCurve : real
指定高度雾的强度。默认值为 1.0。仅当 `heightEnabled ` 设置为 true 时才适用。
另请参阅 heightEnabled 。
heightEnabled : bool
控制是否启用高度雾效。默认值为 false。
另请参阅 depthEnabled 、enabled 、leastIntenseY 、mostIntenseY 以及heightCurve 。
leastIntenseY : real
指定雾气最淡的位置（Y坐标）。默认值为10.0。仅当heightEnabled 设置为true时才适用。
注意：默认情况下， 该值大于mostIntenseY 。只要该值大于 ，雾效将从上至下渲染。当该值小于mostIntenseY 时，雾效将从下至上渲染。
注意： 在启用Qt Quick 3D 的场景中，Y轴 指向上方。
图中展示了一个启用了高度雾（未启用深度雾）的场景，其中 leastIntenseY 被设置为使雾仅在 Sponza 场景底部扩散。
增加 leastIntenseY 的数值会使雾气扩散到更高处，因为此时雾气实际上是从场景中更高的 Y 位置开始扩散的。（请记住 Y 轴指向向上）
注意：与 深度雾效果类似， 场景需相应地进行设置，以便通过 `leastIntenseY` 和 `mostIntenseY` 定义合理的 Y 坐标范围。请勿期望在未对变换进行预先调整的情况下，直接在包含原样导入资产的场景中始终能启用雾效果。 例如，本页面中使用Sponza模型的示例截图，是在对由balsam 工具从 glTF 源资源生成的实例化 Sponza 组件上，手动应用了(100, 100, 100) 的额外缩放比例后生成的。
另请参阅 mostIntenseY 和heightEnabled 。
mostIntenseY : real
指定雾气最浓密的位置（Y坐标）。默认值为0。仅当heightEnabled 设置为true时才适用。
注意：默认情况下， 该值小于 `leastIntenseY`。只要该条件成立，雾就会从上到下渲染。当该值大于 `leastIntenseY` 时，雾将从下到上渲染。
注意： 在Qt Quick 3D 场景中，Y轴 指向上方。
注意：与 深度雾一样， 场景应相应地进行设置，以便通过leastIntenseY 和mostIntenseY定义合理的Y坐标范围。请不要期望在未先调整变换的情况下，直接在包含原样导入的资源的场景中始终能启用雾效。 例如，本页面中展示Sponza模型的示例截图，是在对由balsam 工具从 glTF 源资源生成的 Sponza 组件实例，手动应用了(100, 100, 100) 的额外缩放比例后生成的。
另请参阅 leastIntenseY 和heightEnabled 。
transmitCurve : real
光透射效果的强度。默认值为 1.0。仅当 `transmitEnabled ` 设置为 `true` 时才适用。
transmitEnabled : bool
控制雾是否具有透光效果。默认值为 false。
© 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.
