ShaderLab 커맨드: Stencil

GPU의 스텐실 버퍼와 관련된 설정을 구성합니다.

스텐실 버퍼는 프레임 버퍼의 모든 픽셀에 대해 8비트 정수 값을 저장합니다. 특정 픽셀의 프래그먼트 셰이더를 실행하기 전에 GPU는 스텐실 버퍼의 현재 값을 특정한 레퍼런스 값과 비교할 수 있습니다. 이를 스텐실 테스트라고 합니다. 스텐실 테스트에 통과하면 GPU가 뎁스 테스트를 수행합니다. 스텐실 테스트에 실패하면 GPU가 해당 픽셀의 나머지 처리를 건너뜁니다. 즉, 스텐실 버퍼를 마스크로 사용하여 GPU에 드로우할 픽셀과 폐기할 픽셀을 지시할 수 있습니다.

스텐실 버퍼는 일반적으로 포털이나 미러와 같은 특수효과에 사용합니다. 또한 간혹 하드 섀도우 렌더링 또는 구조적 입체 지오메트리(CSG)에 스텐실 버퍼를 사용하기도 합니다.

렌더 파이프라인 호환성

기능 이름	빌트인 렌더 파이프라인	유니버설 렌더 파이프라인(URP)	고해상도 렌더 파이프라인(HDRP)	커스텀 SRP
Stencil	지원	지원	지원	지원

사용법

이 커맨드는 렌더 상태를 변경합니다. Pass 블록에서 사용하여 해당 패스의 렌더 상태를 설정하거나, SubShader 블록에서 사용하여 해당 서브셰이더에 있는 모든 패스의 렌더 상태를 설정할 수 있습니다.

Stencil 커맨드를 사용하여 두 가지를 작업을 수행할 수 있습니다. 하나는 스텐실 테스트 설정이며, 다른 하나는 GPU가 스텐실 버퍼에 작성하는 내용 설정입니다. 같은 커맨드에서 이 두 가지를 모두 수행할 수 있으나, 가장 일반적인 사용 사례는 다른 셰이더 오브젝트가 드로우할 수 없도록 일부 화면 영역을 마스크하는 셰이더 오브젝트를 만드는 것입니다. 이를 수행하려면 첫 셰이더 오브젝트가 항상 스텐실 테스트를 통과하도록 설정하고, 나머지 셰이더 오브젝트가 스텐실 테스트를 수행하고 스텐실 버퍼에 작성하지 않도록 설정해야 합니다.

Ref, ReadMask 및 Comp 파라미터를 사용하여 스텐실 테스트를 설정하십시오. Ref, WriteMask, Pass, Fail 및 ZFail 파라미터를 사용하여 스텐실 작성 작업을 설정하십시오.

스텐실 테스트 등식은 다음과 같습니다.

(ref & readMask) comparisonFunction (stencilBufferValue & readMask)

서명	예제 구문	기능
`Stencil` `{` `Ref <ref>` `ReadMask <readMask>` `WriteMask <writeMask>` `Comp <comparisonOperation>` `Pass <passOperation>` `Fail <failOperation>` `ZFail <zFailOperation>` `CompBack <comparisonOperationBack>` `PassBack <passOperationBack>` `FailBack <failOperationBack>` `ZFailBack <zFailOperationBack>` `CompFront <comparisonOperationFront>` `PassFront <passOperationFront>` `FailFront <failOperationFront>` `ZFailFront <zFailOperationFront>` `}` Note that all parameters are optional.	`Stencil` `{` `Ref 2` `Comp equal` `Pass keep` `ZFail decrWrap` `}`	특정 파라미터에 따라 스텐실 버퍼를 설정합니다.

유효한 파라미터 값

파라미터	값	기능
ref	정수. 0 - 255의 범위입니다. 기본값은 0입니다.	레퍼런스 값. GPU는 comparisonOperation에 정의된 작업을 사용하여 스텐실 버퍼의 현재 콘텐츠를 이 값과 비교합니다. 이 값은 읽기 작업과 작성 작업 중 어느 것이 발생하는지에 따라 readMask나 writeMask로 마스크합니다. 또한 Pass, Fail 또는 ZFail에 Replace 값이 있는 경우 GPU는 이 값을 스텐실 버퍼에도 작성할 수 있습니다.
readMask	정수. 0 - 255의 범위입니다. 기본값은 255입니다.	GPU는 스텐실 테스트를 수행할 때 이 값을 마스크로 사용합니다. 스텐실 테스트 등식은 위를 참조하십시오.
writeMask	정수. 0 - 255의 범위입니다. 기본값은 255입니다.	GPU는 스텐실 버퍼에 작성할 때 이 값을 마스크로 사용합니다. 다른 마스크와 마찬가지로 이 값은 작업에 포함된 비트를 지정합니다. 예를 들어, 값이 0이면 스텐실 버퍼가 0 값을 수신한다는 것이 아니라 작성 작업에 포함된 비트가 없음을 의미합니다.
comparisonOperation	비교 작업입니다. 유효한 값은 비교 작업 값을 참조하십시오. 기본값은 Always입니다.	GPU가 스텐실 테스트를 위해 모든 픽셀에 대해 수행하는 작업입니다. 방향과 관계없이 모든 픽셀에 대한 작업을 정의합니다. comparisonOperationBack과 comparisonOperationFront에 추가로 정의된 경우, 이 값은 comparisonOperationBack과 comparisonOperationFront를 오버라이드합니다.
passOperation	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트와 뎁스 테스트 모두를 통과한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 방향과 관계없이 모든 픽셀에 대한 작업을 정의합니다. passOperationBack과 passOperationFront에 추가로 정의된 경우, 이 값은 passOperationBack과 passOperationFront를 오버라이드합니다.
failOperation	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트에 실패한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 방향과 관계없이 모든 픽셀에 대한 작업을 정의합니다. failOperationBack과 failOperationFront에 추가로 정의된 경우, 이 값은 failOperationBack과 failOperationFront를 오버라이드합니다.
zFailOperation	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트를 통과했지만 뎁스 테스트에는 실패한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 방향과 관계없이 모든 픽셀에 대한 작업을 정의합니다. zFailOperation과 zFailOperation에 추가로 정의된 경우, 이 값은 zFailOperation과 zFailOperation을 오버라이드합니다.
comparisonOperationBack	비교 작업입니다. 유효한 값은 비교 작업 값을 참조하십시오. 기본값은 Always입니다.	GPU가 스텐실 테스트를 위해 수행하는 작업입니다. 뒤쪽을 향하는 픽셀에 대한 작업만 정의합니다. comparisonOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.
passOperationBack	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트와 뎁스 테스트 모두를 통과한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 뒤쪽을 향하는 픽셀에 대한 작업만 정의합니다. passOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.
failOperationBack	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트에 실패한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 뒤쪽을 향하는 픽셀에 대한 작업만 정의합니다. failOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.
zFailOperationBack	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트에 통과했지만 뎁스 테스트에 실패한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 뒤쪽을 향하는 픽셀에 대한 작업만 정의합니다. zFailOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.
comparisonOperationFront	비교 작업입니다. 유효한 값은 비교 작업 값을 참조하십시오. 기본값은 Always입니다.	GPU가 스텐실 테스트를 위해 수행하는 작업입니다. 앞쪽을 향하는 픽셀에 대한 작업만 정의합니다. comparisonOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.
passOperationFront	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트와 뎁스 테스트 모두를 통과한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 앞쪽을 향하는 픽셀에 대한 작업만 정의합니다. passOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.
failOperationFront	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트에 실패한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 앞쪽을 향하는 픽셀에 대한 작업만 정의합니다. failOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.
zFailOperationFront	스텐실 작업입니다. 유효한 값은 스텐실 작업 값을 참조하십시오. 기본값은 Kepp입니다.	픽셀이 스텐실 테스트에 통과했지만 뎁스 테스트에 실패한 경우, GPU가 스텐실 버퍼에 대해 수행하는 작업입니다. 앞쪽을 향하는 픽셀에 대한 작업만 정의합니다. zFailOperation이 정의된 경우, 해당 값이 이 값을 오버라이드합니다.

비교 작업 값

C#에서 이러한 값은 Rendering.CompareFunction](../ScriptReference/Rendering.CompareFunction.html) 열거형으로 표시됩니다.

값	Rendering.CompareFunction 열거형에서 상응하는 정수값	기능
`Never`	1	픽셀을 절대 렌더링하지 않습니다.
`Less`	2	레퍼런스 값이 스텐실 버퍼 안의 현재 값보다 작은 픽셀을 렌더링합니다.
`Equal`	3	레퍼런스 값이 스텐실 버퍼 안의 현재 값과 같은 픽셀을 렌더링합니다.
`LEqual`	4	레퍼런스 값이 스텐실 버퍼 안의 현재 값보다 작거나 현재 값과 같은 픽셀을 렌더링합니다.
`Greater`	5	레퍼런스 값이 스텐실 버퍼 안의 현재 값보다 큰 픽셀을 렌더링합니다.
`NotEqual`	6	레퍼런스 값이 스텐실 버퍼 안의 현재 값과 다른 픽셀을 렌더링합니다.
`GEqual`	7	레퍼런스 값이 스텐실 버퍼 안의 현재 값보다 크거나 현재 값과 같은 픽셀을 렌더링합니다.
`Always`	8	픽셀을 항상 렌더링합니다.

스텐실 작업 값

C#에서 이러한 값은 Rendering.Rendering.StencilOp 열거형으로 표시됩니다.

값	Rendering.StencilOp 열거형에서 상응하는 정수값	기능
`Keep`	0	스텐실 버퍼의 현재 콘텐츠를 유지합니다.
`Zero`	1	스텐실 버퍼에 0을 작성합니다.
`Replace`	2	버퍼에 레퍼런스 값을 작성합니다.
`IncrSat`	3	버퍼의 현재 값을 증가시킵니다. 만약 값이 이미 255라면 그대로 255를 유지합니다.
`DecrSat`	4	버퍼의 현재 값을 감소시킵니다. 만약 값이 이미 0이면 그대로 0을 유지합니다.
`Invert`	5	버퍼의 현재 값의 모든 비트를 반전합니다.
`IncrWrap`	7	버퍼의 현재 값을 증가시킵니다. 만약 값이 이미 255라면 0이 됩니다.
`DecrWrap`	8	버퍼의 현재 값을 감소시킵니다. 만약 값이 이미 0이면 255가 됩니다.

예제

Shader "Examples/CommandExample"
{
    SubShader
    {
         // The rest of the code that defines the SubShader goes here.

        Pass
        {    
             // All pixels in this Pass will pass the stencil test and write a value of 2 to the stencil buffer
             // You would typically do this if you wanted to prevent subsequent shaders from drawing to this area of the render target or restrict them to render to this area only
             Stencil
             {
                 Ref 2
                 Comp Always
                 Pass Replace
             }            

             // The rest of the code that defines the Pass goes here.
        }
    }
}

이 예제 코드는 SubShader 블록에서 이 커맨드를 사용하기 위한 구문을 나타냅니다.

Shader "Examples/CommandExample"
{
    SubShader
    {
             // All pixels in this SubShader pass the stencil test only if the current value of the stencil buffer is less than 2
             // You would typically do this if you wanted to only draw to areas of the render target that were not "masked out"
             Stencil
             {
                 Ref 2
                 Comp Less
             }  

         // The rest of the code that defines the SubShader goes here.        

        Pass
        {    
              // The rest of the code that defines the Pass goes here.
        }
    }
}

ShaderLab 커맨드: Offset

ShaderLab 커맨드: UsePass