User interface
==============

Overview
--------

Material Maker mainly consists of 7 panels:

* The Project panel (located in the center) contains the graph editors where materials are
  described for current projects

* The Library panel (by default in the top left corner) contains all available nodes that can be used
  to create materials. Library items are shown in a tree view

* The Hierarchy panel (by default in the bottom left corner) shows the hierarchy of node groups
  of the current material graph

* The 2D preview panel (by default in the top right corner) shows the first texture generated by the
  currently selected node

* The 3D preview panel (by default in the bottom right corner) shows the current material
  applied to a sample mesh in a sample environment

* The histogram panel shows the tones histogram of the texture generated by the currently selected node

* The reference panel can be used to display images and generated textures, and pick colors and gradients

The 4 panels on the sides of the user interface can be moved around by dragging their title to their
desired location and hidden using the **View -> Panes**

First steps with the user interface
-----------------------------------

When opening Material Maker, a new empty project is created and shown in the center panel.
An empty project simply consists of a material node where textures for all elements of
the material should be connected.

To create a new node, simply choose one (for example "bricks") from the library (the
top left panel) and drag it into the graph editor. Depending on the selected library
item, a preview or a simple description will be displayed while dragging.

.. image:: images/create_node.gif
  :align: center

An alternate method to create a node is to show the library menu using the space bar
in the Project panel, and select a node from the list. The library menu will also be
shown when connecting a node output into an empty space in the graph (in this case,
the newly created node will be connected automatically).

.. image:: images/create_node_menu.gif
  :align: center

Selecting this new node (by clicking on it) shows it in the 2D preview panel.

To connect a node output to an input of another node, simply drag one to the other.
For example we can drag the first output of the Bricks node to the albedo input of
the Materials node. This will automatically assign the simple Bricks texture to the
albedo element of the material, and the 3D preview will immediately be updated.

Nodes can also be disconnected by dragging a connected input away from its node.

.. image:: images/connect_nodes.gif
  :align: center

Nodes can easily be configured by modifying their parameters, and previews are updated
automatically.

Since each input can be connected to a single output, reconnecting an input will
automatically remove the previous connection.

Graph panel
-----------

The graph panel is where materials can be edited, by adding and configuring nodes,
and connecting them.

.. image:: images/graph_pane.png
  :align: center

Grid and zoom
^^^^^^^^^^^^^

.. |zoom_out_button| image:: images/zoom_out_button.png
.. |zoom_reset_button| image:: images/zoom_reset_button.png
.. |zoom_in_button| image:: images/zoom_in_button.png
.. |grid_button| image:: images/grid_button.png

In the top left corner of the graph panel, the following buttons can be used to modify
the zoom level and configure the grid:

 * the |zoom_out_button| button zooms out.
 * the |zoom_reset_button| button resets the zoom factor.
 * the |zoom_in_button| button zooms in.
 * the |grid_button| button toggles the grid. When moved, nodes will
   stick to the grid when it is active. The grid size can be modified
   using the spinbox next to the grid button

The view can be centered using the **View -> Center view** menu item or the **C** shortcut,
and the zoom factor can be reset using the **View -> Reset zoom** menu item or the **Alt-0**
shortcut.

Material navigation
^^^^^^^^^^^^^^^^^^^

.. |graph_navigation_button| image:: images/graph_navigation_button.png
.. |group_randomness_button| image:: images/group_randomness_button.png
.. |graph_up_button| image:: images/graph_up_button.png

In the top right corner of the graph panel, the graph navigation button
|graph_navigation_button| can be used to show a tree view of the
material (this is only useful when the Hierarchy panel is not visible).
Double clicking on an item in this tree will show it in the graph view.

When a subgraph is shown in the graph panel, additional items are visible in
the top right corner:

* a text entry shows the name of the subgraph and can be used to modify it.
* a |group_randomness_button| button to decide if the current subgraph transmits
  its random seed to its children.
* a |graph_up_button| button to move to the parent of the currently shown subgraph.

Selecting and copying nodes
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Clicking on the title bar of a node will select it. Selecting a node will show its
first output (if any) in the 2D preview. It is possible to select several nodes
by holding the **Control** key while selecting.

Selected nodes can be copied using the **Edit -> Copy** menu or the **Control+C**
keyboard shortcut. They can also be cut using the **Edit -> Cut** menu entry or the
**Control+X** shortcut. Both operations store the selected nodes and their
interconnections in the clipboard. Note that the format used is JSON, and nodes
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.

Selected items can also be duplicated using the **Edit -> Duplicate**
menu or the **Control+D** keyboard shortcut. This operation does not affect
the clipboard.

Background 2D preview
^^^^^^^^^^^^^^^^^^^^^

The bottom left "bricks" button can be used to show a 2D preview in the background
of the graph view. 

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 panel
-------------

The library panel shows all nodes defined in both base and user libraries in a tree
view. The base library is provided with Material Maker and the nodes it contains are
documented in this manual. The user library contains all nodes that were added using
the **Tools -> Add selected node to user library** menu item.

The filter field above the library tree can be used to quickly find a specific node.
The tree will be updated whenever the filter string is modified. It is possible to
give focus to the search field using the **Control+F** keyboard shortcut.

.. image:: images/library_filter.gif
  :align: center

Hierarchy panel
---------------

The hierarchy panel shows the hierarchy of groups of the current material graph.
It shows the name as well as a preview of a number of outputs (for 0 to 3),
that can be configured by right clicking on the panel.

.. image:: images/hierarchy_pane.png
  :align: center

Double clicking on a group in the hierarchy shows the contents of the corresponding group
in the Graph panel.

2D Preview panel
----------------

The 2D preview panel 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.

The 2D preview panel has a context menu that can be used to select the preview
settings, export the previewed texture or render the previewed texture and add
it to the References panel.

3D Preview panel
----------------

The 3D preview panel shows a 3D preview of the current material.

.. image:: images/preview_3d.png
  :align: center

The *Model* menu can be used to:

* select a model for the 3D preview

* show a popup to configure its UV scale and specify if it should be tesselated or not

* start and stop the object's rotation animation

* generate a mesh normal or inverse UV map (this option is only available for custom meshes)

Selecting the *Custom* option in the model list will show a file dialog to select a
3D model in Wavefront .obj format. The model should have UV information to correctly
display materials (normals will be generated if they are missing).

When generating a map from a custom mesh, an image node for the generated map will
be stored in the clipboard, and it is possible to directly paste that node into about
a material graph.

The *Environment* menu provides different environments.

In the 3D view, the view can be rotated about the yaw and the pitch axes (from the
camera's point of view) by holding the left 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.

Holding the Shift key will rotate the object while the view remains static.

Rotating the object or the camera will automatically disable the object's rotate animation.

The mouse wheel can be used to move the camera along its longitudinal axis (hense zooming
forward or backward).

Histogram panel
---------------

The histogram panel shows an histogram of the texture generated by the selected node.

.. image:: images/histogram_pane.png
  :align: center

Reference panel
---------------

The reference panel can be used to show images and generated textures, and pick colors and gradients.

.. image:: images/reference_panel.png
  :align: center

To add a reference, simply drag an image file from the filesystem into the reference panel (dragging
an image from the web page can also work depending on the environment).

Only one reference can be shown at a time and the buttons at the top of the panel can be used to
show the previous or the next reference in the list.

The mouse wheel can be used to zoom, and holding the middle mouse button makes it possible
to pan across the image.

The boxes under the reference image can be used to store 5 colors and a gradient. To store a color,
first select one of the 5 color boxes by clicking on it, and click on the image with the left mouse
button. To store a gradient, click on the gradient box, then click and drag on the image using the
left mouse button.

It is possible to drag and drop colors and gradients from the boxes into the graph panel:

* Dropping a color into the graph panel will create a Uniform node

* Dropping a gradient into the graph panel will create a Colorize node

* Dropping a color into a color parameter or into a cursor of a gradient parameter
  will modify the corresponding color

* Dropping a gradient into a gradient parameter will assign it

Main menu
---------

The main menu bar is organized in 5 menus:

* the *File* menu contains actions to create, load, save and export materials
* the *Edit* menu has common edit actions cut, copy and paste
* the *View* menu contains actions to customize the graphial user interface
* the *Tools* menu has actions to add items to the user library
* the *Help* menu can be used to find more information and submit feedback about the software

File menu
^^^^^^^^^

* *New material* creates a new material and opens a tab in the center panel to edit it

* *Load material* opens a file dialog to select a procedural material (.ptex) file. If
  a material file is selected, it will be open in a new tab in the center panel. If the current
  tab contains an empty material (about material that only consists of a Material node), the
  material will be loaded into this tab.

* *Save material* saves the current material. If it was not previously saved, a file dialog
  will be displayed to select a location and file name.

* *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 already
  saved are ignored.

* the *Export* submenu can be used to export the current Material for Godot, Unity
  or Unreal. It will prompt for a file name and generate PNG files for all components
  of the material. Exporting to one of those engines is described in the
  :ref:`export-section` section.

* *Close material* closes the current material.

* *Quit* closes the software.

Edit menu
^^^^^^^^^

* *Cut* Copies the selected nodes to the clipboard and removes them from the current material.

* *Copy* Copies the selected nodes to the clipboard

* *Paste* Copies the clipboard into the current material. Note that the nodes will be added to
  the center of the view, so it is advised to scroll to the correct location before pasting.
  Pasting also unselects all previously selected nodes and selects all newly created nodes,
  so they can easily be moved around.

* *Load Selection* Loads a graph selection previously saved into a file

* *Save Selection* Saves the current graph selection into a file

* *Set Theme* is used to select the UI Theme

* *Preferences* shows the *Preferences* dialog

View menu
^^^^^^^^^

* *Center view* Centers the current material graph view

* *Reset zoom* Resets the zoom level of the current material graph view

* the *Panels* submenu can be used to show or hide all side panels

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,
  and shows the contents of the newly created group in the current graph
  view.

* the *Make selected nodes editable* menu item will toggle edit mode for
  all selected nodes that support it. Shader and graph nodes will show
  3 buttons to edit, load and save the node, switches will show controls to
  modify the number of choices and outputs, and input/output modes will
  become editable.

* *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. The user library is saved automatically.

* *Export the nodes library* will prompt for a location on the disk and
  save the whole node library.

* *Create a screenshot of the current graph*  will prompt for an image file name
  on the disk and save a screenshot of the whole current graph (it will automatically
  pan the graph to create the screenshot).

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.

* *About* Shows the about dialog.
