Stencil command in ShaderLab reference
Reference for the Stencil command in ShaderLab.
Read time 6 minutesLast updated a month ago
Important
The Built-In Render Pipeline is deprecated and will be made obsolete in a future release.
It remains supported, including bug fixes and maintenance, through the full Unity 6.7 LTS lifecycle.
For more information on migration, refer to Migrating from the Built-In Render Pipeline to the Universal Render Pipeline and Render pipeline feature comparison.
Configures settings relating to the stencil buffer on the GPU.
Render pipeline compatibility
Feature name | Universal Render Pipeline (URP) | High Definition Render Pipeline (HDRP) | Custom SRP | Built-in Render Pipeline |
|---|---|---|---|---|
| Stencil | Yes | Yes | Yes | Yes |
Syntax
Signature | Example syntax | Function |
|---|---|---|
Note that all parameters are optional. | | Configures the stencil buffer according to the given parameters. |
Parameters
Parameter | Value | Function |
|---|---|---|
| ref | An integer. Range 0 through 255. Default is 0. | The reference value. The GPU compares the current contents of the stencil buffer against this value, using the operation defined in comparisonOperation. This value is masked with readMask or writeMask, depending on whether a read or a write operation is occurring. The GPU can also write this value to the stencil buffer, if Pass, Fail or ZFail have a value of Replace. |
| readMask | An integer. Range 0 through 255. Default is 255. | The GPU uses this value as a mask when it performs the stencil test. See above for the stencil test equation. |
| writeMask | An integer. Range 0 through 255. Default is 255. | The GPU uses this value as a mask when it writes to the stencil buffer. Note that, like other masks, it specifies which bits are included in the operation. For example, a value of 0 means that no bits are included in the write operation, not that the stencil buffer receives a value of 0. |
| comparisonOperation | A comparison operation. See Comparison operation values for valid values. Default is Always. | The operation that the GPU performs for the stencil test for all pixels. This defines the operation for all pixels, regardless of facing. If this is defined in addition to comparisonOperationBack and comparisonOperationFront, this value overrides them. |
| passOperation | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel pases both the stencil test and the depth test. This defines the operation for all pixels, regardless of facing. If this is defined in addition to passOperationBack and passOperationFront, this value overrides them. |
| failOperation | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel fails the stencil test. This defines the operation for all pixels, regardless of facing. If this is defined in addition to failOperationBack and failOperationFront, this value overrides them. |
| zFailOperation | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel passes the stencil test, but fails the depth test. This defines the operation for all pixels, regardless of facing. If this is defined in addition to zFailOperationBack and zFailOperationFront, this value overrides them. |
| comparisonOperationBack | A comparison operation. See Comparison operation values for valid values. Default is Always. | The operation that the GPU performs for the stencil test. This defines the operation for back-facing pixels only. If comparisonOperation is defined, that value overrides this one. |
| passOperationBack | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel pases both the stencil test and the depth test. This defines the operation for back-facing pixels only. If passOperation is defined, that value overrides this one. |
| failOperationBack | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel fails the stencil test. This defines the operation for back-facing pixels only. If failOperation is defined, that value overrides this one. |
| zFailOperationBack | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel passes the stencil test, but fails the depth test. This defines the operation for back-facing pixels only. If zFailOperation is defined, that value overrides this one. |
| comparisonOperationFront | A comparison operation. See Comparison operation values for valid values. Default is Always. | The operation that the GPU performs for the stencil test. This defines the operation for front-facing pixels only. If comparisonOperation is defined, that value overrides this one. |
| passOperationFront | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel pases both the stencil test and the depth test. This defines the operation for front-facing pixels only. If passOperation is defined, that value overrides this one. |
| failOperationFront | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel fails the stencil test. This defines the operation for front-facing pixels only. If failOperation is defined, that value overrides this one. |
| zFailOperationFront | A stencil operation. See Stencil operation values for valid values. Default is Keep. | The operation that the GPU performs on the stencil buffer when a pixel passes the stencil test, but fails the depth test. This defines the operation for front-facing pixels only. If zFailOperation is defined, that value overrides this one. |
Comparison values
In C#, these values are represented by the Rendering.CompareFunction enum.
Value | Corresponding integer value in Rendering.CompareFunction enum | Function |
|---|---|---|
| 1 | Never render pixels. |
| 2 | Render pixels when their reference value is less than the current value in the stencil buffer. |
| 3 | Render pixels when their reference value is equal to the current value in the stencil buffer. |
| 4 | Render pixels when their reference value is less than or equal to the current value in the stencil buffer. |
| 5 | Render pixels when their reference value is greater than the current value in the stencil buffer. |
| 6 | Render pixels when their reference value differs from the current value in the stencil buffer. |
| 7 | Render pixels when their reference value is greater than or equal to the current value in the stencil buffer. |
| 8 | Always render pixels. |
Stencil values
In C#, these values are represented by the Rendering.Rendering.StencilOp enum.
Value | Corresponding integer value in Rendering.StencilOp enum | Function |
|---|---|---|
| 0 | Keep the current contents of the stencil buffer. |
| 1 | Write 0 into the stencil buffer. |
| 2 | Write the reference value into the buffer. |
| 3 | Increment the current value in the buffer. If the value is 255 already, it stays at 255. |
| 4 | Decrement the current value in the buffer. If the value is 0 already, it stays at 0. |
| 5 | Negate all the bits of the current value in the buffer. |
| 6 | Increment the current value in the buffer. If the value is 255 already, it becomes 0. |
| 7 | Decrement the current value in the buffer. If the value is 0 already, it becomes 255. |