From f494d0d55897309b31452b26c308bedd4b9efc7d Mon Sep 17 00:00:00 2001 From: Reach Platform Support Date: Wed, 1 Oct 2025 23:44:06 +0000 Subject: [PATCH 01/28] [Port] [6000.0] Move the CompositionMode.BeforeColorPyramidAfterClouds to happen after water --- .../Runtime/RenderPipeline/HDRenderPipeline.RenderGraph.cs | 6 +++--- .../RenderPipeline/LineRendering/Core/LineRendering.cs | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/HDRenderPipeline.RenderGraph.cs b/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/HDRenderPipeline.RenderGraph.cs index 60ef90d321a..ded68994506 100644 --- a/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/HDRenderPipeline.RenderGraph.cs +++ b/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/HDRenderPipeline.RenderGraph.cs @@ -1669,9 +1669,6 @@ TextureHandle RenderTransparency(RenderGraph renderGraph, // Combine volumetric clouds with prerefraction transparents m_VolumetricClouds.CombineVolumetricClouds(renderGraph, hdCamera, colorBuffer, prepassOutput.resolvedDepthBuffer, transparentPrepass, ref opticalFogTransmittance); - // Compose the lines if the user wants lines in the color pyramid (refraction), but after clouds. - ComposeLines(renderGraph, hdCamera, colorBuffer, prepassOutput.resolvedDepthBuffer, prepassOutput.motionVectorsBuffer, (int)LineRendering.CompositionMode.BeforeColorPyramidAfterClouds); - var preRefractionList = renderGraph.CreateRendererList(PrepareForwardTransparentRendererList(cullingResults, hdCamera, true)); var refractionList = renderGraph.CreateRendererList(PrepareForwardTransparentRendererList(cullingResults, hdCamera, false)); @@ -1683,6 +1680,9 @@ TextureHandle RenderTransparency(RenderGraph renderGraph, // If required, render the water debug view m_WaterSystem.RenderWaterDebug(renderGraph, hdCamera, colorBuffer, prepassOutput.depthBuffer, transparentPrepass.waterGBuffer); + // Compose the lines if the user wants lines in the color pyramid (refraction), but after clouds. + ComposeLines(renderGraph, hdCamera, colorBuffer, prepassOutput.resolvedDepthBuffer, prepassOutput.motionVectorsBuffer, (int)LineRendering.CompositionMode.BeforeColorPyramidAfterClouds); + bool ssmsEnabled = Fog.IsMultipleScatteringEnabled(hdCamera, out float fogMultipleScatteringIntensity); if (hdCamera.frameSettings.IsEnabled(FrameSettingsField.Refraction) || hdCamera.IsSSREnabled() || hdCamera.IsSSREnabled(true) || hdCamera.IsSSGIEnabled() || ssmsEnabled) { diff --git a/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/LineRendering/Core/LineRendering.cs b/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/LineRendering/Core/LineRendering.cs index abbfedf47e6..96dd1f45949 100644 --- a/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/LineRendering/Core/LineRendering.cs +++ b/Packages/com.unity.render-pipelines.high-definition/Runtime/RenderPipeline/LineRendering/Core/LineRendering.cs @@ -23,7 +23,7 @@ public enum CompositionMode { /// Composition will occur before the color pyramid is generated. BeforeColorPyramid = 0, - /// Composition will occur before the color pyramid is generated but after clouds are composited. + /// Composition will occur before the color pyramid is generated but after clouds and water are composited. BeforeColorPyramidAfterClouds = 3, /// Composition will occur after temporal anti-aliasing. AfterTemporalAntialiasing = 1, From ef0b790e10e4a5bf906fef07921ca3dc173c2267 Mon Sep 17 00:00:00 2001 From: Reach Platform Support Date: Wed, 1 Oct 2025 23:44:06 +0000 Subject: [PATCH 02/28] [Port] [6000.0] docg-7282: Add Matrix Data types --- .../Documentation~/Property-Types.md | 24 +++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/Packages/com.unity.shadergraph/Documentation~/Property-Types.md b/Packages/com.unity.shadergraph/Documentation~/Property-Types.md index 30849a76d05..164b95111e6 100644 --- a/Packages/com.unity.shadergraph/Documentation~/Property-Types.md +++ b/Packages/com.unity.shadergraph/Documentation~/Property-Types.md @@ -193,3 +193,27 @@ Defines a **Boolean** value. Displays a **ToggleUI** field in the material inspe | Field | Type | Description | |:-------------|:------|:------------| | Default | Boolean | The default value of the [Property](https://docs.unity3d.com/Manual/SL-Properties.html). | + +## Matrix 2x2 + +Defines a Matrix 2. Matrices do not display in the **Inspector** window of the material. + +| Field | Type | +|:--------|:---------| +| Default | Matrix 2 | + +## Matrix 3x3 + +Defines a Matrix 3 value. Can't be displayed in the material inspector. + +| Field | Type | +|:--------|:---------| +| Default | Matrix 3 | + +## Matrix 4x4 + +Defines a Matrix 4 value. Can't be displayed in the material inspector. + +| Field | Type | +|:--------|:---------| +| Default | Matrix 4 | From b07c9b8a4e665fc115d9a2288ac00926d2523be9 Mon Sep 17 00:00:00 2001 From: Reach Platform Support Date: Thu, 2 Oct 2025 10:07:26 +0000 Subject: [PATCH 03/28] [Port] [6000.0] Fix Android glitch by using a different overload for SetRenderTarget --- .../Runtime/Passes/FinalBlitPass.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packages/com.unity.render-pipelines.universal/Runtime/Passes/FinalBlitPass.cs b/Packages/com.unity.render-pipelines.universal/Runtime/Passes/FinalBlitPass.cs index edfe6fbb85c..af8d08d62cc 100644 --- a/Packages/com.unity.render-pipelines.universal/Runtime/Passes/FinalBlitPass.cs +++ b/Packages/com.unity.render-pipelines.universal/Runtime/Passes/FinalBlitPass.cs @@ -212,7 +212,7 @@ public override void Execute(ScriptableRenderContext context, ref RenderingData loadAction = RenderBufferLoadAction.Load; #endif - CoreUtils.SetRenderTarget(renderingData.commandBuffer, cameraTargetHandle, loadAction, RenderBufferStoreAction.Store, ClearFlag.None, Color.clear); + CoreUtils.SetRenderTarget(renderingData.commandBuffer, cameraTargetHandle.nameID, loadAction, RenderBufferStoreAction.Store, ClearFlag.None, Color.clear); ExecutePass(CommandBufferHelpers.GetRasterCommandBuffer(renderingData.commandBuffer), m_PassData, m_Source, cameraTargetHandle, cameraData); cameraData.renderer.ConfigureCameraTarget(cameraTargetHandle, cameraTargetHandle); } From c585ad8a2233584822420acbb49d26ab4fe5528b Mon Sep 17 00:00:00 2001 From: Reach Platform Support Date: Thu, 2 Oct 2025 10:07:27 +0000 Subject: [PATCH 04/28] [Port] [6000.0] [VFX] Forbid dragging a subgraph block onto the graph directly, only allow on compatible contexts --- .../Editor/GraphView/Views/VFXView.cs | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Packages/com.unity.visualeffectgraph/Editor/GraphView/Views/VFXView.cs b/Packages/com.unity.visualeffectgraph/Editor/GraphView/Views/VFXView.cs index dc158602505..2cc374db84d 100644 --- a/Packages/com.unity.visualeffectgraph/Editor/GraphView/Views/VFXView.cs +++ b/Packages/com.unity.visualeffectgraph/Editor/GraphView/Views/VFXView.cs @@ -3133,6 +3133,7 @@ internal DragAndDropVisualMode GetDragAndDropModeForVisualEffectObject(VisualEff if (visualEffectObject != null && visualEffectObject != controller.model.visualEffectObject) { var isOperator = visualEffectObject is VisualEffectSubgraphOperator; + var isBlock = visualEffectObject is VisualEffectSubgraphBlock; var graph = visualEffectObject.GetResource().GetOrCreateGraph(); graph.BuildSubgraphDependencies(); var draggedObjectDependencies = graph.subgraphDependencies; @@ -3143,7 +3144,7 @@ internal DragAndDropVisualMode GetDragAndDropModeForVisualEffectObject(VisualEff return DragAndDropVisualMode.Rejected; } - var vfxIntoVfx = !isOperator && !controller.model.isSubgraph; // dropping a vfx into a vfx + var vfxIntoVfx = !isOperator && !isBlock && !controller.model.isSubgraph; // dropping a vfx into a vfx return vfxIntoVfx || isOperator ? DragAndDropVisualMode.Move @@ -3270,13 +3271,12 @@ void OnDragPerform(DragPerformEvent e) { VFXContextType contextKind = subgraphBlock.GetResource().GetOrCreateGraph().children.OfType().First().compatibleContextType; VFXModelDescriptor contextType = VFXLibrary.GetContexts().First(t => t.modelType == typeof(VFXBasicInitialize)); - var model = (VFXContext)contextType.CreateInstance(); if ((contextKind & VFXContextType.Update) == VFXContextType.Update) contextType = VFXLibrary.GetContexts().First(t => t.modelType == typeof(VFXBasicUpdate)); else if ((contextKind & VFXContextType.Spawner) == VFXContextType.Spawner) contextType = VFXLibrary.GetContexts().First(t => t.modelType == typeof(VFXBasicSpawner)); else if ((contextKind & VFXContextType.Output) == VFXContextType.Output) - contextType = VFXLibrary.GetContexts().First(t => t.modelType == typeof(VFXPlanarPrimitiveOutput) && model.taskType == VFXTaskType.ParticleQuadOutput); + contextType = VFXLibrary.GetContexts().First(t => t.modelType == typeof(VFXPlanarPrimitiveOutput) && t.model.taskType == VFXTaskType.ParticleQuadOutput); UpdateSelectionWithNewNode(); VFXContext ctx = controller.AddVFXContext(mousePosition, contextType.variant); From 0ed3c62103e7ecbe053d05bcfd0c7b9b8877cfee Mon Sep 17 00:00:00 2001 From: Reach Platform Support Date: Thu, 2 Oct 2025 14:24:02 +0000 Subject: [PATCH 05/28] [Port] [6000.0] docg-7352: Fix World to Screen code --- Packages/com.unity.shadergraph/Documentation~/Transform-Node.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packages/com.unity.shadergraph/Documentation~/Transform-Node.md b/Packages/com.unity.shadergraph/Documentation~/Transform-Node.md index 98e7e15a67d..bed7279fbed 100644 --- a/Packages/com.unity.shadergraph/Documentation~/Transform-Node.md +++ b/Packages/com.unity.shadergraph/Documentation~/Transform-Node.md @@ -75,7 +75,7 @@ float3 _Transform_Out = GetAbsolutePositionWS(In); **World > Screen** ``` -float4 hclipPosition = TransformWorldToHClipDir(In); +float4 hclipPosition = TransformWorldToHClip(In); float3 screenPos = hclipPosition.xyz / hclipPosition.w; float3 _Transform_Out = float3(screenPos.xy * 0.5 + 0.5, screenPos.z); ``` From 323d6a97bdd94b10d15fc744b3af4088ab8d7edf Mon Sep 17 00:00:00 2001 From: Erik Hakala Date: Thu, 2 Oct 2025 14:24:02 +0000 Subject: [PATCH 06/28] Backport [6000.0] Fix bloom and lens flare on tiny resolutions. --- .../Runtime/Passes/PostProcessPass.cs | 4 +- .../Passes/PostProcessPassRenderGraph.cs | 40 ++++++++++++++++--- 2 files changed, 36 insertions(+), 8 deletions(-) diff --git a/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPass.cs b/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPass.cs index 811586b292d..8d600c9f0ad 100644 --- a/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPass.cs +++ b/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPass.cs @@ -1342,8 +1342,8 @@ void SetupBloom(CommandBuffer cmd, RTHandle source, Material uberMaterial, bool default: throw new System.ArgumentOutOfRangeException(); } - int tw = m_Descriptor.width >> downres; - int th = m_Descriptor.height >> downres; + int tw = Mathf.Max(1, m_Descriptor.width >> downres); + int th = Mathf.Max(1, m_Descriptor.height >> downres); // Determine the iteration count int maxSize = Mathf.Max(tw, th); diff --git a/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPassRenderGraph.cs b/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPassRenderGraph.cs index 6ee0e5c2adf..c3d3776eea9 100644 --- a/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPassRenderGraph.cs +++ b/Packages/com.unity.render-pipelines.universal/Runtime/Passes/PostProcessPassRenderGraph.cs @@ -353,9 +353,9 @@ internal bool Equals(ref BloomMaterialParams other) } } - public void RenderBloomTexture(RenderGraph renderGraph, in TextureHandle source, out TextureHandle destination, bool enableAlphaOutput) + public Vector2Int CalcBloomResolution(Bloom bloom) { - // Start at half-res + // Start at half-res int downres = 1; switch (m_Bloom.downscale.value) { @@ -374,10 +374,26 @@ public void RenderBloomTexture(RenderGraph renderGraph, in TextureHandle source, int tw = Mathf.Max(1, m_Descriptor.width >> downres); int th = Mathf.Max(1, m_Descriptor.height >> downres); + return new Vector2Int(tw, th); + } + + public int CalcBloomMipCount(Bloom bloom, Vector2Int bloomResolution) + { // Determine the iteration count - int maxSize = Mathf.Max(tw, th); + int maxSize = Mathf.Max(bloomResolution.x, bloomResolution.y); int iterations = Mathf.FloorToInt(Mathf.Log(maxSize, 2f) - 1); int mipCount = Mathf.Clamp(iterations, 1, m_Bloom.maxIterations.value); + return mipCount; + } + + public void RenderBloomTexture(RenderGraph renderGraph, in TextureHandle source, out TextureHandle destination, bool enableAlphaOutput) + { + var srcDesc = source.GetDescriptor(renderGraph); + + Vector2Int bloomRes = CalcBloomResolution(m_Bloom); + int mipCount = CalcBloomMipCount(m_Bloom, bloomRes); + int tw = bloomRes.x; + int th = bloomRes.y; // Setup using(new ProfilingScope(ProfilingSampler.Get(URPProfileId.RG_BloomSetup))) @@ -2088,9 +2104,21 @@ public void RenderPostProcessingRenderGraph(RenderGraph renderGraph, ContextCont if (useLensFlareScreenSpace) { - int maxBloomMip = Mathf.Clamp(m_LensFlareScreenSpace.bloomMip.value, 0, m_Bloom.maxIterations.value/2); - bool sameInputOutputTex = maxBloomMip == 0; - BloomTexture = RenderLensFlareScreenSpace(renderGraph, cameraData.camera, in currentSource, _BloomMipUp[0], _BloomMipUp[maxBloomMip], cameraData.xr.enabled, sameInputOutputTex); + // We need to take into account how many valid mips the bloom pass produced. + int bloomMipCount = CalcBloomMipCount(m_Bloom, CalcBloomResolution(m_Bloom)); + int maxBloomMip = Mathf.Clamp(bloomMipCount - 1, 0, m_Bloom.maxIterations.value / 2); + int useBloomMip = Mathf.Clamp(m_LensFlareScreenSpace.bloomMip.value, 0, maxBloomMip); + + TextureHandle bloomMipFlareSource = _BloomMipUp[useBloomMip]; + bool sameBloomInputOutputTex = useBloomMip == 0; + + // Bloom does only the prefilter into MipDown if there's only 1 iteration. + if(bloomMipCount == 1) + { + bloomMipFlareSource = _BloomMipDown[0]; + } + + BloomTexture = RenderLensFlareScreenSpace(renderGraph, cameraData.camera, in currentSource, BloomTexture, bloomMipFlareSource, cameraData.xr.enabled, sameBloomInputOutputTex); } UberPostSetupBloomPass(renderGraph, in BloomTexture, m_Materials.uber); From 88fe2f0de2c1e1e66732d142e6de9ada2abf9cc4 Mon Sep 17 00:00:00 2001 From: Reach Platform Support Date: Thu, 2 Oct 2025 14:24:02 +0000 Subject: [PATCH 07/28] [Port] [6000.0] [HDRP] Fixing script link in Water sample Cave scene --- .../Scenes/Scene Resources/CaveSampleDescription.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Packages/com.unity.render-pipelines.high-definition/Samples~/WaterSamples/Scenes/Scene Resources/CaveSampleDescription.json b/Packages/com.unity.render-pipelines.high-definition/Samples~/WaterSamples/Scenes/Scene Resources/CaveSampleDescription.json index d4e7c8c028f..039d127107b 100644 --- a/Packages/com.unity.render-pipelines.high-definition/Samples~/WaterSamples/Scenes/Scene Resources/CaveSampleDescription.json +++ b/Packages/com.unity.render-pipelines.high-definition/Samples~/WaterSamples/Scenes/Scene Resources/CaveSampleDescription.json @@ -19,7 +19,7 @@ You can open the Custom Pass

Custom Local Volumetric Fog

• To simulate light rays bouncing on the water surface, a Local Volumetric Fog with a custom material is used. -• This shader, simply sample the caustics texture passed by the script on the Water Surface using absolute world position node. +• This shader, simply sample the caustics texture passed by the BindTexture script on the Water Surface using absolute world position node. You can open the Local Volumetric Fog Shader Graph for more details. From 3fd657ec83e8a17bcdef89f8dd8f596ef460c23e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Duverne?= Date: Fri, 3 Oct 2025 21:53:09 +0000 Subject: [PATCH 08/28] Fix Shader Graph doc debt on keyword and property ref pages --- .../Documentation~/Keywords-concepts.md | 45 ++++++++++ .../Documentation~/Keywords-manage.md | 42 ++++++++++ .../Documentation~/Keywords-reference.md | 55 +++++++++++++ .../Documentation~/Keywords.md | 82 ++----------------- .../Documentation~/Property-Types.md | 58 +++++-------- .../Documentation~/TableOfContents.md | 3 + 6 files changed, 171 insertions(+), 114 deletions(-) create mode 100644 Packages/com.unity.shadergraph/Documentation~/Keywords-concepts.md create mode 100644 Packages/com.unity.shadergraph/Documentation~/Keywords-manage.md create mode 100644 Packages/com.unity.shadergraph/Documentation~/Keywords-reference.md diff --git a/Packages/com.unity.shadergraph/Documentation~/Keywords-concepts.md b/Packages/com.unity.shadergraph/Documentation~/Keywords-concepts.md new file mode 100644 index 00000000000..38f4f31f64c --- /dev/null +++ b/Packages/com.unity.shadergraph/Documentation~/Keywords-concepts.md @@ -0,0 +1,45 @@ +# Introduction to keywords in Shader Graph + +Keywords enable you to create shader variants that address multiple contexts, for example: + +* Features that you can turn on or off for each material instance. +* Features that behave differently on certain platforms. +* Shaders that scale in complexity based on conditions you set. + +For more information about keywords and how they affect the final shader, refer to [Changing how shaders work using keywords](https://docs.unity3d.com/Manual/SL-MultipleProgramVariants.html). + +## Conditions and keyword types + +There are two types of keywords you can use depending on the type of conditions you need to set up: + +* Boolean keywords, either on or off, to enable switching between two shader branches. +* Enum keywords, with two or more states, to enable switching between two or more shader branches. + +## Keyword impact optimization + +Each keyword you add in your shader graph implies the addition of one or more branches in the graph. When you add multiple keywords, the number of branch combinations for a single shader graph increases extremely fast, which might result in significant performance impact at build time. + +**Note**: This version of Shader Graph doesn't support dynamic branching for runtime optimization. + +For more information about keyword declarations and behaviors, refer to [How Unity compiles branching shaders](https://docs.unity3d.com/Manual/shader-conditionals-choose-a-type.html). + +### Keyword Definition + +Each keyword has its own [**Definition** parameter](Keywords-reference.md#common-parameters) which lets you define the keyword behavior at build time and at runtime. + +### Shader variants and build time impacts + +* At build time, Unity compiles multiple shader variants according to the number of branches and keywords you define in your shader graph. +* At runtime, Unity sends the GPU the shader variant that matches the evaluation results. + +**Note**: If you use many keywords, it negatively affects the build time as it requires Unity to generate millions or trillions of shader variants. + +By default, Unity sets the keyword's [**Definition** parameter](Keywords-reference.md#common-parameters) to **Shader Feature** to only compile shader variants you use in your build and reduce build time. If you need all the shader variants in your build, for example because you need to change shader branches at runtime, use **Multi Compile** instead. However, this might significantly increase build time and file sizes. + +> [!NOTE] +> When Unity strips out a variant in the build process, any attempt to use this variant at runtime results in a pink shader error. + +## Additional resources + +* [Manage keywords in Shader Graph](Keywords-manage.md) +* [Keyword parameter reference](Keywords-reference.md) diff --git a/Packages/com.unity.shadergraph/Documentation~/Keywords-manage.md b/Packages/com.unity.shadergraph/Documentation~/Keywords-manage.md new file mode 100644 index 00000000000..7efc6fff62b --- /dev/null +++ b/Packages/com.unity.shadergraph/Documentation~/Keywords-manage.md @@ -0,0 +1,42 @@ +# Manage keywords in Shader Graph + +Get started with adding and managing keywords in a Shader Graph. + +## Add a keyword in a Shader Graph + +To add a keyword in a Shader Graph: + +1. Add a keyword in the [Blackboard](Blackboard.md) and define the [keyword parameters](Keywords-reference.md) according to your needs. + +1. Add a [Keyword Node](Keyword-Node.md) in the graph from the keyword you defined in the Blackboard. + +Unity [declares the keyword](https://docs.unity3d.com/Manual/SL-MultipleProgramVariants-declare.html) in the final shader code. + +## Make the shader behavior conditional on the keyword + +To make the shader behavior conditional on the keyword in the Shader Graph: + +1. Create the upstream Shader Graph branches that define the various behaviors you want to use conditionally. + +1. Connect each branch to a different input port of the Keyword Node according to the keyword value you want to use for later toggling. + +1. Connect the output port of the Keyword Node to the node port you want to apply the conditional graph part to. + +Unity [adds all the conditions and branches](https://docs.unity3d.com/Manual/SL-MultipleProgramVariants-make-conditionals.html) in the final shader code. + +## Toggle the shader keyword in the Editor + +To be able to control a keyword from the Material Inspector, make sure to enable **Generate Material Property** in the [keyword parameters](Keywords-reference.md) in the graph. + +## Toggle the shader keyword in a script + +To enable a Boolean keyword from a script, use `EnableKeyword` on the keyword's **Reference Name**. `DisableKeyword` disables the keyword. To learn more about Boolean keywords, refer to [Shader variants and keywords](https://docs.unity3d.com/Manual/SL-MultipleProgramVariants.html). + +When controlling an Enum keyword via script with a `Material.EnableKeyword` or `Shader.EnableKeyword` function, enter the state label in the format `{REFERENCE}_{REFERENCESUFFIX}`. For example, if your reference name is MYENUM and the desired entry is OPTION1, then you would call `Material.EnableKeyword("MYENUM_OPTION1")`. When you select an option, you must also disable the other options to see the effect. + +**Note:** By default, when you add a keyword, Unity adds an underscore to the start of **Reference Name**. As a result, a keyword with the name **MYENUM** has the reference name **_MYENUM**. + +## Additional resources + +* [Introduction to keywords in Shader Graph](Keywords-concepts.md) +* [Keyword parameter reference](Keywords-reference.md) diff --git a/Packages/com.unity.shadergraph/Documentation~/Keywords-reference.md b/Packages/com.unity.shadergraph/Documentation~/Keywords-reference.md new file mode 100644 index 00000000000..714f132a163 --- /dev/null +++ b/Packages/com.unity.shadergraph/Documentation~/Keywords-reference.md @@ -0,0 +1,55 @@ +# Keyword parameter reference + +There are two types of keywords: Boolean and Enum. Each keyword type has a few specific parameters in addition to the many parameters that all keyword types have in common. + +## Common parameters + +Parameters that all keyword types have in common. + +| **Name** | **Description** | +| :--- | :--- | +| **Name** | The display name of the keyword. Unity shows this name in the title bar of nodes that reference the corresponding keyword, and also in the Material Inspector if you expose that keyword. | +| **Reference** | The internal name for the keyword in the shader. Use this **Reference** name instead of the display **Name** when you reference the keyword in a script.

If you overwrite this parameter, be aware of the following:
  • A Keyword **Reference** has to be in full capitals. Unity converts any lowercase letters to uppercase.
  • If the string contains any characters that HLSL does not support, Unity replaces those characters with underscores.
  • You can revert to the default value: right-click on the **Reference** field label, and select **Reset Reference**.
| +| **Definition** | Sets the keyword declaration type, which determines how Unity compiles the shader code. This allows you to [optimize the balance between build time, runtime, and file sizes](Keywords-concepts.md#keyword-impact-optimization).

The options are:
  • **Shader Feature**: Unity only compiles shader variants for keyword combinations used by materials in your build, and removes other shader variants.
  • **Multi Compile**: Unity compiles shader variants for all keyword combinations regardless of whether the build uses these variants.
  • **Predefined**: Specifies that the target/sub-target already defines the keyword and you just want to reuse it. Predefined Keywords can either use a [built-in macro](https://docs.unity3d.com/Manual/shader-branching-built-in-macros.html), which results in static branching at build time, or any of the keywords already defined by the Shader Graph Target (for example, [URP](https://docs.unity3d.com/Manual/urp/urp-shaders/shader-keywords-macros.html)), including [Built-In keyword sets](https://docs.unity3d.com/Manual/SL-MultipleProgramVariants-shortcuts.html), and where the branching depends on that definition.
| +| **Is Overridable** | Indicates whether the keyword's state can be overridden.
For more information, refer to [Toggle shader keywords in a script](https://docs.unity3d.com/Manual/shader-keywords-scripts.html). | +| **Generate Material Property** | Generates a material property declaration to display the keyword as a property in the material inspector.
This adds a `[Toggle(_KEYWORD)]` attribute to the material property. For more information, refer to [`MaterialPropertyDrawer`](https://docs.unity3d.com/ScriptReference/MaterialPropertyDrawer.html). | +| **Stages** | Set the stage the keyword applies to.

The following options are available:
  • **All** - Applies this keyword to all shader stages.
  • **Vertex** - Applies this keyword to the vertex stage.
  • **Fragment** - Applies this keyword to the fragment stage.
| + + + +## Boolean keywords + +Parameter specific to Boolean keywords in addition to the [common parameters](#common-parameters). + +| **Name** | **Description** | +| :--- | :--- | +| **Default Value** | Enable this parameter to set the keyword's default state to on, and disable it to set the keyword's default state to off.

This parameter determines the value to use for the keyword when Shader Graph generates previews. It also defines the keyword's default value when you use this shader to create a new Material. | + + + +## Enum keywords + +Parameters specific to Enum keywords in addition to the [common parameters](#common-parameters). + +| **Name** | **Description** | +| :--- | :--- | +| **Default Value** | Select an entry from the drop-down menu to determine which value to use for the keyword when Shader Graph generates previews. This also defines the keyword's default value when you use this shader to create a new Material. When you edit the Entries list, Shader Graph automatically updates the options in this control. | +| **Entries** | This list defines all the states for the keyword. Each state has a separate **Entry Name** and **Reference Suffix**.
  • **Entry Name**: The name displayed in drop-down menus for the keyword on the [Internal Inspector](Internal-Inspector.md) and the Material Inspector. Shader Graph also uses this name for port labels on nodes that reference the keyword.
  • **Reference Suffix**: This identifies the final keyword, presented in the format `Reference_ReferenceSuffix`.
| + +When you define an Enum keyword, Shader Graph displays labels for each state consisting of a version of the Enum's **Entry Name** appended to the main **Reference** name. + +> [!NOTE] +> Special characters such as `(`, `)`, `!`, or `@` are not valid in the **Entry Name** of an Enum keyword. Shader Graph converts invalid characters to underscores (`_`). + + + +## Built-in keywords + +The parameters of built-in keywords depend on their type, which is always of either the Boolean or Enum type, and you cannot edit their values. + +All Built-in keyword fields in the **Node Settings** tab of the [Graph Inspector](Internal-Inspector.md) are grayed out except for the **Default** field, which you can enable or disable to show the differences in Shader Graph previews. You also cannot expose Built-in keywords in the Material Inspector. + +## Additional resources + +* [Introduction to keywords in Shader Graph](Keywords-concepts.md) +* [Manage keywords in Shader Graph](Keywords-manage.md) diff --git a/Packages/com.unity.shadergraph/Documentation~/Keywords.md b/Packages/com.unity.shadergraph/Documentation~/Keywords.md index 981514f50bd..1354003f4be 100644 --- a/Packages/com.unity.shadergraph/Documentation~/Keywords.md +++ b/Packages/com.unity.shadergraph/Documentation~/Keywords.md @@ -1,77 +1,9 @@ -# Keywords +# Changing how shaders work using keywords -## Description - -Use Keywords to create different variants for your Shader Graph. - -Keywords enable you to create shaders: - -* With features that you can turn on or off for each Material instance. -* With features that behave differently on certain platforms. -* That scale in complexity based on conditions you set. - -There are three types of Keywords: Boolean, Enum, and Built-in. Unity defines a Keyword in the graph, shader, and optionally, the Material Inspector based on its type. See [Boolean Keyword](#BooleanKeywords), [Enum Keyword](#EnumKeywords), and [Built-in Keyword](#BuiltinKeywords) for more information about Keyword types. For more information about how these Keywords affect the final shader, see documentation on [Making multiple shader program variants](https://docs.unity3d.com/Manual/SL-MultipleProgramVariants.html). - -In Shader Graph, you first define a Keyword on the [Blackboard](Blackboard.md), then use a [Keyword Node](Keyword-Node.md) to create a branch in the graph. - -The Editor is able to compile variants on demand when it needs them to render content. If you declare many different variants, you can end up with millions or trillions of possibilities. However, the Player needs to determine at build time which variants are in use and include them when it pre-compiles your shaders. To manage memory effectively, the Player strips unused variants based on their keyword and Editor settings. See the next section, Common parameters, to learn more about how you can give the Player hints about what it needs to compile and what it can ignore. When the Player strips out a variant in the build process, it displays the pink error shader. - -## Common parameters - -Although some fields are specific to certain types of Keywords, all Keywords have the following parameters. - -| **Name** | **Type** | **Description** | -| ------------------ | -------- | ------------------------------------------------------------ | -| **Display Name** | String | The display name of the Keyword. Unity shows this name in the title bar of nodes that reference the corresponding Keyword, and also in the Material Inspector if you expose that Keyword. | -| **Exposed** | Boolean | When you set this parameter to **true**, Unity displays this Keyword in the Material Inspector. If you set it to **false**, the Keyword does not appear in the Material Inspector.

If you intend to access a GLOBAL shader variable, be sure to add it as you would normally add an input variable, but deselect **Exposed**.| -| **Reference Name** | String | The internal name for the Keyword in the shader.

If you overwrite the Reference Name parameter, take note of the following: