12. 트러블슈팅 / FAQ

이 챕터는 URP/SRP/셰이더를 만지면서 자주 겪는 문제를 “증상 → 원인 → 해결 절차”로 정리합니다.

Q1. Render Feature를 만들었는데 아무 변화가 없다

체크

• Renderer Asset(Forward Renderer 등)에 Feature가 추가되어 있는가
• 카메라가 그 Renderer를 사용하는 URP Asset을 쓰는가
• 패스가 EnqueuePass 되는가(브레이크포인트/로그)

흔한 원인

• AddRenderPasses가 조건문 때문에 실행되지 않음
• 패스 이벤트가 너무 이르거나/늦어서 기대한 타이밍이 아님

Q2. RenderGraph에서 텍스처가 검게 나온다 / 항상 0이다

체크

• builder에 읽기/쓰기 선언이 올바른가 (UseTexture/SetRenderAttachment)
• 실제로 렌더 타겟이 바인딩되었는가
• 패스 함수에서 샘플링/블릿이 올바른가

흔한 원인

• “읽기 선언” 없이 텍스처를 샘플링 → 리소스 준비/배리어 누락
• source와 destination을 동일 텍스처로 설정(특히 블릿) → 정의되지 않은 동작

Q3. Forward+에서 추가 라이트가 안 먹는다

체크

• #pragma multi_compile _ _CLUSTER_LIGHT_LOOP 포함 여부
• Forward+ 활성화 여부(URP Asset 설정)
• 추가 라이트 키워드(_ADDITIONAL_LIGHTS*) 포함 여부

관련: 07. Forward/Forward+/Lights

Q4. Depth/Normals 텍스처가 없어서(또는 샘플이 0) 화면 기반 이펙트가 망가진다

증상

• Outline/SSAO가 항상 꺼져 보이거나, 가장자리가 이상함
• Depth 기반 연산이 항상 0 또는 1로 나옴
• 노말 기반 연산이 의미 없는 값으로 나옴

체크(우선순위)

1. 해당 카메라/렌더러에서 Depth/Normals 생성이 정말 켜져 있는가?
   • Full Screen Pass Renderer Feature라면 Requirements에서 Depth/Normal을 체크
   • 커스텀 패스라면 URP에서 요구/생성 흐름이 어떻게 되는지 소스/문서로 확인
2. RenderGraph Viewer에서 Depth/Normals 리소스가 실제로 생성되는가?
3. 셰이더에서 include/샘플링/선형화가 올바른가?
   • Raw depth → Linear depth 변환을 했는가

관련: 08. URP HLSL 라이브러리 지도, 10. 포스트/풀스크린 패스

Q5. SRP Batcher가 꺼진 것 같다 / 성능이 갑자기 떨어졌다

체크

• 머티리얼 프로퍼티가 UnityPerMaterial CBUFFER에 정리되어 있는가
• 조건부 컴파일로 CBUFFER 레이아웃이 달라지지 않는가
• UNITY_DOTS_INSTANCING_* 등 인스턴싱/배칭 관련 키워드를 무리하게 섞지 않았는가

관련: 09. URP 호환 셰이더 작성

Q6. 내 패스가 씬뷰/게임뷰/특정 카메라에서만 동작한다

체크

• CameraType 필터링을 하고 있지 않은가?
• URP Asset이 씬뷰와 게임뷰에서 같은 설정인가?
• 카메라 스태킹/오버레이 카메라를 쓰고 있다면, 어느 카메라에 패스를 적용했는가?

관련: 03. URP 아키텍처

Q7. 해상도/스케일이 맞지 않는다(흔들림, 블러, 픽셀 오프셋)

원인 후보

• URP Render Scale(동적 해상도) 적용 여부를 고려하지 않고 RT를 생성
• XR/카메라별 타겟 크기 차이를 무시
• RTHandle/TextureHandle desc를 카메라 컬러와 다르게 잡음

해결 절차

• 카메라 컬러 텍스처 desc를 기반으로 임시 텍스처를 만들 것(RenderGraph)
• 가능하면 RTHandle을 사용해 스케일을 URP와 맞출 것

관련: 05. 텍스처/ID/핸들