diff --git a/.gitignore b/.gitignore index cbda340..4a68b5d 100644 --- a/.gitignore +++ b/.gitignore @@ -21,3 +21,4 @@ examples/input_image.png.import *.import *.import /addons/procedural_material/nodes/godot_logo.png.import +_build diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..b6bd2b2 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 0000000..df5e3f1 --- /dev/null +++ b/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'), +] \ No newline at end of file diff --git a/doc/bricks.png b/doc/images/bricks.png similarity index 100% rename from doc/bricks.png rename to doc/images/bricks.png diff --git a/doc/colorize.png b/doc/images/colorize.png similarity index 100% rename from doc/colorize.png rename to doc/images/colorize.png diff --git a/doc/images/connect_nodes.gif b/doc/images/connect_nodes.gif new file mode 100644 index 0000000..9f89c77 Binary files /dev/null and b/doc/images/connect_nodes.gif differ diff --git a/doc/images/create_node.gif b/doc/images/create_node.gif new file mode 100644 index 0000000..3bebb32 Binary files /dev/null and b/doc/images/create_node.gif differ diff --git a/doc/emboss.png b/doc/images/emboss.png similarity index 100% rename from doc/emboss.png rename to doc/images/emboss.png diff --git a/doc/images/node_bricks.png b/doc/images/node_bricks.png new file mode 100644 index 0000000..28c364a Binary files /dev/null and b/doc/images/node_bricks.png differ diff --git a/doc/images/node_image.png b/doc/images/node_image.png new file mode 100644 index 0000000..f703167 Binary files /dev/null and b/doc/images/node_image.png differ diff --git a/doc/images/node_noise.png b/doc/images/node_noise.png new file mode 100644 index 0000000..6e5747c Binary files /dev/null and b/doc/images/node_noise.png differ diff --git a/doc/images/node_pattern.png b/doc/images/node_pattern.png new file mode 100644 index 0000000..958c5d7 Binary files /dev/null and b/doc/images/node_pattern.png differ diff --git a/doc/images/node_perlin.png b/doc/images/node_perlin.png new file mode 100644 index 0000000..663517d Binary files /dev/null and b/doc/images/node_perlin.png differ diff --git a/doc/images/node_uniform.png b/doc/images/node_uniform.png new file mode 100644 index 0000000..51b7f20 Binary files /dev/null and b/doc/images/node_uniform.png differ diff --git a/doc/images/node_voronoi.png b/doc/images/node_voronoi.png new file mode 100644 index 0000000..8963c01 Binary files /dev/null and b/doc/images/node_voronoi.png differ diff --git a/doc/images/noise.png b/doc/images/noise.png new file mode 100644 index 0000000..07e9f90 Binary files /dev/null and b/doc/images/noise.png differ diff --git a/doc/pattern.png b/doc/images/pattern.png similarity index 100% rename from doc/pattern.png rename to doc/images/pattern.png diff --git a/doc/perlin.png b/doc/images/perlin.png similarity index 100% rename from doc/perlin.png rename to doc/images/perlin.png diff --git a/doc/screenshot.png b/doc/images/screenshot.png similarity index 100% rename from doc/screenshot.png rename to doc/images/screenshot.png diff --git a/doc/voronoi.png b/doc/images/voronoi.png similarity index 100% rename from doc/voronoi.png rename to doc/images/voronoi.png diff --git a/doc/warp.png b/doc/images/warp.png similarity index 100% rename from doc/warp.png rename to doc/images/warp.png diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 0000000..ba1a2d7 --- /dev/null +++ b/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` diff --git a/doc/intro.rst b/doc/intro.rst new file mode 100644 index 0000000..5d14ab3 --- /dev/null +++ b/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 + diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..a2e95d1 --- /dev/null +++ b/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 diff --git a/doc/node_bricks.rst b/doc/node_bricks.rst new file mode 100644 index 0000000..421dc52 --- /dev/null +++ b/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. diff --git a/doc/node_image.rst b/doc/node_image.rst new file mode 100644 index 0000000..4b39a80 --- /dev/null +++ b/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. diff --git a/doc/node_noise.rst b/doc/node_noise.rst new file mode 100644 index 0000000..84dd377 --- /dev/null +++ b/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. diff --git a/doc/node_pattern.rst b/doc/node_pattern.rst new file mode 100644 index 0000000..20624ce --- /dev/null +++ b/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* diff --git a/doc/node_perlin.rst b/doc/node_perlin.rst new file mode 100644 index 0000000..ad4e3cd --- /dev/null +++ b/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. diff --git a/doc/node_uniform.rst b/doc/node_uniform.rst new file mode 100644 index 0000000..c657b34 --- /dev/null +++ b/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. diff --git a/doc/node_voronoi.rst b/doc/node_voronoi.rst new file mode 100644 index 0000000..a6a1984 --- /dev/null +++ b/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. diff --git a/doc/nodes.rst b/doc/nodes.rst new file mode 100644 index 0000000..bf6b6b2 --- /dev/null +++ b/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 diff --git a/doc/nodes_generators.rst b/doc/nodes_generators.rst new file mode 100644 index 0000000..22e51a8 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/user_interface.rst b/doc/user_interface.rst new file mode 100644 index 0000000..6b8a0a6 --- /dev/null +++ b/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. + +