Authoring Atom User Guide | Section: Materials

content/docs/atom-guide/core-systems/materials/_index.md

@@ -9,4 +9,4 @@ weight: 200
 ### Contents
 - [Material System](materials.md)
 - [Material File Specification](material-file-spec.md)
-- [Material File Type Specification](material-type-file-spec.md)
+- [Material Type File Specification](material-type-file-spec.md)

content/docs/atom-guide/core-systems/materials/material-file-spec.md

@@ -0,0 +1,27 @@
+---
+title: "Material File Specification"
+description: "Material files (`*.material`) are written in JSON format and contain the following elements."
+date: 2021-03-04
+toc: false
+---
+
+Material files (`*.material`) are written in JSON format and contain the following elements.
+
+<!-- ### **description** (*optional*)  
+An attribute describing the material for user understanding. 
+
+[DEV NOTE (according to @santorac): This is currently not part of the .material file spec. We do have a field for it in code but it is not hooked up to json. We don't have any tooling support to use this field, but will mayeb add in the future] -->
+
+### **parentMaterial** (*optional*)  
+The path to the parent material file. If specified, the material inherits the properties of another parent material. The parent material must have the same material type as the material. The path must be relative to the asset root or to the material file. If not specified, the material inherits directly from the materialType. 
+
+### **materialType** (*optional, if `parentMaterial` is specified*)  
+The path to the material type. Materials must reference a material type. The path must be relative to the asset root or to the material type file.
+
+This attribute is not required if `parentMaterial` is specified. In that case, the material inherits the parent material's `materialType`. If this attribute specifies a different material type from the parent material's, an error is reported.
+
+<!-- ### 
+- **propertyLayoutVersion**  
+    [TODO] An attribute .. 
+
+[DEV NOTE (according to @santorac): This is a placeholder for future functionality where we will automatically support backwards compatibility of .material files, when the .materialtype changes to say add, remove, or rename properties. It is not currently hooked up. And will likely rename it to materialTypeVersion] -->

content/docs/atom-guide/core-systems/materials/material-type-file-spec.md

@@ -0,0 +1,66 @@
+---
+title: "Material Type File Specification"
+description: "Material type files (`*.materialtype`) are in written JSON format."
+date: 2021-03-04
+toc: true
+---
+
+Material type files (`*.materialtype`) are in written JSON format and contain the following elements.
+
+### **propertyLayout**  
+* **groups**: A list of property groups that appear in the **Inspector** window of the Material Editor. Each group contains the following:
+  * **id**: An identifier for this group that is unique to this material type. The value must be formatted in C-style. 
+  * **displayName**: The given name of this group that will appear in the Material Editor. 
+  * **description**: The given description of this group that will appear as tooltips in the Material Editor.
+
+  *Note: The `general` group is built-in and always available, even if there is no `general` group defined in the `groups` section. This group is typically used to contain any basic properties of this material type.*
+
+* **properties**: Defines the groups of properties that can be configured in a material file. Each group is defined as a key/value pair, where *key* is the `group id`, and *value* is an array of property definitions. 
+
+    Material properties support the following data types: 
+    - Bool
+    - Int
+    - UInt
+    - Float
+    - Vector2
+    - Vector3
+    - Vector4
+    - Color
+    - Image
+    - Enum
+
+
+### **shaders**  
+An array of references to shader files (*.shader*). Each reference contains the following values. 
+
+* **file**: The path to the shader file. The path must be relative to the asset root or to the material type file.
+* **tag**: A unique name for this shader item that can be used to reference the shader from other places in the material type definition. It must be a C-Style identifier.
+
+In this example, we reference the ShadowMap and DepthPass shaders. 
+```JSON
+"shaders": [
+    {
+        "file": "../ShadowMap.shader",
+        "tag": "shadowmap"
+    },
+    {
+        "file": "../DepthPass.shader",
+        "tag": "depth"
+    }
+]
+```
+
+### **functor**
+An array of material functors. Each one reads material property values, performs some logic or calculations, and sets shader inputs accordingly. These can be defined in Lua or C++. Each functor data contains the following:
+* **type**: The name of the functor type. This will be "Lua" for custom Lua script functors, or the name of specialized functor type (defined in C++).
+<!-- [Future work] See [TBD link] for a list of available functor types. -->
+* **args**: An object containing key/value pairs of all the arguments to send to this functor. The attributes vary depending on functor type. For 'Lua' functors, there is a single 'file' argument that references the Lua file. 
+<!-- [Future work] See [TBD link] for a list of available functor types and their expected arguments. -->
+
+### **uvNameMap** *(optional)*
+This array lists default identifiers for mesh UV streams. 
+<!-- [Future work] For more information on UV streams, see ___. 
+- If the artists uses these names for their UV streams in DCC (e.g. Maya), the engine will automatically connect those buffers to the appropriate UV stream in the shaders. 
+
+- In O3DE, artists can connect the streams in the Material Component. This is necessary if the UV stream names do not match. 
+-->

content/docs/atom-guide/core-systems/materials/materials.md

@@ -0,0 +1,96 @@
+---
+title: "Material System Overview"
+description: "Materials contain data that control how model surfaces appear in a 3D environment."
+date: 2021-03-04
+toc: false
+weight: 100
+---
+
+**Materials** contain data that control how model surfaces appear in a 3D environment. All materials have a **material type**, which classifies materials that share the same properties such as hard surfaces, cloth, or skin. Materials inherit properties either directly from the material type, or from other materials. 
+
+Materials and material types are stored as data items in JSON files. The Atom Material Builder converts the data files into material assets. The material assets are then consumed by the application and applied to a mesh's surface. 
+
+## Physically Based Rendering in Atom
+**Physically based rendering (PBR)** is a rendering technique that simulates realistic interaction between materials and light. Atom supports PBR and features PBR material types such as StandardPBR, EnhancedPBR, and other variations. These follow industry standard workflows using metallic and roughness properties. Atom's material system is also capable of rendering non-photo-realistic techniques and special effects through alternate material types. We provide built-in material types focused on PBR rendering, but users can author their own material types to suit their needs.
+
+A full list of material types in Atom is listed in [Material Types in Atom](#material-types-in-atom).
+
+For more information on PBR, see [Physically-based Rendering (PBR)](./pbr.md) and [Working with StandardPBR materials](./create-standardpbr-material.md). 
+
+
+## Materials
+A **material** is a data item that references a material type and defines the material's property values. The material must reference a material type, which defines how the material works and what properties are available. Alternatively, a material might reference another material and inherit its property values. The material inheritance tree can go as deep as needed. 
+
+Material files (`*.material`) are in JSON format. They can be edited using the Material Editor or authored directly. The file is in a simple JSON format and can be authored or machine-generated by scripting outside the Material Editor.
+
+For more information, see [Material File Specification](material-file-spec.md).  
+
+### Material File Example
+In the following example, the material uses the **StandardPBR** material type and contains the properties `baseColor`, `roughness`, and `normal`. 
+```json
+{
+    "materialType": "StandardPBR.materialtype",
+    "properties": {
+        "baseColor": {
+            "textureMap": "Textures\\Default\\default_basecolor.tif"
+        },
+        "roughness": {
+            "textureMap": "Textures\\Default\\default_roughness.tif"
+        },
+        "normal": {
+            "factor": 0.8,
+            "textureMap": "Textures\\Default\\default_normal.tif"
+        }
+    }
+}
+```
+
+*Note: The textures in the sample above can be found in the folder Gems/Atom/Feature/Common/Assets/Textures/Default/.*
+
+## Material Types
+A **material type** is a data item that includes everything that's needed to describe how to render a mesh:  
+- A set of `material property` definitions
+- Links to shaders
+- Scripts that describe how to consume the material properties
+- Metadata for the Material Editor to use when displaying material properties
+
+Material type files (`*.materialtype`) are in JSON format and can be authored directly. This will link together several other files as well, to form a complete material type definition. These additional files include *.shader*, *.azsl*, and *.lua* files.
+<!-- [NOTE FOR DEVS] 
+- Can we elaborate on why/when they would need to create material types using C++ or Lua? 
+- What is the API (or files) for programming material types?
+- What is the main purpose of a functor? -->
+
+For more information, see [Material Type File Specification](material-type-file-spec.md).  
+
+### Material Types in Atom
+Atom comes built with common material types that you can create materials from. To suit individual needs, you can also create and configure new material types by defining properties, shaders, and functors.
+
+The following material types are included in Atom: 
+<!-- [NOTE FOR DEVS: Can you review/edit these descriptions for the material types?] -->
+- **StandardPBR**  
+    A full-featured PBR material type, but adopts certain feature limitations in order to improve performance. It is meant to provide as much functionality as possible with a limited number of render targets. 
+    <!-- For more information on StandardPBR material type, see _[TODO]__.    -->  
+
+    This file is located in `Gems/Atom/Feature/Common/Assets/Materials/Types/StandardPBR.materialtype`.
+
+- **EnhancedPBR**  
+    An enhanced version of StandardPBR that includes additional features, but comes at a higher performance cost. It supports more advanced features that require additional render targets (g-buffers). 
+
+    This file is located in `Gems/Atom/Feature/Common/Assets/Materials/Types/EnhancedPBR.materialtype`. 
+
+- **MinimalPBR**  
+    A simple PBR material type with three common properties: base color, metallic factor, and roughness factor. This material type is considered the "hello world" of PBR materials and is provided as an example. It is a good place to start for creating custom material types. 
+
+    This file is located in `Gems/Atom/TestData/TestData/Materials/Types/MinimalPBR.materialtype`. 
+
+- **AutoBrick**  
+    A procedural brick material type that includes settings for color, ambient occlusion, brick (width, height, offset), and grout line (width, depth). This material type is an example of a completely custom material type, expanding from the MinimalPBR material type.  
+
+    This file is located in `Gems/Atom/TestData/TestData/Materials/Types/AutoBrick.materialtype`.     
+
+## Material and Material Type Assets
+Material and material type files produce **Material Assets** and **Material Type Assets** in the cache, respectively.
+
+A material type file (`*.materialtype`) produces a Material Type Asset (`*.azmaterialtype`) in the cache. It contains property layout information, a list of shaders to use, and possibly functors for special processing.
+
+A material file (`*.material`) produces a Material Asset (`*.azmaterial`) in the cache. Every Material Asset references a single Material Type Asset. It contains the inherited tree of material property values and compresses it into a single list. Material Assets can be referenced by Model Assets and/or assigned to a model using a Material Component in the Open 3D Engine (O3DE). Material Assets can create any number of material instances at runtime for the renderer to use. You can change the property values of a material instance without impacting other instances of the same material.  Unlike a Material Asset, a material instance only exists in memory and not on disk. 

content/docs/atom-guide/core-systems/materials/pbr.md

@@ -0,0 +1,3 @@
+---
+title: Physically Based Rendering (PBR)
+---

content/docs/atom-guide/tutorials/_index.md

@@ -1,13 +1,16 @@
 ---
 title: "Tutorials"
-description: "Tutorials for working with Atom Rendering Engine"
+description: "This section contains tutorials such as creating materials and shaders, or developing features in Atom."
 date: 2021-03-04
 toc: true
 weight: 500
 ---
 
-<!-- NOTE: An intro paragraph to this section is in another PR. -->
+## Materials
+The following tutorials cover topics for working with materials. 
+- [**Create a StandardPBR material**](create-standardpbr-material.md): This tutorial walks you through creating your first StandardPBR material using the Material Editor.
 
 ## Render Pipeline Interface (RPI)
 The following tutorials cover topics regarding the RPI. 
-- [**Working with the Scene and Render Pipeline**](rpi/working-with-scene-and-rendering-pipeline.md): This tutorial goes over how to create scenes and render pipelines using the RPI.
+- [**Working with the Scene and Render Pipeline**](rpi/working-with-scene-and-rendering-pipeline.md): This tutorial goes over how to create scenes and render pipelines using the RPI.
+This section contains tutorials such as creating materials and shaders, or developing features in Atom. 

content/docs/atom-guide/tutorials/create-standardpbr-material.md

@@ -0,0 +1,82 @@
+---
+title: "Creating a StandardPBR Material"
+description: "This tutorial walks you through how to create a StandardPBR material in Atom."
+date: 2021-03-04
+toc: false
+---
+
+This tutorial walks you through how to create a StandardPBR material in Atom. The StandardPBR material type allows you to create an artist-friendly, full-featured physically based rendering (PBR) material.
+
+This tutorial covers the following concepts:
+- The elements of a StandardPBR material
+- Creating a material using the Material Editor
+- Working with texture files 
+- Using texture file masks
+
+## Before starting
+A material can have multiple textures, such as base color, normal map, and roughness. These textures contain different data that are combined to create the overall look of the material. You can design the textures for a material using external tools, such as [Substance Designer](https://www.substance3d.com/products/substance-designer/) and [Materialize](http://boundingboxsoftware.com/materialize/). In this tutorial, we use ready-made materials from [Texture Haven](https://texturehaven.com/). 
+
+### Download texture files
+Download the [castle brick material](https://texturehaven.com/tex/?t=castle_brick_02_red) in any resolution from Texture Haven. When downloading, make sure to choose **All Maps** to download all textures that make up this material.
+
+After downloading, move and extract the zip file to the folder `<project-folder>/Materials/TextureHaven/`.
+
+We use the following files as our input textures:
+-  castle_brick_02_red_ao_1k (ambient occlusion)
+-  castle_brick_02_red_diff_1k (diffuse, base color)
+-  castle_brick_02_red_disp_1k (displacement)
+-  castle_brick_02_red_nor_1k (normal)
+-  castle_brick_02_red_rough_1k (roughness)
+
+### Apply a filemask to the texture files
+To make sure that these texture files work correctly, you must indicate which texture preset should be used by the Asset Processor to process these files. The easiest way to do this is rename the files to use a texture file mask. A **texture file mask** is the suffix at the end of a file's name that indicates which texture preset to use. This allows the Asset Processor to correctly convert this image type into its runtime format. <!-- [Future work] For more information on texture presets, see -->
+
+There are different variations of texture file masks that can work for a single texture. For example, "_ao" or "_ambientocclusion" are both valid and the Asset Processor knows to process the texture as an ambient occlusion texture. These texture file masks are defined in the preset (`*.preset`) files that configure Atom's Image Processor. The preset files can be found in the folder  `/Gems/Atom/Asset/ImageProcessingAtom/Config/`. 
+
+We rename the following files to properly apply a filemask. (For the sake of clarity, we use the descriptive texture file mask names.)
+- castle_brick_02_red_**ao**\_1k &rarr; castle_brick_02_red\_**ambientocclusion**
+- castle_brick_02_red_**diff**\_1k &rarr; castle_brick_02_red\_**basecolor**
+- castle_brick_02_red_**disp**\_1k &rarr; castle_brick_02_red\_**displ**
+- castle_brick_02_red_**nor**\_1k &rarr; castle_brick_02_red\_**normal**
+- castle_brick_02_red_**rough**\_1k &rarr; castle_brick_02_red\_**roughness**
+
+
+## Create material with Material Editor
+To create a material using the Material Editor:
+1. Open the Material Editor. If you are in the Open 3D Engine Editor, go to *Tools > Material Editor*, or press *M*. Otherwise, you can open the Material Editor as a standalone application from `<build_folder>/bin/profile/MaterialEditor.exe`.
+
+2. Create a new StandardPBR material by choosing **File** > **New** > **Standard PBR**. This opens the file browser and prompts you to save the new file. In the **Inspector** tab, you can verify that the material type is `StandardPBR` by checking the `Material Type` property in the `Details` property group. 
+
+    {{< note >}} 
+The file browser looks for materials in the project folder, any Gem's *Assets* folders, or any other folder included in the AssetProcessorPlatformConfig.ini.*
+    {{< /note >}}
+
+1. Browse and load each texture file into the `Texture Map` property under the texture's associated property group. Depending on the property group, additional properties might appear so you can further configure the property group. 
+
+    The textures are loaded into their associated property group in the following way. 
+
+   - **Base Color**: castle_brick_02_red_basecolor
+   - **Roughness**: castle_brick_02_red_roughness
+   - **Normal**: castle_brick_02_red_normal
+   - **Ambient Occlusion**: castle_brick_02_red_ambientocclusion
+   - **Parallax Mapping**: castle_brick_02_red_displacement  
+
+    {{< note >}} 
+The downloaded normal map is flipped. To flip it back, enable the `Flip Y Channel` property.*
+    {{< /note >}}
+
+<!--     [Future work] Add a link here to a page that includes:  more detail about all the settings. Provide tips on determining whether they need to flip X/Y channels of a normal map. For one thing, it's easier to tell if you use a light preset with a strong directional light like the "Goegap" presets -->
+
+You've successfully created a new StandardPBR material! The following figure shows the property settings and the expected material.
+
+<!-- [TODO] @HogJonny-AMZN Will need to update this image with up-to-date Material Editor GUI.  -->
+
+![Creating a StandardPBR material using the Material Editor](/images/atom-guide/architecture/materials/create-standardpbr-material.png)
+
+
+<!--
+## Extra Credit 
+Create a high pass texture!  
+
+[WRITER NOTE: TODO. Won't do until after March 9. See wiki: Create a standardpbr material]
+-->