GPU 덤프 뷰어 툴

DumpGPU 는 캡처된 프레임의 중간 렌더링 리소스 바이너리를 디스크에 덤프하는 콘솔 명령어로, 플랫폼에 관계없이 사용할 수 있습니다. 덤프는 .json 및 .bin 파일로 저장되며, 이 파일은 가벼운 웹페이지 뷰어를 사용해 탐색할 수 있습니다.

이 명령은 여러 목적으로 사용됩니다.

• 타사 GPU 디버깅 툴을 설치하거나 에디터를 재시작할 필요 없이 모든 빌드에 사용할 수 있습니다.
• 아래와 같은 모든 지원 플랫폼에서 덤프가 가능합니다.
• Windows D3D11, D3D12, Vulkan
• Linux Vulkan
• Mac Metal, AGX
• PlayStation 4 및 PlayStation 5
• XboxOne, Xbox Series X/S
• Nintendo Switch
• iOS 및 Android
• Chrome과 WebGL 2.0 이용 가능 GPU를 지원하는 모든 플랫폼에서 인터페이스를 탐색할 수 있습니다.
• 간단하고 플랫폼에 구애받지 않기 때문에 누구든 문제가 발생했을 때 GPU 덤프를 만들 수 있습니다.
• 에디터로 작업하는 동안 재현이 어려운 예상치 못한 문제에 부딪히는 아티스트에게 유용합니다.
• 리소스 바이너리를 탐색하는 마찰을 최소화합니다.
• 플랫폼 GPU 캡처로 리소스를 분석하려면 올바른 SDK와 개발 키트가 필요한 경우가 많습니다. GPU 덤프 뷰어를 사용하면 개발자가 버그를 더 잘 분류할 수 있을 뿐 아니라, 문제와 관련된 모든 플랫폼에서 리소스를 살펴볼 수 있습니다.
• 새로운 렌더러 기능을 작성하는 그래픽 프로그래머가 이 툴을 사용하면 문제가 발생했을 때, 분석을 위한 반복작업 워크플로를 더 빠르게 진행할 수 있습니다.

덤핑 프로세스

프레임의 GPU 덤프 생성 과정을 시작하려면 콘솔 창에 명령어 DumpGPU 를 입력하거나 키보드 단축키 CTRL + Shift + / 를 사용합니다.

명령이 시작되면 중간 렌더링 리소스를 디스크에 복사해야 합니다. 따라서 메모리 문제의 발생을 막기 위해 캡처 속도가 저하됩니다. 이렇게 하면 덤프가 문제 재현이 가능했던 프로세스와 충돌하지 않고 재현이 드물거나 어려운 문제의 데이터를 높은 신뢰도로 수집할 수 있습니다.

	GlobalDefinitions.Add("ALLOW_CONSOLE_IN_SHIPPING=1");
	GlobalDefinitions.Add("ALLOW_DUMPGPU_IN_SHIPPING=1");

Copy full snippet

GPU 덤프의 위치 저장하기

GPU 덤프를 수행하면 기본적으로 프로젝트 루트 디렉터리 안의 Saved/GPUDumps 에 덤프가 저장됩니다. 데스크톱 플랫폼의 경우 덤프를 완료하면 자동으로 덤프 위치의 파일 탐색기 창이 열립니다.

스테이지(Staged) 빌드의 경우 스테이지가 저장된 디렉터리에 덤프가 저장됩니다. 저장 경로는 [스테이지 디렉터리] / [플랫폼 이름] / [프로젝트 이름] / Saved / GPUDumps 입니다.

모바일 플랫폼 덤프 저장 위치

모바일 플랫폼의 경우 GPU 덤프가 다음과 같은 위치에 저장됩니다.

덤프 세팅

아래 명령을 사용하면 생성된 GPU 덤프를 필요에 맞춰 수정할 수 있습니다.

DumpGPU 명령이 GPU 덤프 뷰어를 복사하는 방식

GPU 덤프 뷰어의 소스 코드는 엔진 소스와 함께 이용할 수 있으며, /Engine/Extras/GPUDumpViewer 에서 확인할 수 있습니다.

출시(Shipping)가 아닌 빌드의 경우 GPU 덤프 뷰어가 자동으로 스테이징 디렉터리에 복사됩니다. 그리고 프레임 덤핑을 위해 DumpGPU 명령이 호출되면 스테이지 디렉터리의 파일이 덤핑 디렉터리로 복사됩니다.

출시 스테이지 빌드의 경우 스테이지 디렉터리에 GPU 덤프 뷰어의 HTML 소스가 존재하지 않아 덤핑 디렉터리로 복사되지 못할 수 있습니다. 이 경우 덤핑 디렉터리에 저장소의 //Engine/Extras/GPUDumpViewer 애플리케이션을 복사하여 덤프를 열 수 있습니다.

GPU 덤프 뷰어

GPU 덤프 뷰어(GPU Dump Viewer)는 HTML 웹 기반 애플리케이션입니다. 이 뷰어에서는 언리얼 엔진 렌더러의 작동 방식에 관한 정보를 이용할 수 있습니다.

먼저 GPU 덤프가 발생하면 운영체제가 저장된 덤프의 폴더 위치를 엽니다. OpenGPUDumpViewer.bat 파일을 더블클릭하면 Chrome으로 뷰어를 열 수 있습니다.

뷰어가 시작되면 새 Chrome 창이 열리고 GPU 덤프 뷰어(GPUDumpViewer) 가 실행됩니다.

Chrome의 새 시크릿 모드 창에서 GPU 덤프 뷰어 웹 애플리케이션이 열립니다.

GPU 덤프 뷰어는 웹 애플리케이션으로, 다른 브라우저 기반 페이지나 애플리케이션과 비슷하게 작동합니다. 아래에서는 GPU 덤프 뷰어를 사용하는 간단한 팁을 소개합니다.

• 빠른 액세스를 위해 모든 링크는 클릭이 가능하며 새 탭으로 열립니다.
• 뒤로 가기, 앞으로 가기 버튼을 사용하여 이전에 본 페이지로 이동할 수 있습니다.
• 다른 사람과 캡처를 공유하려는 경우, 링크의 # 뒷부분을 공유하면 패널과 덤프 일부로 직접 연결됩니다. 예를 들어, #display_output_resource(96,’0000000067e1bfa0.mip0’); 를 공유합니다.

1. 제목 표시줄과 패널
2. 패스 및 리소스 트리
3. 뷰어

제목 표시줄과 패널

메인 제목 표시줄에는 덤프를 만들 때 사용된 프로젝트 이름, 운영체제, RHI, 빌드 정보가 간략하게 표시됩니다. 클릭해서 프로젝트 기본 정보, 사용된 콘솔 변수, 프로젝트 로그 사본을 볼 수 있는 정보 패널도 있습니다.

정보 패널

정보(Infos) 패널에는 GPU 덤프 내용 요약이 담겨 있습니다. 시스템, 드라이버, 엔진 빌드에 관한 유용한 정보와 백 버퍼의 최종 이미지 스크린샷을 확인할 수 있습니다.

CVar 패널

CVar 패널에서는 덤프가 발생하기 이전에 실행된 렌더링 콘솔 변수 목록을 검색할 수 있습니다. 이 목록에는 .r.* 이나 .sg.* 로 시작하거나 RHI 키워드를 포함한 변수가 나열되어 있습니다.

로그 패널

로그(Log) 패널은 덤핑이 완료되면 덤프와 함께 저장되는 프로젝트 로그의 사본을 제공합니다. 덤핑 과정에서 경고가 발생했는지도 여기서 볼 수 있습니다.

뷰어

보기 영역에는 선택된 여러 패스, 텍스처, 버퍼의 정보가 표시됩니다.

패스 뷰어

이벤트 계층구조에서 패스(Pass) 를 클릭하면 패스가 읽고 변경하는 리소스만 표시됩니다. 자동으로 첫 출력 리소스(텍스처 또는 버퍼)가 열립니다.

뷰어 상단에 있는 패스 이름 옆에는 패스 파라미터(Pass Parameters) 버튼이 있습니다.

이 버튼을 클릭하면 원본 패스 파라미터가 표시됩니다. 간혹 패스 파라미터가 셰이더 파라미터인 경우도 있습니다. 예를 들어, FComputerShaderUtils::AddPass() 또는 FPixelShaderUtils::AddPass() 가 사용되는 경우입니다.

패스 파라미터를 사용하면 CPU의 NaN 인스턴스가 셰이더 파라미터를 통해 셰이더에 영향을 미치지 않는다는 것을 검증할 수 있습니다.

텍스처 뷰어

패스 뷰의 입력 리소스(Input Resources) 또는 출력 리소스(Output Resources) 목록에서 텍스처(Texture) 를 선택하면 뷰어로 픽셀을 시각화할 수 있습니다.

WebGL 2.0의 캔버스로 (RHI가 덤프 디렉터리로 복사한) 원본 리소스 바이너리를 로드하고 비교적 간단한 WebGL 픽셀 셰이더로 표시해 텍스처를 볼 수 있습니다. 32비트 UINT 텍스처 등 WebGL에서 지원하지 않는 포맷의 경우 픽셀 포맷을 정확히 시뮬레이션할 수 있도록 추가 작업이 이루어집니다.

텍스처 뷰어에는 표시되는 텍스처와 더불어 몇 가지 버튼이 있습니다.

• 뷰어에 표시되는 텍스처의 크기를 설정하거나 창에 맞춥니다.

• 클립보드로 복사(Copy to clipboard) 를 눌러 현재 표시되는 텍스처와 관련 리소스 정보를 클립보드로 복사합니다. 텍스트 에디터나 이메일에 붙여 넣으면 아래와 같은 내용이 나타납니다.

  
• 텍스처 뷰 모드는 3개의 버튼을 사용하여 바꿀 수 있습니다. 시각화(Visualization) 는 표준 텍스처 뷰 모드를 가리키고, NaN (Not a Number) 및 Inf (Infinity) 뷰 모드는 해당하는 각 타입의 픽셀 오류를 파악하는 데 사용합니다.

텍스처 위로 마우스를 올리면 커서 텍셀 위치의 현재 RGBA 값이 나타납니다. 마우스 왼쪽 버튼을 클릭하면 텍셀 RGBA 위치 값이 캡처 및 유지됩니다.

텍스처에서 더 자세히 확인하고 싶은 부분이 있다면 마우스 휠을 사용해 줌 인과 줌 아웃이 가능합니다. 줌 인한 경우 마우스 오른쪽 버튼을 클릭한 상태로 드래그하여 텍스처 안에서 이동할 수 있습니다.

표시된 텍스처 아래의 영역은 텍스처와 렌더링 방식에 관한 주요 정보를 제공합니다.

1. 텍스처 디스크립터
2. 커스터마이즈를 위한 WebGL 2.0 시각화 셰이더
3. 리소스를 수정하는 패스
4. 리소스를 읽는 패스

텍스처 디스크립터

텍스처 디스크립터(Texture Descriptor) 에는 현재 표시된 텍스처의 정보가 나타납니다. 이 영역은 FRDGBuilder::CreateTexture() 에 구성되어 있습니다.

WebGL 2.0 시각화 셰이더

WebGL 2.0 시각화 셰이더(WebGL 2.0 Visualization Shader) 는 컴파일되는 코드 프래그먼트를 나타냅니다. 위쪽 창에는 텍스처가 표시되고, 아래에 있는 컴파일 로그 창에는 발생할 수 있는 컴파일 오류가 표시됩니다.

WebGL 2.0 캔버스 창은 편집 가능한 텍스트 박스로, WebGL 2.0 GLSL을 쓸 수 있습니다. 이미지에 채널당 여러 비트의 정보가 압축되어 있거나 다른 색 공간이 사용되는 경우 등에는 커스터마이징을 통해 텍스처를 시각화하고 디코딩할 수 있습니다. 이 필드에 입력된 코드는 자동으로 리컴파일되며 오류가 발생하는 경우 오류 내용이 표시됩니다.

WebGL 2.0 셰이더의 구문은 언리얼 엔진이 사용하는 구문과 다릅니다. HLSL로 내부 렌더링 코드를 쓸 때에는 언리얼 셰이더 포맷(.usf)과 언리얼 셰이더 헤더(.ush) 파일이 사용됩니다. 컴파일 창 하단에 GLSL 구문에 대한 WebGL 2.0 빠른 참조 카드 링크가 포함되어 있습니다.

수정 및 읽기 중인 패스

맨 아래에는 두 개의 창이 있습니다. 하나는 선택한 리소스를 수정 중인 패스, 다른 하나는 선택한 리소스를 읽어들이고 있는 패스의 창입니다. 목록에서 패스를 클릭하면 뷰어로 패스가 표시됩니다.

버퍼 뷰어

패스 입력 리소스(Input Resources) 또는 출력 리소스(Output Resources) 목록에서 텍스처 보기를 선택하면 버퍼(Buffer) 뷰에 디스크립터와 시각화 콘텐츠 목록이 나타납니다.

버퍼 디스크립터(Buffer Descriptor) 는 선택한 리소스의 이름, 크기, 설명, 사용 등 일반적인 정보를 제공합니다.

버퍼 시각화(Buffer Visualization) 목록은 10진법이나 0x로 시작하는 16진법 값을 가진 버퍼 주소를 보여줍니다.

주소(Address) 텍스트 필드를 사용하여 10진법이거나 0x로 시작하는 특정 주소로 이동할 수 있습니다.

목록에 나타난 포맷은 커스터마이징이 가능합니다. 지원되는 커스터마이징 항목은 아래와 같습니다.

• Float, Half
• Int, short, char
• Uint, ushort, char
• 위 포맷을 16진법이나 2진법으로 표시하는 Hex() 또는 bin()

GPU 덤프 뷰어는 데이터 해석 방법을 모르기 때문에 버퍼는 데이터를 시각화할 때 DrawIndirect 사용 플래그가 없으면 기본적으로 hex(uint) 포맷을 사용하고, 플래그가 있으면 Uint 포맷을 사용하도록 설정되어 있습니다.