Spatial Material tutorial

learning/features/3d/fixed_materials.rst

@@ -1,183 +0,0 @@
-.. _doc_fixed_materials:
-
-Fixed materials
-===============
-
-Introduction
-------------
-
-Fixed materials (originally Fixed Pipeline Materials) are the most
-common type of materials, using the most common material options found
-in 3D DCCs (such as Maya, 3DS Max or Blender). The big advantage of
-using them is that 3D artists are very familiar with this layout. They
-also allow to try out different things quickly without the need of
-writing shaders. Fixed Materials inherit from
-:ref:`Material <class_Material>`,
-which also has several options. If you haven't read it before, reading
-the :ref:`doc_materials` tutorial is recommended.
-
-Options
--------
-
-Here is the list of all the options available for fixed materials:
-
-.. image:: /img/fixed_materials.png
-
-From this point, every option will be explained in detail:
-
-Fixed flags
------------
-
-These are a set of flags that control general aspects of the material.
-
-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 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).
-
-.. image:: /img/fixed_material_alpha.png
-
-Use vertex colors
-~~~~~~~~~~~~~~~~~
-
-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.
-
-.. image:: /img/fixed_material_vcols.png
-
-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.
-
-Discard alpha
-~~~~~~~~~~~~~
-
-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 transparent pixels cover other
-objects.
-
-If this is the case, enable this option for the material. This option
-is often used in combination with "opaque pre-pass" hint (see the
-:ref:`doc_materials` tutorial for more information).
-
-Parameters
-----------
-
-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,
-   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).
--  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
-   (although it will not lit anything else around unless baking). This
-   color is constant.
--  Specular Exponent (or "Shininess"/"Intensity" in some 3D DCCs) is the
-   way light is reflected. If the value is high, light is reflected
-   completely, otherwise it is diffused more and more.
-
-Below is an example of how they interact:
-
-.. image:: /img/fixed_material_colors.png
-
-Shader & shader param
-~~~~~~~~~~~~~~~~~~~~~
-
-Regular shader materials allow custom lighting code. Fixed materials
-come with four predefined shader types:
-
--  **Lambert**: The standard diffuse light, where the amount of light is
-   proportional to the angle from the light emitter.
--  **Wrap**: A variation on Lambert, where the "coverage" of the light
-   can be changed. This is useful for many types of materials such as
-   wood, clay, hair, etc.
--  **Velvet**: This is similar to Lambert, but adds light scattering in
-   the edges. It's useful for leathers and some types of metals.
--  **Toon**: Standard toon shading with a coverage parameter. The
-   specular component also becomes toon-ized.
-
-.. image:: /img/fixed_material_shader.png
-
-Detail & detail mix
-~~~~~~~~~~~~~~~~~~~
-
-Detail is a second diffuse texture which can be mixed with the first one
-(more on textures later!). Detail blend and mix control how these are
-added together, here's an example of what detail textures are for:
-
-.. image:: /img/fixed_material_detail.png
-
-Normal depth
-~~~~~~~~~~~~
-
-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
-
-Glow
-~~~~
-
-This value controls how much of the color is sent to the glow buffer. It
-can be greater than 1 for a stronger effect. For glow to work, a
-WorldEnvironment must exist with Glow activated.
-
-.. image:: /img/fixed_material_glow.png
-
-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
-
-Point size, line width
-~~~~~~~~~~~~~~~~~~~~~~
-
-When drawing points or lines, the size of them can be adjusted here per
-material.
-
-Textures
---------
-
-Almost all of the parameters above can have a texture assigned to them.
-There are four options to where they can get their UV coordinates:
-
--  **UV Coordinates (UV Array)**: This is the regular UV coordinate
-   array that was imported with the model.
--  **UV x UV XForm**: UV Coordinates multiplied by the UV Xform matrix.
--  **UV2 Coordinates**: Some imported models might have come with a
-   second set of UV coordinates. These are common for detail textures or
-   for baked light textures.
--  **Sphere**: Spherical coordinates (difference of the normal at the
-   pixel by the camera normal).
-
-The value of every pixel of the texture is multiplied by the original
-parameter. This means that if a texture is loaded for diffuse, it will
-be multiplied by the color of the diffuse color parameter. Same applies
-to all the others except for specular exponent, which is replaced.

learning/features/3d/importing_3d_meshes.rst

@@ -1,59 +0,0 @@
-.. _doc_importing_3d_meshes:
-
-Importing 3D meshes
-===================
-
-Introduction
-------------
-
-Godot supports a flexible and powerful :ref:`3D scene importer
-<doc_importing_3d_scenes>` that allows for full scene importing. For a lot of
-artists and developers this is more than enough. However, many do not like this
-workflow as much and prefer to import individual 3D Meshes and build the scenes
-inside the Godot 3D editor themselves. (Note that for more advanced features
-such as skeletal animation, there is no option to the 3D Scene Importer).
-
-The 3D mesh import workflow is simple and works using the OBJ file
-format. The imported meshes result in a .msh binary file which the user
-can put into a :ref:`class_meshinstance`, which in turn can be placed
-somewhere in the edited scene.
-
-Importing
----------
-
-Importing is done through the Import 3D Mesh menu:
-
-.. image:: /img/mesh_import.png
-
-Which opens the Mesh import window:
-
-.. image:: /img/mesh_dialog.png
-
-This dialog allows the import of one more more OBJ files into a target
-path. OBJ files are converted to .msh files. Files are imported without
-any material on them, material has to be added by the user (see the
-:ref:`doc_fixed_materials` tutorial). If the external OBJ file is changed it
-will be re-imported, while keeping the newly assigned material.
-
-Options
--------
-
-A few options are present. Normals are needed for regular shading, while
-Tangents are needed if you plan to use normal-mapping on the material. In
-general, OBJ files describe how to be shaded very well, but an option to
-force smooth shading is available.
-
-Finally, there is an option to weld vertices. Given OBJ files are
-text-based, it is common to find some of these with vertices that do not
-match, which results in strange shading. The weld vertices option merges
-vertices that are too close to keep proper smooth shading.
-
-Usage
------
-
-Mesh resources (what this importer imports to) are used inside MeshInstance
-nodes. Simply set them to the Mesh property of them.
-
-.. image:: /img/3dmesh_instance.png
-
-And that is it.

learning/features/3d/importing_3d_scenes.rst

@@ -1,435 +0,0 @@
-.. _doc_importing_3d_scenes:
-
-Importing 3D scenes
-===================
-
-Introduction
-------------
-
-Most game engines just import 3D objects, which may contain skeletons or
-animations, and then all further work is done in the engine UI, like
-object placement, full scene animations, etc. In Godot, given the node
-system is very similar to how 3D DCC tools (such as Maya, 3DS Max or Blender)
-work, full 3D scenes can be imported in all their glory. Additionally, by using
-a simple language tag system, it is possible to specify that objects are
-imported as several things, such as collidable, rooms and portals, vehicles
-and wheels, LOD distances, billboards, etc.
-
-This allows for some interesting features:
-
--  Importing simple scenes, rigged objects, animations, etc.
--  Importing full scenes. Entire scenarios can be created and updated in
-   the 3D DCC and imported to Godot each time they change, then only
-   little editing is needed from the engine side.
--  Full cutscenes can be imported, including multiple character
-   animation, lighting, camera motion, etc.
--  Scenes can be further edited and scripted in the engine, where
-   shaders and environment effects can be added, enemies can be
-   instanced, etc. The importer will update geometry changes if the
-   source scene changes but keep the local changes too (in real-time
-   while using the Godot editor!)
--  Textures can be all batch-imported and updated when the source scene
-   changes.
-
-This is achieved by using a very simple language tag that will be
-explained in detail later.
-
-Exporting DAE files
--------------------
-
-Why not FBX?
-~~~~~~~~~~~~
-
-Most game engines use the FBX format for importing 3D scenes, which is
-definitely one of the most standardized in the industry. However, this
-format requires the use of a closed library from Autodesk which is
-distributed with a more restrictive licensing terms than Godot. The plan
-is, sometime in the future, to implement an external conversion binary,
-but meanwhile FBX is not really supported.
-
-Exporting DAE files from Maya and 3DS Max
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Autodesk added built-in collada support to Maya and 3DS Max, but it's
-really broken and should not be used. The best way to export this format
-is by using the
-`OpenCollada <https://github.com/KhronosGroup/OpenCOLLADA/wiki/OpenCOLLADA-Tools>`__
-plugins. They work really well, although they are not always up-to date
-with the latest version of the software.
-
-Exporting DAE files from Blender
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Blender also has built-in collada support, but it's really broken and
-should not be used either.
-
-Godot provides a `Python
-Plugin <https://github.com/godotengine/collada-exporter>`__
-that will do a much better job at exporting the scenes.
-
-The import process
-------------------
-
-Import process begins with the 3D scene import menu:
-
-.. image:: /img/3dimp_menu.png
-
-That opens what is probably the biggest of all the import dialogs:
-
-.. image:: /img/3dimp_dialog.png
-
-Many options exist in there, so each section will be explained as
-follows:
-
-Source & target paths
-~~~~~~~~~~~~~~~~~~~~~
-
-To import, two options are needed. The first is a source .dae file
-("Digital Asset Exchange", the extension of the Collada standard).
-More import formats will eventually added, but Collada is the most
-complete open format as of this writing.
-
-A target folder needs to be provided, so the importer can import the
-scene there. The imported scene will have the same filename as the
-source one, except for the .scn extension, so make sure you pick good
-names when you export!
-
-The textures will be copied and converted. Textures in 3D applications
-are usually just PNG or JPG files. Godot will convert them to video
-memory texture compression format (s3tc, pvrtc, ericsson, etc.) by
-default to improve performance and save resources.
-
-Since the original textures, 3D file and textures are usually not needed,
-it's recommended to keep them outside the project. For some hints on
-how to do this the best way, you can check the :ref:`doc_project_organization`
-tutorial.
-
-Two options for textures are provided. They can be copied to the same
-place as the scene, or they can be copied to a common path (configurable
-in the project settings). If you choose this, make sure no two textures
-are named the same.
-
-3D rigging tips
-~~~~~~~~~~~~~~~
-
-Before going into the options, here are some tips for making sure your
-rigs import properly
-
--  Only up to 4 weights are imported per vertex, if a vertex depends of
-   more than 4 bones, only the 4 most important bones (the one with the
-   most weight) will be imported. For most models this usually works
-   fine, but just keep it in mind.
--  Do not use non-uniform scale in bone animation, as this will likely
-   not import properly. Try to accomplish the same effect with more
-   bones.
--  When exporting from Blender, make sure that objects modified by a
-   skeleton are children of it. Many objects can be modified by a single
-   skeleton, but they all should be direct children.
--  The same way, when using Blender, make sure that the relative
-   transform of children nodes to the skeleton is zero (no rotation, no
-   translation, no scale. All zero and scale at 1.0). The position of
-   both objects (the little orange dot) should be at the same place.
-
-3D import options
-~~~~~~~~~~~~~~~~~
-
-This section contains many options to change the way import workflow
-works. Some (like HDR) will be better explained in other sections, but
-in general a pattern can be visible in the options and that is, many of
-the options end with "-something". For example:
-
--  Remove Nodes (-noimp)
--  Set Alpha in Materials (-alpha)
--  Create Collisions (-col).
-
-This means that the object names in the 3D DCC need to have those
-options appended at the end for the importer to tell what they are. When
-imported, Godot will convert them to what they are meant to be.
-
-**Note:** Maya users must use “_" (underscore) instead of "-" (minus).
-
-Here is an example of how a scene in the 3D DCC looks (using Blender),
-and how it is imported to Godot:
-
-.. image:: /img/3dimp_blender.png
-
-Notice that:
-
--  The camera was imported normally.
--  A Room was created (-room).
--  A Portal was created (-portal).
--  The Mesh got static collision added (-col).
--  The Light was not imported (-noimp).
-
-Options in detail
-~~~~~~~~~~~~~~~~~
-
-Following is a list of most import options and what they do in more
-detail.
-
-Remove nodes (-noimp)
-^^^^^^^^^^^^^^^^^^^^^
-
-Node names that have this at the end will be removed at import time, mo
-matter their type. Erasing them afterwards is most of the times
-pointless because the will be restored if the source scene changes.
-
-Import animations
-^^^^^^^^^^^^^^^^^
-
-Some scene formats (.dae) support one or more animations. If this is
-checked, an :ref:`class_animationplayer` node will be
-created, containing the animations.
-
-Compress geometry
-^^^^^^^^^^^^^^^^^
-
-This option (disabled [STRIKEOUT:or more like, always enabled] at the
-moment at the time of writing this) will compress geometry so it takes
-less space and renders faster (at the cost of less precision).
-
-Force generation of tangent arrays
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-The importer detects when you have used a normalmap texture, or when the
-source file contains tangent/binormal information. These arrays are
-needed for normalmapping to work, and most exporters know what they do
-when they export this. However, it might be possible to run into source
-scenes that do not have this information which, as a result, make
-normal-mapping not work. If you notice that normal-maps do not work when
-importing the scene, turn this on!
-
-SRGB -> linear of diffuse textures
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When rendering using HDR (High Dynamic Range) it might be desirable to
-use linear-space textures to achieve a more real-life lighting.
-Otherwise, colors may saturate and contrast too much when exposure
-changes. This option must be used together with the SRGB option in
-:ref:`class_worldenvironment`. The texture import
-options also have the option to do this conversion, but if this one is
-turned on, conversion will always be done to diffuse textures (usually
-what is desired). For more information, read the :ref:`doc_high_dynamic_range`
-tutorial.
-
-Set alpha in materials (-alpha)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-When working with most 3D DCCs, its pretty obvious when a texture is
-transparent and has opacity and this rarely affects the workflow or
-final rendering. However, when dealing with real-time rendering,
-materials with alpha blending are usually less optimal to draw, so they
-must be explicitly marked as such.
-
-Originally Godot detected this based on whether if the source texture
-had an alpha channel, but most image manipulation applications like Photoshop or
-Gimp will export this channel anyway even if not used. Code was added
-later to check manually if there really was any transparency in the
-texture, but artists will anyway and very often lay uvmaps into opaque
-parts of a texture and leave unused areas (where no UV exists)
-transparent, making this detection worthless.
-
-Finally, it was decided that it's best to import everything as opaque
-and leave artists to fix materials that need transparency when it's
-obvious that they are not looking right (see the :ref:`doc_materials`
-tutorial).
-
-As a helper, since every 3D DCC allows naming the materials and keeping
-their name upon export, the (-alpha) modifier in their name will hint
-the 3D scene importer in Godot that this material will use the alpha
-channel for transparency.
-
-Set vert. color in materials (-vcol)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Most 3D DCCs support vertex color painting. This is generally applied as
-multiplication or screen blending. However, it is also often the case
-that your exporter will export this information as all 1s, or export it
-as something else and you will not realize it. Since most of the cases
-this option is not desired, just add this to any material to confirm
-that vertex colors are desired.
-
-Create collisions (-col, -colonly)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-Option "-col" will work only for Mesh nodes. If it is detected, a child
-static collision node will be added, using the same geometry as the mesh.
-
-However, it is often the case that the visual geometry is too complex or
-too un-smooth for collisions, which end up not working well. To solve
-this, the "-colonly" modifier exists, which will remove the mesh upon
-import and create a :ref:`class_staticbody` collision instead.
-This helps the visual mesh and actual collision to be separated.
-
-Option "-colonly" can be also used with Blender's empty objects.
-On import it will create a :ref:`class_staticbody` with
-collision node as a child. Collision node will have one of predefined shapes,
-depending on the Blender's empty draw type:
-
-.. image:: /img/3dimp_BlenderEmptyDrawTypes.png
-
--  Single arrow will create :ref:`class_rayshape`
--  Cube will create :ref:`class_boxshape`
--  Image will create :ref:`class_planeshape`
--  Sphere (and other non-listed) will create :ref:`class_sphereshape`
-
-For better visibility in Blender's editor user can set "X-Ray" option on collision
-empties and set some distinct color for them in User Preferences / Themes / 3D View / Empty.
-
-Create rooms (-room)
-^^^^^^^^^^^^^^^^^^^^
-
-This is used to create a room. As a general rule, any node that is a
-child of this node will be considered inside the room (including
-portals).
-
-.. For more information about rooms/portals, look at the [[Portals and Rooms]] tutorial.
-
-There are two ways in which this modifier can be used. The first is
-using a Dummy/Empty node in the 3D application with the "-room" tag. For this to
-work, the "interior" of the room must be closed (geometry of the
-children should contain walls, roof, floor, etc. and the only holes to
-the outside should be covered with portals). The importer will then
-create a simplified version of the geometry for the room.
-
-The second way is to use the "-room" modifier on a mesh node. This will
-use the mesh as the base for the BSP tree that contains the room bounds.
-Make sure that the mesh shape is **closed**, all normals **point
-outside** and that the geometry is **not self-intersecting**, otherwise
-the bounds may be computed wrong (BSP Trees are too picky and difficult
-to work with, which is why they are barely used anymore..).
-
-Anyway, the room will need portals, which are described next.
-
-Create portals (-portal)
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Portals are the view to look outside a room. They are always some flat
-shape on the surface of a room. If the portal is left alone, it is used
-to activate occlusion when looking inside<->outside the room.
-
-.. Again, more information on the [[Portals and Rooms]] tutorial.
-
-Basically, the conditions to make and import a portal from the 3D DCC
-are:
-
--  It should be a child of a room.
--  It should lay on the surface of the room (this doesn't need to be
-   super exact, just make it as close as you can by eye and Godot will
-   adjust it)
--  It must be a flat, convex shape, any flat and convex shape is okay, no
-   matter the axis or size.
--  Normals for the flat shape faces must **all point towards the
-   OUTSIDE** of the room.
-
-Here is how it usually looks:
-
-.. image:: /img/3dimp_portal.png
-
-To connect to rooms, simply make two identical portals for both rooms
-and place them overlapped. This does not need to be perfectly exact,
-again, as Godot will fix it.
-
-[..]
-^^^^
-
-The rest of the tags in this section should be rather obvious, or will
-be documented/changed in the future.
-
-Double-sidedness
-~~~~~~~~~~~~~~~~
-
-Collada and other formats support specifying the double-sidedness of
-the geometry (in other words, when not double-sided, back-faces are
-not drawn). Godot supports this option per Material, not per Geometry.
-
-When exporting from 3D DCCs that work with per-object double-sidedness
-(such as Blender of Maya), make sure that the double sided objects do
-not share a material with the single sided ones or the importer will
-not be able to discern.
-
-Animation options
-~~~~~~~~~~~~~~~~~
-
-Some things to keep in mind when importing animations. 3D DCCs allow
-animating with curves for every x,y,z component, doing IK constraints
-and other stuff. When imported for real-time, animations are sampled
-(at small intervals) so all this information is lost. Sampled
-animations are fast to process, but can use considerable amounts of
-memory.
-
-Because of this, the "Optimize" option exists but, in some cases, this
-option might break an animation, so make it sure to disable it if
-you notice any issues.
-
-Some animations are meant to be cycled (like walk animations) if this is
-the case, animation names that end in "-cycle" or "-loop" are
-automatically set to loop.
-
-Import script
-~~~~~~~~~~~~~
-
-Creating a script to parse the imported scene is actually really simple.
-This is great for post processing, changing materials, doing funny stuff
-with the geometry, etc.
-
-Create a script that basically looks like this:
-
-::
-
-    tool # needed so it runs in editor
-    extends EditorScenePostImport
-
-    func post_import(scene):
-      # do your stuff here
-      return scene # remember to return the imported scene
-
-The post-import function takes the imported scene as parameter (the
-parameter is actually the root node of the scene).
-
-Update logic
-~~~~~~~~~~~~
-
-Other types of resources (like samples, meshes, fonts, images, etc.) are
-re-imported entirely when changed and user changes are not kept.
-
-Because of 3D Scenes can be really complex, they use a different update
-strategy. The user might have done local changes to take advantage of
-the engine features and it would be really frustrating if everything is
-lost on re-import because the source asset changed.
-
-This led to the implementation of a special update strategy. The idea
-behind is that the user will not lose anything he or she did, and only
-added data or data that can't be edited inside Godot will be updated.
-
-It works like this:
-
-Strategy
-^^^^^^^^
-
-Upon changes on the source asset (ie: .dae), and on re-import, the
-editor will remember the way the scene originally was, and will track
-your local changes like renaming nodes, moving them or reparenting them.
-Finally, the following will be updated:
-
--  Mesh Data will be replaced by the data from the updated scene.
--  Materials will be kept if they were not modified by the user.
--  Portal and Room shapes will be replaced by the ones from the updated
-   scene.
--  If the user moved a node inside Godot, the transform will be kept. If
-   the user moved a node in the source asset, the transform will be
-   replaced. Finally, if the node was moved in both places, the
-   transform will be combined.
-
-In general, if the user deletes anything from the imported scene (node,
-mesh, material, etc.), updating the source asset will restore what was
-deleted. This is a good way to revert local changes to anything. If you
-really don't want a node anymore in the scene, either delete it from
-both places or add the "-noimp" tag to it in the source asset.
-
-Fresh re-import
-^^^^^^^^^^^^^^^
-
-It can also happen that the source asset changed beyond recognition and
-a full fresh re-import is desired. If so, simply re-open the 3D scene
-import dialog from the Import -> Re-Import menu and perform re-import.

learning/features/3d/index.rst

@@ -7,9 +7,7 @@
 
    introduction_to_3d
    3d_performance_and_limitations
-   importing_3d_meshes
-   importing_3d_scenes
-   materials
-   fixed_materials
+   spatial_material
+   shader_material
    high_dynamic_range
    using_gridmaps

learning/features/3d/introduction_to_3d.rst

@@ -169,30 +169,16 @@ this little menu inside the window because it is often overlooked!
 
 .. image:: /img/tuto_3d6.png
 
-Default lighting
+Default environment
 ----------------
 
-The 3D view has by some default options on lighting:
-
--  There is a directional light that makes objects visible while editing
-   turned on by default. It is no longer visible when running the game.
--  There is subtle default environment light to avoid places not reached
-   by the light to remain visible. It is also no longer visible when
-   running the game (and when the default light is turned off).
-
-These can be turned off by toggling the "Default Light" option:
+When created from the Project Manager, the 3D environment has a default sky.
 
 .. image:: /img/tuto_3d8.png
 
-Customizing this (and other default view options) is also possible via
-the settings menu:
-
-.. image:: /img/tuto_3d7.png
-
-Which opens this window, allowing to customize ambient light color and
-default light direction:
-
-.. image:: /img/tuto_3d9.png
+Given how physically based rendering works, it is advised to always try to
+work with a default environment in order to provide indirect and reflected
+light to your objects.
 
 Cameras
 -------
@@ -228,9 +214,5 @@ Lights
 ------
 
 There is no limitation on the number of lights nor of types of lights in
-Godot. As many as desired can be added (as long as performance allows). Shadow
-maps are, however, limited. The more they are used, the less the quality
-overall.
+Godot. As many as desired can be added (as long as performance allows). 
 
-It is possible to use :ref:`doc_light_baking`, to avoid using large amount of
-real-time lights and improve performance.

learning/features/3d/spatial_material.rst

@@ -0,0 +1,388 @@
+.. _doc_spatial_material:
+
+Spatial Material
+===============
+
+Introduction
+------------
+
+For Godot 3, instead of following the trend and focusing in shader graphs,
+we put most of the work offering a default material that covers far
+most use cases. This replaces the old "FixedMaterial" in Godot 2.x
+
+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.
+
+Flags
+-----
+
+Spatial materials have many flags determining the general usage of a material.
+
+.. image:: /img/spatial_material1.png
+
+Transparent
+~~~~~~~~~~~
+
+In Godot, materials are not transparent unless specifically toggled as such.
+The main reason behind this is because 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). 
+
+For this reason, they are assumed opaque unless specified otherwise. The
+main parameters that enable transparency automatically are:
+
+* Transparent flag (this one)
+* Blend mode set to other than Mix
+* Enabling distance or proximity fade
+
+Unshaded
+~~~~~~~~
+
+In most cases, it is desired that materials are affected by lighting.
+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.
+
+Vertex Lighting
+~~~~~~~~~~~~~~~
+
+Given 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
+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
+
+No Depth Test
+~~~~~~~~~~~~~~~
+
+In order for close objects to appear over far away objects, depth testing is performed.
+Disabling it has the result of objects appearing over (or under) everything else.
+
+Disabling this makes the most sense for drawing indicators in world space, and works
+very well with the "render priority" property of Material (see bottom).
+
+.. image:: /img/spatial_material3.png
+
+Use Point Size
+~~~~~~~~~~~~~~~
+
+This option is only active when the geometry rendered is made of points (it generally is just made of triangles when imported from 3D DCCs).
+If so, then points can be sized (see below).
+
+World Triplanar
+~~~~~~~~~~~~~~~
+
+When using triplanar mapping (see below, in the UV1 and UV2 settings) triplanar is computed in object local space. This option
+makes triplanar work in world space.
+
+Fixed Size
+~~~~~~~~~~
+
+Makes the object rendered at the same sizen no matter the distance. This is, again, useful mostly for indicators (no depth test and high render priority)
+and some types of billboards.
+
+Vertex Color
+------------
+
+This menu allows choosing what is done by default to vertex colors that come from your 3D modelling application. By default they are ignored.
+
+.. image:: /img/spatial_material4.png
+
+Use as Albedo
+~~~~~~~~~~~~~
+
+Vertex color is used as albedo color
+
+Is SRGB
+~~~~~~~
+
+Most 3D DCCs will likely export vertex colors as SRGB, so toggling this option on will help them
+look more faitful.
+
+
+Parameters
+-----------
+
+SpatialMaterial also has several, configurable parameters to tweak many aspects of the rendering:
+
+.. image:: /img/spatial_material5.png
+
+Diffuse Mode
+~~~~~~~~~~~~
+
+Specifies the algorithm used by diffuse scattering of light when hitting the object. The
+default one is Lambert, which does not vary with roughness. Other modes are also available:
+
+* 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.
+* Toon: Provides a hard cut for lighting, with smoothing affected by roughness.
+
+.. image:: /img/spatial_material6.png
+
+Specular Mode
+~~~~~~~~~~~~~
+
+Specified 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
+* 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.
+* Disabled: Sometimes, that blob gets in the way. Be gone!
+
+.. image:: /img/spatial_material7.png
+
+
+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.
+
+* 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.
+* Sub: Object is substracted.
+* Mul: Object is multiplied.
+
+.. image:: /img/spatial_material8.png
+
+Cull Mode
+~~~~~~~~~
+
+Detect which side of the object is not drawn when not visible:
+
+* 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
+
+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
+* 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.
+
+.. image:: /img/material_depth_draw.png
+
+Line Width
+~~~~~~~~~~
+
+When drawing lines, specify the width of the lines being drawn. This option is not available in most modern hardware.
+
+Point Size
+~~~~~~~~~~
+
+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:
+
+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
+
+Above options are only enabled for Particle Billboard.
+
+Grow
+~~~~
+
+Grows the object vertices by the direction pointed by their normal:
+
+.. image:: /img/spatial_material10.png
+
+This is commonly used to create cheap outlines. Add a second material pass, make it black an unshaded, reverse culling (Cull Front), and
+add some grow:
+
+.. image:: /img/spatial_material11.png
+
+
+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.
+
+.. 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.
+
+Material colors, maps and channels
+----------------------------------
+
+Besides the parameters, what defines materials themselves are the colors, textures and channels. Godot supports a very extensive list
+of them (arguably far more than any of the other big game engines). They will be described in detail below:
+
+Albedo
+~~~~~~
+
+Albedo is the base color for the material. Everything else works based on it. When set to *unshaded* this is the only color that is visible as-is.
+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. 
+
+*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.
+
+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
+
+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).
+Most common types of materials can be achieved from the right combination of *Metallic* and *Roughness*.
+
+.. image:: /img/spatial_material14.png
+
+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
+final image, and is not affected by other lighting in the scene.
+
+
+.. image:: /img/spatial_material15.png
+
+
+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.
+
+.. 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.
+
+.. image:: /img/spatial_material17.png
+
+Rim size depends on roughness and there is a special parameter to specify how it must be colored. If *tint* is 0, the color of the light is used for the rim. If *tint* is 1,
+then the albedo of the material is used. Using intermediate values generally works best.
+
+Clearcoat
+~~~~~~~~~
+
+The *clearcoat* parameter is used mostly to add a *secondary* pass of transparent coat to the material. This is very common in car paint and toys.
+In practice, it's a smaller specular blob added on top of the existing material.
+
+Anisotropy
+~~~~~~~~~~
+
+Changes the shape of the specular blow and aligns it to tangent space. Anisotropy is commonly used with hair, or to make materials such as brushed alluminium more realistic.
+It works specially well when combined with flowmaps.
+
+.. image:: /img/spatial_material18.png
+
+
+Ambient Occlusion
+~~~~~~~~~~~~~~~~~~
+
+In Godot's new PBR workflow, it is possible to specify a pre-baked ambient occlusion map. This map affects how much ambient light reaches each surface of the object (it does not affect direct light).
+While it is possible to use Scren Space Ambient Occlusion (SSAO) to generate AO, nothing will beat the quality of a nicely baked AO map. It is recommended to pre-bake AO whenever possible.
+
+.. image:: /img/spatial_material19.png
+
+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.
+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
+
+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.
+
+.. image:: /img/spatial_material21.png
+
+
+Transmission
+~~~~~~~~~~~~
+
+Controls how much light from the lit side (visible to light) is transfered to the dark side (opposite side to light). This works very well for thin objects such as tree/plant leaves,
+grass, human ears, etc.
+
+.. image:: /img/spatial_material22.png
+
+Refraction
+~~~~~~~~~~~
+
+When refraction is enabled, it supersedes alpha blending and Godot attempts to fetch information from behind the object being rendered instead. This allows distorting the transparency
+in a way very similar to refraction.
+
+.. image:: /img/spatial_material23.png
+
+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
+
+UV1 and UV2
+~~~~~~~~~~~~
+
+Godot supports 2 UV channels per material. Secondary UV is often useful for AO or Emission (baked light). UVs can be scaled and offseted, which is useful in textures with repeat.
+
+Triplanar Mapping
+~~~~~~~~~~~~~~~~~
+
+Trilpanar mapping is supported for both UV1 and UV2. This is an alternative way to obtain texture coordinates, often called "Autotexture". Textures are sampled in X,Y and Z and blended by the normal.
+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
+
+Proximity and Distance Fade
+----------------------------
+
+Godot allows material to fade in proximity to another, as well as depending on the distance to the viewer.
+Proximity fade is very useful for effecs such as soft particles, or a mass of water with a smooth blending to the shores.
+Distance fade is useful for light shafts or indicators that are only present after a given distance.
+
+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
+
+Render Priority
+---------------
+
+Rendering order can be changed for objects, although this is mostly useful for transparent ojects (or opaque objects that do depth draw but no color draw, useful for cracks on the floor).
+
+