Quick Reference
| 설정 | 하는 일 | 실수하면 |
|---|---|---|
| Compare function | stored stencil과 reference의 관계를 검사 | Equal과 NotEqual을 반대로 써 effect가 뒤집힘 |
| Reference value | compare와 replace가 기준으로 쓰는 정수 | 같은 bit를 다른 effect가 공유해 충돌 |
| Read mask | 비교에 참여할 bit를 제한 | 필요한 bit를 마스크 밖으로 빼 test가 항상 실패 |
| Write mask | 변경할 bit를 제한 | 다른 시스템의 stencil bit까지 덮어씀 |
| Pass / fail operation | test 결과에 따라 keep, replace, increment 등을 적용 | color는 안 보이는데 stencil만 계속 변함 |
mask pass: color write off, stencil replace 1
effect pass: stencil equal 1, stencil keepTest와 operation
stencil buffer는 depth buffer처럼 화면 위치마다 값을 저장하지만, 깊이 값이 아니라 format이 제공하는 작은 정수 마스크를 저장합니다. 렌더링할 때 current stencil, reference, read mask로 test를 하고, stencil test fail, depth test fail, 둘 다 pass한 경우에 각각 다른 operation을 적용할 수 있습니다.
if stencilTest(storedStencil, reference):
draw fragment
maybe update stencildepth test가 “앞뒤 가림”을 판단한다면, stencil test는 “이 픽셀이 특정 영역에 속하는가”를 판단합니다. 둘은 함께 쓰이는 경우가 많고, 어느 test가 먼저 실패했는지에 따라 적용할 stencil operation도 달라집니다. front face와 back face에 별도 state를 둘 수 있는 API에서는 volume mask처럼 앞·뒤 면을 다르게 누적할 수도 있습니다.
두 pass 패턴
가장 흔한 사용법은 먼저 마스크 영역을 stencil에 기록하고, 다음 pass에서 그 값이 있는 곳만 그리는 방식입니다.
1. mask mesh draw
color write off
stencil write 1
2. effect draw
stencil test equal 1
color write on이 패턴으로 거울, portal, outline, UI clipping, decal 제한 영역을 만들 수 있습니다. 반대로 특정 영역을 제외하고 그리려면 NotEqual 조건을 씁니다. 한 mask가 여러 효과를 위해 필요하면 bit 0은 portal, bit 1은 character outline처럼 소유 bit를 정하고, read/write mask로 자기 bit만 읽고 써야 합니다.
depth와 color state의 조합
| 목표 | color write | depth test / write | stencil operation |
|---|---|---|---|
| 화면 마스크만 기록 | off | 필요 없으면 off / off | pass에서 Replace |
| 보이는 surface에만 mask | off | on / 보통 off | depth pass 때 Replace |
| mask 내부 effect | on | effect 성격에 따름 | Equal, Keep |
| mask 외부 effect | on | effect 성격에 따름 | NotEqual, Keep |
| volume 안쪽 표시 | 보통 off인 marking pass | front/back depth fail 규칙 필요 | increment/decrement 같은 operation |
stencil은 픽셀 단위로 딱 끊기는 마스크에 강합니다. 부드러운 경계, feather, gradient가 필요하면 alpha texture나 별도 mask texture가 더 적합합니다. 단순한 사각형 영역이라면 scissor가 stencil target과 별도 pass 없이 더 싸고 단순합니다.
state 누수와 디버깅
stencil 값은 attachment 전체에서 공유되는 render state 자원입니다. 어떤 pass가 값을 clear하고 쓰는지 명확하지 않으면 이후 pass가 예상치 못한 영역에서 실패할 수 있습니다. 마스크 pass에서 color write만 끄고 depth write를 켜 두면 보이지 않는 mask mesh가 뒤 geometry를 막는 오류도 생깁니다.
| 증상 | 확인할 값 |
|---|---|
| effect가 화면 전체에 나타남 | stencil attachment 존재, compare function, reference/read mask |
| effect가 어디에도 안 나타남 | mask pass의 color/depth/stencil state와 write mask |
| 다른 UI나 outline이 망가짐 | bit ownership, clear 시점, write mask |
| 카메라 각도에 따라 mask가 사라짐 | mask pass depth test, cull mode, front/back state |
참고 링크
1 sources