Browse Source

Improve the doc about materials a bit.

(cherry picked from commit 94c51664f7052c36e4075f005bcaa657d80a7c3e)
Manuel Freiberger 8 years ago
parent
commit
04a1231db2
2 changed files with 36 additions and 29 deletions
  1. 17 13
      tutorials/3d/fixed_materials.rst
  2. 19 16
      tutorials/3d/materials.rst

+ 17 - 13
tutorials/3d/fixed_materials.rst

@@ -36,8 +36,8 @@ Use alpha
 This flag needs to be active for transparent materials to blend with
 what is behind, otherwise display will always be opaque. Do not enable
 this flag unless the material really needs it, because it can severely
-affect performance and quality. Materials with transparency will also
-not cast shadows (unless they contain opaque areas and the "opaque
+affect performance and quality. Materials with transparency also won't
+cast shadows (unless they contain opaque areas and the "opaque
 pre-pass" hint is turned on, see the :ref:`doc_materials` tutorial for more
 information).
 
@@ -46,7 +46,7 @@ information).
 Use vertex colors
 ~~~~~~~~~~~~~~~~~
 
-Vertex color painting is a very common technique to add detail to
+Vertex color painting is a very common technique to add detail to a
 geometry. 3D DCCs all support this, and many even support baking
 occlusion to it. Godot allows this information to be used in the fixed
 material by modulating the diffuse color when enabled.
@@ -57,14 +57,14 @@ Point size
 ~~~~~~~~~~
 
 Point size is used to set the point size (in pixels) for when rendering
-points. This feature is mostly used in tools and HUDs
+points. This feature is mostly used in tools and HUDs.
 
 Discard alpha
 ~~~~~~~~~~~~~
 
-When alpha is enabled (see above) the invisible pixels are blended
+When alpha is enabled (see above) the transparent pixels are blended
 with what is behind them. In some combinations (of using alpha to
-render depth) it may be possible that invisible pixels cover other
+render depth) it may be possible that transparent pixels cover other
 objects.
 
 If this is the case, enable this option for the material. This option
@@ -80,10 +80,11 @@ Diffuse, specular, emission and specular exponent
 These are the base colors for the material.
 
 -  Diffuse color is responsible for the light that reaches the material,
-   then gets diffused around. This color varies by the angle to the
-   light and the distance (in the case of spot and omni lights). It is
+   and is diffusely back-scattered then. This color varies by the angle between
+   the face and the light and the distance to the light source 
+   (in the case of spot and omni lights). It is
    the color that best represents the material. It can also have alpha
-   (transparency)
+   (transparency).
 -  Specular color is the color of the reflected light and responsible
    for shines. It is affected by the specular exponent.
 -  Emission is the color of the light generated within the material
@@ -127,10 +128,13 @@ added together, here's an example of what detail textures are for:
 Normal depth
 ~~~~~~~~~~~~
 
-Normal depth controls the intensity of the normal-mapping as well as the
-direction. On 1 (the default) normalmapping applies normally, on -1 the
-map is inverted and on 0 is disabled. Intermediate or greater values are
-accepted. Here's how it's supposed to look:
+Normal depth controls the strength and the direction of normal-mapping.
+If it is set to 1 (the default), the un-scaled normal map is applied.
+Values larger than 1 make normal-mapping more pronounced (dents and bumps
+become larger), while values smaller than 1 reduce the effect. A normal
+depth of 0 disables normal-mapping. Negative values invert the normal map
+so dents become bumps and vice versa. Here is an example showing the
+influence of the normal depth on the outcome:
 
 .. image:: /img/fixed_material_normal_depth.png
 

+ 19 - 16
tutorials/3d/materials.rst

@@ -6,10 +6,10 @@ Materials
 Introduction
 ------------
 
-Materials can be applied to most visible 3D objects, they basically
-are a description to how light reacts to that object. There are many
+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
+: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`.
 
@@ -20,8 +20,8 @@ This tutorial is about the basic properties shared between them.
 Flags
 -----
 
-Materials, no matter which type they are, have a set of flags
-associated. Each has a different use and will be explained as follows.
+Materials, no matter which type they are, have an associated set of flags.
+Their use will be explained in the following.
 
 Visible
 ~~~~~~~
@@ -29,18 +29,20 @@ Visible
 Toggles whether the material is visible. If unchecked, the object will
 not be shown.
 
-Double sided & invert faces
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Double sided & inverted faces
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Godot by default only shows geometry faces (triangles) when facing the
-camera. To do this it needs them to be in view in clockwise order.
-This saves a lot of GPU power by ensuring that not visible triangles
-are not drawn.
+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.
 
-Some flat objects might need to be drawn all the times though, for
-this the "double sided" flag will make sure that no matter the facing,
+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 counter-clockwise looking faces too, though it's not
+check and draw only counter-clockwise looking faces, though it's not
 very useful except for a few cases (like drawing outlines).
 
 Unshaded
@@ -57,8 +59,9 @@ 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 only
-useful for HUD effects or gizmos.
+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
 ~~~~~~~~~~~~~~~