Environment

Inherits: Resource < RefCounted < Object

Resource for environment nodes (like WorldEnvironment) that define multiple rendering options.

Description

Resource for environment nodes (like WorldEnvironment) that define multiple environment operations (such as background Sky or Color, ambient light, fog, depth-of-field...). These parameters affect the final render of the scene. The order of these operations is:

  • Depth of Field Blur

  • Glow

  • Tonemap (Auto Exposure)

  • Adjustments

Tutorials

Properties

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

Methods

float

get_glow_level ( int idx ) const

void

set_glow_level ( int idx, float intensity )


Enumerations

enum BGMode:

BGMode BG_CLEAR_COLOR = 0

Clears the background using the clear color defined in ProjectSettings.rendering/environment/defaults/default_clear_color.

BGMode BG_COLOR = 1

Clears the background using a custom clear color.

BGMode BG_SKY = 2

Displays a user-defined sky in the background.

BGMode BG_CANVAS = 3

Displays a CanvasLayer in the background.

BGMode BG_KEEP = 4

Keeps on screen every pixel drawn in the background. This is the fastest background mode, but it can only be safely used in fully-interior scenes (no visible sky or sky reflections). If enabled in a scene where the background is visible, "ghost trail" artifacts will be visible when moving the camera.

BGMode BG_CAMERA_FEED = 5

Displays a camera feed in the background.

BGMode BG_MAX = 6

Represents the size of the BGMode enum.


enum AmbientSource:

AmbientSource AMBIENT_SOURCE_BG = 0

Gather ambient light from whichever source is specified as the background.

AmbientSource AMBIENT_SOURCE_DISABLED = 1

Disable ambient light. This provides a slight performance boost over AMBIENT_SOURCE_SKY.

AmbientSource AMBIENT_SOURCE_COLOR = 2

Specify a specific Color for ambient light. This provides a slight performance boost over AMBIENT_SOURCE_SKY.

AmbientSource AMBIENT_SOURCE_SKY = 3

Gather ambient light from the Sky regardless of what the background is.


enum ReflectionSource:

ReflectionSource REFLECTION_SOURCE_BG = 0

Use the background for reflections.

ReflectionSource REFLECTION_SOURCE_DISABLED = 1

Disable reflections. This provides a slight performance boost over other options.

ReflectionSource REFLECTION_SOURCE_SKY = 2

Use the Sky for reflections regardless of what the background is.


enum ToneMapper:

ToneMapper TONE_MAPPER_LINEAR = 0

Linear tonemapper operator. Reads the linear data and passes it on unmodified. This can cause bright lighting to look blown out, with noticeable clipping in the output colors.

ToneMapper TONE_MAPPER_REINHARDT = 1

Reinhardt tonemapper operator. Performs a variation on rendered pixels' colors by this formula: color = color / (1 + color). This avoids clipping bright highlights, but the resulting image can look a bit dull.

ToneMapper TONE_MAPPER_FILMIC = 2

Filmic tonemapper operator. This avoids clipping bright highlights, with a resulting image that usually looks more vivid than TONE_MAPPER_REINHARDT.

ToneMapper TONE_MAPPER_ACES = 3

Use the Academy Color Encoding System tonemapper. ACES is slightly more expensive than other options, but it handles bright lighting in a more realistic fashion by desaturating it as it becomes brighter. ACES typically has a more contrasted output compared to TONE_MAPPER_REINHARDT and TONE_MAPPER_FILMIC.

Note: This tonemapping operator is called "ACES Fitted" in Godot 3.x.


enum GlowBlendMode:

GlowBlendMode GLOW_BLEND_MODE_ADDITIVE = 0

Additive glow blending mode. Mostly used for particles, glows (bloom), lens flare, bright sources.

GlowBlendMode GLOW_BLEND_MODE_SCREEN = 1

Screen glow blending mode. Increases brightness, used frequently with bloom.

GlowBlendMode GLOW_BLEND_MODE_SOFTLIGHT = 2

Soft light glow blending mode. Modifies contrast, exposes shadows and highlights (vivid bloom).

GlowBlendMode GLOW_BLEND_MODE_REPLACE = 3

Replace glow blending mode. Replaces all pixels' color by the glow value. This can be used to simulate a full-screen blur effect by tweaking the glow parameters to match the original image's brightness.

GlowBlendMode GLOW_BLEND_MODE_MIX = 4

Mixes the glow with the underlying color to avoid increasing brightness as much while still maintaining a glow effect.


enum SDFGIYScale:

SDFGIYScale SDFGI_Y_SCALE_50_PERCENT = 0

Use 50% scale for SDFGI on the Y (vertical) axis. SDFGI cells will be twice as short as they are wide. This allows providing increased GI detail and reduced light leaking with thin floors and ceilings. This is usually the best choice for scenes that don't feature much verticality.

SDFGIYScale SDFGI_Y_SCALE_75_PERCENT = 1

Use 75% scale for SDFGI on the Y (vertical) axis. This is a balance between the 50% and 100% SDFGI Y scales.

SDFGIYScale SDFGI_Y_SCALE_100_PERCENT = 2

Use 100% scale for SDFGI on the Y (vertical) axis. SDFGI cells will be as tall as they are wide. This is usually the best choice for highly vertical scenes. The downside is that light leaking may become more noticeable with thin floors and ceilings.


Property Descriptions

float adjustment_brightness = 1.0

  • void set_adjustment_brightness ( float value )

  • float get_adjustment_brightness ( )

The global brightness value of the rendered scene. Effective only if adjustment_enabled is true.


Texture adjustment_color_correction

  • void set_adjustment_color_correction ( Texture value )

  • Texture get_adjustment_color_correction ( )

The Texture2D or Texture3D lookup table (LUT) to use for the built-in post-process color grading. Can use a GradientTexture1D for a 1-dimensional LUT, or a Texture3D for a more complex LUT. Effective only if adjustment_enabled is true.


float adjustment_contrast = 1.0

  • void set_adjustment_contrast ( float value )

  • float get_adjustment_contrast ( )

The global contrast value of the rendered scene (default value is 1). Effective only if adjustment_enabled is true.


bool adjustment_enabled = false

  • void set_adjustment_enabled ( bool value )

  • bool is_adjustment_enabled ( )

If true, enables the adjustment_* properties provided by this resource. If false, modifications to the adjustment_* properties will have no effect on the rendered scene.


float adjustment_saturation = 1.0

  • void set_adjustment_saturation ( float value )

  • float get_adjustment_saturation ( )

The global color saturation value of the rendered scene (default value is 1). Effective only if adjustment_enabled is true.


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

  • void set_ambient_light_color ( Color value )

  • Color get_ambient_light_color ( )

The ambient light's Color. Only effective if ambient_light_sky_contribution is lower than 1.0 (exclusive).


float ambient_light_energy = 1.0

  • void set_ambient_light_energy ( float value )

  • float get_ambient_light_energy ( )

The ambient light's energy. The higher the value, the stronger the light. Only effective if ambient_light_sky_contribution is lower than 1.0 (exclusive).


float ambient_light_sky_contribution = 1.0

  • void set_ambient_light_sky_contribution ( float value )

  • float get_ambient_light_sky_contribution ( )

Defines the amount of light that the sky brings on the scene. A value of 0.0 means that the sky's light emission has no effect on the scene illumination, thus all ambient illumination is provided by the ambient light. On the contrary, a value of 1.0 means that all the light that affects the scene is provided by the sky, thus the ambient light parameter has no effect on the scene.

Note: ambient_light_sky_contribution is internally clamped between 0.0 and 1.0 (inclusive).


AmbientSource ambient_light_source = 0

The ambient light source to use for rendering materials and global illumination.


int background_camera_feed_id = 1

  • void set_camera_feed_id ( int value )

  • int get_camera_feed_id ( )

The ID of the camera feed to show in the background.


int background_canvas_max_layer = 0

  • void set_canvas_max_layer ( int value )

  • int get_canvas_max_layer ( )

The maximum layer ID to display. Only effective when using the BG_CANVAS background mode.


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

  • void set_bg_color ( Color value )

  • Color get_bg_color ( )

The Color displayed for clear areas of the scene. Only effective when using the BG_COLOR background mode.


float background_energy_multiplier = 1.0

  • void set_bg_energy_multiplier ( float value )

  • float get_bg_energy_multiplier ( )

Multiplier for background energy. Increase to make background brighter, decrease to make background dimmer.


float background_intensity = 30000.0

  • void set_bg_intensity ( float value )

  • float get_bg_intensity ( )

Luminance of background measured in nits (candela per square meter). Only used when ProjectSettings.rendering/lights_and_shadows/use_physical_light_units is enabled. The default value is roughly equivalent to the sky at midday.


BGMode background_mode = 0

  • void set_background ( BGMode value )

  • BGMode get_background ( )

The background mode. See BGMode for possible values.


float fog_aerial_perspective = 0.0

  • void set_fog_aerial_perspective ( float value )

  • float get_fog_aerial_perspective ( )

If set above 0.0 (exclusive), blends between the fog's color and the color of the background Sky. This has a small performance cost when set above 0.0. Must have background_mode set to BG_SKY.

This is useful to simulate aerial perspective in large scenes with low density fog. However, it is not very useful for high-density fog, as the sky will shine through. When set to 1.0, the fog color comes completely from the Sky. If set to 0.0, aerial perspective is disabled.


float fog_density = 0.01

  • void set_fog_density ( float value )

  • float get_fog_density ( )

The exponential fog density to use. Higher values result in a more dense fog. Fog rendering is exponential as in real life.


bool fog_enabled = false

  • void set_fog_enabled ( bool value )

  • bool is_fog_enabled ( )

If true, fog effects are enabled.


float fog_height = 0.0

  • void set_fog_height ( float value )

  • float get_fog_height ( )

The height at which the height fog effect begins.


float fog_height_density = 0.0

  • void set_fog_height_density ( float value )

  • float get_fog_height_density ( )

The density used to increase fog as height decreases. To make fog increase as height increases, use a negative value.


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

  • void set_fog_light_color ( Color value )

  • Color get_fog_light_color ( )

The fog's color.


float fog_light_energy = 1.0

  • void set_fog_light_energy ( float value )

  • float get_fog_light_energy ( )

The fog's brightness. Higher values result in brighter fog.


float fog_sky_affect = 1.0

  • void set_fog_sky_affect ( float value )

  • float get_fog_sky_affect ( )

The factor to use when affecting the sky with non-volumetric fog. 1.0 means that fog can fully obscure the sky. Lower values reduce the impact of fog on sky rendering, with 0.0 not affecting sky rendering at all.

Note: fog_sky_affect has no visual effect if fog_aerial_perspective is 1.0.


float fog_sun_scatter = 0.0

  • void set_fog_sun_scatter ( float value )

  • float get_fog_sun_scatter ( )

If set above 0.0, renders the scene's directional light(s) in the fog color depending on the view angle. This can be used to give the impression that the sun is "piercing" through the fog.


GlowBlendMode glow_blend_mode = 2

The glow blending mode.


float glow_bloom = 0.0

  • void set_glow_bloom ( float value )

  • float get_glow_bloom ( )

The bloom's intensity. If set to a value higher than 0, this will make glow visible in areas darker than the glow_hdr_threshold.


bool glow_enabled = false

  • void set_glow_enabled ( bool value )

  • bool is_glow_enabled ( )

If true, the glow effect is enabled.


float glow_hdr_luminance_cap = 12.0

  • void set_glow_hdr_luminance_cap ( float value )

  • float get_glow_hdr_luminance_cap ( )

The higher threshold of the HDR glow. Areas brighter than this threshold will be clamped for the purposes of the glow effect.


float glow_hdr_scale = 2.0

  • void set_glow_hdr_bleed_scale ( float value )

  • float get_glow_hdr_bleed_scale ( )

The bleed scale of the HDR glow.


float glow_hdr_threshold = 1.0

  • void set_glow_hdr_bleed_threshold ( float value )

  • float get_glow_hdr_bleed_threshold ( )

The lower threshold of the HDR glow. When using the OpenGL renderer (which doesn't support HDR), this needs to be below 1.0 for glow to be visible. A value of 0.9 works well in this case.


float glow_intensity = 0.8

  • void set_glow_intensity ( float value )

  • float get_glow_intensity ( )

The overall brightness multiplier of the glow effect. When using the OpenGL renderer, this should be increased to 1.5 to compensate for the lack of HDR rendering.


float glow_levels/1 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

The intensity of the 1st level of glow. This is the most "local" level (least blurry).


float glow_levels/2 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

The intensity of the 2nd level of glow.


float glow_levels/3 = 1.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

The intensity of the 3rd level of glow.


float glow_levels/4 = 0.0

  • void set_glow_level ( int idx, float intensity )

  • float get_glow_level ( int idx ) const

The intensity of the 4th