Doc update (everything except nodes from the library)

addons/material_maker/doc/base_library.rst

@@ -0,0 +1,15 @@
+Available nodes in base library
+===============================
+
+This section describes all nodes that can are provided in the base library
+to describe procedural materials.
+
+.. toctree::
+	:maxdepth: 2
+
+	nodes_simple
+	nodes_pattern
+	nodes_noise
+	nodes_filter
+	nodes_transform
+	nodes_miscellaneous

addons/material_maker/doc/index.rst

@@ -12,3 +12,4 @@ Welcome to Material Maker's documentation!
    intro
    user_interface
    nodes
+   base_library

addons/material_maker/doc/nodes.rst

@@ -1,13 +1,14 @@
-Available nodes
+Nodes overview
-===============
+==============
 
-This section describes all nodes that can be used in a procedural material.
+Material Maker provides different node types to describe materials. Nodes may
+have parameters, inputs and outputs.
 
 .. toctree::
+   :maxdepth: 2
 
-	nodes_simple
+   nodes_common
-	nodes_pattern
+   shader_nodes
-	nodes_noise
+   texture_nodes
-	nodes_filter
+   remote_nodes
-	nodes_transform
+   subgraph_nodes
-	nodes_miscellaneous

addons/material_maker/doc/nodes_common.rst

@@ -0,0 +1,100 @@
+Common properties of nodes
+--------------------------
+
+The nodes will always have outputs that will be connected to the inputs of other
+nodes. They may also (and will probably) have parameters that can be modified
+in the user interface, and inputs to receive data from other nodes.
+
+.. image:: images/node_example.png
+  :align: center
+
+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.
+
+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
+one of them can be previewed at a time.
+
+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.
+
+Parameters
+^^^^^^^^^^
+
+Parameters are used to configure nodes. The following types are supported:
+
+* **float** parameters are used whenever a real number is needed. Float parameters have
+  bounds, but it is possible to ignore them (at your own risk). To modify a float parameter,
+  click in the text field and enter a new value, or click and drag left or right to decrease
+  or decrease its value. When the lower or upper bound is reach, the value wil stick to it,
+  but dragging again from there makes it possible to go beyond the limit.
+* **size** parameters are power of two values for the image size. They are used when
+  actually storing data in a texture, or when performing resolution dependent calculations
+  such as convolutions. They are shown as drop down list boxes.
+* **enumerated** parameters are used when nodes have different named options and shown as
+  drop down list boxes.
+* **boolean** parameters are shown as check boxes.
+* **color** parameters are shown as Color selectors.
+* **gradient** parameters are edited in dedicated editor widgets. Cursors can be added by
+  double-clicking in the lower part of the widget, dragged left and right using the left
+  mouse button, and removed using the right mouse button.
+
+  The drop down list box can be used to select one of the 4 interpolation options.
+  Double clicking in the upper part of the gradient editor will open a larger version of the
+  widget to move cursors mode precisely.
+
+  Finally, it is possible to drag and drop from the upper part of a gradient editor widget to
+  another to duplicate the gradient parameter, or from any **Colorize** node variant in the
+  library to a gradient editor widget.
+
+.. image:: images/gradient_editor.png
+	:align: center
+
+Randomness
+^^^^^^^^^^
+
+Nodes that provide random patterns have an implicit **seed** parameter. It is not possible
+to edit it directly, but moving the node in the graph will change its value. It is possible
+to freeze the seed value using the small dice button in the node's title bar in the graph.
+
+.. image:: images/random_node.png
+	:align: center
+
+Subgraphs also have their seed and transmit it to their children unless not configured to
+do so, or the children's seeds are frozen.
+
+Modifying nodes
+^^^^^^^^^^^^^^^
+
+Most nodes in Material Maker can be modified, but they first have to be made editable.
+To do this, select a node, and use the **Tools -> Make the selected nodes editable**
+menu item or the **Control+E** keyboard shortcut.
+
+.. image:: images/editable_node.png
+	:align: center
+
+When made editable, 3 buttons are shown at the bottom of the node:
+
+* A pencil-shaped button to edit the node (the precise behavior of this button depends
+  on the node type)
+* A folder-like button to load an existing node template
+* A floppy disk button to save the node as a template
+
+To be reusable directly, templates must be saved in the **generators** directory in
+the install dir (or the **addon/material_maker/nodes** directory when using Material
+Maker as a Godot addon). All nodes templates saved in this directory are shown in
+the **Tools -> Create** menu.
+
+It is absolutely not necessary to save newly created nodes as templates, but this
+makes them a lot easier to access and results in smaller material files (only
+references to the templates are saved and not the whole node description).
+Consequently, modifying a template without ensuring compatibility with the old
+version (i.e. removing or renaming parameters, removing or swapping inputs or
+outputs).

addons/material_maker/doc/nodes_filter.rst

@@ -4,6 +4,7 @@ Filter nodes
 The filter nodes accept one or several inputs and generate one or several images.
 
 .. toctree::
+	:maxdepth: 1
 
 	node_filter_blend
 	node_filter_blur

addons/material_maker/doc/nodes_miscellaneous.rst

@@ -0,0 +1,10 @@
+Miscellaneous nodes
+-------------------
+
+.. toctree::
+	:maxdepth: 1
+
+	node_miscellaneous_buffer
+	node_miscellaneous_debug
+	node_miscellaneous_remote
+	node_miscellaneous_switch

addons/material_maker/doc/nodes_noise.rst

@@ -5,6 +5,7 @@ The noise nodes are nodes that do not accept any input and generate one or sever
 made from random patterns.
 
 .. toctree::
+	:maxdepth: 1
 
 	node_noise
 	node_noise_perlin

addons/material_maker/doc/nodes_pattern.rst

@@ -4,6 +4,7 @@ Pattern nodes
 The generator nodes are nodes that do not accept any input and generate one or several images.
 
 .. toctree::
+	:maxdepth: 1
 
 	node_pattern_bricks
 	node_pattern_fibers

addons/material_maker/doc/nodes_simple.rst

@@ -4,6 +4,7 @@ Simple nodes
 The simple nodes are nodes that do not accept any input and generate one or several simple shapes.
 
 .. toctree::
+	:maxdepth: 1
 
 	node_simple_gradient
 	node_simple_gradient_circular

addons/material_maker/doc/nodes_transform.rst

@@ -1,9 +1,10 @@
-Filter nodes
+Transform nodes
 ------------
 
-The generator nodes are nodes that do not accept any input and generate one or several images.
+The transform nodes are nodes that affect the geometry of their input.
 
 .. toctree::
+	:maxdepth: 1
 
 	node_transform
 	node_transform_kaleidoscope

addons/material_maker/doc/remote_nodes.rst

@@ -0,0 +1,74 @@
+Remote nodes
+------------
+
+Remote nodes have no input or output. They are only used to control (remotely) the
+parameters of other nodes. They can be used to either gather important parameters
+of a complex graph or define the parameters of a subgraph node.
+
+Creating a remote node
+^^^^^^^^^^^^^^^^^^^^^^
+
+Remote nodes can be created by dragging a Miscellaneous/Remote node from the library
+pane to a graph pane.
+
+Configuring a remote node
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Remote nodes provide two kinds of controls:
+
+* linked widgets, that are associated to parameters in the graph and whose values are copied
+  into the target parameters
+* configuration widgets, that can be used to define named configurations of the target
+  parameters
+
+Linked widgets
+~~~~~~~~~~~~~~
+
+.. |create_linked_widget| image:: images/create_linked_widget.png
+.. |add_linked_widget| image:: images/add_linked_widget.png
+.. |remove_linked_widget| image:: images/remove_linked_widget.png
+
+Linked widgets can be used to modify at the same time several parameters from several nodes.
+
+When hovering a linked widget, the user interface will show which parameters it controls.
+
+.. image:: images/remote_create_linked_widget.gif
+	:align: center
+
+To create a linked widget, click on the |create_linked_widget| button and select a parameter
+to be controlled in another node. This will create a new linked widget whose type is the
+same as the selected parameter.
+
+More parameters can be controlled by the same linked widget. To add one, click on the
+|add_linked_widget| button of the linked widget, and select the parameter. While
+associating parameters to linked widgets, Material Maker will check compatibility.
+
+To delete a linked widget, click on its |remove_linked_widget| button. 
+
+Configuration widgets
+~~~~~~~~~~~~~~~~~~~~~
+
+.. |create_configuration_widget| image:: images/create_configuration_widget.png
+
+Configuration widgets are used to create named configurations for associated parameters
+in the graph.
+
+.. image:: images/remote_configuration_widget.gif
+	:align: center
+
+To create a configuration widget, click on the |create_configuration_widget| button
+and select a parameter to be controlled in another node. Then, link all other parameters
+that should be controlled using the |add_linked_widget| button.
+
+When all parameters are linked, you can create your first configuration. Set the values
+of all parameters for this first configuration, then select the **add configuration**
+option in the configuration's drop down button. you will be propted for a name for
+the new configuration.
+
+Repeat the same operation (set all parameters values, then **add configuration**) to
+add all other configurations.
+
+Selecting a configuration using the drop down button will recall the associated parameters
+values.
+
+It is also possible to rename, update or delete a configuration using the drop down button.

addons/material_maker/doc/shader_nodes.rst

@@ -0,0 +1,131 @@
+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.
+When shader nodes are connected, Material Maker will combine their shader programs.
+As a consequence, shader nodes are resolution independant.
+
+Editing a shader node will show the **Node Editor** window.
+
+Defining a shader node interface
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A shader node will always have outputs that will be connected to the inputs of other
+nodes. It may also (and will probably) have parameters that can be modified in the
+user interface, and inputs to receive data from other nodes.
+
+.. image:: images/node_editor_general.png
+	:align: center
+
+Inputs and parameters can be added in the **General** tab, but first, you may want to
+choose a nice name for your new node.
+
+Parameters
+~~~~~~~~~~
+
+To add a parameter, just click on the green "+" button in the Parameters section.
+A new parameter line will be created with a red "-" button on its left to delete
+the new parameter. On this line:
+
+* the first text field is the name of the parameter, that will be used in the shader code
+* the second text field is an optional label that will be displayed in the user interface.
+  There are a few tricks with this label that can help tweaking the UI.
+* the option button can be used to select a type for the parameter. The available types
+  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
+
+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.
+Gradient parameters need to be used as functions with a single float parameter.
+So **mygradient** should be refered to as **$mygradient($uv.x)** if you want to spread
+the gradient on the x axis (**$uv** is an implicit variable used by Material Maker for
+UV coordinates).
+
+Inputs
+~~~~~~
+
+Inputs can be added and removed, have a name and a label (but no label trick) just
+like parameters. they also have a type that can be **Greyscale**, **Color** or
+**RGBA**.
+Please note that Material Maker will convert automatically if you connect an input
+to an output of a different type.
+
+On the right of the input type, you must define a default value that will be used
+if the input is not connected. The default value is a GLSL expression that must
+evaluate to a **float** for **Greyscale**, a **vec3** for **Color** or a **vec4**
+for **RGBA**. Inputs default values can use the **$uv** implicit variable. You may
+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).
+
+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.
+
+Outputs
+~~~~~~~
+
+Outputs are defined in the **Outputs** tab and are very similar to inputs, but instead
+of a default value, the generated value of the output should be specified as a
+GLSL expression (**float** for **Greyscale**, a **vec3** for **Color** or a
+**vec4** for **RGBA**). This expression can use everything in the node (parameters,
+inputs, main code, instance functions and global functions) except other outputs.
+And generally, complex nodes mean complex output expressions. You may thus want to
+write simple expressions in the **Outputs** tab and keep complex code in the 3
+remaining tabs.
+
+.. image:: images/node_editor_outputs.png
+	:align: center
+
+Adding the actual GLSL code
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now the parameters, inputs and outputs are defined, the code that will actually
+generate the texture will be in the 3 remaining tabs.
+
+Global functions
+~~~~~~~~~~~~~~~~
+
+The Global functions tab is used to define the functions that are necessary to
+implement the texture generator. Those functions will be included only once (when
+the node is used of course) and cannot use parameters or inputs. This is
+typically where you will paste the code you prepared in Shadertoy.
+
+.. image:: images/node_editor_global.png
+	:align: center
+
+Instance functions
+~~~~~~~~~~~~~~~~~~
+
+Instance functions are functions that are unique to an instance of the node.
+They will typically depend on parameters, and those could either be used as
+parameters when calling global functions, or to form global function names (as
+shown in the screenshot below: the blend_type parameter is an enum whose value
+is the suffix of one of the blend functions defined in the Global Functions pane).
+
+Instance functions must also have a unique name, and the name implicit variable
+can be used to do this: whenever $name or $(name) is used, it will be replaced
+with a unique name that depends on the node instance.
+
+.. image:: images/node_editor_instance.png
+	:align: center
+
+Main code
+~~~~~~~~~
+
+This tab contains code that will be inserted into the main combined shader and
+can be used to define variables that will be used in the outputs expressions.
+This can be useful either to simplify the outputs or to define variables that
+will be used by several outputs (hence optimizing the shader code).
+
+Main code can use the node's parameters and inputs as well as instance and
+global functions.
+
+Since a node can be sampled for several different UV expressions in the same
+combined shader, it is necessary for all variables declared in the main code section
+to have a unique name for each (node instance, UV expression) pair. Material
+Maker provides the name_uv implicit variable for this.
+
+.. image:: images/node_editor_main.png
+	:align: center

addons/material_maker/doc/subgraph_nodes.rst

@@ -0,0 +1,29 @@
+Subgraph nodes
+--------------
+
+Subgraphs are parts of a complex material graph that have been gathered into
+their own level of hierarchy.
+
+To create a subgraph, first select the nodes that must be grouped and use the
+**Tools -> Create group** menu item or the **Control+G** keyboard shortcut.
+This will replace all selected nodes with a single subgraph node, without
+modifying the overall material description.
+
+The subgraph node is not editable by default, but using the **Control+E**
+shortcut will make it possible to edit its contents using the pencil button.
+
+.. image:: images/subgraph.png
+	:align: center
+
+The newly created subgraph contains:
+
+* all nodes that have been grouped
+* an **Input** and an **Output** node that rep^resent the inputs and the outputs
+  of the subgraph. Selecting them and using the **Control+E** shortcut makes them
+  editable so the subgraph inputs and outputs can be added, removed reordered or
+  renamed. Please note that all those operations will (when possible) keep
+  connectivity inside and outside the subgraph.
+* A **Parameters** node that is a **remote** can be edited to expose selected
+  parameters to the parent graph. When grouping nodes with a **remote**, the
+  remote will automatically be used as **Parameters** node in the nealy created
+  subgraph.

addons/material_maker/doc/texture_nodes.rst

@@ -0,0 +1,27 @@
+Texture nodes
+-------------
+
+Texture nodes are nodes that actually hold and output an image (and as a consequence,
+they are resolution dependant). There are two kinds of texture nodes: the image and
+the buffer.
+
+Image node
+^^^^^^^^^^
+
+The image node outputs a single image from a file. Its unique parameter is
+the path of the image file.
+
+Buffer node
+^^^^^^^^^^^
+
+The buffer node has a single input and two outputs. It renders its input into a buffer,
+and its outputs will read from that buffer. The first output emits the buffer in full
+resolution, and the second output will generate a given level of detail.
+
+The buffer node has two parameters:
+
+* the size of the buffer
+* the detail level of the second output
+
+Buffer nodes are generally used as input of shader nodes that sample their inputs multiple
+times (such as convolution nodes).

addons/material_maker/doc/user_interface.rst

@@ -185,14 +185,15 @@ File menu
 
 * *Save material as* prompts for a location and file name and saves the current material.
 
-* *Save all materials* saves all currently open materials. Materials that were not already
+* *Save all materials* saves all currently open materials. Materials that were already
-  saved ae ignored.
+  saved are ignored.
 
 * *Export material* generates PNG image files for all elements of the material. File names are
-  defined using the path of the material and their role (albedo, emission...) in the material.
+  defined using the path of the **.ptex** material file and their role (albedo, emission...)
-  The Ambient occlusion, roughness and metallic textures are merged into a single file whose
+  in the material.
+  The Ambient occlusion, roughness and metallic textures are saved into a single file whose
   suffix is **orm**.
-  If the material contains export nodes, their textures will be exported as well.
+  If the material contains **export** nodes, their textures will be exported as well.
 
 * *Close material* closes the current material.
 
@@ -210,19 +211,32 @@ Edit menu
   Pasting also unselects all previously selected nodes and selects all newly created nodes,
   so they can easily be moved around.
 
+View menu
+^^^^^^^^^
+
+* *Center view* Centers the current material graph view
+
+* *Reset zoom* Resets the zoom level of the current material graph view
+
 Tools menu
 ^^^^^^^^^^
 
+* The *Create* submenu can be used to create any of the node templates
+
+* *Create group* Creates a subgraph node with the currently selected nodes
+
 * *Add selected node to user library* first prompts for an item name. If a name is entered and
   confirmed, the selected nodes in the current material will be added to the user library under
-  that name. Don't forget to use the *Save user library* item, otherwise the newly created library
+  that name. The user library is saved automatically.
-  not be available anymore when the software is restarted.
-
-* *Save user library* saves the user library.
 
 Help menu
 ^^^^^^^^^
 
+* *User manual* opens an external web browser to show this manual
+
+* *Show selected library item documentation* opens an external web browser to show
+  documentation from the User Manual for the current library item
+
 * *Report a bug* opens a web browser on the Issues page of Material Maker's GitHub project. Please
   do not hesitate to use it to suggest improvements for Material Maker.