GPU 덤프 뷰어 툴

렌더링 문제를 조사하고 디버깅할 수 있도록 중간 RDG 텍스처와 버퍼를 디스크에 덤프하는 멀티 플랫폼 명령입니다.

Choose your operating system:

Windows

macOS

Linux

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

gpu 덤프 뷰어

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

  • 타사 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 + / 를 사용합니다.

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

덤프가 리소스의 덤프 여부를 아는 데 필요한 퍼시스턴트 메모리의 양은 무시할 수 있는 수준입니다.

리소스 덤프에 필요한 메모리가 시스템 가용 메모리보다 크면 리소스가 덤프되지 않고 로그에 경고 메시지가 표시됩니다.

DumpGPU 명령어는 디버그(Debug), 디버그게임(DebugGame), 개발(Development), 테스트(Test) 빌드에서 사용할 수 있지만, 출시(Shipping) 빌드에서도 Project.Target.cs 를 사용해 활성화할 수 있습니다.

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

이 방법은 렌더링 문제가 있는 디버깅 테스트 목적으로만 사용해야 하며, 실제로 프로젝트를 출시할 때 활성화해서는 안 됩니다.

GPU 덤프의 위치 저장하기

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

gpu 덤프 뷰어 창 파일 탐색기

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

모든 덤프는 압축되지 않은 원본 리소스 형태이므로 디스크 공간을 많이 차지할 수 있습니다. 하지만 덤프는 Zip 파일로 쉽게 압축할 수 있습니다. 예를 들어, 기술 데모 ‘매트릭스: 어웨이큰스'로 생성한 덤프는 압축하지 않았을 때 약 8GB이지만, Zip 파일로 압축하면 2.2GB가 됩니다.

덤프 압축은 다른 사람들과 데이터를 공유할 때 유용할 수 있습니다.

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

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

모바일 플랫폼

저장 위치 파일 경로

iOS

[앱 컨테이너 경로]/Documents/[프로젝트 이름]/Saved/GPUDumps/

Android

/storage/emulated/0/UnrealGame/[프로젝트 이름]/[프로젝트 이름]/Saved/GPUDumps/

Android OpenGL에서는 스텐실 버퍼가 비어 있습니다.

덤프 세팅

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

콘솔 변수

설명

r.DumpGPU.Root

소속된 부모의 범위와 드로 이벤트를 바탕으로 렌더 종속성 그래프(RDG) 패스의 서브셋을 선택합니다. 이 명령을 활성화하면 단독 표시된 렌더링 기능을 반복작업할 때 필요한 패스만 덤핑하므로 덤핑 프로세스 속도가 크게 향상될 수 있습니다. 예를 들어, 포스트 프로세싱 패스만 덤핑하려면 r.DumpGPU.Root="PostProcessing" 을 입력합니다.

r.DumpGPU.Viewer.Visualize

뷰어상의 이름을 바탕으로 특정 리소스를 자동으로 엽니다. 예를 들어, r.DumpGPU.Viewer.Visualize "<리소스 이름>" 을 입력합니다.

r.DumpGPU.Directory

GPU 덤프는 디스크 공간을 많이 차지할 수 있습니다. ConsoleVariables.ini 환경설정 파일에 이 명령을 사용하면 디렉터리 지정을 통해 모든 GPU 덤프를 한 위치에 저장할 수 있습니다. 예를 들어, r.DumpGPU.Directory="[X:/파일/경로/이름]" 과 같이 위치를 지정합니다.

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

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

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

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

GPU 덤프 뷰어

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

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

windows 파일 탐색기 gpudumpviewer bat 파일

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

gpu 덤프 뷰어

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

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

  • 빠른 액세스를 위해 모든 링크는 클릭이 가능하며 새 탭으로 열립니다.

  • 뒤로 가기, 앞으로 가기 버튼을 사용하여 이전에 본 페이지로 이동할 수 있습니다.

  • 다른 사람과 캡처를 공유하려는 경우, 링크의 # 뒷부분을 공유하면 패널과 덤프 일부로 직접 연결됩니다. 예를 들어, #display_output_resource(96,'0000000067e1bfa0.mip0'); 를 공유합니다.

GPU 덤프 뷰어를 열면 메인 보기 영역에서 다양한 팁과 요령을 넘겨가며 볼 수 있습니다.

각 섹션이 강조된 gpu 덤프 뷰어

  1. 제목 표시줄과 패널

  2. 패스 및 리소스 트리

  3. 뷰어

제목 표시줄과 패널

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

gpu 덤프 뷰어 제목 표시줄

정보 패널

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

gpu 덤프 뷰어 정보 패널

CVar 패널

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

gpu 덤프 뷰어 CVar 패널

콘솔 변수는 프레임 시작 시 캡처됩니다. 따라서 게임플레이가 런타임에서 CVar를 토글하는 경우 일부 변수가 변경될 수 있습니다.

로그 패널

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

gpu 덤프 뷰어 로그 패널

뷰어

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

패스 뷰어

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

gpu 덤프 뷰어 패스 뷰어

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

gpu 덤프 뷰어 패스 파라미터 버튼

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

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

gpu 덤프 뷰어 패스 파라미터 패널

텍스처 뷰어

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

gpu 덤프 뷰어 텍스처 뷰어

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

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

gpu 덤프 뷰어 텍스처 뷰어 버튼

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

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

    클립보드로 복사 예시

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

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

Cursor Texel Pos와 Selected Texel Pos에 표시되는 값은 픽셀 포맷 인코딩이 허용하는 정밀도보다 자릿수가 더 많습니다. 이는 웹페이지가 배정밀도 부동 소수점 포맷(double precision floating point format)을 사용해 JavaScript에서 텍셀을 디코딩하기 때문입니다.

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

gpu 덤프 뷰어 텍스처 뷰어 텍셀 선택

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

gpu 덤프 뷰어 텍스처 뷰어 정보 패널

  1. 텍스처 디스크립터

  2. 커스터마이즈를 위한 WebGL 2.0 시각화 셰이더

  3. 리소스를 수정하는 패스

  4. 리소스를 읽는 패스

텍스처 디스크립터

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

gpu 덤프 뷰어 텍스처 디스크립터

현재 DumpGPU 명령은 FRDGTexture 만을 덤프하며 비 MSAA Texture2D만을 지원합니다. 여기에는 깊이, 스텐실, 밉 레벨이 포함됩니다. Texture2DArray, Texture2DMS, Texture3D, TextureCube, TextureCubeArray와 HTILE, CMask & cie를 비롯한 메타데이터는 아직 지원되지 않습니다.

WebGL 2.0 시각화 셰이더

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

gpu 덤프 뷰어 webgl 2.0 시각화 셰이더

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

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

fetchTexel(uv) 는 표준 GLSL이 아닙니다. 이 명령은 보통 WebGL 2.0이 지원하지 않는 픽셀 포맷을 자동으로 처리하는 커스텀 함수입니다.

수정 및 읽기 중인 패스

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

gpu 덤프 뷰어 수정 및 읽기 중인 패스 패널

버퍼 뷰어

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

gpu 덤프 뷰어 버퍼 뷰어

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

gpu 덤프 뷰어 버퍼 디스크립터

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

gpu 덤프 뷰어 버퍼 시각화

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

gpu 덤프 뷰어 시각화 주소 검색 필드

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

  • Float, Half

  • Int, short, char

  • Uint, ushort, char

  • 위 포맷을 16진법이나 2진법으로 표시하는 Hex() 또는 bin()

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

템플릿이 있는 FRDGBufferDesc::Create*() 함수를 사용하면 셰이더 파라미터 구조체가 있는 FRDGBuffer 를 만들어 더 편리하게 버퍼의 콘텐츠를 둘러볼 수 있습니다.

gpu 덤프 뷰어 버퍼 코드 스니펫 생성 gpu 덤프 뷰어 뷰어에서 버퍼 생성하기

디스크립터 NumElements 가 1보다 크면 버퍼는 멤버 표시 방식을 행 기준에서 열 기준으로 자동 변경합니다.