diff --git a/addons/material_maker/doc/base_library.rst b/addons/material_maker/doc/base_library.rst new file mode 100644 index 00000000..5bf70593 --- /dev/null +++ b/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 diff --git a/addons/material_maker/doc/images/add_linked_widget.png b/addons/material_maker/doc/images/add_linked_widget.png new file mode 100644 index 00000000..e41dc25c Binary files /dev/null and b/addons/material_maker/doc/images/add_linked_widget.png differ diff --git a/addons/material_maker/doc/images/create_configuration_widget.png b/addons/material_maker/doc/images/create_configuration_widget.png new file mode 100644 index 00000000..d9b5f382 Binary files /dev/null and b/addons/material_maker/doc/images/create_configuration_widget.png differ diff --git a/addons/material_maker/doc/images/create_linked_widget.png b/addons/material_maker/doc/images/create_linked_widget.png new file mode 100644 index 00000000..ea401dbb Binary files /dev/null and b/addons/material_maker/doc/images/create_linked_widget.png differ diff --git a/addons/material_maker/doc/images/editable_node.png b/addons/material_maker/doc/images/editable_node.png new file mode 100644 index 00000000..dd719ea4 Binary files /dev/null and b/addons/material_maker/doc/images/editable_node.png differ diff --git a/addons/material_maker/doc/images/gradient_editor.png b/addons/material_maker/doc/images/gradient_editor.png new file mode 100644 index 00000000..051e3b4a Binary files /dev/null and b/addons/material_maker/doc/images/gradient_editor.png differ diff --git a/addons/material_maker/doc/images/node_editor_general.png b/addons/material_maker/doc/images/node_editor_general.png new file mode 100644 index 00000000..70b8173e Binary files /dev/null and b/addons/material_maker/doc/images/node_editor_general.png differ diff --git a/addons/material_maker/doc/images/node_editor_global.png b/addons/material_maker/doc/images/node_editor_global.png new file mode 100644 index 00000000..fca60b7e Binary files /dev/null and b/addons/material_maker/doc/images/node_editor_global.png differ diff --git a/addons/material_maker/doc/images/node_editor_instance.png b/addons/material_maker/doc/images/node_editor_instance.png new file mode 100644 index 00000000..e6c124e8 Binary files /dev/null and b/addons/material_maker/doc/images/node_editor_instance.png differ diff --git a/addons/material_maker/doc/images/node_editor_main.png b/addons/material_maker/doc/images/node_editor_main.png new file mode 100644 index 00000000..e4951738 Binary files /dev/null and b/addons/material_maker/doc/images/node_editor_main.png differ diff --git a/addons/material_maker/doc/images/node_editor_outputs.png b/addons/material_maker/doc/images/node_editor_outputs.png new file mode 100644 index 00000000..b064df72 Binary files /dev/null and b/addons/material_maker/doc/images/node_editor_outputs.png differ diff --git a/addons/material_maker/doc/images/node_example.png b/addons/material_maker/doc/images/node_example.png new file mode 100644 index 00000000..1036477f Binary files /dev/null and b/addons/material_maker/doc/images/node_example.png differ diff --git a/addons/material_maker/doc/images/random_node.png b/addons/material_maker/doc/images/random_node.png new file mode 100644 index 00000000..13722604 Binary files /dev/null and b/addons/material_maker/doc/images/random_node.png differ diff --git a/addons/material_maker/doc/images/remote_configuration_widget.gif b/addons/material_maker/doc/images/remote_configuration_widget.gif new file mode 100644 index 00000000..82a6f2a8 Binary files /dev/null and b/addons/material_maker/doc/images/remote_configuration_widget.gif differ diff --git a/addons/material_maker/doc/images/remote_create_linked_widget.gif b/addons/material_maker/doc/images/remote_create_linked_widget.gif new file mode 100644 index 00000000..0f52e928 Binary files /dev/null and b/addons/material_maker/doc/images/remote_create_linked_widget.gif differ diff --git a/addons/material_maker/doc/images/remove_linked_widget.png b/addons/material_maker/doc/images/remove_linked_widget.png new file mode 100644 index 00000000..90a05f59 Binary files /dev/null and b/addons/material_maker/doc/images/remove_linked_widget.png differ diff --git a/addons/material_maker/doc/images/subgraph.png b/addons/material_maker/doc/images/subgraph.png new file mode 100644 index 00000000..f62462be Binary files /dev/null and b/addons/material_maker/doc/images/subgraph.png differ diff --git a/addons/material_maker/doc/index.rst b/addons/material_maker/doc/index.rst index f6071faa..ac4a6e80 100644 --- a/addons/material_maker/doc/index.rst +++ b/addons/material_maker/doc/index.rst @@ -12,3 +12,4 @@ Welcome to Material Maker's documentation! intro user_interface nodes + base_library diff --git a/addons/material_maker/doc/nodes.rst b/addons/material_maker/doc/nodes.rst index fef35338..51036881 100644 --- a/addons/material_maker/doc/nodes.rst +++ b/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_pattern - nodes_noise - nodes_filter - nodes_transform - nodes_miscellaneous + nodes_common + shader_nodes + texture_nodes + remote_nodes + subgraph_nodes diff --git a/addons/material_maker/doc/nodes_common.rst b/addons/material_maker/doc/nodes_common.rst new file mode 100644 index 00000000..309a018a --- /dev/null +++ b/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). diff --git a/addons/material_maker/doc/nodes_filter.rst b/addons/material_maker/doc/nodes_filter.rst index 959f1b96..4bff4c3d 100644 --- a/addons/material_maker/doc/nodes_filter.rst +++ b/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 diff --git a/addons/material_maker/doc/nodes_miscellaneous.rst b/addons/material_maker/doc/nodes_miscellaneous.rst new file mode 100644 index 00000000..a2a408d9 --- /dev/null +++ b/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 diff --git a/addons/material_maker/doc/nodes_noise.rst b/addons/material_maker/doc/nodes_noise.rst index fd26b510..69eebd7a 100644 --- a/addons/material_maker/doc/nodes_noise.rst +++ b/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 diff --git a/addons/material_maker/doc/nodes_pattern.rst b/addons/material_maker/doc/nodes_pattern.rst index 5c83b3c8..4806adfe 100644 --- a/addons/material_maker/doc/nodes_pattern.rst +++ b/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 diff --git a/addons/material_maker/doc/nodes_simple.rst b/addons/material_maker/doc/nodes_simple.rst index 767335ac..8e4898c6 100644 --- a/addons/material_maker/doc/nodes_simple.rst +++ b/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 diff --git a/addons/material_maker/doc/nodes_transform.rst b/addons/material_maker/doc/nodes_transform.rst index 29672765..86319963 100644 --- a/addons/material_maker/doc/nodes_transform.rst +++ b/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 diff --git a/addons/material_maker/doc/remote_nodes.rst b/addons/material_maker/doc/remote_nodes.rst new file mode 100644 index 00000000..fe4f9aa1 --- /dev/null +++ b/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. diff --git a/addons/material_maker/doc/shader_nodes.rst b/addons/material_maker/doc/shader_nodes.rst new file mode 100644 index 00000000..5dfcd126 --- /dev/null +++ b/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 diff --git a/addons/material_maker/doc/subgraph_nodes.rst b/addons/material_maker/doc/subgraph_nodes.rst new file mode 100644 index 00000000..9427350c --- /dev/null +++ b/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. diff --git a/addons/material_maker/doc/texture_nodes.rst b/addons/material_maker/doc/texture_nodes.rst new file mode 100644 index 00000000..c1fac888 --- /dev/null +++ b/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). diff --git a/addons/material_maker/doc/user_interface.rst b/addons/material_maker/doc/user_interface.rst index ade800a5..a8a7a6cc 100644 --- a/addons/material_maker/doc/user_interface.rst +++ b/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 - saved ae ignored. +* *Save all materials* saves all currently open materials. Materials that were already + 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. - The Ambient occlusion, roughness and metallic textures are merged into a single file whose + defined using the path of the **.ptex** material file and their role (albedo, emission...) + 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 - not be available anymore when the software is restarted. - -* *Save user library* saves the user library. + that name. The user library is saved automatically. 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.