언리얼 엔진의 셰이더 디버깅 워크플로 | 언리얼 엔진 5.7 문서

셰이더를 디버깅하는 주된 방식은 콘솔 변수 r.Shaders.Symbols 를 활성화하는 것입니다. 이렇게 하면 RenderDoc나 PIX와 같은 플랫폼별 프로그램으로 디버깅할 수 있도록 엔진에서 셰이더를 준비합니다.

이 콘솔 변수와 아래의 변수들은 플랫폼별로 오버라이드할 수 있습니다. 추가 셰이더 컴파일을 컨트롤하는 데 중요한 부분입니다.

셰이더 디버깅 워크플로

아래에서는 3가지 셰이더 디버깅 워크플로를 설명합니다. 각각의 방식에서 셰이더를 디버깅하고 싶은 플랫폼에 대해 엔진 환경설정 파일 을 수정해야 합니다. 예를 들어, Android에 대해 셰이더를 디버깅하고 싶다면 AndroidEngine.ini 파일에 콘솔 변수를 추가해야 합니다.

예시: 플랫폼별 셰이더 디버거 사용하기

특정 플랫폼을 위한 셰이더 디버거를 사용해 해당 플랫폼에서 쿠킹된 게임의 셰이더를 디버깅하려고 합니다.

원하는 [플랫폼]Engine.ini 파일에 다음을 추가합니다.

	[ShaderCompiler]
	r.Shaders.Symbols=1

에디터나 언리얼 빌드 툴(UBT)로 해당 플랫폼에 대해 게임을 쿠킹합니다. 플랫폼에 대해 GPU 캡처를 생성합니다. 셰이더 심볼 경로가 필요한 경우 폴더 내 프로젝트 폴더 경로/Saved/ShaderSymbols/Platform 을 지정합니다.

예시: 빌드 머신만 Zip 파일에 심볼을 쓰도록 하기

항상 플랫폼에 대해 셰이더 심볼을 빌드하고 빌드 머신만 이 심볼을 .zip 파일에 쓰려고 합니다.

원하는 [플랫폼]Engine.ini 파일에 다음을 추가합니다.

	[ShaderCompiler]
	r.Shaders.GenerateSymbols=1

	[ShaderCompiler_BuildMachine]
	r.Shaders.WriteSymbols=1
	r.Shaders.WriteSymbols=1

이제 빌드 머신이 아래와 같은 .zip 파일을 생성합니다. 내 프로젝트 폴더 경로/Saved/ShaderSymbols/Platform/ShaderSymbols.zip.

예시: 로컬에서 셰이더 디버깅하기

그래픽 프로그래머가 2번 예시와 동일한 구성으로 프로젝트를 작업하고 있으며 셰이더를 로컬에서 디버깅하려고 합니다.

이 경우 사용자는 로컬에서 [플랫폼]Engine.ini 를 수정하고 다음을 추가해야 합니다.

	[ShaderCompiler]
	r.Shaders.WriteSymbols=1

프로젝트를 쿠킹할 때 셰이더는 내/프로젝트/폴더/경로/Saved/ShaderSymbols/Platform 등의 경로에 작성됩니다.

콘솔 변수 요약

다음은 셰이더 디버깅에 사용할 수 있는 콘솔 변수입니다.

콘솔 변수	설명
`r.Shaders.Symbols`	심볼을 생성해 셰이더 디버깅을 활성화합니다. 플랫폼에서 외부 심볼을 요구하는 경우 이 심볼들은 디스크에 작성됩니다. 그렇지 않으면 런타임에서 로드되는 셰이더 데이터 내부에 저장됩니다. 플랫폼별로 오버라이드 가능합니다.
`r.Shaders.ExtraData`	셰이더 이름과 그 밖의 플랫폼별 추가 셰이더 데이터를 생성합니다. 이 변수는 플랫폼별로 오버라이드 가능합니다.
`r.Shaders.GenerateSymbols`	심볼을 생성하지만 디스크에 쓰지는 않습니다. 이 변수는 플랫폼별로 오버라이드 가능합니다.
`r.Shaders.WriteSymbols`	플랫폼에서 외부 심볼을 지원하는 경우 심볼이 생성되면 디스크에 작성합니다. 이 변수는 플랫폼별로 오버라이드 가능합니다.
`r.Shaders.SymbolPathOverride`	플랫폼에서 외부 심볼을 지원하는 경우 이 콘솔 변수를 사용해 심볼이 작성되는 위치를 오버라이드할 수 있습니다.
`r.Shaders.WriteSymbols.Zip`	플랫폼에서 외부 심볼을 지원하며 심볼을 디스크에 작성해야 하는 경우 심볼을 여러 개의 개별 파일이 아닌 하나의 `.zip` 파일로 작성합니다.
`r.Shaders.AllowUniqueSymbols`	플랫폼에서 외부 심볼을 지원하는 경우 소스 파일이 아닌 결과물 셰이더를 바탕으로 심볼 파일 이름을 생성합니다. 심볼 크기가 상당히 증가할 수 있으므로 활성화를 권장하지 않습니다.

플랫폼 오버라이드

[플랫폼]Engine.ini 파일에 특수 섹션을 추가하면 플랫폼별로 셰이더 심볼 콘솔 변수를 오버라이드할 수 있습니다.

예를 들어, Android 플랫폼에서 셰이더 심볼 콘솔 변수를 오버라이드하려면 AndroidEngine.ini 파일에 아래와 같은 텍스트를 추가합니다.

	[ShaderCompiler_BuildMachine]
	콘솔 변수 입력

UE4 이후 변경사항

언리얼 엔진 5에서 셰이더 디버깅에 사용되는 콘솔 변수가 변경되었습니다. 아래 표는 기존 UE4 콘솔 변수와 UE5에서 사용되는 새로운 변수 이름을 하이라이트한 것입니다. 프로젝트를 UE5로 이주하는 경우 생성된 데이터와 디버그 셰이더를 계속 사용하려면 아래 콘솔 변수를 사용하는 환경설정 파일을 업데이트해야 합니다.

기존 이름	변경된 이름	설명
`r.Shaders.KeepDebugInfo`	`r.Shaders.Symbols`	심볼을 생성하고 이를 콘솔용 디스크에 작성하여 셰이더 디버깅을 활성화합니다. PC 심볼은 계속 인라인에 저장됩니다.
See note.	`r.Shaders.ExtraData`	셰이더 이름과 그 밖의 '추가' 셰이더 데이터를 생성합니다.
`r.Shaders.PrepareExportedDebugInfo`	`r.Shaders.GenerateSymbol`	심볼을 생성하지만 디스크에 작성하지는 않습니다(심볼은 DDC에 저장됩니다).
`r.Shaders.ExportDebugInfo`	`r.Shaders.WriteSymbols`	생성된 심볼을 디스크에 작성합니다.
`r.Shaders.AllowUniqueDebugInfo`	`r.Shaders.AllowUniqueSymbols`	셰이더 소스를 기반으로 심볼 연결을 생성합니다(디폴트로 해제).
`r.Shaders.ExportDebugInfo.Zip`	`.Shaders.WriteSymbols.Zip`	모든 심볼을 단일한 `.zip` 파일로 디스크에 작성할 수 있게 합니다.

r.Shaders.KeepDebugInfo 는 심볼만 필요한 경우에 런타임 셰이더 데이터를 변경사항을 제거할 수 있도록 r.Shaders.Symbols 및 r.Shaders.ExtraData 로 나뉩니다. 이 방식은 최종 셰이더 데이터를 변경하지 않고 출시 빌드의 심볼을 생성할 수 있으므로 내보낸 디버그 정보를 지원하는 플랫폼에 특히 유용합니다.