From b50d954cb01e67eda2184b76f81d637d76d6894c Mon Sep 17 00:00:00 2001 From: clayjohn Date: Thu, 16 Apr 2020 16:05:25 -0700 Subject: [PATCH] Update many docs with recent rendering changes --- doc/classes/BaseMaterial3D.xml | 78 +++++++++++++------- doc/classes/Decal.xml | 111 +++++++++++++++++++++++++++++ doc/classes/DirectionalLight3D.xml | 9 +-- doc/classes/Environment.xml | 10 ++- doc/classes/Light3D.xml | 37 ++++++---- doc/classes/ProjectSettings.xml | 61 ++++++++++------ doc/classes/RenderingServer.xml | 98 ++++++++++++++++++------- doc/classes/Sky.xml | 2 +- doc/classes/Viewport.xml | 42 ++++++++++- scene/main/scene_tree.cpp | 2 +- scene/main/viewport.cpp | 4 ++ servers/rendering_server.cpp | 4 ++ 12 files changed, 365 insertions(+), 93 deletions(-) create mode 100644 doc/classes/Decal.xml diff --git a/doc/classes/BaseMaterial3D.xml b/doc/classes/BaseMaterial3D.xml index 5bb94d28587b..145809aabca1 100644 --- a/doc/classes/BaseMaterial3D.xml +++ b/doc/classes/BaseMaterial3D.xml @@ -108,6 +108,15 @@ Specifies the channel of the [member ao_texture] in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. + + The color used by the backlight effect. Represents the light passing through an object. + + + If [code]true[/code], the backlight effect is enabled. + + + Texture used to control the backlight effect per-pixel. Added to [member backlight]. + If [code]true[/code], the shader will keep the scale set for the mesh. Otherwise the scale is lost when billboarding. Only applies when [member billboard_mode] is [constant BILLBOARD_ENABLED]. @@ -296,6 +305,7 @@ Specifies the channel of the [member ao_texture] in which the ambient occlusion information is stored. This is useful when you store the information for multiple effects in a single texture. For example if you stored metallic in the red channel, roughness in the blue, and ambient occlusion in the green you could reduce the number of textures you use. + Sets whether the shading takes place per-pixel or per-vertex. Per-vertex lighting is faster, making it the best choice for mobile applications, however it looks considerably worse than per-pixel. If [code]true[/code], enables the "shadow to opacity" render mode where lighting modifies the alpha so shadowed areas are opaque and non-shadowed areas are transparent. Useful for overlaying shadows onto a camera feed in AR. @@ -307,6 +317,7 @@ If [code]true[/code], subsurface scattering is enabled. Emulates light that penetrates an object's surface, is scattered, and then emerges. + If [code]true[/code], subsurface scattering will use a special mode optimized for the color and density of human skin. The strength of the subsurface scattering effect. @@ -314,21 +325,24 @@ Texture used to control the subsurface scattering strength. Stored in the red texture channel. Multiplied by [member subsurf_scatter_strength]. + + + + + + + + + + + + Filter flags for the texture. See [enum TextureFilter] for options. Repeat flags for the texture. See [enum TextureFilter] for options. - - The color used by the transmission effect. Represents the light passing through an object. - - - If [code]true[/code], the transmission effect is enabled. - - - Texture used to control the transmission effect per-pixel. Added to [member transmission]. - If [code]true[/code], transparency is enabled on the body. See also [member blend_mode]. @@ -407,39 +421,47 @@ Texture specifying per-pixel subsurface scattering. - - Texture specifying per-pixel transmission color. + + Texture specifying per-pixel transmittance for subsurface scattering. - + + Texture specifying per-pixel backlight color. + + Texture specifying per-pixel refraction strength. - + Texture specifying per-pixel detail mask blending value. - + Texture specifying per-pixel detail color. - + Texture specifying per-pixel detail normal. - + + Texture holding, ambient occlusion, roughness, and metallic. - + Represents the size of the [enum TextureParam] enum. The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. - The texture filter blends between the nearest four pixels. Use this for most cases where you want to avoid a pixelated style. + The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. Use this for most cases as mipmaps are important to smooth out pixels that are far from the camera. + The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. + The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. Represents the size of the [enum TextureFilter] enum. @@ -457,8 +479,10 @@ The material will use the texture's alpha values for transparency. + The material will cut off all values below a threshold, the rest will remain opaque. + The material will use the texture's alpha value for transparency, but will still be rendered in the pre-pass. Represents the size of the [enum Transparency] enum. @@ -494,20 +518,24 @@ Constant for setting [member ao_enabled]. + Constant for setting [member heightmap_enabled]. - + Constant for setting [member subsurf_scatter_enabled]. - - Constant for setting [member transmission_enabled]. + + Constant for setting [member subsurf_scatter_transmittance_enabled]. - + + Constant for setting [member backlight_enabled]. + + Constant for setting [member refraction_enabled]. - + Constant for setting [member detail_enabled]. - + Represents the size of the [enum Feature] enum. @@ -589,11 +617,13 @@ Enables the shadow to opacity feature. + Enables the texture to repeat when UV coordinates are outside the 0-1 range. If using one of the linear filtering modes, this can result in artifacts at the edges of a texture when the sampler filters across the edges of the texture. Invert values read from a depth texture to convert them to height values (heightmap). + Enables the skin mode for subsurface scattering which is used to improve the look of subsurface scattering when used for human skin. Represents the size of the [enum Flags] enum. diff --git a/doc/classes/Decal.xml b/doc/classes/Decal.xml new file mode 100644 index 000000000000..f7329d1537d0 --- /dev/null +++ b/doc/classes/Decal.xml @@ -0,0 +1,111 @@ + + + + Node that projects a texture onto a [MeshInstance3D]. + + + [Decal]s are used to project a texture onto a [Mesh] in the scene. Use Decals to add detail to a scene without affecting the underlying [Mesh]. They are often used to add weathering to building, add dirt or mud to the ground, or add variety to props. Decals can be moved at any time, making them suitable for things like blob shadows or laser sight dots. + They are made of an [AABB] and a group of [Texture2D]s specifying [Color], normal, ORM (ambient occlusion, roughness, metallic), and emission. Decals are projected within their [AABB] so altering the orientation of the Decal affects the direction in which they are projected. By default, Decals are projected down (i.e. from positive Y to negative Y). + The [Texture2D]s associated with the Decal are automatically stored in a texture atlas which is used for drawing the decals so all decals can be drawn at once. Godot uses clustered decals, meaning they are stored in cluster data and drawn when the mesh is drawn, they are not drawn as a postprocessing effect after. + + + + + + + + + + + Returns the [Texture2D] associated with the specified [enum DecalTexture]. This is a convenience method, in most cases you should access the texture directly. + For example, instead of [code]albedo_tex = $Decal.get_texture(Decal.TEXTURE_ALBEDO)[/code], use [code]albedo_tex = $Decal.texture_albedo[/code]. + One case where this is better than accessing the texture directly is when you want to copy one Decal's textures to another. For example: + [codeblock] + for i in Decal.TEXTURE_MAX: + $NewDecal.set_texture(i, $OldDecal.get_texture(i)) + [/codeblock] + + + + + + + + + + + Sets the [Texture2D] associated with the specified [enum DecalTexture]. This is a convenience method, in most cases you should access the texture directly. + For example, instead of [code]$Decal.set_texture(Decal.TEXTURE_ALBEDO, albedo_tex)[/code], use [code]$Decal.texture_albedo = albedo_tex[/code]. + One case where this is better than accessing the texture directly is when you want to copy one Decal's textures to another. For example: + [codeblock] + for i in Decal.TEXTURE_MAX: + $NewDecal.set_texture(i, $OldDecal.get_texture(i)) + [/codeblock] + + + + + + Blends the albedo [Color] of the decal with albedo [Color] of the underlying mesh. + + + Specifies which [member VisualInstance3D.layers] this decal will project on. By default, Decals affect all layers. This is used so you can specify which types of objects receive the Decal and which do not. This is especially useful so you an ensure that dynamic objects don't accidentally receive a Decal intended for the terrain under them. + + + Distance from the camera at which the Decal begins to fade away. + + + If [code]true[/code], decals will smoothly fade away when far from the active [Camera3D] starting at [member distance_fade_begin]. The Decal will fade out over [member distance_fade_length], after which it will be culled and not sent to the shader at all. Use this to reduce the number of active Decals in a scene and thus improve performance. + + + Distance over which the Decal fades. The Decal becomes slowly more transparent over this distance and is completely invisible at the end. + + + Energy multiplier for the emission texture. This will make the decal emit light at a higher intensity. + + + Sets the size of the [AABB] used by the decal. The AABB goes from [code]-extents[/code] to [code]extents[/code]. + + + Sets the curve over which the decal will fade as the surface gets further from the center of the [AABB]. + + + Changes the [Color] of the Decal by multiplying it with this value. + + + Fades the Decal if the angle between the Decal's [AABB] and the target surface becomes too large. A value of [code]0[/code] projects the Decal regardless of angle, a value of [code]1[/code] limits the Decal to surfaces that are nearly perpendicular. + + + [Texture2D] with the base [Color] of the Decal. Either this or the [member texture_emission] must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object. + + + [Texture2D] with the emission [Color] of the Decal. Either this or the [member texture_emission] must be set for the Decal to be visible. Use the alpha channel like a mask to smoothly blend the edges of the decal with the underlying object. + + + [Texture2D] with the per-pixel normalmap for the decal. Use this to add extra detail to decals. + + + [Texture2D] storing ambient occlusion, roughness, and metallic for the decal. Use this to add extra detail to decals. + + + Sets the curve over which the decal will fade as the surface gets further from the center of the [AABB]. + + + + + [Texture2D] corresponding to [member texture_albedo]. + + + [Texture2D] corresponding to [member texture_normal]. + + + [Texture2D] corresponding to [member texture_orm]. + + + [Texture2D] corresponding to [member texture_emission]. + + + Max size of [enum DecalTexture] enum. + + + diff --git a/doc/classes/DirectionalLight3D.xml b/doc/classes/DirectionalLight3D.xml index a5d476f5c83e..6c88dcf42e44 100644 --- a/doc/classes/DirectionalLight3D.xml +++ b/doc/classes/DirectionalLight3D.xml @@ -12,9 +12,6 @@ - - Amount of extra bias for shadow splits that are far away. If self-shadowing occurs only on the splits far away, increasing this value can fix them. - If [code]true[/code], shadow detail is sacrificed in exchange for smoother transitions between splits. @@ -22,6 +19,7 @@ Optimizes shadow rendering for detail versus movement. See [enum ShadowDepthRange]. + Proportion of [member directional_shadow_max_distance] at which point the shadow starts to fade. At [member directional_shadow_max_distance] the shadow will disappear. The maximum distance for shadow splits. @@ -29,8 +27,8 @@ The light's shadow rendering algorithm. See [enum ShadowMode]. - - Can be used to fix special cases of self shadowing when objects are perpendicular to the light. + + Sets the size of the directional shadow pancake. The pancake offsets the start of the shadow's camera frustum to provide a higher effective depth resolution for the shadow. However, a high pancake size can cause artifacts in the shadows of large objects that are close to the edge of the frustum. Reducing the pancake size can help. Setting the size to [code]0[/code] turns off the pancaking effect. The distance from camera to shadow split 1. Relative to [member directional_shadow_max_distance]. Only used when [member directional_shadow_mode] is [code]SHADOW_PARALLEL_2_SPLITS[/code] or [code]SHADOW_PARALLEL_4_SPLITS[/code]. @@ -41,7 +39,6 @@ The distance from shadow split 2 to split 3. Relative to [member directional_shadow_max_distance]. Only used when [member directional_shadow_mode] is [code]SHADOW_PARALLEL_4_SPLITS[/code]. - diff --git a/doc/classes/Environment.xml b/doc/classes/Environment.xml index 6f55bfc229a2..3642d92771b8 100644 --- a/doc/classes/Environment.xml +++ b/doc/classes/Environment.xml @@ -265,18 +265,25 @@ Represents the size of the [enum BGMode] enum. + Gather ambient light from whichever source is specified as the background. + Disable ambient light. + Specify a specific [Color] for ambient light. + Gather ambient light from the [Sky] regardless of what the background is. + Use the background for reflections. + Disable reflections. + Use the [Sky] for reflections regardless of what the background is. Additive glow blending mode. Mostly used for particles, glows (bloom), lens flare, bright sources. @@ -291,6 +298,7 @@ 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. + Mixes the glow with the underlying color to avoid increasing brightness as much while still maintaining a glow effect. Linear tonemapper operator. Reads the linear data and passes it on unmodified. @@ -314,7 +322,7 @@ 2×2 blur for the screen-space ambient occlusion effect. - 3×3 blur for the screen-space ambient occlusion effect (slowest). + 3×3 blur for the screen-space ambient occlusion effect. Increases the radius of the blur for a smoother look, but can result in checkerboard-like artifacts. diff --git a/doc/classes/Light3D.xml b/doc/classes/Light3D.xml index 623b2a2bb08e..ef9c3b49b783 100644 --- a/doc/classes/Light3D.xml +++ b/doc/classes/Light3D.xml @@ -56,13 +56,16 @@ If [code]true[/code], the light's effect is reversed, darkening areas and casting bright shadows. + + [Texture2D] projected by light. [member shadow_enabled] must be on for the projector to work. Light projectors make the light appear as if it is shining through a colored but transparent object, almost like light shining through stained glass. + The size of the light in Godot units. Only available for [OmniLight3D]s and [SpotLight3D]s. The intensity of the specular blob in objects affected by the light. At [code]0[/code] the light becomes a pure diffuse light. - + Used to adjust shadow appearance. Too small a value results in self-shadowing, while too large a value causes shadows to separate from casters. Adjust as needed. @@ -71,15 +74,17 @@ The color of shadows cast by this light. - - Attempts to reduce [member shadow_bias] gap. - If [code]true[/code], the light will cast shadows. + + Offsets the lookup into the shadow map by the objects normal. This can be used reduce self-shadowing artifacts without using [member shadow_bias]. In practice, this value should be tweaked along with [member shadow_bias] to reduce artifacts as much as possible. + If [code]true[/code], reverses the backface culling of the mesh. This can be useful when you have a flat mesh that has a light behind it. If you need to cast a shadow on both sides of the mesh, set the mesh to use double-sided shadows with [constant GeometryInstance3D.SHADOW_CASTING_SETTING_DOUBLE_SIDED]. + + @@ -94,18 +99,15 @@ Constant for accessing [member OmniLight3D.omni_range] or [member SpotLight3D.spot_range]. - + Constant for accessing [member OmniLight3D.omni_attenuation] or [member SpotLight3D.spot_attenuation]. - + Constant for accessing [member SpotLight3D.spot_angle]. - + Constant for accessing [member SpotLight3D.spot_angle_attenuation]. - - Constant for accessing [member shadow_contact]. - Constant for accessing [member DirectionalLight3D.directional_shadow_max_distance]. @@ -119,17 +121,24 @@ Constant for accessing [member DirectionalLight3D.directional_shadow_split_3]. + Constant for accessing [member DirectionalLight3D.directional_shadow_fade_start]. - Constant for accessing [member DirectionalLight3D.directional_shadow_normal_bias]. + Constant for accessing [member shadow_normal_bias]. Constant for accessing [member shadow_bias]. - - Constant for accessing [member DirectionalLight3D.directional_shadow_bias_split_scale]. + + Constant for accessing [member DirectionalLight3D.directional_shadow_pancake_size]. - + + Constant for accessing [member shadow_blur]. + + + Constant for accessing [member shadow_transmittance_bias]. + + Represents the size of the [enum Param] enum. diff --git a/doc/classes/ProjectSettings.xml b/doc/classes/ProjectSettings.xml index 67a033dacafc..09a19058aba0 100644 --- a/doc/classes/ProjectSettings.xml +++ b/doc/classes/ProjectSettings.xml @@ -982,6 +982,15 @@ If [code]true[/code], forces snapping of polygons to pixels in 2D rendering. May help in some pixel art styles. + + Sets the quality of the depth of field effect. Higher quality takes more samples, which is slower but looks smoother. + + + Sets the depth of field shape. Can be Box, Hexagon, or Circle. Box is the fastest. Circle is the most realistic, but also the most expensive to compute. + + + If [code]true[/code], jitters DOF samples to make effect slightly blurrier and hide lines created from low sample rates. This can result in a slightly grainy appearance when used with a low number of samples. + Disables depth pre-pass for some GPU vendors (usually mobile), as their architecture already does this. @@ -998,7 +1007,7 @@ Quality setting for shadows cast by [DirectionalLight3D]s. Higher quality settings use more samples when reading from shadow maps and are thus slower. Low quality settings may result in shadows looking grainy. - Lower-end override for [member rendering/quality/directional_shadow/soft_shadow_quality] on mobile devices, due to performance concerns or driver support. + Lower-end override for [member rendering/quality/directional_shadow/soft_shadow_quality] on mobile devices, due to performance concerns or driver support. The video driver to use ("GLES2" or "Vulkan"). @@ -1006,32 +1015,17 @@ [b]FIXME:[/b] No longer valid after DisplayServer split: In such cases, this property is not updated, so use [code]OS.get_current_video_driver[/code] to query it at run-time. - - - - - - - - - - Sets the number of MSAA samples to use. MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. - [b]Note:[/b] MSAA is not available on HTML5 export using the GLES2 backend. - - - - - - - If [code]true[/code], uses nearest-neighbor mipmap filtering when using mipmaps (also called "bilinear filtering"), which will result in visible seams appearing between mipmap stages. This may increase performance in mobile as less memory bandwidth is used. If [code]false[/code], linear mipmap filtering (also called "trilinear filtering") is used. - + If [code]true[/code], take additional samples when rendering objects affected by a [GIProbe] to reduce artifacts from only sampling in one direction. + Sets the number of cone samples taken when rendering objects affected by [GIProbe]s. + Sets how the glow effect is upscaled before being copied onto the screen. Linear is faster, but looks blocky. Bicubic is slower but looks smooth. + Lower-end override for [member rendering/quality/glow/upscale_mode] on mobile devices, due to performance concerns or driver support. Strategy used for framebuffer allocation. The simpler it is, the less resources it uses (but the less features it supports). If set to "2D Without Sampling" or "3D Without Effects", sample buffers will not be allocated. This means [code]SCREEN_TEXTURE[/code] and [code]DEPTH_TEXTURE[/code] will not be available in shaders and post-processing effects will not be available in the [Environment]. @@ -1066,7 +1060,22 @@ Lower-end override for [member rendering/quality/reflections/texture_array_reflections] on mobile devices, due to performance concerns or driver support. + + Sets the number of MSAA samples to use. MSAA is used to reduce aliasing around the edges of polygons. A higher MSAA value results in smoother edges but can be significantly slower on some hardware. + [b]Note:[/b] MSAA is not available on HTML5 export using the GLES2 backend. + + + Sets the screen-space antialiasing mode for the default screen [Viewport]. Screen-space antialiasing works by selectively blurring edges in a post-process shader. It differs from MSAA which takes multiple coverage samples while rendering objects. Screen-space AA methods are typically faster than MSAA and will smooth out specular aliasing, but tend to make scenes appear blurry. + Another way to combat specular aliasing is to enable [member rendering/quality/screen_filters/screen_space_roughness_limiter]. + + + Enables the screen-space roughness limiter which increases material roughness in areas with a high normal frequency (i.e. when normals change a lot from pixel to pixel). This helps to reduce the amount of specular aliasing in a scene. Specular aliasing looks like random bright pixels that occur in reflections. + + + Curves the amount of the roughness limited effect. A higher value limits the effect to very sharply curved surfaces, while a lower threshold extends the effect to smoother surfaces. + + Sets the quality for rough screen-space reflections. Turning off will make all screen space reflections sharp, while higher values make rough reflections look better. If [code]true[/code], uses faster but lower-quality Blinn model to generate blurred reflections instead of the GGX model. @@ -1111,14 +1120,26 @@ Lower-end override for [member rendering/quality/shadows/soft_shadow_quality] on mobile devices, due to performance concerns or driver support. + If [code]true[/code], screen-space ambient occlusion will be rendered at half size and then upscaled before being added to the scene. This is significantly faster but may miss small details. + Sets the quality of the screen-space ambient occlusion effect. Higher values take more samples and so will result in better quality, at the cost of performance. + Scales the depth over which the subsurface scattering effect is applied. A high value may allow light to scatter into a part of the mesh or another mesh that is close in screen space but far in depth. + Sets the quality of the subsurface scattering effect. Higher values are slower but look nicer. + 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. + + + Sets the maximum number of samples to take when using anisotropic filtering on textures. A higher sample count will result in sharper textures at oblique angles, but is more expensive to compute. + Only power of two values are valid ([code]1[/code], [code]2[/code], [code]4[/code], [code]8[/code], [code]16[/code]). A value of [code]1[/code] forcibly disables anisotropic filtering, even on materials where it is enabled. + + + If [code]true[/code], uses nearest-neighbor mipmap filtering when using mipmaps (also called "bilinear filtering"), which will result in visible seams appearing between mipmap stages. This may increase performance in mobile as less memory bandwidth is used. If [code]false[/code], linear mipmap filtering (also called "trilinear filtering") is used. Thread model for rendering. Rendering on a thread can vastly improve performance, but synchronizing to the main thread can cause a bit more jitter. diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml index bfdcf1bb7909..7dd5e8bd8de0 100644 --- a/doc/classes/RenderingServer.xml +++ b/doc/classes/RenderingServer.xml @@ -4,12 +4,12 @@ Server for anything visible. - Server for anything visible. The visual server is the API backend for everything visible. The whole scene system mounts on it to display. - The visual server is completely opaque, the internals are entirely implementation specific and cannot be accessed. - The visual server can be used to bypass the scene system entirely. + Server for anything visible. The rendering server is the API backend for everything visible. The whole scene system mounts on it to display. + The rendering server is completely opaque, the internals are entirely implementation specific and cannot be accessed. + The rendering server can be used to bypass the scene system entirely. Resources are created using the [code]*_create[/code] functions. All objects are drawn to a viewport. You can use the [Viewport] attached to the [SceneTree] or you can create one yourself with [method viewport_create]. When using a custom scenario or canvas, the scenario or canvas needs to be attached to the viewport using [method viewport_set_scenario] or [method viewport_attach_canvas]. - In 3D, all visual objects must be associated with a scenario. The scenario is a visual representation of the world. If accessing the visual server from a running game, the scenario can be accessed from the scene tree from any [Node3D] node with [method Node3D.get_world]. Otherwise, a scenario can be created with [method scenario_create]. + In 3D, all visual objects must be associated with a scenario. The scenario is a visual representation of the world. If accessing the rendering server from a running game, the scenario can be accessed from the scene tree from any [Node3D] node with [method Node3D.get_world]. Otherwise, a scenario can be created with [method scenario_create]. Similarly in 2D, a canvas is needed to draw all canvas items. In 3D, all visible objects are comprised of a resource and an instance. A resource can be a mesh, a particle system, a light, or any other 3D object. In order to be visible resources must be attached to an instance using [method instance_set_base]. The instance must also be attached to the scenario using [method instance_set_scenario] in order to be visible. In 2D, all visible objects are some form of canvas item. In order to be visible, a canvas item needs to be the child of a canvas attached to a viewport, or it needs to be the child of another canvas item that is eventually attached to the canvas. @@ -1113,7 +1113,7 @@ - Initializes the visual server. This function is called internally by platform-dependent code during engine initialization. If called from a running game, it will not do anything. + Initializes the rendering server. This function is called internally by platform-dependent code during engine initialization. If called from a running game, it will not do anything. @@ -3307,6 +3307,7 @@ Proportion of shadow atlas occupied by the third split. The fourth split occupies the rest. + Proportion of shadow max distance where the shadow will start to fade out. Normal bias used to offset shadow lookup by object normal. Can be used to fix self-shadowing artifacts. @@ -3314,10 +3315,15 @@ Bias the shadow lookup to fix self-shadowing artifacts. - - Increases bias on further splits to fix self-shadowing that only occurs far away from the camera. + + Sets the size of the directional shadow pancake. The pancake offsets the start of the shadow's camera frustum to provide a higher effective depth resolution for the shadow. However, a high pancake size can cause artifacts in the shadows of large objects that are close to the edge of the frustum. Reducing the pancake size can help. Setting the size to [code]0[/code] turns off the pancaking effect. - + + Blurs the edges of the shadow. Can be used to hide pixel artifacts in low resolution shadow maps. A high value can make shadows appear grainy and can cause other unwanted artifacts. Try to keep as near default as possible. + + + + Represents the size of the [enum LightParam] enum. @@ -3383,22 +3389,16 @@ Multisample antialiasing is disabled. - Multisample antialiasing is set to 2×. + Multisample antialiasing uses 2 samples per pixel. - Multisample antialiasing is set to 4×. + Multisample antialiasing uses 4 samples per pixel. - Multisample antialiasing is set to 8×. + Multisample antialiasing uses 8 samples per pixel. - Multisample antialiasing is set to 16×. - - - Multisample antialiasing is set to 2× on external texture. Special mode for GLES2 Android VR (Oculus Quest and Go). - - - Multisample antialiasing is set to 4× on external texture. Special mode for GLES2 Android VR (Oculus Quest and Go). + Multisample antialiasing uses 16 samples per pixel. Number of objects drawn in a single frame. @@ -3425,37 +3425,52 @@ Debug draw is disabled. Default setting. - Debug draw sets objects to unshaded. + Objects are displayed without light information. + Objects are displayed with only light information. - Overwrites clear color to [code](0,0,0,0)[/code]. + Objects are displayed semi-transparent with additive blending so you can see where they are drawing over top of one another. A higher overdraw means you are wasting performance on drawing pixels that are being hidden behind others. Debug draw draws objects in wireframe. + Normal buffer is drawn instead of regular scene so you can see the per-pixel normals that will be used by post-processing effects. + Objects are displayed with only the albedo value from [GIProbe]s. + Objects are displayed with only the lighting value from [GIProbe]s. + Objects are displayed with only the emission color from [GIProbe]s. + Draws the shadow atlas that stores shadows from [OmniLight3D]s and [SpotLight3D]s in the upper left quadrant of the [Viewport]. + Draws the shadow atlas that stores shadows from [DirectionalLight3D]s in the upper left quadrant of the [Viewport]. + Draws the screen space ambient occlusion texture instead of the scene so that you can clearly see how it is affecting objects. In order for this display mode to work, you must have [member Environment.ssao_enabled] set in your [WorldEnvironment]. + Draws the roughness limiter post process over the Viewport so you can see where it has an effect. It must be enabled in [member ProjectSettings.rendering/quality/screen_filters/screen_space_roughness_limiter] to work. + + + Colors each PSSM split for the [DirectionalLight3D]s in the scene a different color so you can see where the splits are. In order they will be colored red, green, blue, yellow. + Uses high quality importance sampling to process the radiance map. In general, this results in much higher quality than [constant Sky.PROCESS_MODE_REALTIME] but takes much longer to generate. This should not be used if you plan on changing the sky at runtime. If you are finding that the reflection is not blurry enough and is showing sparkles or fireflies, try increasing [member ProjectSettings.rendering/quality/reflections/ggx_samples]. + Uses the fast filtering algorithm to process the radiance map. In general this results in lower quality, but substantially faster run times. + [b]Note:[/b] The fast filtering algorithm is limited to 256x256 cubemaps, so [member Sky.radiance_size] must be set to [constant Sky.RADIANCE_SIZE_256]. Use the clear color as background. @@ -3479,28 +3494,40 @@ Represents the size of the [enum EnvironmentBG] enum. + Gather ambient light from whichever source is specified as the background. + Disable ambient light. + Specify a specific [Color] for ambient light. + Gather ambient light from the [Sky] regardless of what the background is. + Use the background for reflections. + Disable reflections. + Use the [Sky] for reflections regardless of what the background is. + Additive glow blending mode. Mostly used for particles, glows (bloom), lens flare, bright sources. + Screen glow blending mode. Increases brightness, used frequently with 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. This can be used to simulate a full-screen blur effect by tweaking the glow parameters to match the original image's brightness. + Mixes the glow with the underlying color to avoid increasing brightness as much while still maintaining a glow effect. Output color as they came in. @@ -3533,23 +3560,31 @@ Medium quality screen space ambient occlusion. - Highest quality screen space ambient occlusion. + High quality screen space ambient occlusion. + Highest quality screen space ambient occlusion. + Lowest quality DOF blur. This is the fastest setting, but you may be able to see filtering artifacts. + Low quality DOF blur. + Medium quality DOF blur. + Highest quality DOF blur. Results in the smoothest looking blur by taking the most samples, but is also significantly slower. + Calculate the DOF blur using a box filter. The fastest option, but results in obvious lines in blur pattern. + Calculates DOF blur using a hexagon shaped filter. + Calculates DOF blur using a circle shaped filter. Best quality and most realistic, but slowest. Use only for areas where a lot of performance can be dedicated to post-processing (e.g. cutscenes). Do not use a debug mode. @@ -3584,13 +3619,13 @@ The instance is a reflection probe. - + The instance is a GI probe. - + The instance is a lightmap capture. - + Represents the size of the [enum InstanceType] enum. @@ -3600,6 +3635,7 @@ Allows the instance to be used in baked lighting. + Allows the instance to be used with dynamic global illumination. When set, manually requests to draw geometry on next frame. @@ -3629,30 +3665,43 @@ The nine patch gets filled with tiles where needed and stretches them a bit if needed. + Uses the default filter mode for this [Viewport]. + The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. + The texture filter reads from the nearest pixel, but selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. + The texture filter blends between the nearest 4 pixels and selects a mipmap based on the angle between the surface and the camera view. This reduces artifacts on surfaces that are almost in line with the camera. This is the slowest of the filtering options, but results in the highest quality texturing. + Max value for [enum CanvasItemTextureFilter] enum. + Uses the default repeat mode for this [Viewport]. + Disables textures repeating. Instead, when reading UVs outside the 0-1 range, the value will be clamped to the edge of the texture, resulting in a stretched out look at the borders of the texture. + Enables the texture to repeat when UV coordinates are outside the 0-1 range. If using one of the linear filtering modes, this can result in artifacts at the edges of a texture when the sampler filters across the edges of the texture. + Flip the texture when repeating so that the edge lines up instead of abruptly changing. + Max value for [enum CanvasItemTextureRepeat] enum. Adds light color additive to the canvas. @@ -3676,6 +3725,7 @@ Use PCF13 filtering to filter canvas light shadows. + Max value of the [enum CanvasLightShadowFilter] enum. Culling of the canvas occluder is disabled. diff --git a/doc/classes/Sky.xml b/doc/classes/Sky.xml index f574f4243162..78c75d9c2bdc 100644 --- a/doc/classes/Sky.xml +++ b/doc/classes/Sky.xml @@ -49,7 +49,7 @@ Represents the size of the [enum RadianceSize] enum. - Uses high quality importance sampling to process the radiance map. In general, this results in much higher quality than [constant PROCESS_MODE_REALTIME] but takes much longer to generate. This should not be used if you plan on changing the sky at runtime. + Uses high quality importance sampling to process the radiance map. In general, this results in much higher quality than [constant PROCESS_MODE_REALTIME] but takes much longer to generate. This should not be used if you plan on changing the sky at runtime. If you are finding that the reflection is not blurry enough and is showing sparkles or fireflies, try increasing [member ProjectSettings.rendering/quality/reflections/ggx_samples]. Uses the fast filtering algorithm to process the radiance map. In general this results in lower quality, but substantially faster run times. diff --git a/doc/classes/Viewport.xml b/doc/classes/Viewport.xml index 5826822c6e54..88839ce9af9c 100644 --- a/doc/classes/Viewport.xml +++ b/doc/classes/Viewport.xml @@ -192,8 +192,10 @@ If [code]true[/code], the viewport will process 3D audio streams. + Sets the default filter mode used by [CanvasItem]s in this Viewport. See [enum DefaultCanvasItemTextureFilter] for options. + Sets the default repeat mode used by [CanvasItem]s in this Viewport. See [enum DefaultCanvasItemTextureRepeat] for options. The canvas transform of the viewport, useful for changing the on-screen positions of all child [CanvasItem]s. This is relative to the global canvas transform of the viewport. @@ -223,6 +225,9 @@ If [code]true[/code], the objects rendered by viewport become subjects of mouse picking process. + + Sets the screen-space antialiasing method used. Screen-space antialiasing works by selectively blurring edges in a post-process shader. It differs from MSAA which takes multiple coverage samples while rendering objects. Screen-space AA methods are typically faster than MSAA and will smooth out specular aliasing, but tend to make scenes appear blurry. + The subdivision amount of the first quadrant on the shadow atlas. @@ -316,27 +321,42 @@ Objects are displayed without light information. - Objected are displayed semi-transparent with additive blending so you can see where they intersect. + Objects are displayed semi-transparent with additive blending so you can see where they are drawing over top of one another. A higher overdraw means you are wasting performance on drawing pixels that are being hidden behind others. Objects are displayed in wireframe style. + Objects are displayed with only the albedo value from [GIProbe]s. + Objects are displayed with only the lighting value from [GIProbe]s. + Objects are displayed with only the emission color from [GIProbe]s. + Draws the shadow atlas that stores shadows from [OmniLight3D]s and [SpotLight3D]s in the upper left quadrant of the [Viewport]. + Draws the shadow atlas that stores shadows from [DirectionalLight3D]s in the upper left quadrant of the [Viewport]. + Draws the screen-space ambient occlusion texture instead of the scene so that you can clearly see how it is affecting objects. In order for this display mode to work, you must have [member Environment.ssao_enabled] set in your [WorldEnvironment]. + + + Draws the roughness limiter post process over the Viewport so you can see where it has an effect. It must be enabled in [member ProjectSettings.rendering/quality/screen_filters/screen_space_roughness_limiter] to work. + + + Colors each PSSM split for the [DirectionalLight3D]s in the scene a different color so you can see where the splits are. In order, they will be colored red, green, blue, and yellow. + + + Draws the decal atlas used by [Decal]s and light projector textures in the upper left quadrant of the [Viewport]. - Multisample anti-aliasing mode disabled. This is the default value. + Multisample antialiasing mode disabled. This is the default value, and also the fastest setting. Use 2x Multisample Antialiasing. @@ -350,23 +370,41 @@ Use 16x Multisample Antialiasing. Likely unsupported on medium and low-end hardware. + + Do not perform any antialiasing in the full screen post-process. + + + Use fast approximate antialiasing. FXAA is a popular screen-space antialising method, which is fast but will make the image look blurry, especially at lower resolutions. It can still work relatively well at large resolutions such as 1440p and 4K. + + + Max enum for screen-space antialiasing effects. + + The texture filter reads from the nearest pixel only. The simplest and fastest method of filtering, but the texture will look pixelized. + The texture filter blends between the nearest 4 pixels. Use this when you want to avoid a pixelated style, but do not want mipmaps. + The texture filter reads from the nearest pixel in the nearest mipmap. The fastest way to read from textures with mipmaps. + The texture filter blends between the nearest 4 pixels and between the nearest 2 mipmaps. + Max value for [enum DefaultCanvasItemTextureFilter] enum. + Disables textures repeating. Instead, when reading UVs outside the 0-1 range, the value will be clamped to the edge of the texture, resulting in a stretched out look at the borders of the texture. + Enables the texture to repeat when UV coordinates are outside the 0-1 range. If using one of the linear filtering modes, this can result in artifacts at the edges of a texture when the sampler filters across the edges of the texture. + Flip the texture when repeating so that the edge lines up instead of abruptly changing. + Max value for [enum DefaultCanvasItemTextureRepeat] enum. diff --git a/scene/main/scene_tree.cpp b/scene/main/scene_tree.cpp index 0418b20e9c02..f30a899d6996 100644 --- a/scene/main/scene_tree.cpp +++ b/scene/main/scene_tree.cpp @@ -1422,7 +1422,7 @@ SceneTree::SceneTree() { current_scene = nullptr; int msaa_mode = GLOBAL_DEF("rendering/quality/screen_filters/msaa", 0); - ProjectSettings::get_singleton()->set_custom_property_info("rendering/quality/screen_filters/msaa", PropertyInfo(Variant::INT, "rendering/quality/screen_filters/msaa", PROPERTY_HINT_ENUM, "Disabled,2x,4x,8x,16x,AndroidVR 2x,AndroidVR 4x")); + ProjectSettings::get_singleton()->set_custom_property_info("rendering/quality/screen_filters/msaa", PropertyInfo(Variant::INT, "rendering/quality/screen_filters/msaa", PROPERTY_HINT_ENUM, "Disabled,2x,4x,8x,16x")); root->set_msaa(Viewport::MSAA(msaa_mode)); int ssaa_mode = GLOBAL_DEF("rendering/quality/screen_filters/screen_space_aa", 0); diff --git a/scene/main/viewport.cpp b/scene/main/viewport.cpp index 72b1a877c169..3d2dcaffc30d 100644 --- a/scene/main/viewport.cpp +++ b/scene/main/viewport.cpp @@ -3525,6 +3525,10 @@ void Viewport::_bind_methods() { BIND_ENUM_CONSTANT(MSAA_8X); BIND_ENUM_CONSTANT(MSAA_16X); + BIND_ENUM_CONSTANT(SCREEN_SPACE_AA_DISABLED); + BIND_ENUM_CONSTANT(SCREEN_SPACE_AA_FXAA); + BIND_ENUM_CONSTANT(SCREEN_SPACE_AA_MAX); + BIND_ENUM_CONSTANT(DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_NEAREST); BIND_ENUM_CONSTANT(DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR); BIND_ENUM_CONSTANT(DEFAULT_CANVAS_ITEM_TEXTURE_FILTER_LINEAR_WITH_MIPMAPS); diff --git a/servers/rendering_server.cpp b/servers/rendering_server.cpp index c288c2986edf..17b82f046108 100644 --- a/servers/rendering_server.cpp +++ b/servers/rendering_server.cpp @@ -2027,6 +2027,7 @@ void RenderingServer::_bind_methods() { BIND_ENUM_CONSTANT(LIGHT_PARAM_INDIRECT_ENERGY); BIND_ENUM_CONSTANT(LIGHT_PARAM_SPECULAR); BIND_ENUM_CONSTANT(LIGHT_PARAM_RANGE); + BIND_ENUM_CONSTANT(LIGHT_PARAM_SIZE); BIND_ENUM_CONSTANT(LIGHT_PARAM_ATTENUATION); BIND_ENUM_CONSTANT(LIGHT_PARAM_SPOT_ANGLE); BIND_ENUM_CONSTANT(LIGHT_PARAM_SPOT_ATTENUATION); @@ -2037,6 +2038,9 @@ void RenderingServer::_bind_methods() { BIND_ENUM_CONSTANT(LIGHT_PARAM_SHADOW_FADE_START); BIND_ENUM_CONSTANT(LIGHT_PARAM_SHADOW_NORMAL_BIAS); BIND_ENUM_CONSTANT(LIGHT_PARAM_SHADOW_BIAS); + BIND_ENUM_CONSTANT(LIGHT_PARAM_SHADOW_PANCAKE_SIZE); + BIND_ENUM_CONSTANT(LIGHT_PARAM_SHADOW_BLUR); + BIND_ENUM_CONSTANT(LIGHT_PARAM_TRANSMITTANCE_BIAS); BIND_ENUM_CONSTANT(LIGHT_PARAM_MAX); BIND_ENUM_CONSTANT(LIGHT_OMNI_SHADOW_DUAL_PARABOLOID);