Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Environment

继承: Resource < RefCounted < Object

定义渲染选项的资源,用于环境节点(例如 WorldEnvironment)。

描述

定义环境操作(例如背景 SkyColor、环境光、雾、景深等)的资源,用于环境节点(例如 WorldEnvironment)。这些参数会对场景的最终渲染造成影响。操作的顺序为:

  • 景深模糊

  • 辉光

  • 色调映射(自动曝光)

  • 调整

教程

属性

float

adjustment_brightness

1.0

Texture

adjustment_color_correction

float

adjustment_contrast

1.0

bool

adjustment_enabled

false

float

adjustment_saturation

1.0

Color

ambient_light_color

Color(0, 0, 0, 1)

float

ambient_light_energy

1.0

float

ambient_light_sky_contribution

1.0

AmbientSource

ambient_light_source

0

int

background_camera_feed_id

1

int

background_canvas_max_layer

0

Color

background_color

Color(0, 0, 0, 1)

float

background_energy_multiplier

1.0

float

background_intensity

30000.0

BGMode

background_mode

0

float

fog_aerial_perspective

0.0

float

fog_density

0.01

bool

fog_enabled

false

float

fog_height

0.0

float

fog_height_density

0.0

Color

fog_light_color

Color(0.518, 0.553, 0.608, 1)

float

fog_light_energy

1.0

float

fog_sky_affect

1.0

float

fog_sun_scatter

0.0

GlowBlendMode

glow_blend_mode

2

float

glow_bloom

0.0

bool

glow_enabled

false

float

glow_hdr_luminance_cap

12.0

float

glow_hdr_scale

2.0

float

glow_hdr_threshold

1.0

float

glow_intensity

0.8

float

glow_levels/1

0.0

float

glow_levels/2

0.0

float

glow_levels/3

1.0

float

glow_levels/4

0.0

float

glow_levels/5

1.0

float

glow_levels/6

0.0

float

glow_levels/7

0.0

Texture

glow_map

float

glow_map_strength

0.8

float

glow_mix

0.05

bool

glow_normalized

false

float

glow_strength

1.0

ReflectionSource

reflected_light_source

0

float

sdfgi_bounce_feedback

0.5

float

sdfgi_cascade0_distance

12.8

int

sdfgi_cascades

4

bool

sdfgi_enabled

false

float

sdfgi_energy

1.0

float

sdfgi_max_distance

204.8

float

sdfgi_min_cell_size

0.2

float

sdfgi_normal_bias

1.1

float

sdfgi_probe_bias

1.1

bool

sdfgi_read_sky_light

true

bool

sdfgi_use_occlusion

false

SDFGIYScale

sdfgi_y_scale

1

Sky

sky

float

sky_custom_fov

0.0

Vector3

sky_rotation

Vector3(0, 0, 0)

float

ssao_ao_channel_affect

0.0

float

ssao_detail

0.5

bool

ssao_enabled

false

float

ssao_horizon

0.06

float

ssao_intensity

2.0

float

ssao_light_affect

0.0

float

ssao_power

1.5

float

ssao_radius

1.0

float

ssao_sharpness

0.98

bool

ssil_enabled

false

float

ssil_intensity

1.0

float

ssil_normal_rejection

1.0

float

ssil_radius

5.0

float

ssil_sharpness

0.98

float

ssr_depth_tolerance

0.2

bool

ssr_enabled

false

float

ssr_fade_in

0.15

float

ssr_fade_out

2.0

int

ssr_max_steps

64

float

tonemap_exposure

1.0

ToneMapper

tonemap_mode

0

float

tonemap_white

1.0

Color

volumetric_fog_albedo

Color(1, 1, 1, 1)

float

volumetric_fog_ambient_inject

0.0

float

volumetric_fog_anisotropy

0.2

float

volumetric_fog_density

0.05

float

volumetric_fog_detail_spread

2.0

Color

volumetric_fog_emission

Color(0, 0, 0, 1)

float

volumetric_fog_emission_energy

1.0

bool

volumetric_fog_enabled

false

float

volumetric_fog_gi_inject

1.0

float

volumetric_fog_length

64.0

float

volumetric_fog_sky_affect

1.0

float

volumetric_fog_temporal_reprojection_amount

0.9

bool

volumetric_fog_temporal_reprojection_enabled

true

方法

float

get_glow_level ( int idx ) const

void

set_glow_level ( int idx, float intensity )


枚举

enum BGMode:

BGMode BG_CLEAR_COLOR = 0

使用 ProjectSettings.rendering/environment/defaults/default_clear_color 中定义的清除颜色来清除背景。

BGMode BG_COLOR = 1

使用自定义的清除颜色来清除背景。

BGMode BG_SKY = 2

在背景中显示用户自定义的天空。

BGMode BG_CANVAS = 3

在背景中显示 CanvasLayer

BGMode BG_KEEP = 4

在屏幕上保留在背景中绘制的每个像素。这是最快的背景模式,但它只能安全地用在完全室内的场景(没有可见的天空或天空反射)。如果在背景可见的场景中启用,则移动相机时,将看到“鬼影踪迹”伪影。

BGMode BG_CAMERA_FEED = 5

在背景中显示相机源。

BGMode BG_MAX = 6

代表 BGMode 枚举的大小。


enum AmbientSource:

AmbientSource AMBIENT_SOURCE_BG = 0

从指定为背景的任何来源收集环境光。

AmbientSource AMBIENT_SOURCE_DISABLED = 1

禁用环境光。这比 AMBIENT_SOURCE_SKY 提供了轻微的性能提升。

AmbientSource AMBIENT_SOURCE_COLOR = 2

为环境光指定特定的 Color。与 AMBIENT_SOURCE_SKY 相比,这提供了轻微的性能提升。

AmbientSource AMBIENT_SOURCE_SKY = 3

无论背景如何,都从 Sky 收集环境光。


enum ReflectionSource:

ReflectionSource REFLECTION_SOURCE_BG = 0

使用背景进行反射。

ReflectionSource REFLECTION_SOURCE_DISABLED = 1

禁用反射。与其他选项相比,这提供了轻微的性能提升。

ReflectionSource REFLECTION_SOURCE_SKY = 2

无论背景如何,都使用 Sky 进行反射。


enum ToneMapper:

ToneMapper TONE_MAPPER_LINEAR = 0

线性色调映射运算子。读取线性数据并将其原样传递。较亮的光照会导致过曝、输出的颜色中会有可见的截断。

ToneMapper TONE_MAPPER_REINHARDT = 1

Reinhardt 色调映射运算子。对渲染后的像素颜色进行调整,使用的是这个公式:color = color / (1 + color)。可以避免对高光的截断,但最终的图像可能看上去有些寡淡。

ToneMapper TONE_MAPPER_FILMIC = 2

电影级色调映射器运算子。可以避免对高光处的截断,最终图像通常比 TONE_MAPPER_REINHARDT 更鲜艳。

ToneMapper TONE_MAPPER_ACES = 3

使用学院色彩编码系统(Academy Color Encoding System)色调映射器。ACES 比其他选项消耗略高,但对于较亮光照的处理更真实,越亮饱和度越低。ACES 的输出在对比度方面通常比 TONE_MAPPER_REINHARDTTONE_MAPPER_FILMIC 更高。

注意:Godot 3.x 将该色调映射运算符称为“ACES Fitted”。


enum GlowBlendMode:

GlowBlendMode GLOW_BLEND_MODE_ADDITIVE = 0

添加辉光混合模式。主要用于粒子、辉光(泛光)、镜头眩光、亮源。

GlowBlendMode GLOW_BLEND_MODE_SCREEN = 1

滤色辉光混合模式。增加亮度,经常与泛光一起使用。

GlowBlendMode GLOW_BLEND_MODE_SOFTLIGHT = 2

柔光辉光混合模式。修改对比度,曝光阴影和高光(高质量泛光)。

GlowBlendMode GLOW_BLEND_MODE_REPLACE = 3

替换辉光混合模式。用辉光值替换所有像素的颜色。这可以通过调整辉光参数来模拟全屏模糊效果,使其与原始图像的亮度相匹配。

GlowBlendMode GLOW_BLEND_MODE_MIX = 4

将辉光与底层颜色混合,以避免在保持辉光效果的同时,尽可能多地增加亮度。


enum SDFGIYScale:

SDFGIYScale SDFGI_Y_SCALE_50_PERCENT = 0

在 Y(垂直)轴上对 SDFGI 使用 50% 的缩放。SDFGI 单元格将比它们的宽度短两倍。这允许提供更多的 GI 细节,并减少薄地板和天花板的漏光。这通常是垂直度不高的场景的最佳选择。

SDFGIYScale SDFGI_Y_SCALE_75_PERCENT = 1

在 Y(垂直)轴上为 SDFGI 使用 75% 的缩放。这是 50% 和 100% SDFGI Y 缩放之间的平衡。

SDFGIYScale SDFGI_Y_SCALE_100_PERCENT = 2

在 Y(垂直)轴上为 SDFGI 使用 100% 的缩放。SDFGI 单元格将与宽度一样高。这通常是高度垂直场景的最佳选择。不利之处在于,薄地板和天花板可能会导致漏光更加明显。


属性说明

float adjustment_brightness = 1.0

  • void set_adjustment_brightness ( float value )

  • float get_adjustment_brightness ( )

渲染场景的全局亮度值。只有当 adjustment_enabledtrue 时才有效。


Texture adjustment_color_correction

  • void set_adjustment_color_correction ( Texture value )

  • Texture get_adjustment_color_correction ( )

用于内置后处理颜色分级的 Texture2DTexture3D 查找表(LUT)。可以将 GradientTexture1D 用于一维 LUT,或将 Texture3D 用于更复杂的 LUT。仅当 adjustment_enabledtrue 时有效。


float adjustment_contrast = 1.0

  • void set_adjustment_contrast ( float value )

  • float get_adjustment_contrast ( )

渲染场景的全局对比度值(默认值为 1)。只有当 adjustment_enabledtrue 时才有效。


bool adjustment_enabled = false

  • void set_adjustment_enabled ( bool value )

  • bool is_adjustment_enabled ( )

如果为 true,则启用该资源提供的 adjustment_* 属性。如果为 false,则对 adjustment_* 属性的修改将不会对渲染场景产生影响。

注意:调整仅支持 Forward+ 和 Mobile 渲染方式,不支持 Compatibility。


float adjustment_saturation = 1.0

  • void set_adjustment_saturation ( float value )

  • float get_adjustment_saturation ( )

渲染场景的全局色彩饱和度值(默认值为 1)。只有在 adjustment_enabledtrue 时才有效。


Color ambient_light_color = Color(0, 0, 0, 1)

  • void set_ambient_light_color ( Color value )

  • Color get_ambient_light_color ( )

环境光的 Color。仅当 ambient_light_sky_contribution 低于 1.0(不包括)时,才有效。


float ambient_light_energy = 1.0

  • void set_ambient_light_energy ( float value )

  • float get_ambient_light_energy ( )

环境光的能量。值越高,光线越强。仅当 ambient_light_sky_contribution 低于 1.0(不包括)时,才有效。


float ambient_light_sky_contribution = 1.0

  • void set_ambient_light_sky_contribution ( float value )

  • float get_ambient_light_sky_contribution ( )

定义天空给场景带来的光照量。值为 0.0 表示天空的发光对场景照明没有影响,因此所有的环境照明都由环境光提供。相反,值为 1.0 表示所有影响场景的光线都由天空提供,因此环境光参数对场景没有影响。

注意:内部会将 ambient_light_sky_contribution 限制在 0.01.0 之间(闭区间)。


AmbientSource ambient_light_source = 0

环境光源,用于渲染材质和全局照明。


int background_camera_feed_id = 1

  • void set_camera_feed_id ( int value )

  • int get_camera_feed_id ( )

在背景中显示的相机源的 ID。


int background_canvas_max_layer = 0

  • void set_canvas_max_layer ( int value )

  • int get_canvas_max_layer ( )

要显示的最大图层 ID。只有在使用 BG_CANVAS 背景模式时有效。


Color background_color = Color(0, 0, 0, 1)

  • void set_bg_color ( Color value )

  • Color get_bg_color ( )

场景中清除区域显示的 Color。仅在使用 BG_COLOR 背景模式时有效。


float background_energy_multiplier = 1.0

  • void set_bg_energy_multiplier ( float value )

  • float get_bg_energy_multiplier ( )

背景能量的倍数。增加可以使背景更亮,减少可以使背景更暗。


float background_intensity = 30000.0

  • void set_bg_intensity ( float value )

  • float get_bg_intensity ( )

背景的亮度,单位是尼特(坎德拉/平方米)。仅当启用 ProjectSettings.rendering/lights_and_shadows/use_physical_light_units 时使用。默认值大致相当于正午时分的天空。


BGMode background_mode = 0

  • void set_background ( BGMode value )

  • BGMode get_background ( )

背景模式。可能的取值见 BGMode


float fog_aerial_perspective = 0.0

  • void set_fog_aerial_perspective ( float value )

  • float get_fog_aerial_perspective ( )

如果设置大于 0.0(不含),会在雾的颜色和背景 Sky 的颜色之间进行混合。设置大于 0.0 时有较小的性能代价。必须将 background_mode 设置为 BG_SKY

对于模拟雾密度较低的大场景中的空气透视很有用。但对于高密度的雾来说不是很有用,因为天空会被照亮。设置为 1.0 时,雾的颜色完全来自 Sky。设置为 0.0 时,会禁用空气透视。


float fog_density = 0.01

  • void set_fog_density ( float value )

  • float get_fog_density ( )

要使用的指数形式雾密度。值越高雾越密。雾的渲染是指数式的,和现实生活中相同。


bool fog_enabled = false

  • void set_fog_enabled ( bool value )

  • bool is_fog_enabled ( )

如果为 true,则启用雾效果。


float fog_height = 0.0

  • void set_fog_height ( float value )

  • float get_fog_height ( )

高度雾效果开始的高度。


float fog_height_density = 0.0

  • void set_fog_height_density ( float value )

  • float get_fog_height_density ( )

用于随着高度降低而增加雾的密度。要使雾随着高度增加而增加,请使用负值。


Color fog_light_color = Color(0.518, 0.553, 0.608, 1)

  • void set_fog_light_color ( Color value )

  • Color get_fog_light_color ( )

雾的颜色。


float fog_light_energy = 1.0

  • void set_fog_light_energy ( float value )

  • float get_fog_light_energy ( )

雾的亮度。值越高,雾越亮。


float fog_sky_affect = 1.0

  • void set_fog_sky_affect ( float value )

  • float get_fog_sky_affect ( )

非体积雾影响天空时使用的系数。1.0 表示雾可以完全遮蔽天空。较低的值会减少雾对天空渲染的影响,0.0 完全不影响天空的渲染。

注意:如果 fog_aerial_perspective1.0fog_sky_affect 不会有视觉效果。


float fog_sun_scatter = 0.0

  • void set_fog_sun_scatter ( float value )

  • float get_fog_sun_scatter ( )

如果设置为 0.0 以上,则根据视角以雾色渲染场景的定向光。这可以用来给人一种太阳正在“穿透”雾的印象。


GlowBlendMode glow_blend_mode = 2

辉光混合模式。


float glow_bloom = 0.0

  • void set_glow_bloom ( float value )

  • float get_glow_bloom ( )

泛光的强度。如果设置为大于 0 的值,则将在比 glow_hdr_threshold 成员更暗的区域中显示辉光。


bool glow_enabled = false

  • void set_glow_enabled ( bool value )

  • bool is_glow_enabled ( )

如果为 true,则启用辉光效果。

注意:只有 Forward+ 和 Mobile 渲染方法支持辉光,Compatibility 不支持。使用 Mobile 渲染方法时,辉光的外观会有些不同,因为 Mobile 渲染方法可用的动态范围较低。


float glow_hdr_luminance_cap = 12.0

  • void set_glow_hdr_luminance_cap ( float value )

  • float get_glow_hdr_luminance_cap ( )

HDR 辉光的较高阈值。比这个阈值更亮的区域将被限制,以达到辉光效果的目的。


float glow_hdr_scale = 2.0

  • void set_glow_hdr_bleed_scale ( float value )

  • float get_glow_hdr_bleed_scale ( )

HDR 辉光的逸出缩放。


float glow_hdr_threshold = 1.0

  • void set_glow_hdr_bleed_threshold ( float value )

  • float get_glow_hdr_bleed_threshold ( )

HDR 辉光的下限阈值。当使用 Mobile 渲染方法时(仅支持较低的动态范围,最大为 2.0),需要低于 1.0 才能看到辉光。在这种情况下取 0.9 可以达到不错的效果。在 2D 中使用辉光时也需要降低到 1.0 以下,因为 2D 渲染使用 SDR。


float glow_intensity = 0.8

  • void set_glow_intensity ( float value )

  • float get_glow_intensity ( )

辉光效果的整体亮度倍数。使用 Mobile 渲染方法时(仅支持较低的动态范围,最大为 2.0),应将其增加到 1.5 进行补偿。


float glow_levels/1 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

第 1 级辉光的强度。这是最“局部”的级别(最不模糊)。


float glow_levels/2 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

第 2 级辉光的强度。


float glow_levels/3 = 1.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

第 3 级辉光的强度。


float glow_levels/4 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

第 4 级辉光的强度。


float glow_levels/5 = 1.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

第 5 级辉光的强度。


float glow_levels/6 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

第 6 级辉光的强度。


float glow_levels/7 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

第 7 级辉光的强度。这是最“全局”的级别(最模糊)。


Texture glow_map

该纹理应被用作一个辉光贴图,以根据 glow_map_strength 乘以 生成的辉光颜色。这可以用来创建一个“镜头污垢”效果。该纹理的 RGB 颜色通道被用于调制,但 Alpha 通道将被忽略。

注意:该纹理将被拉伸以适应屏幕。因此,建议使用长宽比与项目的基本长宽比(通常为 16:9)相匹配的纹理。


float glow_map_strength = 0.8

  • void set_glow_map_strength ( float value )

  • float get_glow_map_strength ( )

glow_map 应该对整体发光效果产生多大的影响。0.0 的强度,表示辉光贴图对整体辉光效果没有影响。1.0 的强度,表示辉光对整体辉光效果具有完全的效果(如果辉光贴图有黑色区域,则可以在屏幕的特定区域完全关闭辉光)。


float glow_mix = 0.05

  • void set_glow_mix ( float value )

  • float get_glow_mix ( )

当使用 GLOW_BLEND_MODE_MIX glow_blend_mode 时,它控制源图像与辉光层混合的程度。0.0 的值使辉光渲染不可见,而 1.0 的值等效于 GLOW_BLEND_MODE_REPLACE


bool glow_normalized = false

  • void set_glow_normalized ( bool value )

  • bool is_glow_normalized ( )

如果为 true,则辉光级别将被归一化,使强度的总和等于