Work in progress
Godot documentation is being updated to reflect the latest changes in version
4.0. Some documentation pages may
still state outdated information. This banner will tell you if you're reading one of such pages.
The contents of this page are up to date. If you can still find outdated information, please open an issue.
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¶
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
Methods¶
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
The global brightness value of the rendered scene. Effective only if adjustment_enabled is true.
Texture 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
The global contrast value of the rendered scene (default value is 1). Effective only if adjustment_enabled is true.
bool adjustment_enabled = false
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.
Note: Adjustments are only supported in the Forward+ and Mobile rendering methods, not Compatibility.
float adjustment_saturation = 1.0
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)
The ambient light's Color. Only effective if ambient_light_sky_contribution is lower than 1.0 (exclusive).
float ambient_light_energy = 1.0
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
void set_ambient_source ( AmbientSource value )
AmbientSource get_ambient_source ( )
The ambient light source to use for rendering materials and global illumination.
int background_camera_feed_id = 1
The ID of the camera feed to show in the background.
int background_canvas_max_layer = 0
The maximum layer ID to display. Only effective when using the BG_CANVAS background mode.
Color background_color = Color(0, 0, 0, 1)
The Color displayed for clear areas of the scene. Only effective when using the BG_COLOR background mode.
float background_energy_multiplier = 1.0
Multiplier for background energy. Increase to make background brighter, decrease to make background dimmer.
float background_intensity = 30000.0
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
The background mode. See BGMode for possible values.
float fog_aerial_perspective = 0.0
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
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
If true, fog effects are enabled.
float fog_height = 0.0
The height at which the height fog effect begins.
float fog_height_density = 0.0
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)
The fog's color.
float fog_light_energy = 1.0
The fog's brightness. Higher values result in brighter fog.
float fog_sky_affect = 1.0
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
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
void set_glow_blend_mode ( GlowBlendMode value )
GlowBlendMode get_glow_blend_mode ( )
The glow blending mode.
float glow_bloom = 0.0
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
If true, the glow effect is enabled.
Note: Glow is only supported in the Forward+ and Mobile rendering methods, not Compatibility. When using the Mobile rendering method, glow will look different due to the lower dynamic range available in the Mobile rendering method.
float glow_hdr_luminance_cap = 12.0
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
The bleed scale of the HDR glow.
float glow_hdr_threshold = 1.0
The lower threshold of the HDR glow. When using the Mobile rendering method (which only supports a lower dynamic range up to 2.0), this may need to be below 1.0 for glow to be visible. A value of 0.9 works well in this case. This value also needs to be decreased below 1.0 when using glow in 2D, as 2D rendering is performed in SDR.
float glow_intensity = 0.8
The overall brightness multiplier of the glow effect. When using the Mobile rendering method (which only supports a lower dynamic range up to 2.0), this should be increased to 1.5 to compensate.
float glow_levels/1 = 0.0
The intensity of the 1st level of glow. This is the most "local" level (least blurry).
float glow_levels/2 = 0.0
The intensity of the 2nd level of glow.
float glow_levels/3 = 1.0
The intensity of the 3rd level of glow.
float glow_levels/4 = 0.0
The intensity of the 4th level of glow.
float glow_levels/5 = 1.0
The intensity of the 5th level of glow.
float glow_levels/6 = 0.0
void set_glow_level (