Share via

PC サンプルの実行

  • [アーティクル]

Microsoft Game Development Kit (GDK) のサンプルは、GitHub からダウンロードできます。 これらは、Microsoft Game Development Kit (GDK) のインストールには含まれません。

サンプルの構成は次のとおりです。

  • キット: サンプルで使用される共有ユーティリティ コード
  • メディア: サンプルで使用されるさまざまな共有アセット
  • GDKSamples:
    • オーディオ: XAudio2 や WASAPI などに関連するサンプル
    • IntroGraphics: 初歩的な DirectX 12 サンプル
    • Live: Xbox サービスのサンプル
    • グラフィックス: DirectX 12.X のサンプル
    • システム: 入力、I/O、メモリなどに関連するサンプル
    • ツール: Microsoft Game Development Kit (GDK) を操作するためのさまざまなサンプル ツール

注意

一部のサンプルは Xbox コンソール専用です。

サンプルのビルド

詳細については、各個別サンプルの Readme.docx ファイルを参照してください。

  1. 必要な開発ツールをインストールします:
    Visual Studio 2019 または Visual Studio 2022、Windows 10 SDK、および Microsoft Game Development Kit (GDK)。
  2. Visual Studio を起動します。
  3. [ファイル]>[開く]>[プロジェクト/ソリューション] を選択します。 サンプル (GDKSamples\IntroGraphics\SimpleTriangleDesktop など) に移動します。 [SimpleTriangleDesktop.sln] を選択します。
  4. 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 テンプレートは、Game.cpp と Game.h ではなく、samplename.cpp および samplename.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 メソッドは、入力と状態の変更だけでなく、時間ベースのアニメーションとシミュレーションを処理します。 次に示すように、通常、このメソッドはフレームごとに 1 回呼び出されますが、StepTimer は、フレームごとに 0 回またはそれ以上更新できる固定時間での更新も使用できます。

void Sample::Update(DX::StepTimer const&)
{
    auto pad = m_gamePad->GetState(0);
    if (pad.IsConnected())
    {
       if (pad.IsViewPressed())
       {
            ExitSample();
       }
    }
}

ほとんどのサンプルは、GamePad、Keyboard、Mouse について DirectX Tool Kit の入力の抽象化を使用します。

通常、オーディオ サンプルは Tick から直接呼び出されるオーディオ レンダリングを処理するため、フレームごとに 1 回処理し、それを Update には含めません。

レンダリング

Sample::Render メソッドは、シーンの 1 つのフレームのレンダリングに使用されます。 次に示すように、これは最後に 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 Tool Kit を使用するため、各フレームの終了後に GraphicsMemory::Commit メソッドを呼び出して、動的な GPU メモリ使用率の継続期間を追跡する必要があります。 詳細については、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 では発生しないため、これらのサンプルに対して、この処理は必要ありません。

スマート ポインター

サンプルは Microsoft::WRL::ComPtr スマート ポインターを使用して、Direct3D や他の nano-COM オブジェクトのライフタイム管理を簡略化します。 このスマート ポインターの詳細については、GitHub の「ComPtr」を参照してください。

エラー処理

多くの Direct3D 関数および他の nano-COM API では HRESULT エラー コードが返されます。 堅牢性を高めデバッグを容易にするため、HRESULT を返すすべての関数の結果を常に調べます。 特定の関数についてエラー状態がないと見なして問題ない場合、その関数自体からは HRESULT ではなく void が返されます。

次に示すように、高速の致命的なエラーを検出して処理するため、サンプルは単純なヘルパー関数 ThrowIfFailed を DX 名前空間で使用します (それ以外の方法では実行時に処理できません)。 このヘルパーの詳細については、GitHub の「ThrowIfFailed」を参照してください。

DX::ThrowIfFailed(D3D12SerializeRootSignature(...));

すべての x64 ネイティブ開発では C++ 例外処理 /EHsc の使用をお勧めします。コードの生成またはパフォーマンスへの影響がほとんどまたはまったくないためです。 ただし、実行時に C++ 例外をスローするとパフォーマンスの高いシナリオになりません。このためフローの制御には使用しません。 C++ 例外に関連する Visual Studio デバッガー設定の使用に関する詳細は、「Visual Studio のデバッガーで例外を管理する」を参照してください。

キット

サンプルによって使用されるプライマリ ユーティリティ コードは DirectX Tool Kit for DX12 です。これは GitHub で入手できます。 DirectXTex が使用されるサンプルも少数あり、GitHub から入手できます。 ドキュメントについては、適切なプロジェクト wiki を参照してください。 DirectX Tool Kit および DirectXTex での Microsoft Game Development Kit (GDK) のサポートは MIT ライセンスの対象であり、コア プロジェクトの一部です。

また、サンプルでは ATGTK フォルダー内の ATG Tool Kit のソース コードも使用されます。 このソース コードは MIT ライセンス コードであり (個々のヘッダーに記載されているとおり)、サンプルでのみ使用することを目的としています。

関連項目

Xbox 移植ガイド (NDA トピック)