MGL::System::Application#

概要#

MGL::System::Applicationは、アプリケーションの動作に関わる情報の取得や設定を行うためのクラスです。アプリケーションの実行時引数の取得や終了要求、システムとの情報のやり取りなどはこのクラスが担っています。

クリップボードにアクセスする際の注意点#

このクラスにはシステムのクリップボード（ペーストボード）にアクセスするためのAPIが存在します。

システムのクリップボードは全てのアプリケーションが共通でアクセス可能な記憶領域ですが、そこにはパスワードなどの個人情報が含まれる場合があります。そのため、ユーザーに明示せずにクリップボードにアクセスする行為は、マルウェアなどの不正なアプリケーションとして疑われる可能性があります。

クリップボードの機能を使用する前に、次の点を確認してください。

  1. 扱う内容がアプリケーションを跨ぐ必要があるかを再確認してください。ゲーム内で完結する内容を一時保存する場合、システムのクリップボードを利用すべきではありません。

  2. ユーザーは自分の操作によらないクリップボードのアクセスに不安を覚えます。これは明示的なインターフェース（「コピー」や「ペースト」ボタン、明示された操作ガイド等）を通して扱うことで回避できます。

  3. クリップボードは開発中のデバッグ機能向けのインターフェースとして非常に有用であり、広く用いられています。しかし、もしそれが製品に残ってしまった場合のリスクも認識しておく必要があります。

宣言#

namespace MGL::System
{
    class Application;
}

利用例#

Escキーを押下したらアプリケーションを終了する例
void Application::OnFrameUpdate() noexcept
{
    MGL::System::Application application;

    // アプリケーションが終了をサポートしているかをチェック
    if (application.IsAvailableQuit())
    {
        // Escキーを押下したら終了
        if (MGL::Input::Keyboard().IsTriggered(MGL::Input::Keycode::Escape))
        {
            application.Quit();
        }
    }
}
スペースキーを押下している間、フレーム間の経過時間を取得する例
void Application::OnFrameUpdate() noexcept
{
    // スペースキーの押下中チェック
    if (MGL::Input::Keyboard().IsPressing(MGL::Input::Keycode::Space))
    {
        // フレーム間の経過時間を取得してトレース表示
        auto elapsedTime = MGL::System::Application().GetFrameElapsedTime();

        MGL_TRACE("%f", elapsedTime);
    }
}

メンバ情報#

種類

名前

内容

バージョン

関数

Caffeinate

省電力モードを抑制

1.0.0+

関数

IsCaffeinated

省電力モードの抑制状態を取得

1.0.0+

関数

GetArguments

実行時引数を取得

1.0.0+

関数

Quit

アプリケーションの終了

1.0.0+

関数

IsAvailableQuit

アプリケーションの終了がサポートされているかを取得

1.0.0+

関数

GetFrameElapsedTime

フレーム間の経過時間を取得

1.0.0+

関数

GetFramesPerSecond

フレームレートを取得

1.0.0+

関数

SetClipboardText

クリップボートにテキストを設定

1.0.0+

関数

GetClipboardText

クリップボードからテキストを取得

1.0.0+

関数

IsAvailableClipboard

クリップボードがサポートされているかを取得

1.0.0+

Caffeinate#

省電力モードを抑制

宣言#

namespace MGL::System
{
    class Application
    {
        bool Caffeinate(bool isEnabled) noexcept;
    };
}

引数#

bool isEnabled

trueで抑制を有効、falseで抑制を無効

戻り値#

bool

成功時にtrue、失敗時にfalse

説明#

無操作期間が続いた際に、システムが自動で省電力モードになる動作を制御します。引数にtrueを指定することで抑制を有効化し、falseで解除します。

省電力モードの具体的な動作内容は環境依存となります。代表的な例としては、画面の輝度を下げたり、スリープモードへ移行するなどがあります。

動作中の環境が省電力モードの抑制に対応していない場合、失敗として戻り値にfalseが返ります。

注意

省電力モードの抑制はエネルギーの浪費やハードウェアの消耗を招く場合があります。本関数は無操作期間が続くと想定されるシーン（ムービーやイベントシーン、リプレイの再生など）のみに適用し、該当シーンが終了次第直ちに解除するようにしてください。

プラットフォームによっては、省電力モードの抑制が規約等で制限されている場合があります。本関数の動作や対応状況に関わらず、制限内容を優先してください。

利用例#

// 省電力モードを抑制
if (!MGL::System::Application().Caffeinate(true))
{
    MGL_TRACE("この環境では利用できません");
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

IsCaffeinated#

省電力モードの抑制状態を取得

宣言#

namespace MGL::System
{
    class Application
    {
        [[nodiscard]] bool IsCaffeinated() const noexcept;
    };
}

戻り値#

省電力モードが抑制されている状態であればtrue、抑制されていなければfalse

説明#

Caffeinateによる省電力モードの抑制が行われているかを取得します。

この関数がtrueを返す場合、無操作期間が続いた際にシステムが省電力モードになる動作が抑制されています。

利用例#

// 省電力モードの抑制状態を取得
if (MGL::System::Application().IsCaffeinated())
{
    MGL_TRACE("省電力モードを抑制中 (Caffeinate()が有効)");
}
else
{
    MGL_TRACE("省電力モードは抑制されていない (Caffeinate()は無効)");
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

関連#

GetArguments#

実行時引数を取得

宣言#

namespace MGL::System
{
    class Application
    {
        [[nodiscard]] const ArgumentArray &GetArguments() const noexcept;
    };
}

戻り値#

MGL::System::ArgumentArray

実行時引数を格納した配列

説明#

アプリケーションの起動時に渡された引数を文字列の配列として取得します。

実行時引数の格納内容はシステム依存です。

利用例#

// 実行時引数を取得
auto arguments = MGL::System::Application().GetArguments();

// 実行時引数の内容をトレース出力
for (const auto &argument : arguments)
{
    MGL_TRACE(argument.c_str());
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

関連#

Quit#

アプリケーションの終了

宣言#

namespace MGL::System
{
    class Application
    {
        void Quit() noexcept;
    };
}

説明#

システムにアプリケーションの終了を要求します。

この機能は対応していない環境では機能しません。対応状況はIsAvailableQuitにて取得できます。

注釈

この関数は、ユーザーが通常手段でアプリケーションを終了する操作（ウィンドウの閉じるボタンを押すなど）をプログラム側から要求するための機能です。アプリケーションプロセスに対する終了要求ではない点にご注意ください。

利用例#

// アプリケーションの終了を要求
MGL::System::Application().Quit();

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

IsAvailableQuit#

アプリケーションの終了がサポートされているかを取得

宣言#

namespace MGL::System
{
    class Application
    {
        [[nodiscard]] bool IsAvailableQuit() const noexcept;
    };
}

戻り値#

対応している場合はtrue、対応していない場合はfalse

説明#

動作中の環境がアプリケーションの終了要求に対応しているかを取得します。この関数がfalseを返す環境においては、Quitによるアプリケーションからの終了が行えません。

MGLの標準構成における対応状況は次の通りです。

環境

対応状況

Windows

対応

macOS

対応

iOS/iPadOS

非対応

tvOS

非対応

利用例#

// アプリケーションの終了要求に対応しているかを取得
if (MGL::System::Application().IsAvailableQuit())
{
    MGL_TRACE("アプリケーションの終了要求に対応している");
}
else
{
    MGL_TRACE("アプリケーションの終了要求に対応していない");
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

MGL 1.1.12

  • リネーム: IsSupportedQuit → IsAvailableQuit

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

関連#

GetFrameElapsedTime#

フレーム間の経過時間を取得

宣言#

namespace MGL::System
{
    class Application
    {
        [[nodiscard]] float GetFrameElapsedTime() const noexcept;
    };
}

戻り値#

フレーム間の経過時間（ミリ秒）

説明#

フレーム間の経過時間をミリ秒単位で取得します。

時間の更新はフレーム更新処理の開始前に行われ、フレーム間の時間差が経過時間として扱われます。

この関数は主にゲーム全体の時間の進行管理を目的として実装されています。局所的な時間の測定を行いたい場合はMGL::System::Chrono::GetTickTimeを使用してください。

利用例#

// Aキーを押下したタイミングで経過時間をトレース表示する例
if (MGL::Input::Keyboard().IsTriggered(MGL::Input::Keycode::KeyA))
{
    // フレーム間の経過時間を取得
    auto elapsedTime = MGL::System::Application().GetFrameElapsedTime()

    // 経過時間をトレース表示
    MGL_TRACE("%f", elapsedTime);
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

関連#

GetFramesPerSecond#

フレームレートを取得

宣言#

namespace MGL::System
{
    class Application
    {
        [[nodiscard]] uint32_t GetFramesPerSecond() const noexcept;
    };
}

戻り値#

uint32_t

過去1秒間のフレーム更新回数（実測値）

説明#

現在のフレームレートを取得します。

アプリケーションクラスはフレーム更新処理が行われた回数をカウントしており、この回数は1秒間隔で更新・クリアされます。本関数は前回の更新値を返すものであり、これは1秒間隔で更新されるフレーム更新回数の実測値となります。

実測値ではなく理論値としてのフレームレートを取得したい場合、GetFrameElapsedTimeを用いて算出してください。

利用例#

// Aキーを押下したタイミングでフレームレートをトレース表示する例
if (MGL::Input::Keyboard().IsTriggered(MGL::Input::Keycode::KeyA))
{
    auto FramesPerSecond = MGL::System::Application().GetFramesPerSecond();
    MGL_TRACE("フレームレート: %d", FramesPerSecond);
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

関連#

SetClipboardText#

クリップボートにテキストを設定

宣言#

namespace MGL::System
{
    class Application
    {
        bool SetClipboardText(const char *text) noexcept;
    };
}

引数#

const char *text

クリップボードに設定する文字列

戻り値#

bool

成功時にtrue、失敗時にfalse

説明#

システムのクリップボード（ペーストボード）に文字列を設定します。

処理に成功した場合、戻り値にtrueが返ります。クリップボードへのアクセスが有効でない環境では常に失敗となり、戻り値としてfalseが返ります。

その環境でクリップボードへのアクセスが可能であるかはIsAvailableClipboardにて確認できます。

注意

本関数の利用についてはクリップボードにアクセスする際の注意点も参照してください。

利用例#

// システムのクリップボードへ文字列 "Hello, MGL" を設定する例
MGL::System::Application().SetClipboardText("Hello, MGL");

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

GetClipboardText#

クリップボードからテキストを取得

宣言#

namespace MGL::System
{
    class Application
    {
        bool GetClipboardText(STL::string &text) noexcept;
    };
}

引数#

MGL::STL::string &text

取得したテキストの格納先

戻り値#

成功時にtrue、失敗時にfalse

説明#

システムのクリップボード（ペーストボード）からテキストを取得し、引数textにその内容を格納します。

処理に成功した場合、戻り値にtrueが返ります。クリップボードの内容がテキストでなかったり、クリップボードへのアクセスができない環境で実行した場合は失敗となりfalseが返ります。

その環境でクリップボードへのアクセスが可能であるかはIsAvailableClipboardにて確認できます。

注意

本関数の利用についてはクリップボードにアクセスする際の注意点も参照してください。

利用例#

MGL::STL::string text;

// システムのクリップボードから文字列を取得
if (MGL::System::Application().GetClipboardText(text))
{
    // クリップボードの内容をトレース表示
    MGL_TRACE(text.c_str());
}
else
{
    MGL_TRACE("クリップボードからのテキスト取得に失敗");
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

関連#

IsAvailableClipboard#

クリップボードがサポートされているかを取得

宣言#

namespace MGL::System
{
    class Application
    {
        [[nodiscard]] bool IsAvailableClipboard() const noexcept;
    };
}

戻り値#

動作中の環境でクリップボード（ペーストボード）へのアクセスが有効な場合はtrue、利用できない場合はfalse

説明#

動作中の環境でクリップボードへのアクセスが有効であるかを取得します。

本関数がfalseを返す環境ではクリップボードは利用できず、SetClipboardTextおよびGetClipboardTextは常に失敗します。

利用例#

// クリップボードが利用可能かを判別する例
if (MGL::System::Application().IsAvailableClipboard())
{
    MGL_TRACE("クリップボードへのアクセスが有効");
}
else
{
    MGL_TRACE("クリップボードへのアクセスは無効");
}

バージョン情報#

MGL 1.0.0

  • 初回リリース

MGL 1.1.12

  • リネーム: IsSupportedClipboard → IsAvailableQuit

MGL 1.1.13

  • 関数の戻り値に[[nodiscard]]属性を付与

関連#