[7.x.x backport] [Ready to merge] DOC-1818 writing custom shaders

com.unity.render-pipelines.universal/Documentation~/TableOfContents.md

@@ -61,6 +61,12 @@
   * [Particles Unlit](particles-unlit-shader.md)
   * [Upgrading shaders from Built-in](upgrading-your-shaders.md)
   * [Shader stripping](shader-stripping.md)
+  * [Writing custom shaders](writing-custom-shaders-urp.md)
+    * [Creating a sample scene](writing-shaders-urp-basic-prerequisites.md)
+    * [URP basic unlit shader](writing-shaders-urp-basic-unlit-structure.md)    
+    * [URP unlit shader with color input](writing-shaders-urp-unlit-color.md)
+    * [Drawing a texture](writing-shaders-urp-unlit-texture.md)
+    * [Visualizing normal vectors](writing-shaders-urp-unlit-normals.md)
 
 * [Customizing URP](customizing-urp.md)
   * [beginCameraRendering event](using-begincamerarendering.md)

com.unity.render-pipelines.universal/Documentation~/shader-structure.md

@@ -0,0 +1,82 @@
+# Shader structure
+
+This section provides an overview of a Unity shader structure.
+
+Unity shader assets are written in a Unity-specific language called [ShaderLab](https://docs.unity3d.com/Manual/SL-Shader.html). 
+
+A URP-compatible ShaderLab file contains some or all of the following blocks:
+* [Shader](#shader)
+* [Properties](#properties)
+* [SubShader](#subshader)
+* [Pass](#pass)
+* [HLSLPROGRAM](#hlsl)
+* [CBUFFER](#cbuffer)
+
+<a name="shader"></a>
+
+## Shader block
+
+A ShaderLab file starts with the `Shader` declaration.
+
+```c++
+Shader "Example/URPUnlitShaderBasic"
+```
+
+The path in this declaration determines the location of the shader in the Shader menu on a Material.
+![location of the shader in the Shader menu on a Material](Images/shader-examples/urp-material-ui-shader-path.png)
+
+<a name="properties"></a>
+
+## Properties block
+
+This block contains Shader properties that you can access in the Inspector window on a Material.
+
+```c++
+Properties
+{ 
+    _BaseMap("Texture", 2D) = "white" {}
+    _BaseColor("Color", Color) = (1, 1, 1, 1)
+}
+```
+
+For more information on the Properties block, see the the page [ShaderLab: Properties](https://docs.unity3d.com/Manual/SL-Properties.html).
+
+<a name="subshader"></a>
+
+## SubShader block
+
+A ShaderLab file contains one or more SubShader blocks. When rendering a mesh, Unity selects the first SubShader block that is compatible with the GPU on the target device.
+
+For more information on the SubShader block, see the page [ShaderLab: SubShader](https://docs.unity3d.com/Manual/SL-SubShader.html).
+
+A SubShader block contains the __Tags__ element and the [__Pass__](#pass) block.
+
+Tags define when and under which conditions a SubShader block is executed. For more information on Tags, see [ShaderLab: SubShader Tags](https://docs.unity3d.com/Manual/SL-SubShaderTags.html).
+
+<a name="pass"></a>
+
+## Pass block
+
+A Pass can contain information about the Pass itself (Pass name, Pass tags, etc.), and the HLSL program code. For more information, see [ShaderLab: Pass](https://docs.unity3d.com/Manual/SL-Pass.html).
+
+
+<a name="hlsl"></a>
+
+## HLSLPROGRAM block
+
+This block contains the HLSL program code.
+
+SRP shaders support only the HLSL language.
+
+<a name="cbuffer"></a>
+
+## CBUFFER block
+
+In this block, you declare the variables that must be in the constant buffer.
+
+### SRP Batcher compatibility
+
+To ensure that a Shader is SRP Batcher compatible:
+* Declare all Material properties in a single CBUFFER called `UnityPerMaterial`.
+* Declare all built-in engine properties, such as `unity_ObjectToWorld` or `unity_WorldTransformParams`, in a single CBUFFER called `UnityPerDraw`.
+

com.unity.render-pipelines.universal/Documentation~/shaders-in-universalrp.md

@@ -20,16 +20,22 @@ For [SpeedTree](https://docs.unity3d.com/Manual/SpeedTree.html) Shaders, Unity d
 
 **Note:** Unlit Shaders from the Unity built-in render pipeline work in URP.
 
-
-
 ## Choosing a Shader 
 
 With the Universal Render Pipeline, you can have real-time lighting wither either Physically Based Shaders (PBS) and non-Physically Based Rendering (PBR).
 
-For PBS, use the [Lit Shader](lit-shader.md). You can use it on all platforms. The Shader quality scales, depending on the platform, but keeps physically based rendering on all platforms. This gives you realistic graphics across hardware. The Unity [Standard Shader](<https://docs.unity3d.com/Manual/shader-StandardShader.html>) and the [Standard (Specular setup)](https://docs.unity3d.com/Manual/StandardShaderMetallicVsSpecular.html) Shaders both map to the Lit Shader in URP. For a list of Shader mappings, see [Shader mappings under Upgradring your Shaders.](upgrading-your-shaders.md#shaderMappings)
+For PBS, use the [Lit Shader](lit-shader.md). You can use it on all platforms. The Shader quality scales depending on the platform, but keeps physically based rendering on all platforms. This gives you realistic graphics across hardware. The Unity [Standard Shader](https://docs.unity3d.com/Manual/shader-StandardShader.html) and the [Standard (Specular setup) Shaders](https://docs.unity3d.com/Manual/StandardShaderMetallicVsSpecular.html) both map to the Lit Shader in URP. For a list of Shader mappings, see section [Shader mappings](upgrading-your-shaders.md#built-in-to-urp-shader-mappings).
 
-If you’re targeting less powerful devices, or just would like simpler shading, use the [Simple Lit Shader](simple-lit-shader.md), which is non-PBR. 
+If you are targeting less powerful devices, or your project has simpler shading, use the [Simple Lit shader](simple-lit-shader.md), which is non-PBR. 
 
 If you don’t need real-time lighting, or would rather only use [baked lighting](https://docs.unity3d.com/Manual/LightMode-Baked.html) and sample global illumination, choose a Baked Lit Shader. 
 
-If you don’t need lighting on a Material at all, you can choose the an Unlit Shader. 
+If you don’t need lighting on a Material at all, you can choose the Unlit Shader. 
+
+## SRP Batcher compatibility
+
+To ensure that a Shader is SRP Batcher compatible:
+* Declare all Material properties in a single CBUFFER called `UnityPerMaterial`.
+* Declare all built-in engine properties, such as `unity_ObjectToWorld` or `unity_WorldTransformParams`, in a single CBUFFER called `UnityPerDraw`.
+
+For more information on the SRP Batcher, see the page [Scriptable Render Pipeline (SRP) Batcher](https://docs.unity3d.com/Manual/SRPBatcher.html).

com.unity.render-pipelines.universal/Documentation~/upgrading-your-shaders.md

@@ -13,6 +13,8 @@ To upgrade built-in Shaders:
 
 For [SpeedTree](https://docs.unity3d.com/Manual/SpeedTree.html) Shaders, Unity does not re-generate Materials when you re-import them, unless you click the **Generate Materials** or **Apply & Generate Materials** button.
 
+<a name="built-in-to-urp-shader-mappings">
+
 ## Shader mappings
 
 The table below shows which URP shaders the Unity built-in shaders convert to when you run the shader upgrader.
@@ -44,4 +46,4 @@ The table below shows which URP shaders the Unity built-in shaders convert to wh
 | Legacy Shaders/Transparent/Cutout/Diffuse         | Universal Render Pipeline/Simple Lit      |
 | Legacy Shaders/Transparent/Cutout/Specular        | Universal Render Pipeline/Simple Lit      |
 | Legacy Shaders/Transparent/Cutout/Bumped Diffuse  | Universal Render Pipeline/Simple Lit      |
-| Legacy Shaders/Transparent/Cutout/Bumped Specular | Universal Render Pipeline/Simple Lit      |
+| Legacy Shaders/Transparent/Cutout/Bumped Specular | Universal Render Pipeline/Simple Lit      |