Browse Source

Documented Reflection Probes

Juan Linietsky 7 years ago
parent
commit
70a7bf788c

BIN
learning/features/3d/img/refprobe_ambient.png


BIN
learning/features/3d/img/refprobe_atlas.png


BIN
learning/features/3d/img/refprobe_blending.png


BIN
learning/features/3d/img/refprobe_box_property.png


BIN
learning/features/3d/img/refprobe_boxcorrect.png


BIN
learning/features/3d/img/refprobe_center_gizmo.png


BIN
learning/features/3d/img/refprobe_cullmask.png


BIN
learning/features/3d/img/refprobe_setup.png


BIN
learning/features/3d/img/refprobe_shadows.png


BIN
learning/features/3d/img/refprobe_ssr.png


+ 2 - 1
learning/features/3d/index.rst

@@ -8,6 +8,7 @@
    introduction_to_3d
    3d_performance_and_limitations
    spatial_material
-   lighting
+   lights_and_shadows
+   reflection_probes
    high_dynamic_range
    using_gridmaps

+ 3 - 3
learning/features/3d/lighting.rst

@@ -1,7 +1,7 @@
-.. _doc_lighting:
+.. _doc_lights_and_shadows:
 
-Lighting
-========
+Lights And Shadows
+==================
 
 Introduction
 ------------

+ 233 - 0
learning/features/3d/lights_and_shadows.rst

@@ -0,0 +1,233 @@
+.. _doc_lights_and_shadows:
+
+Lights And Shadows
+==================
+
+Introduction
+------------
+
+Lights emit light that mix with the materials and produces a visible
+result. Light can come from several types of sources in a scene:
+
+-  From the Material itself, in the form of the emission color (though
+   it does not affect nearby objects unless baked).
+-  Light Nodes: Directional, Omni and Spot.
+-  Ambient Light in the
+   :ref:`Environment <class_Environment>`.
+-  Baked Light (read :ref:`doc_light_baking`).
+
+The emission color is a material property. You can read more about it
+in the :ref:`doc_fixed_materials` tutorial.
+
+Light nodes
+-----------
+
+As mentioned before, there are three types of light nodes: Directional,
+Omni and Spot. Each has different uses and will be described in
+detail below, but first let's take a look at the common parameters for
+lights:
+
+.. image:: img/light_params.png
+
+Each one has a specific function:
+
+-  **Color**: Base color for emitted light.
+-  **Energy**: Energy multiplier. This is useful to saturate lights or working with :ref:`doc_high_dynamic_range`.
+-  **Indirect Energy**: Secondary multiplier used with indirect light (light bounces). This works in baked light or GIProbe.
+-  **Negative**: Light becomes substractive instead of additive. It's sometimes useful to manually compensate some dark corners.
+-  **Specular**: Affects the intensity of the specular blob in objects affected by this light. At zero, this light becomes a pure diffuse light. 
+-  **Cull Mask**: Objects that are in the selected layers below will be affected by this light.
+
+Shadow Mapping
+^^^^^^^^^^^^^^
+
+Lights can optionally cast shadows. This gives them greater realism (light does not reach occluded areas), but it can incur a bigger performance cost.
+There is a list of generic shadow parameters, each also has a specific function:
+
+-  **Enabled**: Check to enable shadow mapping in this light.
+-  **Color**: Areas occluded are multiplied by this color. It is black by default, but it can be changed to tint shadows.
+-  **Bias**: When this parameter is too small, self shadowing occurs. When too large, shadows separate from the casters. Tweak to what works best for you.
+-  **Contact**: Performs a short screen-space raycast to reduce the gap generated by the bias.
+-  **Reverse Cull Faces**: Some scenes work better when shadow mapping is rendered with face-culling inverted.
+
+Below is an image of how tweaking bias looks like. Default values work for most cases, but in general it depends on the size and complexity of geometry.
+
+.. image:: img/shadow_bias.png
+
+Finally, if gaps cant be solved, the **Contact** option can help:
+
+.. image:: img/shadow_contact.png
+
+Any sort of bias issues can always be fixed by increasing the shadow map resolution, although that may lead to decreased peformance on low-end hardware.
+
+Directional light
+~~~~~~~~~~~~~~~~~
+
+This is the most common type of light and represents a light source 
+very far away (such as the sun). It is also the cheapest light to compute and should be used whenever possible
+(although it's not the cheapest shadow-map to compute, but more on that later). 
+
+Directional light models an infinite number of parallel light rays
+covering the whole scene. The directional light node is represented by a big arrow, which
+indicates the direction of the light rays. However, the position of the node
+does not affect the lighting at all, and can be anywhere.
+
+.. image:: img/light_directional.png
+
+Every face whose front-side is hit by the light rays is lit, the others stay dark. Most light types
+have specific parameters but directional lights are pretty simple in nature so they don't.
+
+Directional Shadow Mapping
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To compute shadow maps, the scene is rendered (only depth) from an orthogonal point of view that covers
+the whole scene (or up to the max distance). There is, however, a problem with this approach because objects
+closer to the camera receive blocky shadows.
+
+.. image:: img/shadow_blocky.png
+
+To fix this, a technique named "Parallel Split Shadow Maps" (or PSSM) is used. This splits the view frustum in 2 or 4 areas. Each
+area gets it's own shadow map. This allows small, close areas to the viewer to have the same shadow resolution as a huge, far-away area.
+
+.. image:: img/pssm_explained.png
+
+With this, shadows become more detailed:
+
+.. image:: img/shadow_pssm.png
+
+To control PSSM, a number of parameters are exposed:
+
+.. image:: img/directional_shadow_params.png
+
+Each split distance is controlled relative to the camera far (or shadow **Max Distance** if greater than zero), so *0.0* is the eye position and *1.0* is where the shadow ends at a distance.
+Splits are in-between. Default values generally work well, but tweaking the first split a bit is common to give more detail to close objects (like a character in a third person game).
+
+Always make sure to set a shadow *Max Distance* according to what the scene needs. The closer the max distance, the higher quality they shadows will have.
+
+Sometimes, the transition between a split and the next can look bad. To fix this, the **"Blend Splits"** option can be turned own, which sacrifices detail in exchange for smoother
+transitions:
+
+.. image:: img/blend_splits.png
+
+The **"Normal Bias"** parameter can be used to fix special cases of self shadowing when objects are perpendicular to the light. The only downside is that it makes
+the shadow a bit thinner.
+
+.. image:: img/normal_bias.png
+
+The **"Bias Split Scale"** parameter can control extra bias for the splits that are far away. If self shadowing occurs only on the splits far away, this value can fix them.
+
+Finally, the **"Depth Range"** has to settings:
+
+- **Stable**: Keeps the shadow stable while the camera moves, the blocks that appear in the outline when close to the shadow edges remain in-place. This is the default and generally desired,
+but it reduces the effective shadow resolution.
+- **Optimized**: Triest to achieve the maximum resolution available at any given time. This may result in a "moving saw" effect on shadow edges, but at the same time the shadow looks more detailed (so this effect may be subtle enough to be forgiven).
+
+Just experiment which setting works better for your scene.
+
+Shadowmap size for directional lights can be changed in Project Settings -> Rendering -> Quality:
+
+.. image:: img/project_setting_shadow.png
+
+Increasing it can solve bias problems, but reduce performance. Shadow mapping is an art of tweaking.
+
+Omni light
+~~~~~~~~~~
+
+Omni light is a point source that emits light spherically in all directions up to a given
+radius .
+
+.. image:: img/light_omni.png
+
+In real life, light attenuation is an inverse function, which means omni lights don't really have a radius.
+This is a problem, because it means computing several omni lights would become really demanding.
+
+To solve this, a *Range* is introduced, together with an attenuation function. 
+
+.. image:: img/light_omni_params.png
+
+These two parameters allow tweaking how this works visually, in order to find aesthetically pleasing results.
+
+.. image:: img/light_attenuation.png
+
+
+Omni Shadow Mapping
+^^^^^^^^^^^^^^^^^^^
+
+Omni light shadow mapping is relatively straightforward, as it just works. The main issue that needs to be
+considered is the algorithm used to render it. 
+
+Omni Shadows can be rendered as either **"Dual Paraboloid" or "Cube Mapped"**. The former renders very quickly but can cause deformations,
+while the later is more correct but more costly. 
+
+.. image:: img/shadow_omni_dp_cm.png
+
+If the objects being renderer are mostly irregular, Dual Paraboloid is usually enough. In any case, as these shadows are cached in a shadow atlas (more on that at the end), it
+may not make a difference in performance for most scenes.
+
+
+Spot light
+~~~~~~~~~~
+
+Spot lights are similar to omni lights, except they emit light only into a cone
+(or "cutoff"). They are useful to simulate flashlights,
+car lights, reflectors, spots, etc. This type of light is also attenuated towards the
+opposite direction it points to.
+
+.. image:: img/light_spot.png
+
+Spot lights share the same **Range** and **Attenuation** as **OmniLight**, and add two extra parameters:
+
+- **Angle**: The aperture angle of the light
+- **Angle Attenuation**: The cone attenuation, which helps soften the cone borders.
+
+
+Spot Shadow Mapping
+^^^^^^^^^^^^^^^^^^^
+
+Spots dont need any parameters for shadow mapping, they should just work. Keep in mind that, at more than 89 degrees of aperture, shadows
+stop functioning for spots, and you should consider using an Omni light.
+
+Shadow Atlas
+~~~~~~~~~~~~
+
+Unlike Directional lights, which have their own shadow texture, Omni and Spot lights are assigned to slots of a shadow atlas.
+This atlas can be configured in Project Settings -> Rendering -> Quality -> Shadow Atlas.
+
+.. image:: img/shadow_atlas.png
+
+The resolution applies to the whole Shadow Atlas. This atlas is divided in four quadrants:
+
+.. image:: img/shadow_quadrants.png
+
+Each quadrant, can be subdivided to allocate any number of shadow maps, following is the default subdivision:
+
+.. image:: img/shadow_quadrants2.png
+
+The allocation logic is simple, the biggest shadow map size (when no subdivision is used) represents a light the size of the screen (or bigger).
+Subdivisions (smaller maps) represent shadows for lights that are further away from view and proportionally smaller.
+
+Every frame, the following logic is done for all lights:
+
+1. Check if the light is on a slot of the right size, if not, re-render it and move it to a larger/smaller slot.
+2. Check if any object affecting the shadow map has changed, if it did, re-render the light.
+3. If neither of the above has happened, nothing is done and the shadow is left untouched.
+
+If the slots in a quadrant are full, lights are pushed back to smaller slots depending on size and distance.
+
+This allocation strategy works for most games, but you may to use a separate one in some cases (as example, a top-down game where
+all lights are around the same size and quadrands may have all the same subdivision).
+
+Shadow Filter Quality
+~~~~~~~~~~~~~~~~~~~~~
+
+The filter quality of shadows can be tweaked. This can be found in Project Settings -> Rendering -> Quality -> Shadows. Godot supports no filter, PCF5 and PCF13.
+
+.. image:: img/shadow_pcf1.png
+
+It affects the blockyness of the shadow outline:
+
+.. image:: img/shadow_pcf2.png
+
+
+
+

+ 213 - 0
learning/features/3d/refletion_probes.rst

@@ -0,0 +1,213 @@
+.. _doc_reflection_probes:
+
+Reflection Probes
+=========
+
+Introduction
+------------
+
+As stated in the :ref:`doc_spatial_materials`, objects can show reflected or diffuse light.
+Reflection Probes are used as a source of reflected and ambient light for objects inside their area of influence.
+
+A probe of this type captures the surroundings (as a sort of 360 degrees image), and stores versions
+of it with increasing levels of *blur*. This is used to simulate roughness in materials, as well as ambient lighting.
+
+While these probes are a very efficient way of storing reflections, they have a few shortcomings:
+
+* They are efficient to render, but expensive to compute. This leads to a default behavior where they only capture on scene load.
+* They work best for rectangular shaped rooms or places, otherwise the reflections shown are not as faithful (specially when roughness is 0).
+
+Setting Up
+----------
+
+Setting up reflection probes is really easy! Just create a ReflectionProbe node, and wrap it around the area where you want to have reflections:
+
+.. image:: /img/refprobe_setup.png
+
+This should result in immediate local reflections. If you are using a Sky texture, reflections are by default blended. with it. 
+
+By default, or interiors, reflections may appear to not have much consistence. In this scenario, make sure to tick the *"Box Correct"* property.
+
+.. image:: /img/refprobe_box_property.png
+
+
+This setting changes the reflection from an infinite skybox to reflecting a box the size of the probe:
+
+.. image:: /img/refprobe_boxcorrect.png
+
+Adjusting the box walls may help improve the reflection a bit, but it will always look the best in box shaped rooms.
+
+The probe captures the surrounding from the center of the gizmo. If, for some reason, the room shape or contents occlude the center, it
+can be displaced to an empty place by moving the handles in the center:
+
+.. image:: /img/refprobe_center_gizmo.png
+
+By default, shadow mapping is disabled when rendering probes (only in the rendered image inside the probe, not the actual scene). This is
+a simple way to save on performance and memory. If you really want shadows in the probe, they can be toggled on/of with the *Enable Shadow* setting:
+
+.. image:: /img/refprobe_shadows.png
+
+Finally, keep in mind that you may not want the Reflection Probe to render some objects. A typical scenario is an enemy inside the room which will
+move around. To keep objects from being rendered in the reflections, use the *Cull Mask* setting:
+
+.. image:: /img/refprobe_cullmask.png
+
+Interior vs Exterior
+--------------------
+
+If you are using reflection probes in an interior setting, it is recommended that the **Interior** property is enabled. This makes
+the probe not render the sky, and also allows custom amibent lighting settings.
+
+.. image:: /img/refprobe_cullmask.png
+
+When probes are set to **Interior**, custom constant ambient lighting can be specified per probe. Just choose a color and an energy.
+Optionally, you can blend this ambient light with the probe diffuse capture by tweaking the **Ambient Contribution* property (0.0 means, pure ambient color, while 1.0 means pure diffuse capture).
+
+
+Blending
+--------
+
+Multiple reflection probes can be used and Godot will blend them where they overlap using a smart algorithm:
+
+.. image:: /img/refprobe_blending.png
+
+As you can see, this blending is never perfect (after all, these are box reflections, not real reflections), but these arctifacts
+are only visible when using perfectly mirrored reflections. Normally, scenes have normal mapping and varying levels of roughness which
+can hide this. 
+
+Alternatively, Reflection Probes work very well blended together with Screen Space Reflections to solve these problems. Combining them makes local reflections appear
+more faithful, while probes only used as fallback when no screen-sace information is found:
+
+.. image:: /img/refprobe_ssr.png
+
+Finally, blending interior and exterior probes is a recommended approach when making levels that combine both interiors and exteriors. Near the door, a probe can
+be marked as *exterior* (so it will get sky reflections), while on the inside it can be interior.
+
+Reflection Atlas
+-----------------
+
+In the current renderer implementation, all probes are the same size and they are fit into a Reflection Atlas. The size and amount of probes can be
+customized in Project Settings -> Quality -> Reflections
+
+.. image:: /img/refprobe_atlas.png
+
+
+
+
+
+
+
+
+
+
+Materials can be applied to most visible 3D objects. Basically they
+describe how light interacts with that object. There are many
+types of materials, but the main ones are the
+:ref:`FixedMaterial <class_FixedMaterial>` and the
+:ref:`ShaderMaterial <class_ShaderMaterial>`.
+Tutorials for each of them exist :ref:`doc_fixed_materials` and :ref:`doc_shader_materials`.
+
+This tutorial is about the basic properties shared between them.
+
+.. image:: /img/material_flags.png
+
+Flags
+-----
+
+Materials, no matter which type they are, have an associated set of flags.
+Their use will be explained in the following.
+
+Visible
+~~~~~~~
+
+Toggles whether the material is visible. If unchecked, the object will
+not be shown.
+
+Double sided & inverted faces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Godot by default only shows geometry faces (triangles) when their front-side
+faces the camera. If looking at the front-side of a face, its vertices
+have to be oriented clockwise by definition. For closed objects, the
+back-side of faces is never visible because they are hidden by other
+faces. SO not drawing invisible triangles (whose vertices are oriented
+counter-clockwise on the view plane) saves a lot of GPU power.
+
+However, for flat or open objects, the back-side of faces might be visible
+and needs to be drawn as well. The "double sided" flag makes sure that no matter the facing,
+the triangle will always be drawn. It is also possible to invert this
+check and draw only counter-clockwise looking faces, though it's not
+very useful except for a few cases (like drawing outlines).
+
+Unshaded
+~~~~~~~~
+
+Objects are always black unless light affects them, and their shading
+changes according to the type and direction of lights. When this flag is
+turned on, the diffuse color is displayed right the same as it appears
+in the texture or parameter:
+
+.. image:: /img/material_unshaded.png
+
+On top
+~~~~~~
+
+When this flag is turned on, the object will be drawn after everything
+else has been drawn and without a depth test. This is generally useful
+for objects which shall never be hidden by other objects such as HUD effects
+or gizmos.
+
+Ligthmap on UV2
+~~~~~~~~~~~~~~~
+
+When using lightmapping (see the :ref:`doc_light_baking` tutorial), this option
+determines that the lightmap should be accessed on the UV2 array instead
+of regular UV.
+
+Parameters
+----------
+
+Some parameters also exist for controlling drawing and blending:
+
+Blend mode
+~~~~~~~~~~
+
+Objects are usually blended in Mix mode. Other blend modes (Add and Sub)
+exist for special cases (usually particle effects, light rays, etc.) but
+materials can be set to them:
+
+.. image:: /img/fixed_material_blend.png
+
+Line width
+~~~~~~~~~~
+
+When drawing lines, the size of them can be adjusted here per material.
+
+Depth draw mode
+~~~~~~~~~~~~~~~
+
+This is a tricky but very useful setting. By default, opaque objects are
+drawn using the depth buffer and translucent objects are not (but are
+sorted by depth). This behavior can be changed here. The options are:
+
+-  **Always**: Draw objects with depth always, even those with alpha.
+   This often results in glitches like the one in the first image (which
+   is why it's not the default).
+-  **Opaque Only**: Draw objects with depth only when they are opaque,
+   and do not set depth for alpha. This is the default because it's fast,
+   but it's not the most correct setting. Objects with transparency that
+   self-intersect will always look wrong, especially those that mix
+   opaque and transparent areas, like grass, tree leaves, etc. Objects
+   with transparency also can't cast shadows, this is evident in the
+   second image.
+-  **Alpha Pre-Pass**: The same as above, but a depth pass is performed
+   for the opaque areas of objects with transparency. This makes objects
+   with transparency look much more correct. In the third image it is
+   evident how the leaves cast shadows between them and into the floor.
+   This setting is turned off by default because, while on PC this is
+   not very costly, mobile devices suffer a lot when this setting is
+   turned on, so use it with care.
+-  **Never**: Never use the depth buffer for this material. This is
+   mostly useful in combination with the "On Top" flag explained above.
+
+.. image:: /img/material_depth_draw.png