Updated documentation

addons/material_maker/doc/index.rst

@@ -1,10 +1,5 @@
-.. Material Maker documentation master file, created by
-   sphinx-quickstart on Wed Aug 22 07:12:09 2018.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
-Welcome to Material Maker's documentation!
-==========================================
+Material Maker User Manual
+==========================
 
 .. toctree::
    :maxdepth: 2

addons/material_maker/doc/nodes_common.rst

@@ -12,8 +12,26 @@ Outputs
 ^^^^^^^
 
 Nodes can have several outputs that represent the images they provide. Each node output can be
-connected to several node inputs. Each node output can be either **greyscale**, **color** or
-**RGBA**. Greyscale ports are drawn in grey, color in blue and RGBA in semi-transparent green.
+connected to several node inputs. Each node output (and input) can be:
+
+* a **greyscale image** (shown in grey) 
+
+* a **color image** (shown in blue)
+
+* an **RGBA image** (shown in semi-transparent green)
+
+* a **2D signed distance function** (shown in orange)
+
+* a **3D signed distance function** (shown in red)
+
+Greyscale, color and RGBA inputs and outputs can be connected to each other and will automatically be
+converted when required.
+
+2D signed distance functions have a specific preview that shows the associated signed distance
+field. They can be converted into greyscale images using the `sdShow node`.
+
+3D signed distance functions have a specific preview that shows the lit 3Dscene. They can be
+converted into a greyscale height map and a color normal map using the `Render node`.
 
 Next to the output, an (open or closed) eye icon indicates that a preview is available. Clicking
 on it will show the preview at the bottom of the node. When a node has several outputs, only
@@ -23,7 +41,7 @@ Inputs
 ^^^^^^
 
 Inputs are images the node will transform (if any). An input is always connected to at most
-an output. Inputs generally have a default image that is used when it is not connected.
+an output. Inputs generally have a default value that is used when it is not connected.
 
 Parameters
 ^^^^^^^^^^

addons/material_maker/doc/shader_nodes.rst

@@ -2,9 +2,16 @@ Shader nodes
 ------------
 
 Most nodes in Material Maker are shader nodes. Their outputs are not defined as images,
-but as shader programs that calculates the color of a pixel from its coordinates.
+but as shader programs that calculates
+
+* the color of a pixel from its coordinates for greyscale, color and RGBA outputs
+
+* the signed distance of a 2D point from its coordinates for SDF2D outputs
+
+* the signed distance of a 3D point from its coordinates for SDF3D outputs
+
 When shader nodes are connected, Material Maker will combine their shader programs.
-As a consequence, shader nodes are resolution independant.
+As a consequence, most shader nodes are resolution independant.
 
 Editing a shader node will show the **Node Editor** window.
 
@@ -35,6 +42,7 @@ the new parameter. On this line:
   are **float**, **size**, **enum**, **boolean**, **color** and **gradient**
 * on the right of the type selector, controls can be used to define a default value and
   constraints for the parameter
+* **float** parameters can be assigned a **control** variable in the 2D preview
 
 To use a parameter in your shader code it is necessary to prefix it with a dollar sign.
 So a **foo** parameter can be refered to by **$foo** or **$(foo)** in the shader code.
@@ -60,6 +68,12 @@ want to define interesting default inputs for your nodes, so it is possible
 to see their effect without connecting the inputs (the screenshot above is the
 Blend filter and has a vertical and an horizontal gradient as default inputs).
 
+The "Function" checkbox changes the way the code is generated for this input.
+When set to true, the input is generated as a function and can be used in the *Instance
+functions* section. If the parameter is false, the input code is inlined. is is not advised
+to set this parameter to true when not required, because generating functions can have
+an impact on performance.
+
 In shader code, inputs are used as functions that take a single **vec2** parameter. For
 example **$myinput(2.0*$uv+vec2(0.2, 0.3))** refers to **myinput**, scaled and translated.
 

addons/material_maker/doc/user_interface.rst

@@ -117,6 +117,13 @@ or group of nodes can easily be shared using this format.
 The contents of the clipboard can be pasted into a graph using the **Edit -> Paste**
 menu or the **Control+V** keyboard shortcut.
 
+Background 3D preview
+^^^^^^^^^^^^^^^^^^^^^
+
+The bottom left ("cube") button can be used to show a 3D preview in the background
+of the graph view. The blue/red arrows icon is used to rotate the object or the view,
+and other controls are similar to the 3D preview.
+
 Library pane
 ------------
 
@@ -135,18 +142,34 @@ give focus to the search field using the **Control+F** keyboard shortcut.
 Preview pane
 ------------
 
-The preview pane shows a 3D preview of the material, and a 2D preview of the first output
-of the selected node.
+The preview pane has tabs for a 2D preview and the 3D preview.
 
-.. image:: images/preview.png
+2D preview
+^^^^^^^^^^
+
+The 2D preview shows a tiled preview of the first output of the selected
+node. The animated dashed lines show the bounds of the texture, so it is
+easy to check that the texture wraps correctly.
+
+.. image:: images/preview_2d.png
+  :align: center
+
+Depending on the selected node, controls can be shown and they can me moved
+around to modify the associated parameters.
+
+3D preview
+^^^^^^^^^^
+
+The 3D preview pane shows a 3D preview of the current material.
+
+.. image:: images/preview_3d.png
   :align: center
 
 The left select button can be used to select a model for the 3D preview, and the second
 one provides different environments. The **R** button can be used to start and stop the
-object's rotation animation. Pressing the **O** button will show the 3D preview as
-background of the graph pane.
+object's rotation animation.
 
-In the 3d view, the object can be rotated about the yaw and the pitch axes (from the
+In the 3D view, the object can be rotated about the yaw and the pitch axes (from the
 camera's point of view) by holding the right mouse button and moving the mouse horizontally
 or vertically. The object can also be rotated about the roll axis by holding Shift and
 and the right mouse button and moving the mouse horizontally.
@@ -158,8 +181,6 @@ Rotating the object or the camera will automatically disable the object's rotate
 The mouse wheel can be used to move the camera along its longitudinal axis (hense zooming
 forward or backward).
 
-Clicking on the 2D preview will minimize or maximize it.
-
 Main menu
 ---------