Windows#

動作環境#

WindowsでMGLを利用するには次の環境が必要です。

  • Windows 10以降（64bit）

  • Visual Studio 2019以降

本項では次の環境を利用して説明を進めます。この環境は、MGLのバージョン1.1.0時点における開発環境と同等です。

  • Windows 10 Pro 22H2

  • Visual Studio Community 2019 Version 16.11.20

  • Windows 10 SDK (10.0.19041.0)

Visual StudioにはC++向けのコンポーネントがインストールされている必要があります。新規インストール時またはVisual Studio Installerのワークロードから「C++によるゲーム開発」を選択してインストールしてください。

../_images/vs_installer.png

Visual Studio Installerのワークロード選択画面#

プロジェクトの新規作成#

Visual Studioの準備が整ったら、これから作成するゲーム用のプロジェクトを作成します。

Visual Studioの起動画面
../_images/vs_start_ss.png

まず、Visual Studioの起動後の画面右側から「新しいプロジェクトの作成」を選択します。

テンプレートの選択画面
../_images/vs_new_project_1_ss.png

選択後、テンプレートの選択画面に移ります。ここでは上部のプルダウンメニューから「C++」を選択し、その中にある「Windowsデスクトップアプリケーション」を選択してください。

プロジェクト名と保存の選択画面
../_images/vs_new_project_2_ss.png

「次へ」を押すとプロジェクト名と保存先の選択画面に移ります。プロジェクト名には任意の名前を入力し、保存先はディレクトリ構成で作成したprojectのディレクトリを選択してください。今回の例ではプロジェクト名はmgl-test-winとします。

注釈

プロジェクト名は任意ですが、名前の衝突を避けるためにプラットフォームを表す名前を含めることを推奨します。

最後に「作成」を押すことで、指定した場所に新たなプロジェクトが生成されます。

この方法で生成したプロジェクトには、いくつかの自動生成されたコードが最初から追加されています。MGLではこれらを使用せず、後に削除することになりますが、今はとりあえずそのままにしておいてください。

MGLプロジェクトの追加#

次に、新規に作成したプロジェクトにMGLのプロジェクトを取り込みます。

既存のプロジェクトの追加
../_images/vs_add_mgl_project_1_ss.png

まず、メニューバーの「ファイル」から「追加」を選び、その中にある「既存のプロジェクト」を選択します。ファイル選択ダイアログが表示されるため、そこでframeworkディレクトリ内の次のファイルを選択してください。

framework/mgl/project/mgl/mgl_win32/mgl_win32/mgl_win32.vcproj

成功したらソリューションエクスプローラーに「mgl_win32」という項目が追加されます。

MGLプロジェクト追加後の状態
../_images/vs_add_mgl_project_2_ss.png

ここで、一旦テストとしてビルドしてみます。上部の「Debug」の隣にある「x86」の部分を「x64」に変更し、「ビルド」から「ソリューションのビルド」を選択してください。これまでの手順に誤りがなければ、エラーと警告は共に0となるはずです。

注釈

MGLは32bitアプリケーション (x86) に対応していません。ビルドは通るかもしれませんが、動作検証を行っていません。

ビルドが正しく通ることを確認できたら、プロジェクト間の依存設定を行います。

プロジェクトの依存関係
../_images/vs_build_depend_1_ss.png

ソリューションエクスプローラーから新規に作成したプロジェクト（ここではmgl-test-win）を右クリックし、「ビルドの依存関係」から「プロジェクトの依存関係」を選択します。

プロジェクトの依存関係 (2)
../_images/vs_build_depend_2_ss.png

プロジェクトの依存関係を設定するウィンドウが表示されるため、ここで「mgl_win32」にチェックを入れてください。

プロジェクトのプロパティ設定#

プロジェクトにMGLを取り込んだだけでは、まだプログラムからMGLを扱うことはできません。プロジェクトのプロパティにいくつかの設定を行う必要があります。

ソリューションエクスプローラーから作成したプロジェクトを右クリックし、最下段の「プロパティ」を選択してください。プロパティページと呼ばれるプロジェクトの設定を行うウィンドウが表示されます。

プロジェクトのプロパティはビルド構成ごとに管理されているため、まず最初に上段にある「構成」と「プラットフォーム」に適切なものが選択されているかを確認してください。ここでは構成に「Debug」、プラットフォームに「x64」が選択されていることを確認します。

注釈

Releaseでビルドする場合は構成の「Release」にも同じ設定を行う必要があります。「すべての構成」を選択して設定した場合はその両方に適用しますが、その項目に異なるパラメータが設定されている際に両方を上書きしてしまうため注意が必要です。

インクルードパスの設定#

プログラムがMGLのヘッダファイルを参照できるようにするには、インクルードディレクトリのパスをコンパイラに伝える必要があります。また、マルチプラットフォームでの開発においてはゲームのソースコードを特定のプロジェクト以下に配置できないため、こちらも併せて設定が必要です。

まず、構成プロパティの「C/C++」の項目から「全般」を選択し、「追加のインクルードディレクトリ」から「編集」を選択してください。

../_images/vs_include_path_1_ss.png

インクルードパスの設定場所#

インクルードパスの設定ウィンドウが表示され、ここにMGLのヘッダファイルの場所とゲームのソースコードの格納場所の2つを相対パスで入力します。パスの起点はプロジェクトファイル(.vcproj)のあるディレクトリです。これまで例の通りの手順で進めてきた場合は、次の2つを追加することになります。

../../../framework/mgl/include
../../../src
../_images/vs_include_path_2_ss.png

インクルードパスの設定画面#

C++言語標準の設定#

MGLはC++17に準拠して作られているため、MGLを利用するプロジェクトもこれに合わせる必要があります。

構成プロパティの「C/C++」の項目から「言語」を選択し、「C++言語標準」の項目を「ISO C++17標準」に設定してください。

../_images/vs_cpp17_ss.png

C++言語標準の設定#

追加の依存ファイルの設定#

WindowsではMGLは静的ライブラリとして生成されるため、実行ファイル生成時にMGLとリンクする必要があります。

構成プロパティの「リンカー」の項目から「入力」を選択し、「追加の依存ファイル」から「編集」を選択してください。

../_images/vs_link_lib_1_ss.png

追加の依存ファイルの設定場所#

プロジェクト間の依存関係の設定が正しく行われている場合、オブジェクトコードと同じ出力先にMGLの静的リンクライブラリも出力されます。この出力先はマクロを用いることで表現可能です。

追加の依存ファイルの設定画面にて、次の1行を追加してください。

$(SolutionDir)x64\$(Configuration)\mgl_win32.lib
../_images/vs_link_lib_2_ss.png

追加の依存ファイルの設定画面#

文字コードの変更#

MGLは文字コードにUTF-8を使用し、改行コードにLF(0x0A)を使用しています。この形式は多くのプラットフォームで標準的に扱われていますが、Windowsでは異なる形式が広く使用されており、Visual Studioが標準的にUnicodeを扱うように変更する必要があります。

まず、構成プロパティの「詳細」から「文字セット」の項目を探し、「Unicode文字セットを使用する」になっていることを確認してください。Visual Studioのバージョンが最新であればデフォルトでUnicode文字セットとなっているはずですが、異なる設定になっている場合は変更してください。この項目はWindowsのAPIの挙動に大きく影響を与える重要な設定です。

../_images/vs_charset_1_ss.png

文字セットの変更場所#

次に、ソースコードが標準で扱う文字コードを変更します。構成プロパティの「C/C++」から「コマンドライン」を選択し、「追加のオプション」の欄に次の文字を追加してください。

/source-charset:utf-8
../_images/vs_charset_2_ss.png

ソースの文字セットの変更場所#

このオプションにより、コンパイラは文字コードの指定がないソースコードをUTF-8エンコーディングとして扱うようになります。

これらの設定に併せて、Visual Studioのエディタが標準で扱う文字コードも設定しておくことを推奨します。エディタの設定を行うには、プロジェクトファイルのある場所（ここではproject/mgl-test-win/mgl-test-win/）に.editorconfigという名前のファイルを作成し、テキストで内容を記述します。

.editorconfigで文字コードにUTF-8を、改行コードにLFを設定する例を次に示します。

.editorconfigの内容
root = true

[*]
charset = utf-8
end_of_line = lf

記述が完了したら、一旦Visual Studioを終了して起動し直してください。

DPI認識設定#

MGLは高DPIの表示に対応しています。この機能を有効にするには、構成プロパティの「マニフェストツール」から「入出力」を選択して「DPI認識」の項目を「モニターごとの高いDPI認識」に変更します。

../_images/vs_manifest_dpi.png

DPI認識の設定場所#

この設定は、例えば4Kなどの高解像度ディスプレイを利用している環境において、表示スケール設定の差異を適切に吸収するために必要になります。必須ではありませんが、特別な理由がない限りは有効にすることを推奨します。

作業ディレクトリの設定#

Visual Studio上からデバッグを開始する際に、カレントディレクトリとして設定されるパスを設定する必要があります。デフォルトではプロジェクトファイルと同じディレクトリに設定されていますが、この場所ではリソースファイルなどを他のプラットフォームと共有する際に都合が良くありません。ディレクトリ構成で作業ディレクトリとしてworkdirを用意していますので、こちらで実行するように変更します。

作業ディレクトリは構成プロパティの「デバッグ」にある「作業ディレクトリ」で指定します。デフォルトではプロジェクトファイルの場所を指す$(ProjectDir)となっているため、ここから次のように相対パスでworkdirへと変更します。

$(ProjectDir)..\..\..\workdir\
../_images/vs_debug_workdir.png

作業ディレクトリの設定画面#

Windowsにおける作業ディレクトリは、MGLではリソースファイルやユーザーデータなどのデフォルトのパスとして利用しています。詳細はファイルアクセスのプラットフォーム別情報を参照してください。

WinMain()とMGLの初期化#

遂に最後の手順です。WindowsアプリケーションにおけるエントリポイントとなるWinMain関数を記述し、MGLの初期化とアプリケーションデリゲートの登録を行います。

まず、アプリケーションデリゲートの作成で作成したapp_main.ccとapp_main.hをこのプロジェクトに追加します。ソースの追加はファイルをソリューションエクスプローラーへとドラッグ＆ドロップするだけで問題ありません。

次に、プロジェクト名と同じ名前のソース（ここでの例ではmgl-test-win.cpp）を開き、次の内容で上書きしてください。自動生成された既存の記述は全て削除して構いません。

/* ------------------------------------------------------------------------- */
/*!
 *  \file       mgl-test-win.cpp
 *  \brief      MGL Windows用エントリポイント
 *  \date       Since: October 30, 2022. 15:01:35 JST.
 *  \author     Acerola
 */
/* ------------------------------------------------------------------------- */

#include <app_main.h>

#include "Resource.h"

#include <mgl/mgl.h>
#include <mgl/platform/win32/mgl_win32_main.h>
#include <mgl/initialize/mgl_initializer_win32.h>

#include <Windows.h>

/* ------------------------------------------------------------------------- */
/*!
 *  \brief      エントリポイント
 *  \param[in]  hInstance       アプリケーションインスタンス
 *  \param[in]  hPrevInstance   未使用
 *  \param[in]  lpCmdLine       コマンドラインオプション
 *  \param[in]  nCmdShow        ウィンドウの表示状態
 *  \return     終了コード
 */
/* ------------------------------------------------------------------------- */
int WINAPI WinMain(_In_ HINSTANCE hInstance, _In_opt_ HINSTANCE hPrevInstance, _In_ LPSTR lpCmdLine, _In_ int nCmdShow)
{
    MGL::Win32::Initializer initializer;

    /*
     *  ログレベルの設定
     *      通常は AppTrace のままで問題ありません。
     *      MGL側のトレースを表示したい場合は LibraryTrace に変更してください。
     */
    initializer.SetLogLevel(MGL::System::LogLevel::AppTrace);

    /*
     *  オーディオの初期化モード
     *      作るゲームにとって都合の良いモードを指定してください。
     *      オーディオ再生が不要な場合には None を指定できます。
     */
    initializer.SetAudioInitializeMode(MGL::Audio::InitializeMode::Sample44k2ch);

    /*
     *  XInput ゲームパッドの有効化
     *      不要な場合は false を指定してください。
     */
    initializer.EnableXInputGamepad(true);

    /*
     *  DirectInput ゲームパッドの有効化
     *      不要な場合は false を指定してください。
     *      この指定が true であっても、XInputゲームパッドが接続されている場合は
     *      DirectInputゲームパッドは利用できません。
     */
    initializer.EnableDirectInputGamepad(true);


    // ウィンドウの設定
    MGL::Win32::Window::Descriptor windowDescriptor;
    windowDescriptor.width = 1280;                                              // 幅
    windowDescriptor.height = 720;                                              // 高さ
    windowDescriptor.windowTitle = L"YourAppName";                              // ウィンドウタイトルに表示する文字列
    windowDescriptor.className = windowDescriptor.windowTitle;                  // ウィンドウのクラス名に設定する文字列
    windowDescriptor.icon = LoadIcon(hInstance, MAKEINTRESOURCE(IDC_MYICON));   // ウィンドウアイコン
    windowDescriptor.smallIcon = windowDescriptor.icon;                         // ウィンドウの小アイコン

    /*
     *   MGLのメイン関数の呼び出し
     *      テンプレート引数には登録するアプリケーションデリゲートのクラス名を記述してください。
     */
    auto result = MGL::Win32::Main<YourApp::Application>(hInstance, hPrevInstance, lpCmdLine, nCmdShow, initializer, windowDescriptor);

    return result;
}

// vim: et ts=4 sw=4 sts=4

このソースコードの記述内容は主にMGLの初期化パラメータの設定となります。コメントを参照しながら必要に応じてパラメータを変更して利用してください。

最後のメイン関数の呼び出し部分にあるYourApp::Applicationの部分が登録するアプリケーションデリゲートの指定となります。ゲームごとに適切な名前に変更してください。

これまでの手順に誤りがなければ、ビルドして実行することで次のような青い画面が表示されます。

../_images/vs_sample_exec.png

実行結果#

注釈

自動生成されたヘッダファイルのmgl-test-win.hとframework.hはもう必要ないため、削除しても問題ありません。