22. URP Lit Call Flow & Edit Points (URP 17.3.0)

이 챕터는 “URP Lit을 공부했는데 어디를 고쳐야 할지 모르겠다”를 끝내기 위한 실전 지도입니다.

• Lit Forward(UniversalForward) 프래그먼트의 실제 흐름을 “정확 레퍼런스”로 고정하고
• 커스터마이즈를 어디에 넣어야 호환성을 깨지 않는지(=edit points)
• 무엇을 건드리면 바로 깨질 위험이 큰지(=risk points)

를 단계별로 정리합니다.

22.0 정확 레퍼런스(Generated)

이 챕터의 심볼/정의/호출처는 아래 generated 문서를 1차 원본으로 삼습니다.

• Lit 핵심 심볼 xref: book/generated/urp-17.3.0/xref/lit-key-symbols.md
• 함수 시그니처: book/generated/urp-17.3.0/symbols/functions.md
• 구조체/필드: book/generated/urp-17.3.0/symbols/structs.md
• Lit Pass/Include 맵: book/generated/urp-lit-map.md

22.1 Lit Forward 엔트리 고정(정의 위치/시그니처)

URP 17.3.0 기준:

• LitPassVertex
  • 정의: <URP>/Shaders/LitForwardPass.hlsl:158
  • 시그니처: Varyings LitPassVertex(Attributes input)
• LitPassFragment
  • 정의: <URP>/Shaders/LitForwardPass.hlsl:223
  • 핵심: void + out SV_Target* 출력

LitPassFragment의 출력 구조(요약):

void LitPassFragment(
    Varyings input,
    out half4 outColor : SV_Target0
    // + optional: outRenderingLayers : SV_Target1
)

왜 return half4가 아닌가?
MRT/Rendering Layers 같은 기능 확장을 위해 “출력 계약을 out 파라미터로 유지”하는 구조가 더 안전합니다.
관련: 16. URP Lit include 체인 맵

22.2 Lit Forward의 실제 호출 흐름(URP 17.3.0)

URP 17.3.0 LitForwardPass의 핵심 흐름은 아래로 요약됩니다(정확 호출 지점은 xref에 있음).

1. (옵션) Parallax / LODFade
2. InitializeStandardLitSurfaceData로 SurfaceData 구성
3. InitializeInputData로 InputData 구성
4. (옵션) Decal(DBuffer)
5. InitializeBakedGIData 등으로 baked GI 준비
6. UniversalFragmentPBR로 조명 합성
7. Fog/Alpha 처리 후 출력

핵심 함수 정의 위치(URP 17.3.0):

Mermaid로 흐름 고정:

Parse error on line 1:
flowchart TD  A[Lit
^
Expecting 'NEWLINE', 'SPACE', 'GRAPH', got 'ALPHA'

22.3 Edit Points(안전한 커스터마이즈 지점) — “어디를 바꾸면 덜 깨지나?”

URP Lit은 주변 기능(Forward+/Decal/Rendering Layers/GI/ShadowMixing 등)과 강하게 결합되어 있습니다. 따라서 “호환성을 유지하는 커스터마이즈”는 라이트 루프/패스 계약을 유지한 채 내부 값을 조정하는 방식이 가장 안전합니다.

22.3.1 Edit Point A: SurfaceData를 조정(가장 안전)

대상:

• surfaceData.albedo, surfaceData.normalTS, surfaceData.smoothness, surfaceData.emission 등

장점:

• Pass 계약/Forward+ 루프/그림자/GI 결합을 유지하면서, 재질 모델을 바꿀 수 있음

리스크:

• 낮음(단, alpha/_ALPHATEST_ON과 결합되면 ShadowCaster/DepthOnly까지 확인 필요)

검증:

• Frame Debugger에서 ShadowCaster/DepthOnly/DepthNormals가 함께 정상인지 확인
• SRP Batcher(머티리얼 상수) 유지 여부 확인(Chapter 09)

22.3.2 Edit Point B: InputData를 조정(중간 난이도)

대상:

• inputData.normalWS, inputData.viewDirectionWS, inputData.shadowCoord, inputData.normalizedScreenSpaceUV 등

장점:

• 뷰/공간 기반 효과(예: custom fresnel, view-dependent term)를 넣기 쉬움

리스크:

• 중간
  • 특히 normalizedScreenSpaceUV를 망치면 Forward+ 클러스터 루프가 깨질 수 있음

검증:

• Forward+ ON에서 추가 라이트가 정상인지 확인(Chapter 07)

22.3.3 Edit Point C: UniversalFragmentPBR 전/후로 색을 조정(용도 명확할 때만)

대상:

• half4 color = UniversalFragmentPBR(...) 결과를 후처리(rim, toon, custom tone)하거나
• PBR 입력을 정규화(예: roughness clamp)하는 식

리스크:

• 중간~높음
  • 물리 기반 가정이 깨질 수 있고, Debug Display/Decal/Rendering Layers와 결합할 때 예상 밖 결과가 나올 수 있음

검증:

• Debug Display/후처리/Decal이 켜진 상태에서 확인

22.3.4 Risk Point: “추가 라이트 루프를 직접 구현”(가장 위험)

Forward+에서는 GetAdditionalLightsCount()가 0일 수 있다는 계약이 존재합니다.

• 정의: <URP>/ShaderLibrary/RealtimeLights.hlsl:271

따라서 추가 라이트 루프를 직접 구현해야 한다면, 최소한 URP의 매크로를 사용하세요.

uint count = GetAdditionalLightsCount();
LIGHT_LOOP_BEGIN(count)
    Light light = GetAdditionalLight(lightIndex, inputData, shadowMask, aoFactor);
    // accumulate...
LIGHT_LOOP_END

자세한 내용: 07. Forward/Forward+/Lights

22.4 Edit Point 매트릭스(요약)

22.5 검증 루틴(필수)

1. generated로 정의 위치 고정: book/generated/urp-17.3.0/xref/lit-key-symbols.md
2. Frame Debugger: 내 오브젝트가 어떤 LightMode Pass로 그려지는지 확인
3. Forward+ ON/OFF 비교: 추가 라이트가 두 모드에서 모두 정상인지 확인
4. DepthNormals/MotionVectors: SSAO/TAA 등 기능이 켜진 프로젝트라면 해당 pass가 실제로 소비되는지 확인

문제 해결 플레이북: book/24-debugging-playbook-unity6-urp.md