Started documentation

Added documentation for the UI and all generator nodes

.gitignore

@@ -21,3 +21,4 @@ examples/input_image.png.import
 *.import
 *.import
 /addons/procedural_material/nodes/godot_logo.png.import
+_build

doc/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SPHINXPROJ    = MaterialMaker
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/conf.py

@@ -0,0 +1,157 @@
+# -*- coding: utf-8 -*-
+#
+# Configuration file for the Sphinx documentation builder.
+#
+# This file does only contain a selection of the most common options. For a
+# full list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'Material Maker'
+copyright = '2018, Rodz Labs'
+author = 'Rodz Labs'
+
+# The short X.Y version
+version = ''
+# The full version, including alpha/beta/rc tags
+release = ''
+
+
+# -- General configuration ---------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#
+# needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+html_show_sourcelink = False
+
+# The master toctree document.
+master_doc = 'index'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path .
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#
+# html_theme_options = {}
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# The default sidebars (for documents that don't match any pattern) are
+# defined by theme itself.  Builtin themes are using these templates by
+# default: ``['localtoc.html', 'relations.html', 'sourcelink.html',
+# 'searchbox.html']``.
+#
+# html_sidebars = {}
+
+
+# -- Options for HTMLHelp output ---------------------------------------------
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'MaterialMakerdoc'
+
+
+# -- Options for LaTeX output ------------------------------------------------
+
+latex_elements = {
+    # The paper size ('letterpaper' or 'a4paper').
+    #
+    # 'papersize': 'letterpaper',
+
+    # The font size ('10pt', '11pt' or '12pt').
+    #
+    # 'pointsize': '10pt',
+
+    # Additional stuff for the LaTeX preamble.
+    #
+    # 'preamble': '',
+
+    # Latex figure (float) alignment
+    #
+    # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'MaterialMaker.tex', 'Material Maker Documentation',
+     'Rodz Labs', 'manual'),
+]
+
+
+# -- Options for manual page output ------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'materialmaker', 'Material Maker Documentation',
+     [author], 1)
+]
+
+
+# -- Options for Texinfo output ----------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'MaterialMaker', 'Material Maker Documentation',
+     author, 'MaterialMaker', 'One line description of project.',
+     'Miscellaneous'),
+]

doc/index.rst

@@ -0,0 +1,21 @@
+.. 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!
+==========================================
+
+.. toctree::
+   :maxdepth: 2
+   
+   intro
+   user_interface
+   nodes
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/intro.rst

@@ -0,0 +1,23 @@
+Introduction
+============
+
+Material Maker is a procedural material editor based on the Godot Engine.
+
+It can be used to describe the textures that define a material by interconnecting basic
+nodes that generate, transform or combine seamless textures in a graph.
+
+* Generator nodes describe configurable patterns that can be used to create the basic shapes
+  and textures of the material.
+
+* Transform nodes change the colors and shapes of their input images to create a more complex
+  texture.
+
+* Combine nodes use several input images to generate a new one.
+
+Many nodes in Material Maker are resolution independant, which makes it possible to use transforms
+to zoom on an image detail without affecting the generated texture quality. Only a few nodes such
+as the image generator and convolution filters (blur, emboss, normal map generation) will limit
+the resolution of their output.
+
+.. image:: images/screenshot.png
+

doc/make.bat

@@ -0,0 +1,36 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+set SPHINXPROJ=MaterialMaker
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS%
+
+:end
+popd

doc/node_bricks.rst

@@ -0,0 +1,53 @@
+Bricks node
+~~~~~~~~~~~
+
+The bricks node outputs two related bricks pattern textures.
+
+.. image:: images/node_bricks.png
+
+Inputs
+++++++
+
+The bricks node does not accept any input.
+
+Outputs
++++++++
+
+The bricks node provides the following textures:
+
+* The first one is a greyscale image where bricks are shown in white and mortar in black.
+
+* The second one is a color image where all bricks are drawn using a random uniform color.
+
+Both images can be used together to create complex materials that show for example bricks
+of different colors.
+
+.. image:: images/bricks.png
+
+Parameters
+++++++++++
+
+The Bricks node accepts the following parameters:
+
+* the "Pattern" parameter defines the bricks pattern that will be generated.
+
+* the "Repeat" parameter defines the number of patterns on the horizontal and vertical
+  axes of the texture.
+
+* the "Rows" parameter defines the number of brick rows in a single pattern of the texture.
+
+* the "Columns" parameter defines the number of brick rows in a single pattern of the texture.
+
+* the "Offset" parameter defines the offset of odd rows of the pattern. This parameter
+  only applies to the "Running bond" patterns.
+
+* the "Mortar" parameter defines the relative thickness of mortar in patterns.
+
+* the "Bevel" parameter defines the relative thickness of brick bevel in patterns.
+
+Notes
++++++
+
+As with all random nodes, the seed is held by the node's position, so moving the node in the graph
+will modify the texture, and the outputs will remain the same if its position and parameters
+are not changed.

doc/node_image.rst

@@ -0,0 +1,22 @@
+Image node
+~~~~~~~~~~
+
+The image node outputs a single texture based on an image file.
+
+.. image:: images/node_image.png
+
+Inputs
+++++++
+
+The image node does not accept any input.
+
+Outputs
++++++++
+
+The image node provides a single color texture.
+
+Parameters
+++++++++++
+
+The image node has a single parameter that defines the image file the node provides.
+It can be modified by clicking the thumbnail and selecting a new image file.

doc/node_noise.rst

@@ -0,0 +1,36 @@
+Noise node
+~~~~~~~~~~
+
+The Noise node outputs a randomly generated black and white texture.
+
+.. image:: images/node_noise.png
+
+Inputs
+++++++
+
+The Noise node does not accept any input.
+
+Outputs
++++++++
+
+The Noise node provides a black and white noise texture.
+
+.. image:: images/noise.png
+
+Parameters
+++++++++++
+
+The Noise node accepts the following parameters:
+
+* *Grid size* is the number of rows and columns in the texture.
+
+* *Density* is the likelihood for each cell to be white.
+
+Notes
++++++
+
+As with all random nodes, the seed is held by the node's position, so moving the node in the graph
+will modify the texture, and the outputs will remain the same if its position and parameters
+are not changed.
+
+Although this node has a grid size, it generates a resolution independant texture.

doc/node_pattern.rst

@@ -0,0 +1,42 @@
+Pattern node
+~~~~~~~~~~~~
+
+The Pattern node outputs a pattern texture generated from common waveform shapes.
+
+.. image:: images/node_pattern.png
+
+Inputs
+++++++
+
+The Pattern node does not accept any input.
+
+Outputs
++++++++
+
+The Pattern node provides a grayscale texture obtained by mixing a horizontal and a vertical pattern.
+
+Many different patterns can be created using this node, do not hesitate to experiment.
+
+.. image:: images/pattern.png
+
+Parameters
+++++++++++
+
+The Pattern node accepts the following parameters:
+
+* the *X* and *Y* parameters define the pattern and their number of repetitions
+  that will be propagated along the X axis and Y.
+  The following patterns are available:
+  
+  * Sine: the value follows a sinus waveform
+  
+  * Triangle: the value follows a triangle waveform (changes linearly from 0 to 1 and from 1 to 0)
+  
+  * Square: the value follows a square waveform (stays constant at 0, then 1)
+
+  * Sawtooth: the value follows a sawtooth waveform (hanges linearly from 0 to 1, then jumps back to 0)
+
+  * constant: the value is 1
+
+* the *Combiner* parameter is the function used to combine the *X* and *Y* patterns. The available
+  functions are *multiply*, *add*, *max*, *min*, *xor* and *pow*

doc/node_perlin.rst

@@ -0,0 +1,37 @@
+Perlin noise node
+~~~~~~~~~~~~~~~~~
+
+The Perlin noise node outputs a Perlin noise texture.
+
+.. image:: images/node_perlin.png
+
+Inputs
+++++++
+
+The Perlin noise node does not accept any input.
+
+Outputs
++++++++
+
+The Perlin noise node provides a greyscale Perlin noise texture.
+
+.. image:: images/perlin.png
+
+Parameters
+++++++++++
+
+The Perlin noise node accepts the following parameters:
+
+* *Scale X* and *Scale Y* are the subdivisions of the first iteration
+
+* *Iterations* is the number of iterations
+
+* *Persistance* is the weight ratio between 2 subsequent iterations. Lower values of persistance
+  generate smoother noise.
+
+Notes
++++++
+
+As with all random nodes, the seed is held by the node's position, so moving the node in the graph
+will modify the texture, and the outputs will remain the same if its position and parameters
+are not changed.

doc/node_uniform.rst

@@ -0,0 +1,21 @@
+Uniform node
+~~~~~~~~~~~~
+
+The uniform node outputs a single uniform image whose color is configurable.
+
+.. image:: images/node_uniform.png
+
+Inputs
+++++++
+
+The uniform node does not accept any input.
+
+Outputs
++++++++
+
+The uniform node provides an output that generates a uniform color image.
+
+Parameters
+++++++++++
+
+The uniform node has a single *color* parameter that defines the color of the output image.

doc/node_voronoi.rst

@@ -0,0 +1,40 @@
+Voronoi noise node
+~~~~~~~~~~~~~~~~~~
+
+The Voronoi noise node outputs Voronoi noise textures.
+
+.. image:: images/node_voronoi.png
+
+Inputs
+++++++
+
+The Voronoi noise node does not accept any input.
+
+Outputs
++++++++
+
+The Voronoi noise node provides three outputs:
+
+* a greyscale Voronoi noise texture that shows the distance to the feature points.
+
+* a greyscale texture that shows the distance to the closest segment bisector of all feature points pairs.
+
+* a color Voronoi partition.
+
+.. image:: images/voronoi.png
+
+Parameters
+++++++++++
+
+The Voronoi noise node accepts the following parameters:
+
+* *Scale X* and *Scale Y* define the number of feature points that define the noise
+
+* *Intersity* is a factor applied to the first output of the node.
+
+Notes
++++++
+
+As with all random nodes, the seed is held by the node's position, so moving the node in the graph
+will modify the texture, and the outputs will remain the same if its position and parameters
+are not changed.

doc/nodes.rst

@@ -0,0 +1,8 @@
+Available nodes
+===============
+
+This section describes all nodes that can be used in a procedural material.
+
+.. toctree::
+
+	nodes_generators

doc/nodes_generators.rst

@@ -0,0 +1,14 @@
+Generator nodes
+---------------
+
+The generator nodes are nodes that do not accept any input and generate one or several images.
+
+.. toctree::
+
+	node_uniform
+	node_image
+	node_pattern
+	node_bricks
+	node_noise
+	node_perlin
+	node_voronoi

doc/user_interface.rst

@@ -0,0 +1,115 @@
+User interface
+==============
+
+Overview
+--------
+
+Material Maker mainly consists of 3 panes:
+
+* The top left pane is the library, that contains all available nodes that can be used
+  to create materials. Library items are shown in a tree view
+
+* The bottom left pane is the preview, that shows at the same time the currecnt material
+  applied to a sample mesh in a sample environment, and the texture generated by the
+  currently selected node
+
+* The right pane contains the graph editors where materials are described for current
+  projects
+
+First steps with the user interface
+-----------------------------------
+
+When opening Material Maker, a new empty project is created and shown in the right pane.
+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 pane) 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
+
+Selecting this new node (by clicking on it) shows it in the preview pane. The very small
+2d preview of the preview pane can be maximized by double cliking on it. This will hide
+the 3d preview but is useful when working on the different textures of the material.
+
+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 (if
+you maximized the 2d preview it can be minimized by double-clicking on it again).
+
+.. image:: images/connect_nodes.gif
+
+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.
+
+Main menu
+---------
+
+The main menu is organized in 4 sections:
+
+* the *File* menu contains actions to create, load, save and export materials
+* the *Edit* menu has common edit actions cut, copy and paste
+* 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 right pane 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 right pane. 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 not already
+  saved ae 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, metallic...) in the material.
+
+* *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.
+
+Tools menu
+^^^^^^^^^^
+
+* *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.
+
+Help menu
+^^^^^^^^^
+
+* *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.
+
+