Library/PackageCache/com.unity.postprocessing@2.1.2/Documentation~/Writing-Custom-Effects.md

   1 # Writing Custom Effects
   2
   3 This framework allows you to write custom post-processing effects and plug them to the stack without having to modify the codebase. Of course, all effects written against the framework will work out-of-the-box with volume blending, and unless you need loop-dependent features they'll also automatically work with upcoming  [Scriptable Render Pipelines](https://github.com/Unity-Technologies/ScriptableRenderLoop)!
   4
   5 Let's write a very simple grayscale effect to show it off.
   6
   7 Custom effects need a minimum of two files: a C# and a HLSL source files (note that HLSL gets cross-compiled to GLSL, Metal and others API by Unity so it doesn't mean it's restricted to DirectX).
   8
   9 > **Note:** this quick-start guide requires moderate knowledge of C# and shader programming. We won't go over every detail here, consider it as an overview more than an in-depth tutorial.
  10
  11 ## C#
  12
  13 Full code listing:
  14
  15 ```csharp
  16 using System;
  17 using UnityEngine;
  18 using UnityEngine.Rendering.PostProcessing;
  19
  20 [Serializable]
  21 [PostProcess(typeof(GrayscaleRenderer), PostProcessEvent.AfterStack, "Custom/Grayscale")]
  22 public sealed class Grayscale : PostProcessEffectSettings
  23 {
  24     [Range(0f, 1f), Tooltip("Grayscale effect intensity.")]
  25     public FloatParameter blend = new FloatParameter { value = 0.5f };
  26 }
  27
  28 public sealed class GrayscaleRenderer : PostProcessEffectRenderer<Grayscale>
  29 {
  30     public override void Render(PostProcessRenderContext context)
  31     {
  32         var sheet = context.propertySheets.Get(Shader.Find("Hidden/Custom/Grayscale"));
  33         sheet.properties.SetFloat("_Blend", settings.blend);
  34         context.command.BlitFullscreenTriangle(context.source, context.destination, sheet, 0);
  35     }
  36 }
  37 ```
  38
  39 > **Important**: this code has to be stored in a file named `Grayscale.cs`. Because of how serialization works in Unity, you have to make sure that the file is named after your settings class name or it won't be serialized properly.
  40
  41 We need two classes, one to store settings (data) and another one to handle the rendering part (logic).
  42
  43 ### Settings
  44
  45 The settings class holds the data for our effect. These are all the user-facing fields you'll see in the volume inspector.
  46
  47 ```csharp
  48 [Serializable]
  49 [PostProcess(typeof(GrayscaleRenderer), PostProcessEvent.AfterStack, "Custom/Grayscale")]
  50 public sealed class Grayscale : PostProcessEffectSettings
  51 {
  52     [Range(0f, 1f), Tooltip("Grayscale effect intensity.")]
  53     public FloatParameter blend = new FloatParameter { value = 0.5f };
  54 }
  55 ```
  56
  57 First, you need to make sure this class extends `PostProcessEffectSettings` and can be serialized, so don't forget the `[Serializable]` attribute!
  58
  59 Second, you'll need to tell Unity that this is a class that holds post-processing data. That's what the `[PostProcess()]` attribute is for. First parameter links the settings to a renderer (more about that in the next section). Second parameter is the injection point for the effect. Right now you have 3 of those available:
  60
  61 - `BeforeTransparent`: the effect will only be applied to opaque objects before the transparent pass is done.
  62 - `BeforeStack`: the effect will be applied before the built-in stack kicks-in. That includes anti-aliasing, depth-of-field, tonemapping etc.
  63 - `AfterStack`: the effect will be applied after the builtin stack and before FXAA (if it's enabled) & final-pass dithering.
  64
  65 The third parameter is the menu entry for the effect. You can use `/` to create sub-menu categories.
  66
  67 Finally, there's an optional fourth parameter `allowInSceneView` which, as its name suggests, enables the effect in the scene view or not. It's set to `true` by default but you may want to disable it for temporal effects or effects that make level editing hard.
  68
  69 For parameters themselves you can use any type you need, but if you want these to be overridable and blendable in volumes you'll have to use boxed fields. In our case we'll simply add a `FloatParameter` with a fixed range going from `0` to `1`. You can get a full list of builtin parameter classes by browsing through the `ParameterOverride.cs` source file in `/PostProcessing/Runtime/`, or you can create your own quite easily by following the way it's done in that same source file.
  70
  71 Note that you can also override the `IsEnabledAndSupported()` method of `PostProcessEffectSettings` to set your own requirements for the effect (in case it requires specific hardware) or even to silently disable the effect until a condition is met. For example, in our case we could automatically disable the effect if the blend parameter is `0` like this:
  72
  73 ```csharp
  74 public override bool IsEnabledAndSupported(PostProcessRenderContext context)
  75 {
  76     return enabled.value
  77         && blend.value > 0f;
  78 }
  79 ```
  80
  81 That way the effect won't be executed at all unless `blend > 0`.
  82
  83 ### Renderer
  84
  85 Let's look at the rendering logic now. Our renderer extends `PostProcessEffectRenderer<T>`, with `T` being the settings type to attach to this renderer.
  86
  87 ```csharp
  88 public sealed class GrayscaleRenderer : PostProcessEffectRenderer<Grayscale>
  89 {
  90     public override void Render(PostProcessRenderContext context)
  91     {
  92         var sheet = context.propertySheets.Get(Shader.Find("Hidden/Custom/Grayscale"));
  93         sheet.properties.SetFloat("_Blend", settings.blend);
  94         context.command.BlitFullscreenTriangle(context.source, context.destination, sheet, 0);
  95     }
  96 }
  97 ```
  98
  99 Everything happens in the `Render()` method that takes a `PostProcessRenderContext` as parameter. This context holds useful data that you can use and is passed around effects when they are rendered. Look into `/PostProcessing/Runtime/PostProcessRenderContext.cs` for a list of what's available (the file is heavily commented).
 100
 101 `PostProcessEffectRenderer<T>` also have a few other methods you can override, such as:
 102
 103 - `void Init()`: called when the renderer is created.
 104 - `DepthTextureMode GetLegacyCameraFlags()`: used to set camera flags and request depth map, motion vectors, etc.
 105 - `void ResetHistory()`: called when a "reset history" event is dispatched. Mainly used for temporal effects to clear history buffers and whatnot.
 106 - `void Release()`: called when the renderer is destroyed. Do your cleanup there if you need it.
 107
 108 Our effect is quite simple. We need two things:
 109
 110 - Send the `blend` parameter value to the shader.
 111 - Blit a fullscreen pass with the shader to a destination using our source image as an input.
 112
 113 Because we only use command buffers, the system relies on `MaterialPropertyBlock` to store shader data. You don't need to create those yourself as the framework does automatic pooling for you to save time and make sure performances are optimal. So we'll just request a `PropertySheet` for our shader and set the uniform in it.
 114
 115 Finally we use the `CommandBuffer` provided by the context to blit a fullscreen pass with our source, destination, sheet and pass number.
 116
 117 And that's it for the C# part.
 118
 119 ## Shader
 120
 121 Writing custom effect shaders is fairly straightforward as well, but there are a few things you should know before you get to it. This framework makes heavy use of macros to abstract platform differences and make your life easier. Compatibility is key, even more so with the upcoming Scriptable Render Pipelines.
 122
 123 Full code listing:
 124
 125 ```hlsl
 126 Shader "Hidden/Custom/Grayscale"
 127 {
 128     HLSLINCLUDE
 129
 130         #include "Packages/com.unity.postprocessing/PostProcessing/Shaders/StdLib.hlsl"
 131
 132         TEXTURE2D_SAMPLER2D(_MainTex, sampler_MainTex);
 133         float _Blend;
 134
 135         float4 Frag(VaryingsDefault i) : SV_Target
 136         {
 137             float4 color = SAMPLE_TEXTURE2D(_MainTex, sampler_MainTex, i.texcoord);
 138             float luminance = dot(color.rgb, float3(0.2126729, 0.7151522, 0.0721750));
 139             color.rgb = lerp(color.rgb, luminance.xxx, _Blend.xxx);
 140             return color;
 141         }
 142
 143     ENDHLSL
 144
 145     SubShader
 146     {
 147         Cull Off ZWrite Off ZTest Always
 148
 149         Pass
 150         {
 151             HLSLPROGRAM
 152
 153                 #pragma vertex VertDefault
 154                 #pragma fragment Frag
 155
 156             ENDHLSL
 157         }
 158     }
 159 }
 160 ```
 161
 162 First thing to note: we don't use `CG` blocks anymore. If future compatibility with Scriptable Render Pipelines is important to you, do not use them as they'll break the shader when switching over because `CG` blocks add hidden code you don't want to the shader. Instead, use `HLSL` blocks.
 163
 164 At a minimum you'll need to include `StdLib.hlsl`. This holds pre-configured vertex shaders and varying structs (`VertDefault`, `VaryingsDefault`) and most of the data you need to write common effects.
 165
 166 Texture declaration is done using macros. To get a list of available macros we recommend you look into one of the api files in `/PostProcessing/Shaders/API/`.
 167
 168 Other than that, the rest is standard shader code. Here we compute the luminance for the current pixel, we lerp the pixel color with the luminance using the `_Blend` uniform and we return the result.
 169
 170 > **Important:** if the shader is never referenced in any of your scenes it won't get built and the effect will not work when running the game outside of the editor. Either add it to a [Resources folder](https://docs.unity3d.com/Manual/LoadingResourcesatRuntime.html) or put it in the **Always Included Shaders** list in `Edit -> Project Settings -> Graphics`.
 171
 172 ## Effect ordering
 173
 174 Builtin effects are automatically ordered, but what about custom effects? As soon as you create a new effect or import it into your project it'll be added to the `Custom Effect Sorting` lists in the `Post Process Layer` component on your camera(s).
 175
 176 > **TODO:** editor UI screenshot
 177
 178 They will be pre-sorted by injection point but you can re-order these at will. The order is per-layer, which means you can use different ordering schemes per-camera.
 179
 180 ## Custom editor
 181
 182 By default editors for settings classes are automatically created for you. But sometimes you'll want more control over how fields are displayed. Like classic Unity components, you have the ability to create custom editors.
 183
 184 > **Important:** like classic editors, you'll have to put these in an `Editor` folder.
 185
 186 If we were to replicate the default editor for our `Grayscale` effect, it would look like this:
 187
 188 ```csharp
 189 using UnityEngine.Rendering.PostProcessing;
 190 using UnityEditor.Rendering.PostProcessing;
 191
 192 [PostProcessEditor(typeof(Grayscale))]
 193 public sealed class GrayscaleEditor : PostProcessEffectEditor<Grayscale>
 194 {
 195     SerializedParameterOverride m_Blend;
 196
 197     public override void OnEnable()
 198     {
 199         m_Blend = FindParameterOverride(x => x.blend);
 200     }
 201
 202     public override void OnInspectorGUI()
 203     {
 204         PropertyField(m_Blend);
 205     }
 206 }
 207 ```
 208
 209 ## Additional notes
 210
 211 For performance reasons, FXAA expects the LDR luminance value of each pixel to be stored in the alpha channel of its source target. If you need FXAA and wants to inject custom effects at the `AfterStack` injection point, make sure that the last executed effect contains LDR luminance in the alpha channel (or simply copy alpha from the incoming source). If it's not FXAA won't work correctly.