From 4fbcc19853703bfcd4ad5caf06583226ffe0ec7f Mon Sep 17 00:00:00 2001 From: Hugo Locurcio Date: Tue, 7 Jan 2020 17:18:57 +0100 Subject: [PATCH] Complete the Environment class documentation This closes #34846. --- doc/classes/Environment.xml | 174 +++++++++++++++++++++--------------- 1 file changed, 102 insertions(+), 72 deletions(-) diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index 1feccec5010..00a80a084b4 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -21,6 +21,7 @@ + Returns [code]true[/code] if the glow level [code]idx[/code] is specified, [code]false[/code] otherwise. @@ -31,132 +32,134 @@ + Enables or disables the glow level at index [code]idx[/code]. The more glow levels are enabled, the slower the glow effect will be. - Global brightness value of the rendered scene (default value is 1). + The global brightness value of the rendered scene. Effective only if [code]adjustment_enabled[/code] is [code]true[/code]. - Applies the provided [Texture] resource to affect the global color aspect of the rendered scene. + Applies the provided [Texture] resource to affect the global color aspect of the rendered scene. Effective only if [code]adjustment_enabled[/code] is [code]true[/code]. - Global contrast value of the rendered scene (default value is 1). + The global contrast value of the rendered scene (default value is 1). Effective only if [code]adjustment_enabled[/code] is [code]true[/code]. - Enables the [code]adjustment_*[/code] options provided by this resource. If [code]false[/code], adjustments modifications will have no effect on the rendered scene. + If [code]true[/code], enables the [code]adjustment_*[/code] properties provided by this resource. If [code]false[/code], modifications to the [code]adjustment_*[/code] properties will have no effect on the rendered scene. - Global color saturation value of the rendered scene (default value is 1). + The global color saturation value of the rendered scene (default value is 1). Effective only if [code]adjustment_enabled[/code] is [code]true[/code]. - [Color] of the ambient light. + The ambient light's [Color]. - Energy of the ambient light. The higher the value, the stronger the light. + The ambient light's energy. The higher the value, the stronger the light. Defines the amount of light that the sky brings on the scene. A value of 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 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. + This value is multiplied by [member ambient_light_energy], so it must be set to a value higher than [code]0[/code] for changes to be visible when adjusting [member ambient_light_sky_contribution]. - Enables the tonemapping auto exposure mode of the scene renderer. If activated, the renderer will automatically determine the exposure setting to adapt to the illumination of the scene and the observed light. + If [code]true[/code], enables the tonemapping auto exposure mode of the scene renderer. If [code]true[/code], the renderer will automatically determine the exposure setting to adapt to the scene's illumination and the observed light. - Maximum luminance value for the auto exposure. + The maximum luminance value for the auto exposure. - Minimum luminance value for the auto exposure. + The minimum luminance value for the auto exposure. - Scale of the auto exposure effect. Affects the intensity of auto exposure. + The scale of the auto exposure effect. Affects the intensity of auto exposure. - Speed of the auto exposure effect. Affects the time needed for the camera to perform auto exposure. + The speed of the auto exposure effect. Affects the time needed for the camera to perform auto exposure. - The id of the camera feed to show in the background. + The ID of the camera feed to show in the background. - Maximum layer id (if using Layer background mode). + The maximum layer ID to display. Only effective when using the [constant BG_CANVAS] background mode. - Color displayed for clear areas of the scene (if using Custom color or Color+Sky background modes). + The [Color] displayed for clear areas of the scene. Only effective when using the [constant BG_COLOR] or [constant BG_COLOR_SKY] background modes). - Power of light emitted by the background. + The power of the light emitted by the background. - Defines the mode of background. + The background mode. See [enum BGMode] for possible values. - [Sky] resource defined as background. + The [Sky] resource defined as background. - [Sky] resource's custom field of view. + The [Sky] resource's custom field of view. - [Sky] resource's rotation expressed as a [Basis]. + The [Sky] resource's rotation expressed as a [Basis]. - [Sky] resource's rotation expressed as Euler angles in radians. + The [Sky] resource's rotation expressed as Euler angles in radians. - [Sky] resource's rotation expressed as Euler angles in degrees. + The [Sky] resource's rotation expressed as Euler angles in degrees. - Amount of far blur. + The amount of far blur for the depth-of-field effect. - Distance from the camera where the far blur effect affects the rendering. + The distance from the camera where the far blur effect affects the rendering. - Enables the far blur effect. + If [code]true[/code], enables the depth-of-field far blur effect. - Quality of the far blur quality. + The depth-of-field far blur's quality. Higher values can mitigate the visible banding effect seen at higher strengths, but are much slower. - Transition between no-blur area and far blur. + The length of the transition between the no-blur area and far blur. - Amount of near blur. + The amount of near blur for the depth-of-field effect. Distance from the camera where the near blur effect affects the rendering. - Enables the near blur effect. + If [code]true[/code], enables the depth-of-field near blur effect. - Quality of the near blur quality. + The depth-of-field near blur's quality. Higher values can mitigate the visible banding effect seen at higher strengths, but are much slower. - Transition between near blur and no-blur area. + The length of the transition between the near blur and no-blur area. - Fog's [Color]. + The fog's [Color]. - Fog's depth starting distance from the camera. + The fog's depth starting distance from the camera. - Value defining the fog depth intensity. + The fog depth's intensity curve. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. - Enables the fog depth. + If [code]true[/code], the depth fog effect is enabled. When enabled, fog will appear in the distance (relative to the camera). - Fog's depth end distance from the camera. If this value is set to 0, it will be equal to the current camera's [member Camera.far] value. + The fog's depth end distance from the camera. If this value is set to 0, it will be equal to the current camera's [member Camera.far] value. - Enables the fog. Needs [member fog_height_enabled] and/or [member fog_depth_enabled] to actually display fog. + If [code]true[/code], fog effects are enabled. [member fog_height_enabled] and/or [member fog_depth_enabled] must be set to [code]true[/code] to actually display fog. - Value defining the fog height intensity. + The height fog's intensity. A number of presets are available in the [b]Inspector[/b] by right-clicking the curve. - Enables the fog height. + If [code]true[/code], the height fog effect is enabled. When enabled, fog will appear in a defined height range, regardless of the distance from the camera. This can be used to simulate "deep water" effects with a lower performance cost compared to a dedicated shader. The Y coordinate where the height fog will be the most intense. If this value is greater than [member fog_height_min], fog will be displayed from bottom to top. Otherwise, it will be displayed from top to bottom. @@ -165,131 +168,151 @@ The Y coordinate where the height fog will be the least intense. If this value is greater than [member fog_height_max], fog will be displayed from top to bottom. Otherwise, it will be displayed from bottom to top. - Amount of sun that affects the fog rendering. + The intensity of the depth fog color transition when looking towards the sun. The sun's direction is determined automatically using the DirectionalLight node in the scene. - Sun [Color]. + The depth fog's [Color] when looking towards the sun. - Amount of light that the fog transmits. + The intensity of the fog light transmittance effect. Amount of light that the fog transmits. - Enables fog's light transmission. If enabled, lets reflections light to be transmitted by the fog. + Enables fog's light transmission effect. If [code]true[/code], light will be more visible in the fog to simulate light scattering as in real life. - Smooths out blockiness created by sampling higher levels. + Smooths out the blockiness created by sampling higher levels, at the cost of performance. + [b]Note:[/b] Only available when using the GLES3 renderer. - Glow blending mode. + The glow blending mode. - Bloom value (global glow). + The bloom's intensity. If set to a value higher than [code]0[/code], this will make glow visible in areas darker than the [member glow_hdr_threshold]. - Enables glow rendering. + If [code]true[/code], the glow effect is enabled. + The higher threshold of the HDR glow. Areas brighter than this threshold will be clamped for the purposes of the glow effect. - Bleed scale of the HDR glow. + The bleed scale of the HDR glow. - Bleed threshold of the HDR glow. In GLES2, this needs to be below 1.0 in order for glow to be visible, a default value of 0.9 works well. + The lower threshold of the HDR glow. When using the GLES2 renderer (which doesn't support HDR), this needs to be below [code]1.0[/code] for glow to be visible. A value of [code]0.9[/code] works well in this case. - Glow intensity. In GLES2, this should be increased to 1.5 by default to compensate for not using HDR. + The glow intensity. When using the GLES2 renderer, this should be increased to 1.5 to compensate for the lack of HDR rendering. - First level of glow (most local). + If [code]true[/code], the 1st level of glow is enabled. This is the most "local" level (least blurry). - Second level of glow. + If [code]true[/code], the 2th level of glow is enabled. - Third level of glow. + If [code]true[/code], the 3th level of glow is enabled. - Fourth level of glow. + If [code]true[/code], the 4th level of glow is enabled. - Fifth level of glow. + If [code]true[/code], the 5th level of glow is enabled. - Sixth level of glow. + If [code]true[/code], the 6th level of glow is enabled. - Seventh level of glow (most global). + If [code]true[/code], the 7th level of glow is enabled. This is the most "global" level (blurriest). - Glow strength. In GLES2, this should be increased to 1.3 by default to compensate for not using HDR. + The glow strength. When using the GLES2 renderer, this should be increased to 1.3 to compensate for the lack of HDR rendering. + The depth tolerance for screen-space reflections. + If [code]true[/code], screen-space reflections are enabled. Screen-space reflections are more accurate than reflections from [GIProbe]s or [ReflectionProbe]s, but are slower and can't reflect surfaces occluded by others. + The fade-in distance for screen-space reflections. Affects the area from the reflected material to the screen-space reflection). + The fade-out distance for screen-space reflections. Affects the area from the screen-space reflection to the "global" reflection. + The maximum number of steps for screen-space reflections. Higher values are slower. + If [code]true[/code], screen-space reflections will take the material roughness into account. + The screen-space ambient occlusion intensity on materials that have an AO texture defined. Values higher than [code]0[/code] will make the SSAO effect visible in areas darkened by AO textures. + The screen-space ambient occlusion bias. This should be kept high enough to prevent "smooth" curves from being affected by ambient occlusion. + The screen-space ambient occlusion blur quality. See [enum SSAOBlur] for possible values. + The screen-space ambient occlusion color. + The screen-space ambient occlusion edge sharpness. + If [code]true[/code], the screen-space ambient occlusion effect is enabled. This is a costly effect and should be disabled first when having performance issues. + The primary screen-space ambient occlusion intensity. See also [member ssao_radius]. + The secondary screen-space ambient occlusion intensity. See also [member ssao_radius2]. + The screen-space ambient occlusion intensity in direct light. In real life, ambient occlusion only applies to indirect light, which means its effects can't be seen in direct light. Values higher than [code]0[/code] will make the SSAO effect visible in direct light. + The screen-space ambient occlusion quality. Higher qualities will make better use of small objects for ambient occlusion, but are slower. + The primary screen-space ambient occlusion radius. + The secondary screen-space ambient occlusion radius. If set to a value higher than [code]0[/code], enables the secondary screen-space ambient occlusion effect which can be used to improve the effect's appearance (at the cost of performance). - Default exposure for tonemap. + The default exposure used for tonemapping. - Tonemapping mode. + The tonemapping mode to use. Tonemapping is the process that "converts" HDR values to be suitable for rendering on a LDR display. (Godot doesn't support rendering on HDR displays yet.) - White reference value for tonemap. + The white reference value for tonemapping. Only effective if the [member tonemap_mode] isn't set to [constant TONE_MAPPER_LINEAR]. - Keep on screen every pixel drawn in the background. + 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. - Clear the background using the project's clear color. + Clears the background using the clear color defined in [member ProjectSettings.rendering/environment/default_clear_color]. - Clear the background using a custom clear color. + Clears the background using a custom clear color. - Display a user-defined sky in the background. + Displays a user-defined sky in the background. - Clear the background using a custom clear color and allows defining a sky for shading and reflection. + Clears the background using a custom clear color and allows defining a sky for shading and reflection. This mode is slightly faster than [constant BG_SKY] and should be preferred in scenes where reflections can be visible, but the sky itself never is (e.g. top-down camera). - Display a [CanvasLayer] in the background. + Displays a [CanvasLayer] in the background. - Display a camera feed in the background. + Displays a camera feed in the background. Represents the size of the [enum BGMode] enum. @@ -301,10 +324,10 @@ Screen glow blending mode. Increases brightness, used frequently with bloom. - Soft light glow blending mode. Modifies contrast, exposes shadows and highlights, vivid bloom. + Soft light glow blending mode. Modifies contrast, exposes shadows and highlights (vivid bloom). - Replace glow blending mode. Replaces all pixels' color by the glow value. + 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. Linear tonemapper operator. Reads the linear data and passes it on unmodified. @@ -319,27 +342,34 @@ Academy Color Encoding System tonemapper operator. - Low depth-of-field blur quality. + Low depth-of-field blur quality (fastest). Medium depth-of-field blur quality. - High depth-of-field blur quality. + High depth-of-field blur quality (slowest). + No blur for the screen-space ambient occlusion effect (fastest). + 1×1 blur for the screen-space ambient occlusion effect. + 2×2 blur for the screen-space ambient occlusion effect. + 3×3 blur for the screen-space ambient occlusion effect (slowest). + Low quality for the screen-space ambient occlusion effect (fastest). + Low quality for the screen-space ambient occlusion effect. + Low quality for the screen-space ambient occlusion effect (slowest).