셰이더 컴파일 프로세스 디버깅

개발하는 과정에 언리얼 엔진이 플랫폼의 셰이더 컴파일러에 무엇을 전송하는지 파악해보는 것이 좋습니다. 이 페이지에 포함된 정보로 이와 관련된 문제를 디버깅할 수 있습니다.

중간 셰이더 덤프 활성화하기

엔진 설치로 디버깅을 시작하려면, Engine/Config 폴더에 있는 ConsoleVariables.ini 구성 파일에서 사전 정의된 콘솔 변수를 활성화해야 합니다. [Startup] 섹션에서 이렇게 생긴 콘솔 변수 목록을 찾으세요.

	[Startup]

	; 셰이더 컴파일에 관한 상세 로그와 오류 재시도 기회를 받으려면 언코멘트합니다.
	r.ShaderDevelopmentMode=1
	; Saved 폴더에서 셰이더를 덤프하려면 언코멘트합니다.
	; 경고: 이것을 한동안 남겨두면 다수의 작은 파일과 폴더로 하드 드라이브가 가득 차게 됩니다.
	r.DumpShaderDebugInfo=1
	; 활성화된 경우, SCW 크래시가 현재 작업자의 작업 목록을 출력합니다.
	r.ShaderCompiler.DumpQueuedJobs=1
	; 활성화된 경우, 셰이더를 덤프할 때 ShaderCompilerWorker -direct 모드와 사용할 추가 파일이 생성됩니다.
	r.DumpShaderDebugWorkerCommandLine=1
	; 활성화된 경우, 모든 셰이더를 로드할 때 셰이더 컴파일러 경고가 해당 셰이더 로그에 전송됩니다(DDC 또는 셰이더 컴파일 작업에서).
	r.ShaderCompiler.EmitWarningsOnLoad=1
Copy full snippet

[Startup] ; 셰이더 컴파일에 관한 상세 로그와 오류 재시도 기회를 받으려면 언코멘트합니다. r.ShaderDevelopmentMode=1 ; Saved 폴더에서 셰이더를 덤프하려면 언코멘트합니다. ; 경고: 이것을 한동안 남겨두면 다수의 작은 파일과 폴더로 하드 드라이브가 가득 차게 됩니다. r.DumpShaderDebugInfo=1 ; 활성화된 경우, SCW 크래시가 현재 작업자의 작업 목록을 출력합니다. r.ShaderCompiler.DumpQueuedJobs=1 ; 활성화된 경우, 셰이더를 덤프할 때 ShaderCompilerWorker -direct 모드와 사용할 추가 파일이 생성됩니다. r.DumpShaderDebugWorkerCommandLine=1 ; 활성화된 경우, 모든 셰이더를 로드할 때 셰이더 컴파일러 경고가 해당 셰이더 로그에 전송됩니다(DDC 또는 셰이더 컴파일 작업에서). r.ShaderCompiler.EmitWarningsOnLoad=1

각 콘솔 변수 옆에 있는 ;(세미콜론) 을 제거해 사용을 활성화하면, 위의 예에 나온 코드처럼 보입니다.

디버그 모드에서 ShaderCompileWorker 빌드하기

UnrealBuildTool(UBT)는 기본적으로 툴을 위한 프로젝트를 생성하며, 항상 개발 모드에서 컴파일합니다. 디버깅 목적이라면 프로젝트 코드 디버깅의 심볼을 포함한 디버그 모드에서 엔진과 프로젝트를 빌드하는 것을 권장합니다.

디버그 모드에서 프로젝트를 빌드하려면 다음 작업을 수행하세요.

1. 빌드(Build) 메뉴에서 열 수 있는 구성 매니저(Configuration Manager) 를 사용해 Visual Studio의 솔루션 프로퍼티를 변경합니다.
2. ShaderCompileWorker(SCW) 드롭다운을 Debug_Program 으로 설정합니다.

이러한 작업에 대한 추가 정보는 Build Configuration Reference 페이지를 참조하십시오.

중간 파일 생성하기

셰이더를 디버깅하려면 우선 디버깅할 파일을 생성해야 합니다. 그러기 위해서는 후속 컴파일에서 생성된 파일을 덤프할 수 있도록 중간 셰이더를 덤프하기 위해 콘솔 변수를 활성화해야 합니다.

이 페이지의 Enabling Dumping of Intermediate Shaders 섹션에서 적절한 콘솔 변수를 활성화하는 방법을 참조하십시오.

공백을 추가하거나, Engine/Shaders 폴더에 위치한 Common.usf 파일에 사소한 변경을 추가해 모든 셰이더를 강제로 리빌드한 후 에디터를 다시 실행하세요. 이 작업은 모든 셰이더의 리컴파일을 트리거하고 프로젝트의 Saved/ShaderDebugInfo 폴더에 있는 모든 중간 파일을 덤프합니다.

특정 머티리얼을 디버깅하는 경우 변경을 트리거하도록 노드를 움직이는 등의 사소한 변경이나 원하는 변경을 수행할 수 있습니다. 셰이더 파일을 다시 덤프하기 위해 툴바를 사용해 머티리얼의 변경 사항을 저장 또는 적용 하세요.

덤프된 셰이더의 폴더 구조

덤프된 셰이더가 생성한 폴더 경로에는 관련 정보가 포함됩니다. 덤프된 셰이더 경로의 예를 살펴보고 일부를 분석해보겠습니다.

> D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\BPPSFNoLMPolicy\BasePassPixelShader.usf

첫 번째 부분은 프로젝트의 루트 경로입니다. 이 경우에는 루트 경로가 Tappy Chicken이라는 프로젝트입니다.

> D:\UE4\Samples\Games\TappyChicken\

경로의 다음 부분은 덤프된 셰이더가 저장된 위치입니다.

> D:\UE4\Samples\Games\TappyChicken\ Saved\ShaderDebugInfo\

모든 셰이더 포맷 및/또는 플랫폼마다 서브폴더가 생성됩니다. 이 경로는 PC D3D Shader Model 5에 해당하는 서브폴더를 생성합니다.

> D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\ PCD3D_SM5\

머티리얼별 폴더와 글로벌 이라는 특별한 폴더가 생성됩니다. 여기 보이는 디버그 셰이더는 M_Egg 머티리얼에 대한 것입니다.

> D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\ M_Egg\

셰이더는 맵에서 대부분 메시/컴포넌트 타입으로 구분되는 버텍스 팩토리에 따라 그룹으로 정렬됩니다. 이 경로는 로컬 버텍스 팩토리 를 나타내는 LocalVF 를 가리킵니다.

> D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\ LocalVF\

경로의 마지막 부분은 머티리얼에 사용된 기능의 순열입니다.

> D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\ BPPSFNoLMPolicy\

콘솔 변수 r.DumpShaderDebugShortNames=1 이 ConsoleVariables.ini 파일에 설정되었기 때문에, 파일 길이를 줄이기 위해 이름이 단축되었습니다.

예를 들어 콘솔 변수가 활성화되지 않았다면 경로는 다음과 같을 것입니다.

> D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\FLocalVertexFactory\TBasePassPSFNoLightMapPolicy\

셰이더 덤프 폴더에는 생성된 배치 파일, 텍스트 파일, usf 파일이 포함됩니다.

• usf 파일은 플랫폼의 컴파일러로 전달되는 마지막 셰이더 코드로, 프리 프로세서 이후에 실행됩니다.
• 배치 파일은 플랫폼 컴파일러를 호출하여 중간 코드를 살펴보는 데 사용됩니다.
• DirectCompile.txt 라는 이름의 텍스트 파일에는 ShaderCompileWorker로 디버깅하기 위한 명령줄이 포함됩니다.

ShaderCompileWorker를 사용해 디버깅하기

ShaderCompileWorker는 다음 명령줄을 사용해 플랫폼 컴파일러에 대한 호출을 디버깅할 수 있습니다.

	PathToGeneratedUsfFile -directcompile -format=ShaderFormat -ShaderType -entry=EntryPoint {plus platform specific switches}
Copy full snippet

PathToGeneratedUsfFile -directcompile -format=ShaderFormat -ShaderType -entry=EntryPoint {plus platform specific switches}

• PathToGeneratedUsfFile 은 ShaderDebugInfo 폴더의 마지막 usf 파일입니다.
• ShaderFormat 은 디버깅하려는 셰이더 플랫폼 포맷입니다(이 경우에는 PCD3D_SM5).
• ShaderType 은 아래의 셰이더 타입에 각각 해당하는 vs/ps/gs/hs/ds/cs일 수 있습니다.

• EntryPoint 는 usf 파일의 이 셰이더에 대한 엔트리 포인트의 함수 이름입니다.

예:

> D:\UE4\Samples\Games\TappyChicken\Saved\ShaderDebugInfo\PCD3D_SM5\M_Egg\LocalVF\BPPSFNoLMPolicy\BasePassPixelShader.usf -format=PCD3D_SM5 -ps -entry=Main

D3D11ShaderCompiler.cpp의 CompileD3D11Shader() 함수에 브레이크포인트를 추가하면, 이 명령줄로 SCW를 실행해 엔진이 플랫폼 컴파일러를 호출하는 과정에 개입할 수 있습니다.

생성된 usf 파일 옆에 DirectCompile.txt 라는 파일을 덤프하는 ConsoleVariables.ini 파일의 콘솔 변수 r.DumpShaderDebugWorkerCommandLine=1 을 활성화하면 이 명령줄을 직접 복사할 수 있습니다.