feat: add shader stencil operations

Docs/pure-base-shader-contract.md

@@ -53,6 +53,18 @@ Every product shader source retains exactly four passes:
 
 The effective tags, queue, blend state, depth writing, and pass enablement are selected by the rendering-mode ABI below. The `ForwardAdd` additive blend state in Opaque and Cutout is an additional direct-light pass, not transparent blending.
 
+### Stencil pass policy
+
+The camera Stencil policy is bounded to the forward passes:
+
+- `ForwardBase` applies all seven public Stencil settings.
+- `ForwardAdd` compares the Stencil value left by `ForwardBase` using only `_StencilRef`, `_StencilReadMask`, and `_StencilComp`. It fixes `WriteMask` to `0` and `Pass`, `Fail`, and `ZFail` to `Keep`, so additional lights cannot mutate Stencil.
+- `ShadowCaster` and `Meta` do not apply the camera Stencil policy.
+
+The defaults are `Always` with `Keep` for all outcomes (`0, 255, 255, 8, 0, 0, 0`). They are a no-op Stencil state: a legacy material without saved Stencil fields continues to draw and does not mutate Stencil. A `ForwardBase` operation such as `Replace`, `Incr`, `Decr`, or `Invert` can intentionally change the value observed by `ForwardAdd`; the additional-light pass then accepts or rejects independently based on that post-`ForwardBase` value. It does not preserve a comparison against the pre-`ForwardBase` value.
+
+The Stencil ABI adds no Stencil-specific keyword, shader variant, pass, or package dependency. Rendering-mode changes and Resync synchronize rendering-mode state while preserving all user Stencil values.
+
 ## Rendering-mode ABI
 
 `_RenderingMode` is a ShaderLab `Integer` backed by `SC_uint` with these values:
@@ -71,17 +83,24 @@ The explicit editor action is `PureBaseMaterialRenderingMode.Apply(Material)`. T
 
 ## Public Property ABI
 
-All four shaders expose exactly these common properties:
+All four shaders expose exactly these common visible properties, in declaration order:
 
 | Property | Applies to |
 | --- | --- |
 | `_BaseTexture` | All shaders |
 | `_BaseColor` | All shaders |
 | `_SharedMask` | All shaders |
 | `_SharedGradients` | All shaders |
+| `_RenderingMode` | All shaders |
 | `_Cutoff` | All shaders |
 | `_Cull` | All shaders |
-| `_RenderingMode` | All shaders |
+| `_StencilRef` | All shaders |
+| `_StencilReadMask` | All shaders |
+| `_StencilWriteMask` | All shaders |
+| `_StencilComp` | All shaders |
+| `_StencilPass` | All shaders |
+| `_StencilFail` | All shaders |
+| `_StencilZFail` | All shaders |
 
 The model-specific properties are:
 
@@ -96,6 +115,22 @@ PBR and Hybrid use byte-identical property declarations. `_Roughness` clamps fro
 
 The forbidden release-boundary property names `_Emission`, `_Rim`, `_MatCap`, and `_ClearCoat` are not part of this ABI.
 
+### Stencil ABI
+
+All four product shaders expose the following public Stencil properties. The declarations use the Float-compatible `SC_float` ABI, including the enum-backed values.
+
+| Property | Public UI contract | Default |
+| --- | --- | ---: |
+| `_StencilRef` | `SC_float`; integer UI range `0-255` | `0` |
+| `_StencilReadMask` | `SC_float`; integer UI range `0-255` | `255` |
+| `_StencilWriteMask` | `SC_float`; integer UI range `0-255` | `255` |
+| `_StencilComp` | `SC_float`; `UnityEngine.Rendering.CompareFunction` | `8` (`Always`) |
+| `_StencilPass` | `SC_float`; `UnityEngine.Rendering.StencilOp` | `0` (`Keep`) |
+| `_StencilFail` | `SC_float`; `UnityEngine.Rendering.StencilOp` | `0` (`Keep`) |
+| `_StencilZFail` | `SC_float`; `UnityEngine.Rendering.StencilOp` | `0` (`Keep`) |
+
+The three mask/reference properties use the `0-255` UI range. The comparison and operation properties use Unity's `CompareFunction` and `StencilOp` enums respectively.
+
 ## Shader-Core Phase ABI
 
 The standard insertion points are shared by the product hosts in this order:

Docs/technical-information.ja.md

@@ -75,6 +75,26 @@ Pure Base は Shader-Core を動かすための最小構成の土台です。多
 
 `PureBase/PBR` と `PureBase/Hybrid` は、法線マップ用の項目に加えて `_Metallic` と `_Roughness` を公開します。両者の公開項目定義は完全に同一です。粗さは `0.002` から `1` の範囲に制限されます。
 
+### ステンシル ABI
+
+4つの製品シェーダーは、Float互換の `SC_float` ABI を通じて、次のステンシル項目を公開します。列挙型に対応する項目も `SC_float` として宣言されます。
+
+| 項目 | UI の仕様 | 初期値 |
+| --- | --- | ---: |
+| `_StencilRef` | 整数範囲 `0-255` | `0` |
+| `_StencilReadMask` | 整数範囲 `0-255` | `255` |
+| `_StencilWriteMask` | 整数範囲 `0-255` | `255` |
+| `_StencilComp` | `UnityEngine.Rendering.CompareFunction` | `8`（`Always`） |
+| `_StencilPass` | `UnityEngine.Rendering.StencilOp` | `0`（`Keep`） |
+| `_StencilFail` | `UnityEngine.Rendering.StencilOp` | `0`（`Keep`） |
+| `_StencilZFail` | `UnityEngine.Rendering.StencilOp` | `0`（`Keep`） |
+
+`ForwardBase` は7項目すべてを適用します。`ForwardAdd` は `ForwardBase` 後のステンシル値を `_StencilRef`、`_StencilReadMask`、`_StencilComp` だけで比較します。`WriteMask` は `0`、`Pass`、`Fail`、`ZFail` は `Keep` に固定されるため、追加ライトがステンシルを書き換えることはありません。`ShadowCaster` と `Meta` ではカメラ用のステンシル方針を適用しません。
+
+初期値の `Always` と `Keep` の組み合わせは、ステンシルに対する何もしない状態です。保存済みのステンシル項目を持たない旧形式のマテリアルも描画を継続し、ステンシルを書き換えません。`ForwardBase` で `Replace`、`Incr`、`Decr`、`Invert` などを指定すると、`ForwardAdd` が変更後の値を比較するため、追加ライトは独立して通過または拒否されることがあります。`ForwardBase` 前の値との比較を維持する仕様ではありません。
+
+ステンシルの追加によって、ステンシル専用のキーワード、シェーダーバリアント、パス、パッケージ依存関係は増えません。描画モードの変更と Resync は描画モードの状態を同期しますが、ユーザーが設定した7つのステンシル項目は保持します。
+
 ## Shader-Core との連携
 
 共通の処理差し込み位置は、次の順で実行されます。

Docs/technical-information.md

@@ -75,6 +75,26 @@ All four shaders expose these common properties:
 
 `PureBase/PBR` and `PureBase/Hybrid` expose the same normal-map properties plus `_Metallic` and `_Roughness`. Their public property declarations are byte-identical. Roughness is clamped from `0.002` to `1`.
 
+### Stencil ABI
+
+All four product shaders expose these public Stencil properties through the Float-compatible `SC_float` ABI:
+
+| Property | UI contract | Default |
+| --- | --- | ---: |
+| `_StencilRef` | Integer range `0-255` | `0` |
+| `_StencilReadMask` | Integer range `0-255` | `255` |
+| `_StencilWriteMask` | Integer range `0-255` | `255` |
+| `_StencilComp` | `UnityEngine.Rendering.CompareFunction` | `8` (`Always`) |
+| `_StencilPass` | `UnityEngine.Rendering.StencilOp` | `0` (`Keep`) |
+| `_StencilFail` | `UnityEngine.Rendering.StencilOp` | `0` (`Keep`) |
+| `_StencilZFail` | `UnityEngine.Rendering.StencilOp` | `0` (`Keep`) |
+
+`ForwardBase` applies all seven settings. `ForwardAdd` compares the post-`ForwardBase` Stencil value using `_StencilRef`, `_StencilReadMask`, and `_StencilComp` only; it fixes `WriteMask` to `0` and `Pass`, `Fail`, and `ZFail` to `Keep`, so additional lights do not mutate Stencil. `ShadowCaster` and `Meta` do not apply the camera Stencil policy.
+
+The default `Always` plus `Keep` state is a no-op: a legacy material without saved Stencil fields continues to draw and does not mutate Stencil. If `ForwardBase` uses `Replace`, `Incr`, `Decr`, `Invert`, or another mutating operation, `ForwardAdd` may compare the changed value and therefore accept or reject independently. The policy intentionally does not preserve a comparison against the pre-`ForwardBase` value.
+
+Stencil adds no Stencil-specific keyword, variant, pass, or package dependency. Rendering-mode changes and Resync preserve user values for all seven Stencil properties.
+
 ## Shader-Core integration
 
 The shared standard phase ABI is executed in this order:

Shaders/PureBaseHybrid.scshader

@@ -41,6 +41,16 @@ Shader "PureBase/Hybrid"
         {
             Name "ForwardBase"
             Tags { "LightMode" = "ForwardBase" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                WriteMask [_StencilWriteMask]
+                Comp [_StencilComp]
+                Pass [_StencilPass]
+                Fail [_StencilFail]
+                ZFail [_StencilZFail]
+            }
             Cull [_Cull]
             ZWrite [_ZWrite]
             ZTest LEqual
@@ -61,6 +71,16 @@ Shader "PureBase/Hybrid"
         {
             Name "ForwardAdd"
             Tags { "LightMode" = "ForwardAdd" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                Comp [_StencilComp]
+                WriteMask 0
+                Pass Keep
+                Fail Keep
+                ZFail Keep
+            }
             Cull [_Cull]
             ZWrite Off
             ZTest LEqual

Shaders/PureBaseHybrid_properties.hlsl

@@ -7,6 +7,13 @@ SC_Texture2DArray(_SharedGradients, "white", [SCGradients], "__SharedGradients",
 SC_uint(_RenderingMode, 1, [PureBaseRenderingMode], "Rendering Mode", "")
 SC_float(_Cutoff, 0.5, [PureBaseCutoff][SCRange(-0.001,1.001)], "Cutoff", "")
 SC_float(_Cull, 2, [SCEnum(Off, 0, Front, 1, Back, 2)], "Cull", "")
+SC_float(_StencilRef, 0, [SCRangeInt(0,255)], "Stencil Reference", "")
+SC_float(_StencilReadMask, 255, [SCRangeInt(0,255)], "Stencil Read Mask", "")
+SC_float(_StencilWriteMask, 255, [SCRangeInt(0,255)], "Stencil Write Mask", "")
+SC_float(_StencilComp, 8, [SCEnum(UnityEngine.Rendering.CompareFunction)], "Stencil Comparison", "")
+SC_float(_StencilPass, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Pass", "")
+SC_float(_StencilFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Fail", "")
+SC_float(_StencilZFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Z Fail", "")
 SC_Texture2D(_NormalMap, "bump", [], "Normal Map", "")
 SC_SamplerState(sampler_NormalMap)
 SC_float(_NormalScale, 1, [SCRange(0,2)], "Normal Scale", "")

Shaders/PureBasePBR.scshader

@@ -41,6 +41,16 @@ Shader "PureBase/PBR"
         {
             Name "ForwardBase"
             Tags { "LightMode" = "ForwardBase" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                WriteMask [_StencilWriteMask]
+                Comp [_StencilComp]
+                Pass [_StencilPass]
+                Fail [_StencilFail]
+                ZFail [_StencilZFail]
+            }
             Cull [_Cull]
             ZWrite [_ZWrite]
             ZTest LEqual
@@ -61,6 +71,16 @@ Shader "PureBase/PBR"
         {
             Name "ForwardAdd"
             Tags { "LightMode" = "ForwardAdd" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                Comp [_StencilComp]
+                WriteMask 0
+                Pass Keep
+                Fail Keep
+                ZFail Keep
+            }
             Cull [_Cull]
             ZWrite Off
             ZTest LEqual

Shaders/PureBasePBR_properties.hlsl

@@ -7,6 +7,13 @@ SC_Texture2DArray(_SharedGradients, "white", [SCGradients], "__SharedGradients",
 SC_uint(_RenderingMode, 1, [PureBaseRenderingMode], "Rendering Mode", "")
 SC_float(_Cutoff, 0.5, [PureBaseCutoff][SCRange(-0.001,1.001)], "Cutoff", "")
 SC_float(_Cull, 2, [SCEnum(Off, 0, Front, 1, Back, 2)], "Cull", "")
+SC_float(_StencilRef, 0, [SCRangeInt(0,255)], "Stencil Reference", "")
+SC_float(_StencilReadMask, 255, [SCRangeInt(0,255)], "Stencil Read Mask", "")
+SC_float(_StencilWriteMask, 255, [SCRangeInt(0,255)], "Stencil Write Mask", "")
+SC_float(_StencilComp, 8, [SCEnum(UnityEngine.Rendering.CompareFunction)], "Stencil Comparison", "")
+SC_float(_StencilPass, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Pass", "")
+SC_float(_StencilFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Fail", "")
+SC_float(_StencilZFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Z Fail", "")
 SC_Texture2D(_NormalMap, "bump", [], "Normal Map", "")
 SC_SamplerState(sampler_NormalMap)
 SC_float(_NormalScale, 1, [SCRange(0,2)], "Normal Scale", "")

Shaders/PureBaseToon.scshader

@@ -41,6 +41,16 @@ Shader "PureBase/Toon"
         {
             Name "ForwardBase"
             Tags { "LightMode" = "ForwardBase" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                WriteMask [_StencilWriteMask]
+                Comp [_StencilComp]
+                Pass [_StencilPass]
+                Fail [_StencilFail]
+                ZFail [_StencilZFail]
+            }
             Cull [_Cull]
             ZWrite [_ZWrite]
             ZTest LEqual
@@ -58,6 +68,16 @@ Shader "PureBase/Toon"
         {
             Name "ForwardAdd"
             Tags { "LightMode" = "ForwardAdd" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                Comp [_StencilComp]
+                WriteMask 0
+                Pass Keep
+                Fail Keep
+                ZFail Keep
+            }
             Cull [_Cull]
             ZWrite Off
             ZTest LEqual

Shaders/PureBaseToon_properties.hlsl

@@ -7,6 +7,13 @@ SC_Texture2DArray(_SharedGradients, "white", [SCGradients], "__SharedGradients",
 SC_uint(_RenderingMode, 1, [PureBaseRenderingMode], "Rendering Mode", "")
 SC_float(_Cutoff, 0.5, [PureBaseCutoff][SCRange(-0.001,1.001)], "Cutoff", "")
 SC_float(_Cull, 2, [SCEnum(Off, 0, Front, 1, Back, 2)], "Cull", "")
+SC_float(_StencilRef, 0, [SCRangeInt(0,255)], "Stencil Reference", "")
+SC_float(_StencilReadMask, 255, [SCRangeInt(0,255)], "Stencil Read Mask", "")
+SC_float(_StencilWriteMask, 255, [SCRangeInt(0,255)], "Stencil Write Mask", "")
+SC_float(_StencilComp, 8, [SCEnum(UnityEngine.Rendering.CompareFunction)], "Stencil Comparison", "")
+SC_float(_StencilPass, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Pass", "")
+SC_float(_StencilFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Fail", "")
+SC_float(_StencilZFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Z Fail", "")
 SC_Texture2D(_NormalMap, "bump", [], "Normal Map", "")
 SC_SamplerState(sampler_NormalMap)
 SC_float(_NormalScale, 1, [SCRange(0,2)], "Normal Scale", "")

Shaders/PureBaseUnlit.scshader

@@ -41,6 +41,16 @@ Shader "PureBase/Unlit"
         {
             Name "ForwardBase"
             Tags { "LightMode" = "ForwardBase" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                WriteMask [_StencilWriteMask]
+                Comp [_StencilComp]
+                Pass [_StencilPass]
+                Fail [_StencilFail]
+                ZFail [_StencilZFail]
+            }
             Cull [_Cull]
             ZWrite [_ZWrite]
             ZTest LEqual
@@ -57,6 +67,16 @@ Shader "PureBase/Unlit"
         {
             Name "ForwardAdd"
             Tags { "LightMode" = "ForwardAdd" }
+            Stencil
+            {
+                Ref [_StencilRef]
+                ReadMask [_StencilReadMask]
+                Comp [_StencilComp]
+                WriteMask 0
+                Pass Keep
+                Fail Keep
+                ZFail Keep
+            }
             Cull [_Cull]
             ZWrite Off
             ZTest LEqual

Shaders/PureBaseUnlit_properties.hlsl

@@ -7,3 +7,10 @@ SC_Texture2DArray(_SharedGradients, "white", [SCGradients], "__SharedGradients",
 SC_uint(_RenderingMode, 1, [PureBaseRenderingMode], "Rendering Mode", "")
 SC_float(_Cutoff, 0.5, [PureBaseCutoff][SCRange(-0.001,1.001)], "Cutoff", "")
 SC_float(_Cull, 2, [SCEnum(Off, 0, Front, 1, Back, 2)], "Cull", "")
+SC_float(_StencilRef, 0, [SCRangeInt(0,255)], "Stencil Reference", "")
+SC_float(_StencilReadMask, 255, [SCRangeInt(0,255)], "Stencil Read Mask", "")
+SC_float(_StencilWriteMask, 255, [SCRangeInt(0,255)], "Stencil Write Mask", "")
+SC_float(_StencilComp, 8, [SCEnum(UnityEngine.Rendering.CompareFunction)], "Stencil Comparison", "")
+SC_float(_StencilPass, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Pass", "")
+SC_float(_StencilFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Fail", "")
+SC_float(_StencilZFail, 0, [SCEnum(UnityEngine.Rendering.StencilOp)], "Stencil Z Fail", "")

Tests/Daily/Editor/PureBaseD24S8StencilTarget.renderTexture

@@ -0,0 +1,40 @@
+%YAML 1.1
+%TAG !u! tag:unity3d.com,2011:
+--- !u!84 &8400000
+RenderTexture:
+  m_ObjectHideFlags: 0
+  m_CorrespondingSourceObject: {fileID: 0}
+  m_PrefabInstance: {fileID: 0}
+  m_PrefabAsset: {fileID: 0}
+  m_Name: PureBaseD24S8StencilTarget
+  m_ImageContentsHash:
+    serializedVersion: 2
+    Hash: 00000000000000000000000000000000
+  m_ForcedFallbackFormat: 4
+  m_DownscaleFallback: 0
+  m_IsAlphaChannelOptional: 0
+  serializedVersion: 5
+  m_Width: 256
+  m_Height: 256
+  m_AntiAliasing: 1
+  m_MipCount: -1
+  m_DepthStencilFormat: 92
+  m_ColorFormat: 8
+  m_MipMap: 0
+  m_GenerateMips: 1
+  m_SRGB: 0
+  m_UseDynamicScale: 0
+  m_BindMS: 0
+  m_EnableCompatibleFormat: 0
+  m_EnableRandomWrite: 0
+  m_TextureSettings:
+    serializedVersion: 2
+    m_FilterMode: 1
+    m_Aniso: 0
+    m_MipBias: 0
+    m_WrapU: 1
+    m_WrapV: 1
+    m_WrapW: 1
+  m_Dimension: 2
+  m_VolumeDepth: 1
+  m_ShadowSamplingMode: 2