PC 샘플 실행
GitHub에서 Microsoft 게임 개발 키트(GDK)용 샘플을 다운로드할 수 있습니다. 이 항목은 Microsoft GDK(게임 개발 키트) 설치에 포함되어 있지 않습니다.
샘플은 다음과 같이 구성되어 있습니다.
- 키트: 샘플에 사용되는 공유 유틸리티 코드
- 미디어: 샘플에서 사용하는 다양한 공유 자산
- GDKSamples:
- 오디오: XAudio2, WASAPI 등과 관련된 샘플
- IntroGraphics: DirectX 12 샘플 소개
- 라이브: Xbox 서비스 샘플
- 그래픽: DirectX 12.X 샘플
- 시스템: 입력, IO, 메모리 등과 관련된 샘플
- 도구: Microsoft GDK(게임 개발 키트)를 사용하기 위한 다양한 샘플 도구
참고 항목
일부 샘플은 Xbox 본체에만 사용할 수 있습니다.
샘플 작성
자세한 내용은 각 샘플의 Readme.docx 파일을 참조하세요.
- 필요한 개발 도구를 설치합니다.
Visual Studio 2019 또는 Visual Studio 2022, Windows 10 SDK 및 Microsoft 게임 개발 키트(GDK). - Visual Studio를 엽니다.
- 파일>열기>프로젝트/솔루션을 선택합니다. 샘플(예: GDKSamples\IntroGraphics\SimpleTriangleDesktop)로 이동합니다. SimpleTriangleDesktop.sln을 선택합니다.
- F5를 선택하여 빌드, 배포, 디버그합니다.
샘플은 DirectX 12를 사용하므로 Windows 10 또는 Windows 11, 비디오 카드 및 DirectX 12를 지원하는 비디오 드라이버가 필요합니다.
이 샘플의 디버그 구성 빌드에서는 DirectX 12 디바이스를 사용할 수 없는 경우, 샘플에서 WARP12 소프트웨어 디바이스를 사용하려고 합니다. 이는 디버그 출력 창에서 "Direct3D Adapter - WARP12"로 기록됩니다. Windows 10 시스템에서 선택적 기능 그래픽 도구를 활성화하여 WARP12 (Direct3D 12 디버그 디바이스와 함께)를 설치합니다. 자세한 내용은 Windows 10 블로그 게시물용 Visual Studio 2015 및 그래픽 도구를 참조하세요.
WARP12는 개발자 시스템에서만 사용할 수 있으므로, 릴리스 구성 빌드는 소프트웨어 디바이스를 사용하려고 시도하지 않으며, 대신에 DirectX 12 지원 하드웨어를 찾지 못하는 경우에는 실패합니다.
Visual Studio 노트
기본적으로, 샘플은 Visual Studio 2019 플랫폼 도구 집합 v142을 사용하도록 설정됩니다. Visual Studio 2022를 사용할 때는 v142 설정을 이용해 샘플을 빌드하거나 샘플의 대상을 v143(으)로 변경할 수 있습니다.
Visual Studio 2022를 설치할 때는 MSVC v142 - VS 2019 C++ x64/x86 빌드 도구 선택적 구성 요소(Microsoft.VisualStudio.ComponentGroup.VC.Tools.142.x86.x64)를 포함하는 것이 좋습니다.
샘플 둘러보기
대부분의 샘플은 동일한 기본 구조를 사용하며 다음 파일을 포함합니다.
samplename.cpp및samplename.h(샘플과 일치하도록 이름 지정됨)에는 핵심 샘플 기능이 포함되어 있으며 소스 코드를 볼 때 시작할 부분입니다.Main.cpp에는 진입점, 창 작성 및 메인 메시지 루프가 포함되어 있습니다.DeviceResources.cpp및DeviceResources.h에는 Direct3D 12 장치 및 스왑 체인에 대한 추상화가 포함되어 있습니다. 자세한 내용은 GitHub에서 DeviceResources를 참조하세요. 디바이스 만들기와 스왑 체인에 대한 자세한 내용은 IntroGraphics 샘플 SimpleDeviceAndSwapChain을 참조하세요.StepTimer.h은 가변적이고 고정된 단계의 게임 타이밍에 대한 간단한 추상화를 포함합니다. 자세한 내용은 GitHub에서 StepTimer를 참조하세요.pch.h및pch.cpp은(는) 샘플에 대한 사전 컴파일된 헤더 파일 및 전역#include문을 구현합니다.Assets 폴더에는 패키징용 시작 화면과 로고가 포함된 로컬 미디어가 포함되어 있습니다. 샘플에는 MicrosoftGameConfig.mgc 파일도 포함되어 있습니다.
참고 항목
GDK 서식 파일에서 samplename.cpp 및 samplename.h이(가) 아니라, Game.cpp 및 Game.h에서 동일한 구조를 사용합니다. 기본 클래스는 Sample이(가) 아니라 Game(이)라고 합니다.
생성자
샘플의 핵심 기능은 Sample 클래스에서 구현됩니다. 다음과 같이, 생성자의 최소 구현은 DeviceResources 인스턴스를 만듭니다.
Sample::Sample() noexcept(false) :
m_frame(0)
{
m_deviceResources = std::make_unique<DX::DeviceResources>();
}
DeviceResources 생성자는 렌더링 대상의 형식, 깊이 스텐실 형식(심층 스텐실 버퍼가 필요하지 않으면 DXGI_UNKNOWN으로 설정할 수 있음), 백 버퍼 카운트(2 또는 3), 선택적 특징 플래그를 제어하기 위해 여러 가지 선택적 기본 매개 변수를 가지고 있습니다. 자세한 내용은 GitHub에서 DeviceResources를 참조하세요.
초기화
다음과 같이, 샘플이 처음 시작되면 프레젠테이션 창에 처리를 제공하는 Sample::Initialize 메서드를 실행하고 Direct3D 디바이스, 리소스, 기타 자산을 초기화합니다.
// Initialize the Direct3D resources that are required to run.
void Sample::Initialize(HWND window)
{
m_deviceResources->SetWindow(window);
m_deviceResources->CreateDeviceResources();
CreateDeviceDependentResources();
m_deviceResources->CreateWindowSizeDependentResources();
CreateWindowSizeDependentResources();
}
Sample::CreateDeviceDependentResources 도우미는 Direct3D 12 장치에 필요한 리소스를 만들지만 Sample::CreateWindowSizeDependentResources는 장치에 필요한 리소스를 만들고 표시 창의 크기에 따라 다른 리소스를 만듭니다.
업데이트
Sample::Update 메서드는 입력 및 상태 수정뿐만 아니라 시간 기반 애니메이션 및 시뮬레이션을 처리합니다. 다음과 같이, StepTimer는 프레임당 0회 이상 업데이트할 수 있는 고정 시간 업데이트도 가능하지만 보통 이 메서드는 프레임당 한 번 호출됩니다.
void Sample::Update(DX::StepTimer const&)
{
auto pad = m_gamePad->GetState(0);
if (pad.IsConnected())
{
if (pad.IsViewPressed())
{
ExitSample();
}
}
}
대부분의 샘플은 게임 패드, 키보드 및 마우스를 위해 DirectX 도구 키트 입력 추상화를 사용합니다.
오디오 샘플은 일반적으로 Tick에서 직접 호출되는 오디오 렌더링을 처리하기 때문에 프레임당 한 번 처리하고 Update에 넣지 않습니다.
Render
Sample::Render 메서드는 장면의 한 프레임을 렌더링하는 데 사용됩니다. 다음과 같이, 이는 기본 명령 목록을 제출하고 렌더링된 프레임을 표시하는 데 필요한 DeviceResources::Present 메서드에 대한 호출로 끝납니다.
void Sample::Render()
{
// Don't try to render anything before the first Update.
if (m_timer.GetFrameCount() == 0)
{
return;
}
// Prepare the command list to render a new frame.
m_deviceResources->Prepare();
Clear();
auto commandList = m_deviceResources->GetCommandList();
...
// Show the new frame.
m_deviceResources->Present();
m_graphicsMemory->Commit(m_deviceResources->GetCommandQueue());
}
DeviceResources::Prepare 메서드는 기본 명령 목록을 준비하는 데 사용됩니다.
Sample::Clear 메서드는 렌더링 대상을 설정하고 배경색으로 설정하는 동시에 초기 렌더링 뷰포트 및 가위 직사각형을 설정하는 데 사용됩니다.
대부분의 샘플은 DirectX 도구 키트를 사용하기 때문에 동적 GPU 메모리 사용 수명을 추적하기 위해 각 프레임이 끝난 후 GraphicsMemory::Commit 메서드를 호출해야 합니다. 자세한 내용은 GitHub에서 GraphicsMemory를 참조하세요.
이벤트
PLM(프로세스 수명 관리)은 Sample::OnSuspending 및 Sample::OnResuming 메서드를 통해 처리됩니다. Xbox 샘플의 경우 일반적으로 필요한 GPU suspend와 resume 메서드를 호출하고 StepTimer를 재설정합니다.
데스크톱 샘플에는 Sample::OnWindowMoved 및 Sample::OnWindowSizeChanged를 통한 창 크기 변경 관련 메시지가 있습니다. Xbox 샘플은 고정된 표시 크기를 사용하므로 이러한 메서드가 없습니다.
데스크톱 샘플은 또한 Sample::OnDeviceLost와 Sample::OnDeviceRestored를 통해 장치 분실 상황을 처리해야 합니다. 이는 DXGI_ERROR_DEVICE_REMOVED 또는 DXGI_ERROR_DEVICE_RESET이 발생했을 때 Present가 트리거합니다. 디바이스 분실은 Xbox에서 발생하지 않으므로 샘플에서는 이러한 처리가 필요하지 않습니다.
스마트 포인터
샘플은 Direct3D 및 기타 Nano-COM 개체의 수명 관리를 단순화하기 위해 Microsoft::WRL::ComPtr 스마트 포인터를 사용합니다. 이 스마트 포인터에 대한 자세한 내용은 GitHub에서 ComPtr를 참조하세요.
오류 처리
많은 Direct3D 기능과 기타 Nano-COM API는 HRESULT 오류 코드를 반환합니다. 견고성과 더 쉬운 디버깅을 위해 HRESULT를 반환하는 모든 함수의 결과를 항상 확인하세요. 특정 함수에 오류 조건이 없다고 가정해도 안전하다면, 함수 자체가 HRESULT 대신 void를 반환합니다.
다음과 같이, 런타임에 처리할 수 없는 fast fatal 오류를 탐지하고 처리하기 위해 샘플은 ThrowIfFailed 네임스페이스에서 간단한 도우미 함수인 DX를 사용합니다. 이 도우미에 대한 자세한 내용은 GitHub에서 ThrowIfFailed를 참조하세요.
DX::ThrowIfFailed(D3D12SerializeRootSignature(...));
코드 생성이나 성능에 거의 또는 전혀 영향을 미치지 않으므로 모든 x64 기본 개발에는 C++ 예외 처리 /EHsc를 사용하는 것이 좋습니다. 런타임에 C++ 예외를 발생시키는 것은 성능 시나리오가 아니므로 흐름 제어에 사용하지 않습니다. C++ 예외와 관련된 Visual Studio 디버거 설정 사용에 대한 자세한 내용은 Visual Studio에서 디버거를 사용하여 예외 관리를 참조하세요.
키트
샘플에 의해 사용되는 주요 유틸리티 코드는 GitHub에서 사용할 수 있는 DX12용 DirectX 도구 키트입니다. 몇 가지 샘플에서 DirectXTex를 사용하며, GitHub에서도 사용 가능합니다. 설명서에 대한 적절한 프로젝트 WiKi를 참조하세요. DirectX 도구 키트 및 DirectXTex의 Microsoft GDK(게임 개발 키트) 지원은 MIT 라이선스의 적용을 받으며 핵심 프로젝트의 일부입니다.
또한 샘플은 ATGTK 폴더에 있는 ATG 도구 키트의 소스 코드를 사용합니다. 이 소스 코드는 개별 헤더에 설명된 대로 MIT 사용이 허가된 코드이며 샘플에서만 사용하기 위한 것입니다.