doc fixes

learning/features/3d/spatial_material.rst

@@ -14,7 +14,7 @@ SpatialMaterial is a 3D material and aims to have most features that
 artists look for in a material. Additionally, it can be converted
 to shader code to be further modified in case this is desired.
 
-This tutorial will attempt to conver most parameters present in SpatialMaterial.
+This tutorial will attempt to cover most parameters present in SpatialMaterial.
 
 Flags
 -----
@@ -27,14 +27,15 @@ Transparent
 ~~~~~~~~~~~
 
 In Godot, materials are not transparent unless specifically toggled as such.
-The main reason behind this is because transparent materials are rendered
+The main reason behind this is that transparent materials are rendered
 using a different technique (sorted from back to front and rendered in order).
 
-This technique is less efficient and makes such materials unusable with many
-mid and post processing effects (such as SSAO, SSR, etc). 
+This technique is less efficient (many state changes hapen) and makes the materials
+unusable with many mid and post processing effects (such as SSAO, SSR, etc) that
+require perfectly opaque geometry.
 
-For this reason, they are assumed opaque unless specified otherwise. The
-main parameters that enable transparency automatically are:
+For this reason, materials in Godot are assumed opaque unless specified otherwise. 
+The main settings that enable transparency are:
 
 * Transparent flag (this one)
 * Blend mode set to other than Mix
@@ -43,26 +44,30 @@ main parameters that enable transparency automatically are:
 Unshaded
 ~~~~~~~~
 
-In most cases, it is desired that materials are affected by lighting.
+In most cases, it is common that materials are affected by lighting (shaded).
+
 Sometimes, however, one might want to show just the albedo (color) part
 of it and ignore the rest. Toggling this flag on will remove all
-shading and only pure, unlit, color.
+shading and show pure, unlit, color.
+
+.. image:: /img/spatial_material26.png
 
 Vertex Lighting
 ~~~~~~~~~~~~~~~
 
-Given Godot has a more or less uniform cost per pixel (thanks to depth pre pass), all lighting calculations are made
+Godot has a more or less uniform cost per pixel (thanks to depth pre pass), all lighting calculations are made
 by running the lighting shader on every pixel.
 
-As these calculations are costly, performance can be brought down considerable in some corner cases such as drawing
+As these calculations are costly, performance can be brought down considerably in some corner cases such as drawing
 several layers of transparency (common in particle systems). Switching to per vertex lighting may help these cases.
 
 Additionaly, on very low end devices cuch as mobile, switching to vertex lighting can considerably increase rendering performance.
 
-When vertex lighting is enabled, for performance reasons, only directional lighting can produce shadows.
 
 .. image:: /img/spatial_material2.png
 
+Keep in mind that, when vertex lighting is enabled, only directional lighting can produce shadows (for performance reasons).
+
 No Depth Test
 ~~~~~~~~~~~~~~~
 
@@ -108,7 +113,7 @@ Is SRGB
 ~~~~~~~
 
 Most 3D DCCs will likely export vertex colors as SRGB, so toggling this option on will help them
-look more faitful.
+look correct.
 
 
 Parameters
@@ -126,8 +131,8 @@ default one is Lambert, which does not vary with roughness. Other modes are also
 
 * Lambert: Default mode, is not affected by roughness.
 * Lambert Wrap: Extends lambert to cover more than 90 degrees when roughness increases. Works great for hair and simulating cheap subsurface scattering. This implementation is energy conserving.
-* Oren Nayar: This implementation aims to take microsurfacetting into account in lambert lighting (via roughness). Works really well for clay-like materials and some types of cloth. 
-* Burley: The original Disney diffuse algorithm for diffuse.
+* Oren Nayar: This implementation aims to take microsurfacetting into account (via roughness). Works really well for clay-like materials and some types of cloth. 
+* Burley: The original Disney Principled PBS diffuse algorithm.
 * Toon: Provides a hard cut for lighting, with smoothing affected by roughness.
 
 .. image:: /img/spatial_material6.png
@@ -135,9 +140,9 @@ default one is Lambert, which does not vary with roughness. Other modes are also
 Specular Mode
 ~~~~~~~~~~~~~
 
-Specified how the specular blob will be rendered. The specular blob represents the shape of a light source reflected in the object.
+Specifies how the specular blob will be rendered. The specular blob represents the shape of a light source reflected in the object.
 
-* ShlickGGX: The most common blob used by 3D engines
+* ShlickGGX: The most common blob used by PBR 3D engines nowadays.
 * Blinn: Common in previous gen engines. Not worth using nowadays, but left here for the sake of compatibility.
 * Phong: Same as above.
 * Toon: Creates a toon blob, which changes size depending on roughness.
@@ -149,7 +154,7 @@ Specified how the specular blob will be rendered. The specular blob represents t
 Blend Mode
 ~~~~~~~~~~
 
-Controls the blend mode for the material. Keep in mind that any mode other than Mix forced the object to go through transparent pipeline.
+Controls the blend mode for the material. Keep in mind that any mode other than Mix forces the object to go through transparent pipeline.
 
 * Mix: Default blend mode, alpha controls how much the object is visible.
 * Add: Object is blended additively, nice for flares or some fire-like effects.
@@ -161,11 +166,11 @@ Controls the blend mode for the material. Keep in mind that any mode other than
 Cull Mode
 ~~~~~~~~~
 
-Detect which side of the object is not drawn when not visible:
+Determines which side of the object is not drawn when back-faces are rendered:
 
 * Back: Back of the object is culled when not visible (default)
 * Front: Front of the object is culled when not visible
-* Disabled: Used for objects that are double sided
+* Disabled: Used for objects that are double sided (no culling is performed)
 
 Depth Draw Mode
 ~~~~~~~~~~~~~~~
@@ -173,9 +178,10 @@ Depth Draw Mode
 Specifies when depth rendering must take place. 
 
 * Opaque Only (default): Depth is only drawn for opaque objects
-* Always: Depth draw is only drawn for opaque and transparent objects
+* Always: Depth draw is drawn for both opaque and transparent objects
 * Never: No depth draw takes place (note: do not confuse with depth test option above)
-* Depth Pre-Pass: For transparent objects, an opaque pass is made first with the opaque parts, then tranparency is drawn above.
+* Depth Pre-Pass: For transparent objects, an opaque pass is made first with the opaque parts, then tranparency is drawn above. Use this option
+with transparent grass or tree foliage.
 
 .. image:: /img/material_depth_draw.png
 
@@ -192,12 +198,12 @@ When drawing points, specify the point size in pixels.
 Billboard Mode
 ~~~~~~~~~~~~~~
 
-Enabled billboard mode for drawing materials. This control how the object faces the camera:
+Enables billboard mode for drawing materials. This control how the object faces the camera:
 
-Disabled: Billboard mode is disabled
-Enabled: Billboard mode is enabled, object -Z axis will always face the camera.
-Y-Billboard: Object X axis will always be aligned with the camera
-Particles: When using particle systems, this type of billboar is best, because it allows specifying animation options.
+* Disabled: Billboard mode is disabled
+* Enabled: Billboard mode is enabled, object -Z axis will always face the camera.
+* Y-Billboard: Object X axis will always be aligned with the camera
+* Particles: When using particle systems, this type of billboar is best, because it allows specifying animation options.
 
 .. image:: /img/spatial_material9.png
 
@@ -206,7 +212,7 @@ Above options are only enabled for Particle Billboard.
 Grow
 ~~~~
 
-Grows the object vertices by the direction pointed by their normal:
+Grows the object vertices in the direction pointed by their normals:
 
 .. image:: /img/spatial_material10.png
 
@@ -219,13 +225,11 @@ add some grow:
 Use Alpha Scissor
 ~~~~~~~~~~~~~~~~~
 
-For many types of materials, having different degrees of transparency is not always needed: Only visible and not visible is enough.
-In such cases, without even enabling transparency, it's possible to set a treshold to avoid the object from rendering these pixels.
+When transparency other than 0 or 1 is not needed, it's possible to set a treshold to avoid the object from rendering these pixels.
 
 .. image:: /img/spatial_material12.png
 
-The advantage of this method over regular transparency is that these materials can use the opaque pipeline, which is faster and can
-take of mid and post process effects such as SSAO, SSR, etc.
+This renders the object via the opaque pipeline, which is faster and allows it to do mid and post process effects such as SSAO, SSR, etc.
 
 Material colors, maps and channels
 ----------------------------------
@@ -240,7 +244,7 @@ Albedo is the base color for the material. Everything else works based on it. Wh
 In previous versions of Godot, this channel was named *diffuse*. The change of name mainly happens because, in PBR rendering, this color affects many more
 calculations than just the diffuse lighting path.
 
-Albedo color and texture can be used together, and they will be multiplied. 
+Albedo color and texture can be used together, as they are multiplied. 
 
 *Alpha channel* in albedo color and texture is also used for the object transparency. If you use a color or texture with *alpha channel*, make sure to either enable
 transparency or *alpha scissoring* for it to work.
@@ -250,7 +254,9 @@ Metallic
 
 Godot uses a Metallic model over competing models due to it's simplicity. This parameter pretty much defines how reflective the materials is. The more reflective it is, the least diffuse/ambient
 light and the more reflected light. This model is called "energy conserving".
+
 The "specular" parameter here is just a general amount of for the reflectivity (unlike *metallic*, this one is not energy conserving, so simply leave it as 0.5 and don't touch it unless you need to).
+
 The minimum internal reflectivity is 0.04, so (just like in real life) it's impossible to make a material completely unreflective.
 
 .. image:: /img/spatial_material13.png
@@ -258,7 +264,7 @@ The minimum internal reflectivity is 0.04, so (just like in real life) it's impo
 Roughness
 ~~~~~~~~~
 
-Roughness affects mainly the way the reflection happens. A value if 0 makes it a perfect mirror, while a value of 1 completely blurs the reflection (simulating the natural microsurfacetting of surfaces).
+Roughness affects mainly the way the reflection happens. A value if 0 makes it a perfect mirror, while a value of 1 completely blurs the reflection (simulating the natural microsurfacetting).
 Most common types of materials can be achieved from the right combination of *Metallic* and *Roughness*.
 
 .. image:: /img/spatial_material14.png
@@ -266,7 +272,7 @@ Most common types of materials can be achieved from the right combination of *Me
 Emission
 ~~~~~~~~
 
-Emission allows to specify how much light is emitted by the material (keep in mind this does not do lighting on surrounded geometry unless GI Probe is used). This value is just added to the resulting
+Emission allows to specify how much light is emitted by the material (keep in mind this does not do lighting on surrounding geometry unless GI Probe is used). This value is just added to the resulting
 final image, and is not affected by other lighting in the scene.
 
 
@@ -276,16 +282,16 @@ final image, and is not affected by other lighting in the scene.
 Normalmap
 ~~~~~~~~~
 
-Normap mapping allows to set a texture that represents finer shape detail. This does not modify geometry, just lighting is when hitting it. 
-In Godot, only R and G are used from the normalmap, in order to attain better compatibility.
+Normap mapping allows to set a texture that represents finer shape detail. This does not modify geometry, just the incident angle for light.
+In Godot, only R and G are used for normalmaps, in order to attain better compatibility.
 
 .. image:: /img/spatial_material16.png
 
 Rim
 ~~~
 
-Some fabrics have small micro fur that causes light to scatter through it's rim. Godot emulates this with the *rim* parameter. Unlike other rim lighting implementations,
-which just use the emission channel, this one actually takes light into account (no light means no rim). This makes the effect considerably more beliable.
+Some fabrics have small micro fur that causes light to scatter around it. Godot emulates this with the *rim* parameter. Unlike other rim lighting implementations,
+which just use the emission channel, this one actually takes light into account (no light means no rim). This makes the effect considerably more believable.
 
 .. image:: /img/spatial_material17.png
 
@@ -318,7 +324,7 @@ While it is possible to use Scren Space Ambient Occlusion (SSAO) to generate AO,
 Depth
 ~~~~~
 
-Setting a depth map to a material produces a ray-marched search to emulate the proper displacement of cavities according to the view. This is not real added geometry, but an illusion of depth.
+Setting a depth map to a material produces a ray-marched search to emulate the proper displacement of cavities along the view direction. This is not real added geometry, but an illusion of depth.
 It may not work for complex objets, but it produces a realistic depth effect for textues. For best results, *Depth* should be used together with normal mapping.
 
 .. image:: /img/spatial_material20.png
@@ -326,7 +332,7 @@ It may not work for complex objets, but it produces a realistic depth effect for
 Subsurface Scattering
 ~~~~~~~~~~~~~~~~~~~~~
 
-This effect emulates light that goes beneath an object's surface, scattering and them coming out again. It's very useful to make realistic skin, marble, colored liquids, etc.
+This effect emulates light that goes beneath an object's surface, is scattered, and then comes out. It's very useful to make realistic skin, marble, colored liquids, etc.
 
 .. image:: /img/spatial_material21.png
 
@@ -352,7 +358,7 @@ Detail
 
 Godot allows using secondary albedo and normal to generate a detail texture, which can be blended in many ways. Combining with secondary UV or triplanar modes, many interesting textures can be achieved.
 
-.. image:: /img/spatial_material23.png
+.. image:: /img/spatial_material24.png
 
 UV1 and UV2
 ~~~~~~~~~~~~
@@ -367,7 +373,7 @@ Triplanar can be either worldspace or object space.
 
 In the image below, you can see how all primitives share the same material with world triplanar, so bricks continue smoothly between them.
 
-.. image:: /img/spatial_material24.png
+.. image:: /img/spatial_material25.png
 
 Proximity and Distance Fade
 ----------------------------
@@ -378,7 +384,7 @@ Distance fade is useful for light shafts or indicators that are only present aft
 
 Keep in mind enabling these enables alpha blending, so abusing them for a whole scene is not generally a good idea.
 
-.. image:: /img/spatial_material_proxfade.png
+.. image:: /img/spatial_material_proxfade.gif
 
 Render Priority
 ---------------