From 1b2cd9f2519d54c0cf9cf58939f09d7a6834f292 Mon Sep 17 00:00:00 2001 From: clayjohn Date: Sun, 3 Oct 2021 04:28:55 -0700 Subject: Addition of FogVolumes, FogShaders, FogMaterial, and overhaul of VolumetricFog Co-authored-by: Brian Semrau --- doc/classes/Environment.xml | 36 ++++++++++++-------- doc/classes/FogMaterial.xml | 31 +++++++++++++++++ doc/classes/FogVolume.xml | 23 +++++++++++++ doc/classes/ProjectSettings.xml | 5 ++- doc/classes/RenderingServer.xml | 74 ++++++++++++++++++++++++++++++++++++----- doc/classes/Shader.xml | 3 ++ doc/classes/VisualShader.xml | 5 ++- 7 files changed, 153 insertions(+), 24 deletions(-) create mode 100644 doc/classes/FogMaterial.xml create mode 100644 doc/classes/FogVolume.xml (limited to 'doc') diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index 80298a0319..57f6e9547a 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -248,23 +248,41 @@ The white reference value for tonemapping. Only effective if the [member tonemap_mode] isn't set to [constant TONE_MAPPER_LINEAR]. - + + The [Color] of the volumetric fog when interacting with lights. Mist and fog have an albedo close to [code]Color(1, 1, 1, 1)[/code] while smoke has a darker albedo. + + + Scales the strength of ambient light used in the volumetric fog. A value of [code]0[/code] means that ambient light will not impact the volumetric fog. + + + The direction of scattered light as it goes through the volumetric fog. A value close [code]1[/code] means almost all light is scattered forward. A value close to [code]0[/code] means light is scattered equally in all directions. A value close to [code]-1[/code] means light is scattered mostly backward. Fog and mist scatter light slightly forward, while smoke scatters light equally in all directions. + + + The base density of the volumetric fog. Set this to the lowest density you want to have globally. + The distribution of size down the length of the froxel buffer. A higher value compresses the froxels closer to the camera and places more detail closer to the camera. + + + The emitted light from the volumetric fog. Even with emission, volumetric fog will not cast light onto other surfaces. Emission is useful to establish an ambient color. As the volumetric fog effect uses single-scattering only, fog tends to need a little bit of emission to soften the harsh shadows. + + + The brightness of the emitted light from the volumetric fog. + Enables the volumetric fog effect. Volumetric fog uses a screen-aligned froxel buffer to calculate accurate volumetric scattering in the short to medium range. Volumetric fog interacts with [FogVolume]s and lights to calculate localized and global fog. Volumetric fog uses a PBR single-scattering model based on extinction, scattering, and emission which it exposes to users as density, albedo, and emission. + Scales the strength of Global Illumination used in the volumetric fog. A value of [code]0[/code] means that Global Illumination will not impact the volumetric fog. - - - - + The distance over which the volumetric fog is computed. Increase to compute fog over a greater range, decrease to add more detail when a long range is not needed. For best quality fog, keep this as low as possible. + The amount by which to blend the last frame with the current frame. A higher number results in smoother volumetric fog, but makes "ghosting" much worse. A lower value reduces ghosting but can result in the per-frame temporal jitter becoming visible. + Enables temporal reprojection in the volumetric fog. Temporal reprojection blends the current frame's volumetric fog with the last frame's volumetric fog to smooth out jagged edges. The performance cost is minimal, however it does lead to moving [FogVolume]s and [Light3D]s "ghosting" and leaving a trail behind them. When temporal reprojection is enabled, try to avoid moving [FogVolume]s or [Light3D]s too fast. @@ -349,13 +367,5 @@ - - - - - - - - diff --git a/doc/classes/FogMaterial.xml b/doc/classes/FogMaterial.xml new file mode 100644 index 0000000000..431f3ac2b7 --- /dev/null +++ b/doc/classes/FogMaterial.xml @@ -0,0 +1,31 @@ + + + + [Material] used with a [FogVolume] to draw things with the volumetric fog effect. + + + A [Material] resource that can be used by [FogVolume]s to draw volumetric effects. + + + + + + Sets the single-scattering [Color] of the [FogVolume]. Internally [member albedo] is converted into single-scattering which is additively blended with other [FogVolume]s and the [member Environment.volumetric_fog_albedo]. + + + Sets the density of the [FogVolume]. Denser objects are more opaque, but may suffer from under-sampling artifacts that look like stripes. + + + Sets a 3D texture that is used to scale the [member density] of the [FogVolume]. + + + Sets the hardness of the edges of the [FogVolume]. A higher number will result in softer edges while a lower number will result in harder edges. + + + Sets the [Color] of the light emitted by the [FogVolume]. Emitted light will not cast light or shadows on other objects, but can be useful for modulating the [Color] of the [FogVolume] independently from light sources. + + + Sets the rate by which the height-based fog decreases in density as height increases in world space. A high falloff will result in a sharp transition, while a low falloff will result in a smoother transition. A value of [code]0[/code] results in uniform-density fog. The height threshold is determined by the height of the associated [FogVolume]. + + + diff --git a/doc/classes/FogVolume.xml b/doc/classes/FogVolume.xml new file mode 100644 index 0000000000..ba1b5d3372 --- /dev/null +++ b/doc/classes/FogVolume.xml @@ -0,0 +1,23 @@ + + + + A node used to add local fog with the volumetric fog effect. + + + [FogVolume]s are used to add localized fog into the global volumetric fog effect. + Performance of [FogVolume]s is directly related to their relative size on the screen and the complexity of their attached [FogMaterial]. It is best to keep [FogVolume]s relatively small and simple where possible. + + + + + + Sets the size of the [FogVolume] when [member shape] is [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID] or [constant RenderingServer.FOG_VOLUME_SHAPE_BOX]. + + + Sets the [Material] to be used by the [FogVolume]. Can be either a [FogMaterial] or a custom [ShaderMaterial]. + + + Sets the shape of the [FogVolume] to either [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_BOX], or [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID] or [constant RenderingServer.FOG_VOLUME_SHAPE_WORLD]. + + + diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index c646380bee..e67ccf9efd 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -1577,10 +1577,13 @@ Scales the distance over which samples are taken for subsurface scattering effect. Changing this does not impact performance, but higher values will result in significant artifacts as the samples will become obviously spread out. A lower value results in a smaller spread of scattered light. + Enables filtering of the volumetric fog effect prior to integration. This substantially blurs the fog which reduces fine details but also smooths out harsh edges and aliasing artifacts. Disable when more detail is required. - + + Number of slices to use along the depth of the froxel buffer for volumetric fog. A lower number will be more efficient but may result in artifacts appearing during camera movement. + Base size used to determine size of froxel buffer in the camera X-axis and Y-axis. The final size is scaled by the aspect ratio of the screen, so actual values may differ from what is set. Set a larger size for more detailed fog, set a smaller size for better performance. diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index b53233add5..86e66a5738 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -1120,13 +1120,16 @@ - - - - - - - + + + + + + + + + + @@ -1134,6 +1137,7 @@ + Enables filtering of the volumetric fog scattering buffer. This results in much smoother volumes with very few under-sampling artifacts. @@ -1141,6 +1145,37 @@ + Sets the resolution of the volumetric fog's froxel buffer. [code]size[/code] is modified by the screen's aspect ratio and then used to set the width and height of the buffer. While [code]depth[/code] is directly used to set the depth of the buffer. + + + + + + Creates a new fog volume and allocates an RID. + + + + + + + + Sets the size of the fog volume when shape is [constant FOG_VOLUME_SHAPE_ELLIPSOID] or [constant FOG_VOLUME_SHAPE_BOX]. + + + + + + + + Sets the [Material] of the fog volume. Can be either a [FogMaterial] or a custom [ShaderMaterial]. + + + + + + + + Sets the shape of the fog volume to either [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID], [constant RenderingServer.FOG_VOLUME_SHAPE_BOX], or [constant RenderingServer.FOG_VOLUME_SHAPE_ELLIPSOID] or [constant RenderingServer.FOG_VOLUME_SHAPE_WORLD]. @@ -1430,6 +1465,13 @@ Sets a margin to increase the size of the AABB when culling objects from the view frustum. This allows you to avoid culling objects that fall outside the view frustum. Equivalent to [member GeometryInstance3D.extra_cull_margin]. + + + + + + + @@ -3417,7 +3459,10 @@ Shader is a sky shader. - + + Shader is a fog shader. + + Represents the size of the [enum ShaderMode] enum. @@ -3789,6 +3834,15 @@ + + [FogVolume] will be shaped like an ellipsoid. + + + [FogVolume] will be shaped like a box. + + + [FogVolume] will have no shape, will cover the whole world and will not be culled. + Do not update the viewport. @@ -4155,7 +4209,9 @@ - + + + Represents the size of the [enum InstanceType] enum. diff --git a/doc/classes/Shader.xml b/doc/classes/Shader.xml index 14c5ba9247..99e38e969d 100644 --- a/doc/classes/Shader.xml +++ b/doc/classes/Shader.xml @@ -60,5 +60,8 @@ Mode used for drawing skies. Only works with shaders attached to [Sky] objects. + + Mode used for setting the color and density of volumetric fog effect. + diff --git a/doc/classes/VisualShader.xml b/doc/classes/VisualShader.xml index cdb9de4f86..d7b4673b9f 100644 --- a/doc/classes/VisualShader.xml +++ b/doc/classes/VisualShader.xml @@ -176,7 +176,10 @@ - + + A compute shader that runs for each froxel of the volumetric fog map. + + Represents the size of the [enum Type] enum. -- cgit v1.2.3