Docs: Materials and Shading Environment

docs/rendering/index.rst

@@ -6,3 +6,5 @@ Rendering
     :maxdepth: 2
 
     lighting
+    materials
+    shading_environment

docs/rendering/lighting.rst

@@ -83,4 +83,4 @@ Crown automatically adds an implicit skydome Unit to every new Level created
 with the :ref:`Level Editor <level_editor>`. It is rendered on the current
 camera's far plane and is always centered to it, so it appears infinitely
 distant and does not shift as the camera moves. Its texture and intensity are
-configured via the :ref:`Shading Environment`.
+configured via the :ref:`Shading Environment <Global Lighting>`.

docs/rendering/materials.rst

@@ -0,0 +1,59 @@
+=========
+Materials
+=========
+
+Materials in Crown are resources with the ``.material`` extension. They define
+the shading (i.e. the visual appearance) of objects in the scene.
+
+.. figure:: images/materials.png
+   :align: center
+
+   Some materials displayed in the Project Browser.
+
+At the technical level, a material binds a shader together with its options
+and parameters (uniforms and samplers). For example, the built-in
+``core/units/primitive`` material uses the shader named ``mesh`` and assigns
+values appropriate to primitive objects to all uniforms that shader exposes.
+
+Creating Materials
+==================
+
+Materials are normally created indirectly by the :ref:`importers
+<importing_resources>` when you bring in external resources.
+
+For instance:
+
+* Importing a 3D scene automatically generates the required ``.material``
+  resources
+* Importing sprites also produces associated material resources
+
+You can also create standalone materials directly in the :ref:`Level Editor
+<level_editor>`:
+
+1. Open the :ref:`Project Browser`
+2. Right-click inside the target folder
+3. Choose ``New Material...``
+4. Give it a unique name and confirm
+
+Assigning Materials to Units
+============================
+
+Materials are assigned to units through their rendering components. The ``Mesh
+Renderer`` component for example exposes a ``Material`` property.
+
+.. figure:: images/mesh_renderer_material.svg
+   :align: center
+
+   The Material selector in the Mesh Renderer component.
+
+Click the folder icon next to the material's name to open the Material Chooser
+and pick the desired material from the list.
+
+You can also assign materials programmatically at runtime via
+the :ref:`RenderWorld` Lua API.
+
+Modifying Material properties
+=============================
+
+Once a material is assigned, you can modify its properties dynamically from
+Lua scripts using the :ref:`Material` API.

docs/rendering/shading_environment.rst

@@ -0,0 +1,77 @@
+===================
+Shading Environment
+===================
+
+The shading environment is a regular :ref:`unit <Units>` that groups
+components controlling global rendering features. Crown uses the properties
+defined in this unit to drive many aspects of scene rendering.
+
+.. figure:: images/shading_environment.png
+   :align: center
+
+   The Shading Environment unit with some of its components shown in the Inspector.
+
+Custom Shading Environment
+==========================
+
+Every level must contain exactly one shading environment unit named
+``shading_environment``. When you create a new level with the :ref:`Level
+Editor`, Crown inserts a default shading environment unit for that level.
+
+Because the shading environment is a Unit, you can edit its components in the
+Inspector and :ref:`save the unit as a prefab<From the Level Editor>` for
+reuse in other levels.
+
+Default components
+==================
+
+Crown provides a set of components commonly attached to the shading
+environment. These components establish the scene base look and control
+post-processing effects.
+
+Global Lighting
+---------------
+
+The Global Lighting component controls the :ref:`Skydome` and ambient light
+contribution:
+
+* ``Skydome Map``: equirectangular projection texture used to render the skydome
+* ``Skydome Intensity``: multiplier applied to the skydome texture to boost or
+  soften its contribution
+* ``Ambient Color``: base color added to objects when direct lighting is
+  absent
+
+Fog
+---
+
+The Fog component simulates atmospheric scattering between the camera and
+shaded objects:
+
+* ``Color``: fog base color
+* ``Density``: overall fog strength; higher values make distant objects appear
+  foggier
+* ``Range Min`` / ``Range Max``: distances from the camera where fog starts
+  and ends
+* ``Sun Blend``: mixes the :ref:`sun <Directional light>` color into the fog
+  (0 = no sun influence, 1 = fog color replaced by sun color)
+* ``Enabled``: toggle the fog simulation
+
+Bloom
+-----
+
+The Bloom component adds glow around very bright parts of the image.
+
+* ``Weight``: blending weight of the bloom contribution (0 = no bloom contribution, 1 = image is replaced by bloom)
+* ``Intensity``: bloom brightness
+* ``Enabled``: toggle the effect
+
+Tonemap
+-------
+
+The Tonemap component maps the renderer's HDR output to the displayable color
+range of the monitor.
+
+* ``Gamma``: no complex tonemapping, only gamma correction
+* ``Reinhard``
+* ``Filmic``
+* ``ACES``