[Port] [6000.3] Refactor the Shader Graph doc section about Custom Lighting sample

Author: svc-reach-platform-support

Packages/com.unity.shadergraph/Documentation~/Shader-Graph-Sample-Custom-Lighting-Components.md

@@ -0,0 +1,39 @@
+# Get started with the Custom Lighting sample
+
+Use the templates and sub graphs included in the **Custom Lighting** sample to get started with lighting model customization in Shader Graph.
+
+> [!NOTE]
+> To use the **Custom Lighting** templates and sub graphs, you first need to [import the sample in your project](ShaderGraph-Samples.md#add-samples).
+
+## Start from a shader graph template
+
+To use one of the available Custom Lighting templates as a starting point to customize lighting in a prebuilt shader graph asset, follow these steps:
+
+1. [Create a shader graph asset from a template](create-shader-graph.md).
+
+1. In the [template browser](template-browser.md), select one of the templates from the **URP Custom Lighting** section.
+
+1. Select **Create**.
+
+1. Open the created shader graph asset in the Shader Graph window if the window doesn't open automatically.
+
+## Start from an empty shader graph
+
+To use one of the available Lighting Model sub graphs as a starting point to customize lighting in an empty shader graph asset, follow these steps:
+
+1. [Create a shader graph asset with a preset target](create-shader-graph.md#create-a-shader-graph-with-a-preset-target) and select **URP** > **Unlit Shader Graph**.
+
+1. Open the created shader graph asset in the Shader Graph window if the window doesn't open automatically.
+
+1. Go to the [**Create Node** menu](Create-Node-Menu.md) and add one of the sub graphs from the **Custom Lighting** > **Lighting Models** section.
+
+1. Connect the **Lit** output port of the added sub graph to the **Base Color** input port of the Master Stack.
+
+1. To allow the Unlit target to correctly support custom lighting models, set the [Graph Settings](Graph-Settings-Tab.md) as follows:
+   * Enable **Keep Lighting Variants**.
+   * Disable **Default Decal Blending** and **Default SSAO**.
+
+## Additional resources
+
+* [Create a shader graph asset](Create-Shader-Graph.md)
+* [Add and connect nodes](Create-Node-Menu.md)

Packages/com.unity.shadergraph/Documentation~/Shader-Graph-Sample-Custom-Lighting-Get-Started.md

@@ -0,0 +1,41 @@
+# Introduction to lighting model customization with Shader Graph
+
+You can customize lighting models to do the following:
+
+* Improve rendering performance. You can remove or simplify one or more types of lighting calculations and sacrifice visual quality for rendering speed.
+
+* Make your lighting look different from Unity's default lighting. For example, to make your project look like a watercolor painting or a pen and ink drawing.
+
+
+## Lighting model customization examples
+
+The assets available in the **Custom Lighting** sample allow you to [get started with lighting model customization](Shader-Graph-Sample-Custom-Lighting-Get-Started.md) in different contexts and for various purposes. 
+
+| **Context** | **Description** | **Template** |
+| :--- | :--- | :--- |
+| Model for devices where performance is critical | With XR or low-end mobile devices where performance is critical, you likely need to reduce the cost of calculations in your shaders. For example, you might skip any fog, specular, reflections, light cookies, or SSAO support and only keep the basics. | [Custom Lighting Basic](Shader-Graph-Sample-Custom-Lighting-Templates.md#custom-lighting-basic) |
+| Simplified URP model with performance optimization | If you need to optimize performance in URP, you might want to use a Blinn model, which is similar to the main lighting in URP but slightly cheaper for specular highlights. The Blinn model slightly affects the redering quality but renders faster in most cases. | [Custom Lighting Simple](Shader-Graph-Sample-Custom-Lighting-Templates.md#custom-lighting-simple) |
+| Posterization model for cartoon appearance | You can alter the lighting in a shader graph to achieve stylized effects such as posterization, to give the visuals of your project the appearance of a cartoon. | [Custom Lighting Toon](Shader-Graph-Sample-Custom-Lighting-Templates.md#custom-lighting-toon) |
+| Lit URP model customization | You might want to explore the process of lighting customization directly from a shader based on the Lit URP model. | [Custom Lighting URP](Shader-Graph-Sample-Custom-Lighting-Templates.md#custom-lighting-urp) |
+| Other types of lighting customization | You can use any of the [Lighting Model](Shader-Graph-Sample-Custom-Lighting-Lighting-Models.md) sub graphs available in the **Custom Lighting** sample to create any type of lighting that you need within your own shader graphs. These sub graphs use a recommended pattern that illustrates how Unity expects custom lighting models to be defined. | N/A |
+
+
+## Limitations
+
+Before you start to customize lighting models with Shader Graph, be aware of the following limitations:
+
+### Shader Graph doesn't support deferred rendering
+
+Customizable lighting is only intended to be used when you set the render type to Forward or Forward+ in the Render Asset.
+
+When you set the render type to Deferred or Deferred+, it's not possible to control the lighting directly in an object’s shader, because the lighting occurs in a pass that is not directly connected to the object's shader.
+
+If you need to customize lighting in a deferred rendering context, you have to [write shaders in code](xref:um-shader-writing) instead of using Shader Graph.
+
+### Handling multiple light sources in Shader Graph requires HLSL coding
+
+To support multiple light sources in Shader Graph, you have to write a small amount of code.
+
+For the main directional light, you can create custom lighting in Shader Graph without coding. However, the part of the graph that does multiple light calculations requires the use of a [Custom Function node](Custom-Function-Node.md), because Shader Graph doesn’t support `For` loops.
+
+The sample includes multiple examples of Additional Lights nodes, but if you want to create your own, you need to know a little bit of HLSL coding.

Packages/com.unity.shadergraph/Documentation~/Shader-Graph-Sample-Custom-Lighting-Introduction.md

@@ -1,21 +1,46 @@
-# Lighting Models
+# Lighting Model sub graph reference
 
-Use any of these subgraphs with the Unlit material type to create lighting that is defined in the Shader Graph. To know how to use these subgraphs, refer to the [main page](Shader-Graph-Sample-Custom-Lighting.md#examples).
+Explore the Lighting Model sub graphs used in the [URP Custom Lighting templates](Shader-Graph-Sample-Custom-Lighting-Templates.md) included in the Custom Lighting sample.
 
-All of the following subgraphs include the ApplyDecals subgraph to blend decal data, and the Debug Lighting and Debug Materials subgraph nodes to support the debug rendering modes (available in the Rendering Debugger window). They also include a subgraph from the Core Lighting Models category to define the behavior of the lighting itself as described below.
+These sub graphs are available in the [**Create Node** menu](Create-Node-Menu.md) under the **Lighting** > **Light Models** section.
 
-## Lit Basic
-The Lit Basic lighting model does very simple lighting and leaves out most lighting features to render as fast as possible. It calculates simple diffuse lighting and a simple form of ambient lighting. It does not support fog, reflections, specular, light cookies, or any other lighting features. But it does render fast and is ideal for low-end mobile devices and XR headsets.
+> [!NOTE]
+> To use any of these sub graphs, you must include it in a shader graph set up with the **Universal** (URP) target and the **Unlit** material type.
 
-## Lit Colorize
-The Colorize lighting model is an example of custom behavior type you can create when you can control the lighting model. The main directional light renders the scene in grayscale with no color. Color is introduced with point lights, which allows you to control where the scene has color based on where you place the point lights in the scene.
+## Common sub graph structure
 
-## Lit Simple
-The Lit Simple lighting model is the same as the URP lighting model, except it uses the Blinn formula for the specular highlights. This makes it slightly cheaper to render than standard URP while looking fairly similar. If you still need all of the lighting features (specular, fog, screen space ambient occlusion, reflections, etc), but you want to make the lighting cheaper, this may be a good choice.
+Each Lighting Model sub graph includes the following:
+* The [ApplyDecals](Shader-Graph-Sample-Custom-Lighting-Components.md#general) sub graph, to blend decal data with the original material properties.
+* The [Debug Lighting and Debug Materials](Shader-Graph-Sample-Custom-Lighting-Components.md#debug) sub graphs, to support the debug rendering modes (available in the Rendering Debugger window).
+* A sub graph from the [Core Models](Shader-Graph-Sample-Custom-Lighting-Components.md#core-models) category, to define the lighting behavior according to the model.
 
-## Lit Toon
-The Lit Toon lighting model uses a Posterize operation to break the smooth lighting gradient into distinct bands of shading. It simulates the look of cartoons where lighting is rendered with distinct colors of paint rather than smooth gradients.
+> [!NOTE]
+> The ApplyDecals, DebugLighting, and DebugMaterials sub graph nodes aren’t strictly required. They enable the decals and debug rendering modes, which are core engine features. When you don't use these features, the corresponding sub graph nodes don't affect your project's performance.
 
-## Lit URP
-The Lit URP lighting model closely matches the lighting that the Universal Render Pipeline does by default. If you want to start with the URP lighting and then alter it, this is the node to use.
+## Available Lighting Model sub graphs
 
+### Lit Basic
+
+This lighting model does very simple lighting and leaves out most lighting features to render as fast as possible. It calculates simple diffuse lighting and a simple form of ambient lighting. It does not support fog, reflections, specular, light cookies, or any other lighting features. But it does render fast and is ideal for low-end mobile devices and XR headsets.
+
+### Lit Colorize
+
+This lighting model is an example of custom behavior type you can create when you can control the lighting model. The main directional light renders the scene in grayscale with no color. Color is introduced with point lights, which allows you to control where the scene has color based on where you place the point lights in the scene.
+
+### Lit Simple
+
+This lighting model is the same as the URP lighting model, except it uses the Blinn formula for the specular highlights. This makes it slightly cheaper to render than standard URP while looking fairly similar. If you still need all of the lighting features (specular, fog, screen space ambient occlusion, reflections, etc), but you want to make the lighting cheaper, this may be a good choice.
+
+### Lit Toon
+
+This lighting model uses a Posterize operation to break the smooth lighting gradient into distinct bands of shading. It simulates the look of cartoons where lighting is rendered with distinct colors of paint rather than smooth gradients.
+
+### Lit URP
+
+This lighting model closely matches the lighting that the Universal Render Pipeline does by default. If you want to start with the URP lighting and then alter it, this is the node to use.
+
+## Additional resources
+
+* [Introduction to lighting model customization](Shader-Graph-Sample-Custom-Lighting-Introduction.md)
+* [Get started with the Custom Lighting sample](Shader-Graph-Sample-Custom-Lighting-Get-Started.md)
+* [URP Custom Lighting template reference](Shader-Graph-Sample-Custom-Lighting-Templates.md)

Packages/com.unity.shadergraph/Documentation~/Shader-Graph-Sample-Custom-Lighting-Lighting-Models.md

@@ -0,0 +1,29 @@
+# URP Custom Lighting template reference
+
+Explore the prebuilt URP Custom Lighting shader graph templates included in the Custom Lighting sample.
+
+> [!NOTE]
+> These templates are available in the [template browser](template-browser.md) under the **URP Custom Lighting** section. Don't edit the corresponding assets in the **Assets** > **Samples** > **Shader Graph** folder of your project.
+
+Each Custom Lighting template includes a specific [Lighting Model sub graph](Shader-Graph-Sample-Custom-Lighting-Lighting-Models.md).
+
+## Custom Lighting Basic
+
+This template uses a basic lighting model that calculates diffuse lighting for multiple light sources. To reduce the cost of calculations, this shader does not support fog, specular, reflections, light cookies, and SSAO, but you can reintegrate any of these features if needed. This model makes the lighting as cheap as possible by only including the basic requirements. This type of lighting model is ideal for XR or low-end mobile devices where performance is critical.
+
+## Custom Lighting Simple
+
+This template uses a lighting model designed to be similar to the main lighting used by URP. It uses a slightly cheaper Blinn model for specular highlights, which reduces the quality but speeds up the rendering in most cases.
+
+## Custom Lighting Toon
+
+This template uses a lighting model that posterizes the lighting to give it the appearance of a cartoon. This shows you how you can alter lighting in the graph to achieve stylized effects that give your project a unique appearance.
+
+## Custom Lighting URP
+
+This template uses the same lighting formula as the Lit URP model. You can use it as a starting point if you want to begin with URP as is and then make changes.
+
+## Additional resources
+
+* [Introduction to lighting model customization](Shader-Graph-Sample-Custom-Lighting-Introduction.md)
+* [Get started with the Custom Lighting sample](Shader-Graph-Sample-Custom-Lighting-Get-Started.md)

Packages/com.unity.shadergraph/Documentation~/Shader-Graph-Sample-Custom-Lighting-Templates.md

@@ -1,57 +1,13 @@
 # Custom Lighting
-![The Shader Graph Custom Lighting Sample: A collection of Shader Graph subgraphs that serve as building blocks for building user interface elements.](images/CustomLightingSample.png) 
 
-The Shader Graph Custom Lighting sample shows how you can create your own custom lighting in Shader Graph and provides dozens of example templates, shaders, and subgraphs to help you get started with your own custom lighting.
+![An example scene with custom lighting effects.](images/CustomLightingSample.png) 
 
- Documentation for this set of samples is broken into two pages:
+Use the additional templates and sub graphs provided in the **Custom Lighting** sample to get started with lighting model customization in Shader Graph.
 
-* [Lighting Models](Shader-Graph-Sample-Custom-Lighting-Lighting-Models.md)
-* [Components](Shader-Graph-Sample-Custom-Lighting-Components.md)
-
-## Limitations
-Before making your own custom lighting model in Shader Graph, be aware of the following limitations:
-
-* Customizable lighting is only intended to be used when the render type is set to Forward or Forward+ in the Render Asset.
-  
-  When the render type is set to Deferred or Deferred+, it's not possible to control the lighting directly in an object’s shader, because the lighting occurs in a pass that is not directly connected to the object's shader.
-  
-  If you need to customize lighting in deferred rendering context, you have to write code instead of using Shader Graph.
-
-* To support multiple light sources, you have to write a small amount of code.
-  
-  For the main directional light, you can create custom lighting 100% in Shader Graph. However, the part of the graph that does multiple light calculations requires the use of a Custom Function node, because Shader Graph doesn’t support `For` loops.
-  
-  The sample includes multiple examples of Additional Lights nodes, but if you want to create your own, you need to know a little bit of HLSL coding.
-
-
-## Motivations
-There are two main reasons you might want to customize the lighting model in Shader Graph:
-
-* Improve rendering performance by leaving out one or more types of lighting calculations, sacrificing visual quality for rendering speed.
-
-* Make your lighting look different from the lighting that Unity already provides. For example, you might want your project to look like a watercolor painting, like it’s drawn with pen and ink, etc.
-
-## Examples
-The sample includes the following subgraph examples in the Shader Graph node library:
-
-* Lighting / Light Models / Lit Basic
-* Lighting / Light Models / Lit Colorize
-* Lighting / Light Models / Lit Simple
-* Lighting / Light Models / Lit Toon
-* Lighting / Light Models / Lit URP
-
-To get customized lighting with any of these subgraphs: 
-1. Add the subgraph to an empty Shader Graph.
-1. Connect the Lit output port to the Base Color input port on the Unlit Master Stack.
-1. To allow the Unlit target to correctly support custom lighting models, make sure to set the Graph inspector as follows:
-   * Enable *Keep Lighting Variants*.
-   * Disable *Default Decal Blending* and *Default SSAO*.
-
-Notice that each of the above subgraphs use the following:
-* The ApplyDecals subgraph to blend decal data with the original material properties.
-* The Debug Lighting and Debug Materials subgraph nodes to support the debug rendering modes (available in the Rendering Debugger window).
-* A subgraph from the Core Lighting Models category to define the behavior of the lighting itself.
-
-While the ApplyDecals, DebugLighting, and DebugMaterials subgraph nodes aren’t strictly required, they are included in the lighting model subgraphs to enable these core engine features: decals and debug rendering modes. When these features are not in use, the ApplyDecals, DebugLighting, and DebugMaterials subgraph nodes don't add any performance cost to the shader overall. You can use them without worrying that you’re slowing down your project.
-
-You can create any type of lighting that you want, but the above subgraphs show you a recommended pattern to illustrate how Unity expects custom lighting models to be defined.
+| **Topic** | **Description** |
+| :--- | :--- |
+| [Introduction to lighting model customization with Shader Graph](Shader-Graph-Sample-Custom-Lighting-Introduction.md) | Learn about the purpose and limitations of lighting model customization in Shader Graph and get an overview of the use cases covered in the **Custom Lighting** sample. |
+| [Get started with the Custom Lighting sample](Shader-Graph-Sample-Custom-Lighting-Get-Started.md) | Start your lighting customization from either a prebuilt shader graph template or a lighting model sub graph in your own shader graph. |
+| [URP Custom Lighting template reference](Shader-Graph-Sample-Custom-Lighting-Templates.md) | Explore the prebuilt shader graph templates included in the sample. |
+| [Lighting Model sub graph reference](Shader-Graph-Sample-Custom-Lighting-Lighting-Models.md) | Explore the Lighting Model sub graphs included in the sample and used in the URP Custom Lighting templates. |
+| [Component sub graph reference](Shader-Graph-Sample-Custom-Lighting-Components.md) | Explore the Component sub graphs used as building blocks for the Lighting Model sub graphs included in the sample. |

Packages/com.unity.shadergraph/Documentation~/Shader-Graph-Sample-Custom-Lighting.md

@@ -353,8 +353,11 @@
             * [How to make shapes that adapt to the aspect ratio of the UI element](Shader-Graph-Sample-UGUI-Shaders-How-tos-aspect-ratio.md)
         * [Notes on performance](Shader-Graph-Sample-UGUI-Shaders-Notes-on-performance.md)
     * [Custom Lighting](Shader-Graph-Sample-Custom-Lighting.md)
-        * [Lighting Models](Shader-Graph-Sample-Custom-Lighting-Lighting-Models.md)
-        * [Components](Shader-Graph-Sample-Custom-Lighting-Components.md)
+        * [Introduction to lighting model customization](Shader-Graph-Sample-Custom-Lighting-Introduction.md)
+        * [Get started with the Custom Lighting sample](Shader-Graph-Sample-Custom-Lighting-Get-Started.md)
+        * [URP Custom Lighting template reference](Shader-Graph-Sample-Custom-Lighting-Templates.md)
+        * [Lighting Model sub graph reference](Shader-Graph-Sample-Custom-Lighting-Lighting-Models.md)
+        * [Component sub graph reference](Shader-Graph-Sample-Custom-Lighting-Components.md)
     * [Terrain Shaders](Shader-Graph-Sample-Terrain.md)
         * [Texture Packing Schemes](Shader-Graph-Sample-Terrain-Packing.md)
         * [Shaders](Shader-Graph-Sample-Terrain-Shaders.md)