diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-basic-hardcoded-color.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-basic-hardcoded-color.png new file mode 100644 index 00000000000..28914487d5b --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-basic-hardcoded-color.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:2c013208b3fe28f3806228990e43f6c6e022e9db7a18b534a6cd586ef7817373 +size 393690 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-color-field-with-scene.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-color-field-with-scene.png new file mode 100644 index 00000000000..2b27f9437e7 --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-color-field-with-scene.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:6d7a0b0d8cadc3309c7567cb582f15e040caf2bb6844474fc039236ac4d44126 +size 385588 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-normals-uncompressed.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-normals-uncompressed.png new file mode 100644 index 00000000000..2b51b08c476 --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-normals-uncompressed.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:a0024975b322035108655e18fed92a2f084f0cde009a7cfe95c8adbd787e4463 +size 293722 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-normals.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-normals.png new file mode 100644 index 00000000000..a5f3c461870 --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-normals.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:085c656bfa85a406c3e5bdd294d7cd2452089c7453be7525cfd36843f54bf322 +size 286974 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-texture-property-in-inspector.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-texture-property-in-inspector.png new file mode 100644 index 00000000000..3c69bd39b03 --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-texture-property-in-inspector.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:86b367b56ebd6360d69977dfd5a2701114275e87df8821a22e4f230b999fde23 +size 11846 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-texture-with-scene.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-texture-with-scene.png new file mode 100644 index 00000000000..4f632ec5f4d --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/unlit-shader-tutorial-texture-with-scene.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:ad85f6636b2be4654159cd8db5a228c9c9a5f5007e01d30a2b6d81565747d679 +size 453394 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-material-prop-base-color.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-material-prop-base-color.png new file mode 100644 index 00000000000..3496b8cbafc --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-material-prop-base-color.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:dd15564e6e79a7db125a4f3722b3626b6d9a279ea35a2c1fd42be84e2e886be9 +size 8300 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-material-ui-shader-path.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-material-ui-shader-path.png new file mode 100644 index 00000000000..7f3443dc898 --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-material-ui-shader-path.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f87a913c97919ae1717c9a6482faee41e87794a6e4add2b27055ac28b0d505c1 +size 16108 diff --git a/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-template-sample-object.png b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-template-sample-object.png new file mode 100644 index 00000000000..15bc20de8da --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/Images/shader-examples/urp-template-sample-object.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:bc6294d13b71aad9b5895561b014d81a809ca47f91f4c70fcfc3f28a9856b4e5 +size 278965 diff --git a/com.unity.render-pipelines.universal/Documentation~/TableOfContents.md b/com.unity.render-pipelines.universal/Documentation~/TableOfContents.md index add874a1b58..23137001b07 100644 --- a/com.unity.render-pipelines.universal/Documentation~/TableOfContents.md +++ b/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) diff --git a/com.unity.render-pipelines.universal/Documentation~/shader-structure.md b/com.unity.render-pipelines.universal/Documentation~/shader-structure.md new file mode 100644 index 00000000000..ff631187809 --- /dev/null +++ b/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) + + + +## 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) + + + +## 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). + + + +## 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). + + + +## 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). + + + + +## HLSLPROGRAM block + +This block contains the HLSL program code. + +SRP shaders support only the HLSL language. + + + +## 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`. + diff --git a/com.unity.render-pipelines.universal/Documentation~/shaders-in-universalrp.md b/com.unity.render-pipelines.universal/Documentation~/shaders-in-universalrp.md index 6454b06ffee..642cc47cfa8 100644 --- a/com.unity.render-pipelines.universal/Documentation~/shaders-in-universalrp.md +++ b/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]() 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). diff --git a/com.unity.render-pipelines.universal/Documentation~/upgrading-your-shaders.md b/com.unity.render-pipelines.universal/Documentation~/upgrading-your-shaders.md index 3b5e81614a6..cb6740af1db 100644 --- a/com.unity.render-pipelines.universal/Documentation~/upgrading-your-shaders.md +++ b/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. + + ## 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 | \ No newline at end of file +| Legacy Shaders/Transparent/Cutout/Bumped Specular | Universal Render Pipeline/Simple Lit | diff --git a/com.unity.render-pipelines.universal/Documentation~/urp-shader-examples.md b/com.unity.render-pipelines.universal/Documentation~/urp-shader-examples.md new file mode 100644 index 00000000000..9a2ac213ecc --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/urp-shader-examples.md @@ -0,0 +1,581 @@ +# URP unlit shader examples + +This section contains URP-compatible shader examples that help you to get started with writing shaders for URP. + +The section contains the following topics: + +* [Creating a sample scene](#prerequisites) +* [URP basic shader](#urp-unlit-basic-shader) +* [URP unlit shader with color input](#urp-unlit-color-shader) +* [Visualizing normal vectors](#urp-unlit-normals-shader) +* [Drawing a texture](#urp-unlit-normals-shader) + +Each example covers some extra information compared to the basic shader example, and contains the explanation of that information. + + + +## Creating a sample scene + +To follow the examples in this section: + +1. Create a new project using the [__Universal Project Template__](https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@8.0/manual/creating-a-new-project-with-urp.html). + +2. In the sample Scene, create a GameObject to test the shaders on, for example, a capsule. + ![Sample GameObject](Images/shader-examples/urp-template-sample-object.jpg) + +3. Create a new Material and assign it to the capsule. + +4. Create a new Shader asset and assign it to the Material of the capsule. When following an example, replace the code in the Shader asset with the code in the example. + + + +## URP unlit basic shader + +This example shows a basic URP-compatible shader. This shader fills the mesh shape with a color predefined in the shader code. + +To see the shader in action, copy and paste the following ShadeLab code into the Shader asset. + +```c++ +// This shader fills the mesh shape with a color predefined in the code. +Shader "Example/URPUnlitShaderBasic" +{ + // The properties block of the shader. In this example this block is empty since + // the output color is predefined in the fragment shader code. + Properties + { } + + // The SubShader block containing the Shader code. + SubShader + { + // Tags define when and under which conditions a SubShader block or a pass + // is executed. + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalRenderPipeline" } + + Pass + { + // The HLSL code block. Unity SRP uses the HLSL language. + HLSLPROGRAM + // This line defines the name of the vertex shader. + #pragma vertex vert + // This line defines the name of the fragment shader. + #pragma fragment frag + + // The Core.hlsl file contains definitions of frequently used HLSL macros and + // functions, and also contains #include references to other HLSL files + // (for example, Common.hlsl, SpaceTransforms.hlsl, etc.). + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + // The structure definition defines which variables it contains. + // This example uses the Attributes structure as an input structure in the + // vertex shader. + struct Attributes + { + // The positionOS variable contains the vertex positions. + float4 positionOS : POSITION; + }; + + struct Varyings + { + // The positions in this struct must have the SV_POSITION semantic. + float4 positionHCS : SV_POSITION; + }; + + // The vertex shader definition with paroperties defined in the Varyings + // structure. The type of the vert function must match the type (struct) that it + // returns. + Varyings vert(Attributes IN) + { + // Declaring the output object (OUT) with the Varyings struct. + Varyings OUT; + // The TransformObjectToHClip function transforms vertex positions from + // object space to homogenous space + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + // Returning the output. + return OUT; + } + + // The fragment shader definition. + half4 frag() : SV_Target + { + // Defining the color variable and returning it. + half4 customColor; + customColor = half4(0.5, 0, 0, 1); + return customColor; + } + ENDHLSL + } + } +} +``` + +The shader paints the GameObject dark red. + +![The shader paints the GameObject dark red](Images/shader-examples/unlit-shader-tutorial-basic-hardcoded-color.jpg) + +The following sections introduce you to the structure of this basic shader. + +The shader in this example has the following blocks: + +* [Shader](#shader) +* [Properties](#properties) +* [SubShader](#subshader) +* [Pass](#pass) +* [HLSLPROGRAM](#hlsl) + + + +### Shader block + +Unity shader assets are written in a Unity-specific language called [ShaderLab](https://docs.unity3d.com/Manual/SL-Shader.html). + +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) + + + +### Properties block + +The [Properties](https://docs.unity3d.com/Manual/SL-Properties.html) block contains the declarations of properties that users can set in the Inspector window on a Material. + +In this example, the Properties block is empty, since this shader does not expose any Material properties that a user can define. TODO:reference to Color. + +### SubShader block + +A ShaderLab file contains one or more [SubShader](https://docs.unity3d.com/Manual/SL-SubShader.html) blocks. When rendering a mesh, Unity selects the first SubShader block that is compatible with the GPU on the target device. + +A SubShader block contains the __Tags__ element. + +``` +Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalRenderPipeline" } +``` + +The `RenderPipeline` tag in this Shader instructs Unity to use this SubShader block only when the project is using the Universal Render Pipeline. + +For more information on Tags, see [ShaderLab: SubShader Tags](https://docs.unity3d.com/Manual/SL-SubShaderTags.html). + +### Pass block + +In this example, there is one Pass block that contains the HLSL program code. For more information on Pass blocks, see [ShaderLab: Pass](https://docs.unity3d.com/Manual/SL-Pass.html). + +### HLSLPROGRAM block + +This block contains the HLSL program code. + +> **NOTE**: SRP shaders support only the HLSL language. + +This block contains the `#include` declaration with the reference to the `Core.hlsl` file. + +```c++ +#include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" +``` + +The `Core.hlsl` file contains definitions of frequently used HLSL macros and functions, and also contains #include references to other HLSL files (for example, Common.hlsl, SpaceTransforms.hlsl, etc.). + +For example the vertex shader in the HLSL program uses the `TransformObjectToHClip` function from the `SpaceTransforms.hlsl` file. The function transforms vertex positions from object space to homogenous space: + +```c++ +Varyings vert(Attributes IN) +{ + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + return OUT; +} +``` + +The fragment shader in this basic HLSL program outputs the single color predefined in the code: + +```c++ +half4 frag() : SV_Target +{ + half4 customColor; + customColor = half4(0.5, 0, 0, 1); + return customColor; +} +``` + +Section [URP unlit shader with color input](#urp-unlit-color-shader) shows how to add the editable color property in the Inspector window on the Material. + + + +## URP unlit shader with color input + +The shader in this example adds the __Base Color__ property to the Material. You can select the color using that property and the shader fills the mesh shape with the color. + +Use the ShaderLab code from section [URP unlit basic shader](#urp-unlit-basic-shader) and make the following changes to it: + +1. Add the `_BaseColor` property definition to the Properties block: + + ```c++ + Properties + { + _BaseColor("Base Color", Color) = (1, 1, 1, 1) + } + ``` + + This declaration adds the `_BaseColor` property with the label __Base Color__ to the Material: + + ![Base Color property on a Material](Images/shader-examples/urp-material-prop-base-color.png) + + The `_BaseColor` property name is a reserved name. When you declare a property with this name, Unity uses this property as the [main color](https://docs.unity3d.com/ScriptReference/Material-color.html) of the Material. + +2. After declaring a property in the Properties block, it's necessary to declare it in the HLSL program block. + + > __NOTE__: To ensure that the shader is SRP Batcher compatible, declare all Material properties inside a single `CBUFFER` block with the name `UnityPerMaterial`. + + Add the following code before the vertex shader: + + ```c++ + CBUFFER_START(UnityPerMaterial) + half4 _BaseColor; + CBUFFER_END + ``` + +3. Change the code in the fragment shader so that it returns the `_BaseColor` property. + + ```c++ + half4 frag() : SV_Target + { + return _BaseColor; + } + ``` + +Now you can select the color in the Base Color field in the Inspector window and the shader fills the mesh with that color. + +![Base Color field on a Material](Images/shader-examples/unlit-shader-tutorial-color-field-with-scene.jpg) + +Below is the complete ShaderLab code for this example. + +```c++ +// This shader fills the mesh shape with a color that a user can change using the Inspector window on a Material. +Shader "Example/URPUnlitShaderColor" +{ + // The _BaseColor variable is visible as a field called Base Color in the Inspector window on a Material. + // This variable has the default value, and you can select a custom color using the Base Color field. + Properties + { + _BaseColor("Base Color", Color) = (1, 1, 1, 1) + } + + SubShader + { + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalRenderPipeline" } + + Pass + { + HLSLPROGRAM + #pragma vertex vert + #pragma fragment frag + + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + struct Attributes + { + float4 positionOS : POSITION; + }; + + struct Varyings + { + float4 positionHCS : SV_POSITION; + }; + + // To make the shader SRP Batcher compatible, declare all properties related to a Material + // in a a single CBUFFER block with the name UnityPerMaterial. + CBUFFER_START(UnityPerMaterial) + // The following line declares the _BaseColor variable, so that you can use it in the fragment shader. + half4 _BaseColor; + CBUFFER_END + + Varyings vert(Attributes IN) + { + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + return OUT; + } + + half4 frag() : SV_Target + { + // Returning the _BaseColor value. + return _BaseColor; + } + ENDHLSL + } + } +} +``` + +Section [Drawing a texture](#urp-unlit-texture-shader) shows how to draw a texture on the mesh. + + + +## Drawing a texture + +The shader in this example draws a texture on the mesh. + +Use the ShaderLab code from section [URP unlit shader with color input](#urp-unlit-color-shader) and make the following changes to it: + +1. In the Properties block, replace the existing code with the `_BaseMap` property definition. + + ```c++ + Properties + { + _BaseMap("Base Map", 2D) = "white" + } + ``` + + This declaration adds the `_BaseMap` property with the label __Base Map__ to the Material. + + The `_BaseMap` property name is a reserved name. When you declare a property with this name, Unity uses this property as the [main texture](https://docs.unity3d.com/ScriptReference/Material-mainTexture.html) of the Material. + +2. In `struct Attributes` and `struct Varyings`, add the `uv` variable for the UV coordinates on the texture: + + ```c++ + float2 uv : TEXCOORD0; + ``` + +3. Define the texture as a 2D texture and specify a sampler for it. Add the following lines before the CBUFFER block: + + ```c++ + TEXTURE2D(_BaseMap); + SAMPLER(sampler_BaseMap); + ``` + + The TEXTURE2D and the SAMPLER macros are defined in one of the files referenced in `Core.hlsl`. + +4. When you declare a texture property in the Properties block, Unity adds the Tiling and Offset controls to that property in the Inspector. For tiling and offset to work, it's necessary to declare the texture property with the `_ST` suffix in the 'CBUFFER' block. The `_ST` suffix is necessary because some macros (for example, `TRANSFORM_TEX`) use it. + + > __NOTE__: To ensure that the shader is SRP Batcher compatible, declare all Material properties inside a single `CBUFFER` block with the name `UnityPerMaterial`. + + ```c++ + CBUFFER_START(UnityPerMaterial) + float4 _BaseMap_ST; + CBUFFER_END + ``` + +5. To apply the tiling and offset transformation, add the following line in the vertex shader: + + ```c++ + OUT.uv = TRANSFORM_TEX(IN.uv, _BaseMap); + ``` + + The `TRANSFORM_TEX` macro is defined in the `Macros.hlsl` file. The `#include` declaration contains a reference to that file. + +6. In the fragment shader, use the `SAMPLE_TEXTURE2D` macro to sample the texture: + + ```c++ + half4 frag(Varyings IN) : SV_Target + { + half4 color = SAMPLE_TEXTURE2D(_BaseMap, sampler_BaseMap, IN.uv); + return color; + } + ``` + +Now you can select a texture in the __Base Map__ field in the Inspector window and the shader draws that texture on the mesh. + +![Base Map texture on a Material](Images/shader-examples/unlit-shader-tutorial-texture-with-scene.jpg) + +Below is the complete ShaderLab code for this example. + +```c++ +// This shader draws a texture on the mesh. +Shader "Example/URPUnlitShaderTexture" +{ + // The _BaseMap variable is visible as a field called Base Map in the Inspector window on a Material. + Properties + { + _BaseMap("Base Map", 2D) = "white" + } + + SubShader + { + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalRenderPipeline" } + + Pass + { + HLSLPROGRAM + #pragma vertex vert + #pragma fragment frag + + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + struct Attributes + { + float4 positionOS : POSITION; + // The uv variable contains the UV coordinate on the texture for the given + // vertex. + float2 uv : TEXCOORD0; + }; + + struct Varyings + { + float4 positionHCS : SV_POSITION; + // The uv variable contains the UV coordinate on the texture for the given + // vertex. + float2 uv : TEXCOORD0; + }; + + // This macro declares _BaseMap as a Texture2D object. + TEXTURE2D(_BaseMap); + // This macro declares the sampler for the _BaseMap texture. + SAMPLER(sampler_BaseMap); + + CBUFFER_START(UnityPerMaterial) + // The following line declares the _BaseMap_ST variable, so that you can use + // the _BaseMap variable in the fragment shader. + // The _ST suffix is necessary for the tiling and offset function to work. + float4 _BaseMap_ST; + CBUFFER_END + + Varyings vert(Attributes IN) + { + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + // The TRANSFORM_TEX macro performs the tiling and offset transformation. + OUT.uv = TRANSFORM_TEX(IN.uv, _BaseMap); + return OUT; + } + + half4 frag(Varyings IN) : SV_Target + { + // The SAMPLE_TEXTURE2D marco samples the texture with the given sampler. + half4 color = SAMPLE_TEXTURE2D(_BaseMap, sampler_BaseMap, IN.uv); + return color; + } + ENDHLSL + } + } +} +``` + +Section [Visualizing normal vectors](#urp-unlit-normals-shader) shows how to visualize normal vectors on the mesh. + + + +## Visualizing normal vectors + +The shader in this example visualizes the normal vector values on the mesh. + +Use the ShaderLab code from section [URP unlit basic shader](#urp-unlit-basic-shader) and make the following changes to it: + +1. In `struct Attributes`, which is the input structure for the vertex shader in this example, declare the variable containing the normal vector for each vertex. + + ```c++ + struct Attributes + { + float4 positionOS : POSITION; + // Declaring the variable containing the normal vector for each vertex. + half3 normal : NORMAL; + }; + ``` + +2. In `struct Varyings`, which is the input structure for the fragment shader in this example, declare the variable for storing the normal vector values for each fragment: + + ```c++ + struct Varyings + { + float4 positionHCS : SV_POSITION; + // The variable for storing the normal vector values. + half3 normal : TEXCOORD0; + }; + ``` + + This example uses the three components of the normal vector as RGB color values for each fragment. + +3. To render the normal vector values on the mesh, use the following code as the fragment shader: + + ```c++ + half4 frag(Varyings IN) : SV_Target + { + half4 color = 0; + color.rgb = IN.normal; + return color; + } + ``` + +4. Unity renders the normal vector values on the mesh: + + ![Rendering normals without compression](Images/shader-examples/unlit-shader-tutorial-normals-uncompressed.jpg) + + A part of the capsule is black. This is because in those points all three components of the normal vector are negative. The next step shows how to render values in those areas as well. + +5. To render negative normal vector components, use the compression technique. To compress the range of normal component values `(-1..1)` to color value range `(0..1)`, change the following line: + + ```c++ + color.rgb = IN.normal; + ``` + + to this line: + + ```c++ + color.rgb = IN.normal * 0.5 + 0.5; + ``` + +Now Unity renders the normal vector vales as colors on the mesh. + +![Rendering normals with compression](Images/shader-examples/unlit-shader-tutorial-normals.jpg) + +Below is the complete ShaderLab code for this example. + +```c++ +// This shader visuzlizes the normal vector values on the mesh. +Shader "Example/URPUnlitShaderNormal" +{ + Properties + { } + + SubShader + { + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalRenderPipeline" } + + Pass + { + HLSLPROGRAM + #pragma vertex vert + #pragma fragment frag + + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + struct Attributes + { + float4 positionOS : POSITION; + // Declaring the variable containing the normal vector for each vertex. + half3 normal : NORMAL; + }; + + struct Varyings + { + float4 positionHCS : SV_POSITION; + half3 normal : TEXCOORD0; + }; + + Varyings vert(Attributes IN) + { + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + // Using the TransformObjectToWorldNormal function to transform the normals + // from object to world space. This function is from the + // SpaceTransforms.hlsl file, which is referenced in Core.hlsl. + OUT.normal = TransformObjectToWorldNormal(IN.normal); + return OUT; + } + + half4 frag(Varyings IN) : SV_Target + { + half4 color = 0; + // IN.normal is a 3D vector. Each vector component has the range -1..1. + // To show all vector elements as color, including the negative values, + // compress each value into the range 0..1. + color.rgb = IN.normal * 0.5 + 0.5; + return color; + } + ENDHLSL + } + } +} +``` diff --git a/com.unity.render-pipelines.universal/Documentation~/writing-custom-shaders-urp.md b/com.unity.render-pipelines.universal/Documentation~/writing-custom-shaders-urp.md new file mode 100644 index 00000000000..f741fbaceda --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/writing-custom-shaders-urp.md @@ -0,0 +1,14 @@ +# Writing custom shaders + +This section contains guidelines that help you to get started with writing shaders for Universal Render Pipeline (URP). + +The section contains the following topics: + +* [Creating a sample scene](writing-shaders-urp-basic-prerequisites.md) +* [URP basic unlit shader](writing-shaders-urp-basic-unlit-structure.md) + * [Basic ShaderLab structure](writing-shaders-urp-basic-unlit-structure.md#basic-shaderlab-structure) +* [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) + +Each example covers some extra information compared to the basic shader example. If you are new to writing shaders using Unity's ShaderLab language, consider going through the sections in the order of appearance on this page. diff --git a/com.unity.render-pipelines.universal/Documentation~/writing-custom-shaders.md b/com.unity.render-pipelines.universal/Documentation~/writing-custom-shaders.md new file mode 100644 index 00000000000..d2b1b8a2b65 --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/writing-custom-shaders.md @@ -0,0 +1,6 @@ +# Writing custom shaders + +This section contains guidelines on writing custom URP-compatible shaders. + +* [Shader structure](shader-structure.md) +* [URP unlit shader examples](urp-shader-examples.md) diff --git a/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-basic-prerequisites.md b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-basic-prerequisites.md new file mode 100644 index 00000000000..70de16018ad --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-basic-prerequisites.md @@ -0,0 +1,15 @@ +# Creating a sample scene + +To follow the examples in this section: + +1. Install URP into an existing Unity project, or create a new project using the [__Universal Project Template__](https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@8.0/manual/creating-a-new-project-with-urp.html). + +2. In the sample Scene, create a GameObject to test the shaders on; for example, a capsule. + + ![Sample GameObject](Images/shader-examples/urp-template-sample-object.png) + +3. Create a new Material and assign it to the capsule. + +4. Create a new Shader asset and assign it to the Material of the capsule. When following an example, open the shader asset to edit the Unity shader source file. Replace the code in the source file with the code in the example. + +To start writing URP shaders, continue to section [URP unlit basic shader](writing-shaders-urp-basic-unlit-structure.md). diff --git a/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-basic-unlit-structure.md b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-basic-unlit-structure.md new file mode 100644 index 00000000000..025f0dae495 --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-basic-unlit-structure.md @@ -0,0 +1,177 @@ +# URP unlit basic shader + +This example shows a basic URP-compatible shader. This shader fills the mesh shape with a color predefined in the shader code. + +To see the shader in action, copy and paste the following ShaderLab code into the Shader asset. + +```c++ +// This shader fills the mesh shape with a color predefined in the code. +Shader "Example/URPUnlitShaderBasic" +{ + // The properties block of the Unity shader. In this example this block is empty + // because the output color is predefined in the fragment shader code. + Properties + { } + + // The SubShader block containing the Shader code. + SubShader + { + // SubShader Tags define when and under which conditions a SubShader block or + // a pass is executed. + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" } + + Pass + { + // The HLSL code block. Unity SRP uses the HLSL language. + HLSLPROGRAM + // This line defines the name of the vertex shader. + #pragma vertex vert + // This line defines the name of the fragment shader. + #pragma fragment frag + + // The Core.hlsl file contains definitions of frequently used HLSL + // macros and functions, and also contains #include references to other + // HLSL files (for example, Common.hlsl, SpaceTransforms.hlsl, etc.). + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + // The structure definition defines which variables it contains. + // This example uses the Attributes structure as an input structure in + // the vertex shader. + struct Attributes + { + // The positionOS variable contains the vertex positions in object + // space. + float4 positionOS : POSITION; + }; + + struct Varyings + { + // The positions in this struct must have the SV_POSITION semantic. + float4 positionHCS : SV_POSITION; + }; + + // The vertex shader definition with properties defined in the Varyings + // structure. The type of the vert function must match the type (struct) + // that it returns. + Varyings vert(Attributes IN) + { + // Declaring the output object (OUT) with the Varyings struct. + Varyings OUT; + // The TransformObjectToHClip function transforms vertex positions + // from object space to homogenous space + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + // Returning the output. + return OUT; + } + + // The fragment shader definition. + half4 frag() : SV_Target + { + // Defining the color variable and returning it. + half4 customColor; + customColor = half4(0.5, 0, 0, 1); + return customColor; + } + ENDHLSL + } + } +} +``` + +The fragment shader colors the GameObject dark red (RGB value (0.5, 0, 0)). + +![The shader paints the GameObject dark red](Images/shader-examples/unlit-shader-tutorial-basic-hardcoded-color.png) + +The following section introduces you to the structure of this basic Unity shader. + + + +## Basic ShaderLab structure + +Unity shaders are written in a Unity-specific language called [ShaderLab](https://docs.unity3d.com/Manual/SL-Shader.html). + +The Unity shader in this example has the following blocks: + +* [Shader](#shader) +* [Properties](#properties) +* [SubShader](#subshader) +* [Pass](#pass) +* [HLSLPROGRAM](#hlsl) + + + +### Shader block + +ShaderLab code starts with the `Shader` declaration. + +```c++ +Shader "Example/URPUnlitShaderBasic" +``` + +The path in this declaration determines the display name and location of the Unity 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) + + + +### Properties block + +The [Properties](https://docs.unity3d.com/Manual/SL-Properties.html) block contains the declarations of properties that users can set in the Inspector window on a Material. + +In this example, the Properties block is empty, because this Unity shader does not expose any Material properties that a user can define. + +### SubShader block + +A Unity shader source file contains one or more [SubShader](https://docs.unity3d.com/Manual/SL-SubShader.html) blocks. When rendering a mesh, Unity selects the first SubShader that is compatible with the GPU on the target device. + +A SubShader block can optionally contain a SubShader Tags block. Use the `Tags` keyword to declare a SubShader Tags block. + +``` +Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" } +``` + +A SubShader Tag with a name of `RenderPipeline` tells Unity which render pipelines to use this SubShader with, and the value of `UniversalPipeline` indicates that Unity should use this SubShader with URP. + +For more information on SubShader Tags, see [ShaderLab: SubShader Tags](https://docs.unity3d.com/Manual/SL-SubShaderTags.html). + +### Pass block + +In this example, there is one Pass block that contains the HLSL program code. For more information on Pass blocks, see [ShaderLab: Pass](https://docs.unity3d.com/Manual/SL-Pass.html). + +### HLSLPROGRAM block + +This block contains the HLSL program code. + +> **NOTE**: URP shaders support only the HLSL language. + +This block contains the `#include` declaration with the reference to the `Core.hlsl` file. + +```c++ +#include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" +``` + +The `Core.hlsl` file contains definitions of frequently used HLSL macros and functions, and also contains #include references to other HLSL files (for example, `Common.hlsl` and `SpaceTransforms.hlsl`). + +For example, the vertex shader in the HLSL code uses the `TransformObjectToHClip` function from the `SpaceTransforms.hlsl` file. The function transforms vertex positions from object space to homogenous space: + +```c++ +Varyings vert(Attributes IN) +{ + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + return OUT; +} +``` + +The fragment shader in this basic HLSL code outputs the single color predefined in the code: + +```c++ +half4 frag() : SV_Target +{ + half4 customColor; + customColor = half4(0.5, 0, 0, 1); + return customColor; +} +``` + +Section [URP unlit shader with color input](writing-shaders-urp-unlit-color.md) shows how to add the editable color property in the Inspector window on the Material. diff --git a/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-color.md b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-color.md new file mode 100644 index 00000000000..28b68c53eda --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-color.md @@ -0,0 +1,111 @@ +# URP unlit shader with color input + +The Unity shader in this example adds the __Base Color__ property to the Material. You can select the color using that property and the shader fills the mesh shape with the color. + +Use the Unity shader source file from section [URP unlit basic shader](writing-shaders-urp-basic-unlit-structure.md) and make the following changes to the ShaderLab code: + +1. Add the `_BaseColor` property definition to the Properties block: + + ```c++ + Properties + { + _BaseColor("Base Color", Color) = (1, 1, 1, 1) + } + ``` + + This declaration adds the `_BaseColor` property with the label __Base Color__ to the Material: + + ![Base Color property on a Material](Images/shader-examples/urp-material-prop-base-color.png) + + The `_BaseColor` property name is a reserved name. When you declare a property with this name, Unity uses this property as the [main color](https://docs.unity3d.com/ScriptReference/Material-color.html) of the Material. + +2. When you declare a property in the Properties block, you also need to declare it in the HLSL code. + + > __NOTE__: To ensure that the Unity shader is SRP Batcher compatible, declare all Material properties inside a single `CBUFFER` block with the name `UnityPerMaterial`. For more information on the SRP Batcher, see the page [Scriptable Render Pipeline (SRP) Batcher](https://docs.unity3d.com/Manual/SRPBatcher.html). + + Add the following code before the vertex shader: + + ```c++ + CBUFFER_START(UnityPerMaterial) + half4 _BaseColor; + CBUFFER_END + ``` + +3. Change the code in the fragment shader so that it returns the `_BaseColor` property. + + ```c++ + half4 frag() : SV_Target + { + return _BaseColor; + } + ``` + +Now you can select the color in the **Base Color** field in the Inspector window. The fragment shader fills the mesh with the color you select. + +![Base Color field on a Material](Images/shader-examples/unlit-shader-tutorial-color-field-with-scene.png) + +Below is the complete ShaderLab code for this example. + +```c++ +// This shader fills the mesh shape with a color that a user can change using the +// Inspector window on a Material. +Shader "Example/URPUnlitShaderColor" +{ + // The _BaseColor variable is visible in the Material's Inspector, as a field + // called Base Color. You can use it to select a custom color. This variable + // has the default value (1, 1, 1, 1). + Properties + { + _BaseColor("Base Color", Color) = (1, 1, 1, 1) + } + + SubShader + { + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" } + + Pass + { + HLSLPROGRAM + #pragma vertex vert + #pragma fragment frag + + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + struct Attributes + { + float4 positionOS : POSITION; + }; + + struct Varyings + { + float4 positionHCS : SV_POSITION; + }; + + // To make the Unity shader SRP Batcher compatible, declare all + // properties related to a Material in a a single CBUFFER block with + // the name UnityPerMaterial. + CBUFFER_START(UnityPerMaterial) + // The following line declares the _BaseColor variable, so that you + // can use it in the fragment shader. + half4 _BaseColor; + CBUFFER_END + + Varyings vert(Attributes IN) + { + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + return OUT; + } + + half4 frag() : SV_Target + { + // Returning the _BaseColor value. + return _BaseColor; + } + ENDHLSL + } + } +} +``` + +Section [Drawing a texture](writing-shaders-urp-unlit-texture.md) shows how to draw a texture on the mesh. diff --git a/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-normals.md b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-normals.md new file mode 100644 index 00000000000..d32cadba63e --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-normals.md @@ -0,0 +1,123 @@ +# Visualizing normal vectors + +The Unity shader in this example visualizes the normal vector values on the mesh. + +Use the Unity shader source file from section [URP unlit basic shader](writing-shaders-urp-basic-unlit-structure.md) and make the following changes to the ShaderLab code: + +1. In `struct Attributes`, which is the input structure for the vertex shader in this example, declare the variable containing the normal vector for each vertex. + + ```c++ + struct Attributes + { + float4 positionOS : POSITION; + // Declaring the variable containing the normal vector for each vertex. + half3 normal : NORMAL; + }; + ``` + +2. In `struct Varyings`, which is the input structure for the fragment shader in this example, declare the variable for storing the normal vector values for each fragment: + + ```c++ + struct Varyings + { + float4 positionHCS : SV_POSITION; + // The variable for storing the normal vector values. + half3 normal : TEXCOORD0; + }; + ``` + + This example uses the three components of the normal vector as RGB color values for each fragment. + +3. To render the normal vector values on the mesh, use the following code as the fragment shader: + + ```c++ + half4 frag(Varyings IN) : SV_Target + { + half4 color = 0; + color.rgb = IN.normal; + return color; + } + ``` + +4. Unity renders the normal vector values on the mesh: + + ![Rendering normals without compression](Images/shader-examples/unlit-shader-tutorial-normals-uncompressed.png) + + A part of the capsule is black. This is because in those points, all three components of the normal vector are negative. The next step shows how to render values in those areas as well. + +5. To render negative normal vector components, use the compression technique. To compress the range of normal component values `(-1..1)` to color value range `(0..1)`, change the following line: + + ```c++ + color.rgb = IN.normal; + ``` + + to this line: + + ```c++ + color.rgb = IN.normal * 0.5 + 0.5; + ``` + +Now Unity renders the normal vector values as colors on the mesh. + +![Rendering normals with compression](Images/shader-examples/unlit-shader-tutorial-normals.png) + +Below is the complete ShaderLab code for this example. + +```c++ +// This shader visuzlizes the normal vector values on the mesh. +Shader "Example/URPUnlitShaderNormal" +{ + Properties + { } + + SubShader + { + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" } + + Pass + { + HLSLPROGRAM + #pragma vertex vert + #pragma fragment frag + + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + struct Attributes + { + float4 positionOS : POSITION; + // Declaring the variable containing the normal vector for each + // vertex. + half3 normal : NORMAL; + }; + + struct Varyings + { + float4 positionHCS : SV_POSITION; + half3 normal : TEXCOORD0; + }; + + Varyings vert(Attributes IN) + { + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + // Use the TransformObjectToWorldNormal function to transform the + // normals from object to world space. This function is from the + // SpaceTransforms.hlsl file, which is referenced in Core.hlsl. + OUT.normal = TransformObjectToWorldNormal(IN.normal); + return OUT; + } + + half4 frag(Varyings IN) : SV_Target + { + half4 color = 0; + // IN.normal is a 3D vector. Each vector component has the range + // -1..1. To show all vector elements as color, including the + // negative values, compress each value into the range 0..1. + color.rgb = IN.normal * 0.5 + 0.5; + return color; + } + ENDHLSL + } + } +} +``` diff --git a/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-texture.md b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-texture.md new file mode 100644 index 00000000000..2b770783bee --- /dev/null +++ b/com.unity.render-pipelines.universal/Documentation~/writing-shaders-urp-unlit-texture.md @@ -0,0 +1,145 @@ +# Drawing a texture + +The Unity shader in this example draws a texture on the mesh. + +Use the Unity shader source file from section [URP unlit shader with color input](writing-shaders-urp-unlit-color.md) and make the following changes to the ShaderLab code: + +1. In the Properties block, replace the existing code with the `_BaseMap` property definition. + + ```c++ + Properties + { + _BaseMap("Base Map", 2D) = "white" + } + ``` + + When you declare a texture property in the Properties block, Unity adds the `_BaseMap` property with the label __Base Map__ to the Material, and adds the Tiling and the Offset controls. + + !["Texture property with Tiling and Offset controls"](Images/shader-examples/unlit-shader-tutorial-texture-property-in-inspector.png) + + The `_BaseMap` property name is a reserved name. When you declare a property with this name, Unity uses this property as the [main texture](https://docs.unity3d.com/ScriptReference/Material-mainTexture.html) of the Material. + +2. In `struct Attributes` and `struct Varyings`, add the `uv` variable for the UV coordinates on the texture: + + ```c++ + float2 uv : TEXCOORD0; + ``` + +3. Define the texture as a 2D texture and specify a sampler for it. Add the following lines before the CBUFFER block: + + ```c++ + TEXTURE2D(_BaseMap); + SAMPLER(sampler_BaseMap); + ``` + + The TEXTURE2D and the SAMPLER macros are defined in one of the files referenced in `Core.hlsl`. + +4. For tiling and offset to work, it's necessary to declare the texture property with the `_ST` suffix in the 'CBUFFER' block. The `_ST` suffix is necessary because some macros (for example, `TRANSFORM_TEX`) use it. + + > __NOTE__: To ensure that the Unity shader is SRP Batcher compatible, declare all Material properties inside a single `CBUFFER` block with the name `UnityPerMaterial`. For more information on the SRP Batcher, see the page [Scriptable Render Pipeline (SRP) Batcher](https://docs.unity3d.com/Manual/SRPBatcher.html). + + ```c++ + CBUFFER_START(UnityPerMaterial) + float4 _BaseMap_ST; + CBUFFER_END + ``` + +5. To apply the tiling and offset transformation, add the following line in the vertex shader: + + ```c++ + OUT.uv = TRANSFORM_TEX(IN.uv, _BaseMap); + ``` + + The `TRANSFORM_TEX` macro is defined in the `Macros.hlsl` file. The `#include` declaration contains a reference to that file. + +6. In the fragment shader, use the `SAMPLE_TEXTURE2D` macro to sample the texture: + + ```c++ + half4 frag(Varyings IN) : SV_Target + { + half4 color = SAMPLE_TEXTURE2D(_BaseMap, sampler_BaseMap, IN.uv); + return color; + } + ``` + +Now you can select a texture in the __Base Map__ field in the Inspector window. The shader draws that texture on the mesh. + +![Base Map texture on a Material](Images/shader-examples/unlit-shader-tutorial-texture-with-scene.png) + +Below is the complete ShaderLab code for this example. + +```c++ +// This shader draws a texture on the mesh. +Shader "Example/URPUnlitShaderTexture" +{ + // The _BaseMap variable is visible in the Material's Inspector, as a field + // called Base Map. + Properties + { + _BaseMap("Base Map", 2D) = "white" + } + + SubShader + { + Tags { "RenderType" = "Opaque" "RenderPipeline" = "UniversalPipeline" } + + Pass + { + HLSLPROGRAM + #pragma vertex vert + #pragma fragment frag + + #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl" + + struct Attributes + { + float4 positionOS : POSITION; + // The uv variable contains the UV coordinate on the texture for the + // given vertex. + float2 uv : TEXCOORD0; + }; + + struct Varyings + { + float4 positionHCS : SV_POSITION; + // The uv variable contains the UV coordinate on the texture for the + // given vertex. + float2 uv : TEXCOORD0; + }; + + // This macro declares _BaseMap as a Texture2D object. + TEXTURE2D(_BaseMap); + // This macro declares the sampler for the _BaseMap texture. + SAMPLER(sampler_BaseMap); + + CBUFFER_START(UnityPerMaterial) + // The following line declares the _BaseMap_ST variable, so that you + // can use the _BaseMap variable in the fragment shader. The _ST + // suffix is necessary for the tiling and offset function to work. + float4 _BaseMap_ST; + CBUFFER_END + + Varyings vert(Attributes IN) + { + Varyings OUT; + OUT.positionHCS = TransformObjectToHClip(IN.positionOS.xyz); + // The TRANSFORM_TEX macro performs the tiling and offset + // transformation. + OUT.uv = TRANSFORM_TEX(IN.uv, _BaseMap); + return OUT; + } + + half4 frag(Varyings IN) : SV_Target + { + // The SAMPLE_TEXTURE2D marco samples the texture with the given + // sampler. + half4 color = SAMPLE_TEXTURE2D(_BaseMap, sampler_BaseMap, IN.uv); + return color; + } + ENDHLSL + } + } +} +``` + +Section [Visualizing normal vectors](writing-shaders-urp-unlit-normals.md) shows how to visualize normal vectors on the mesh.