MGL::Task#

概要#

MGL::Taskに定義されているAPIの情報です。型や定数の情報に関してはMGL::Task 各種定義を参照してください。

タスクシステムの使用方法についてはタスクシステムを参照してください。

関数#

種類	名前	内容	バージョン
関数	Initialize	タスクシステムの初期化	1.0.0+
関数	Create	タスクの生成	1.0.0+
関数	Execute	タスクシステムの実行	1.0.0+
関数	Kill	タスクの削除要求	1.0.0+
関数	DestroyThemAll	全てのタスクを強制的に削除	1.1.0+
関数	GetCount	登録されているタスクの数を取得	1.0.0+
関数	Find	タスクの検索	1.0.0+
関数	NotifyEvent	タスクへのイベント通知	1.0.0+

Initialize#

タスクシステムの初期化

宣言#

namespace MGL::Task
{
    bool Initialize(
        size_t capacity,
        const InitializeDescriptor &descriptor) noexcept;
}

引数#

size_t capacity: 登録可能なタスクノードの最大数
const MGL::Task::InitializeDescriptor descriptor: タスクシステム初期化用の記述子

戻り値#

成功時にtrue、失敗時にfalse

説明#

タスクシステムを初期化し、利用可能な状態にするための関数です。

引数capacityには登録可能なタスクの最大数を、descriptorにはタスクシステムの動作設定を格納した初期化記述子MGL::Task::InitializeDescriptorを指定します。

初期化方法の詳細についてはタスクシステムを参照してください。

利用例#

bool Application::OnInitialize() noexcept
{
    // タスクシステムの初期化
    if (!MGL::Task::Initialize(
        kTaskCapacity,
        TaskNode::GetInitializeDescriptor()))
    {
        return false;
    }

    return true;
}

より詳しい情報は初期化と実行を参照してください。

バージョン情報#

MGL 1.0.0

初回リリース

Create#

タスクの生成

宣言#

namespace MGL::Task
{
    template <class TaskClass, class... Args>
    constexpr WeakNode Create(Args... args) noexcept;
}

テンプレート引数#

class TaskClass: 生成するタスクノードの型

引数#

Args... Args: TaskClassに指定した型のコンストラクタに渡す引数

戻り値#

MGL::Task::WeakNode: 生成したタスクノードへの弱参照ノード

説明#

タスクを新規に生成し、タスクシステムへと登録します。

テンプレート引数TaskClassには、登録するタスクのタスクノードクラスを指定してください。クラスがコンストラクタを持つ場合、この関数の引数に指定した値がそのままタスクノードクラスのコンストラクタへと渡されます。

タスク生成に関する詳しい情報についてはタスクシステムのタスクの生成を参照してください。

生成に成功した場合、戻り値には有効な弱参照タスクが返ります。弱参照タスクの取り扱いについてはMGL::Task::WeakNodeまたはタスクの参照を参照してください。

利用例#

// 例1：引数を持たないタスク EmptyTask を生成
MGL::Task::Create<EmptyTask>();

// 例2：引数を持つタスク PlayerTask を生成
auto weakNode = MGL::Task::Create<PlayerTask>(MGL::Vector2(0.0f, 0.0f), 7.0f);
if (!weakNode)
{
    // 生成に失敗している場合はここに到達
}

バージョン情報#

MGL 1.0.0

初回リリース

Execute#

タスクシステムの実行

宣言#

namespace MGL::Task
{
    inline void Execute() noexcept;
}

説明#

タスクシステムを実行し、登録されている全てのタスクの更新処理を呼び出します。

通常、この関数はフレーム更新処理中に1回だけ呼び出します。

利用例#

/* ------------------------------------------------------------------------- */
/*!
 *  \brief      フレーム更新処理
 */
/* ------------------------------------------------------------------------- */
void Application::OnFrameUpdate() noexcept
{
    // 画面をクリア
    MGL::Render::Renderer2D renderer;
    renderer.Clear(MGL::kColorBlack);

    // タスクの実行
    MGL::Task::Execute();
}

バージョン情報#

MGL 1.0.0

初回リリース

Kill#

タスクの削除要求

宣言#

namespace MGL::Task
{
    // (1) 全てのタスクに対して削除を要求
    inline size_t Kill(
        ResideLevel resideLevel = ResideLevel::NoResident) noexcept;

    // (2) 特定の種類のタスクに対して削除を要求
    template <typename TaskIDType>
    inline size_t Kill(
        TaskIDType identifier,
        ResideLevel resideLevel = ResideLevel::NoResident) noexcept

}

テンプレート引数#

(1) 全てのタスクに対して削除を要求

テンプレート引数なし

(2) 特定の種類のタスクに対して削除を要求

typename TaskIDType: タスクの種類を表す型

引数#

(1) 全てのタスクに対して削除を要求

MGL::Task::ResideLevel resideLevel: 常駐レベル

(2) 特定の種類のタスクに対して削除を要求

TaskIDType identifier: 削除するタスクの種類
MGL::Task::ResideLevel resideLevel: 常駐レベル

戻り値#

size_t: 削除要求を発行したタスクの数

説明#

タスクに対して削除要求を行うための関数です。

(1)は現在登録されている全てのタスクに対して、(2)は特定のタスクIDを持ったタスクに対して削除要求を行います。特定の1つのタスクに対する削除要求はMGL::Task::WeakNode::Killを使用してください。

引数resideLevelは常駐レベルの指定です。対象となるタスクの常駐レベルとこの引数を比較し、より大きな常駐レベルが設定されているタスクに対しては削除要求を行いません。各々のタスクの常駐レベルの設定はMGL::Task::Node::SetResideLevelにて行えます。

戻り値には実際に削除要求を行ったタスクの数を返します。

タスクの削除に関する詳細はタスクシステムのタスクの削除を参照してください。

利用例#

// 敵弾タスク (TaskID::EnemyBullet と仮定)を一括で削除する例
MGL::Task::Kill(TaskID::EnemyBullet);

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.11

(2)をテンプレート関数に変更し、第1引数に任意の型を指定できるよう変更

DestroyThemAll#

全てのタスクを強制的に削除

宣言#

namespace MGL::Task
{
    inline size_t DestroyThemAll() noexcept;
}

戻り値#

size_t: 削除要求を発行したタスクの数

説明#

現在登録されている全てのタスクに対し、常駐レベルを無視して削除要求を行います。

通常のゲームシーケンスにおいて、この関数を使用することは推奨されません。何らかの理由でタスクを初期状態に戻したい場合（デバッグ用のソフトリセットなど）にのみ使用を検討してください。

利用例#

// 全てのタスクを削除
MGL::Task::DestroyThemAll();

バージョン情報#

MGL 1.0.0

初回リリース

GetCount#

登録されているタスクの数を取得

宣言#

namespace MGL::Task
{
    // (1) 全てのタスクの数を取得
    inline size_t GetCount() noexcept;

    // (2) 特定の種類のタスクの数を取得
    template <typename TaskIDType>
    inline size_t GetCount(TaskIDType identifier) noexcept;
}

テンプレート引数#

(1) 全てのタスクの数を取得

引数なし

(2) 特定の種類のタスクの数を取得

TaskIDType: タスクの種類を表す型

引数#

(1) 全てのタスクの数を取得

引数なし

(2) 特定の種類のタスクの数を取得

TaskIDType identifier: 取得するタスクの種類

戻り値#

size_t: 現在登録されているタスクノードの数

説明#

現在登録されているタスクの数を取得するための関数です。 (1)は登録されている全てのタスクの数を、(2)は指定したタスクIDの数をそれぞれ取得します。

(2)はテンプレート関数となっており、タスクIDをスコープ付きの列挙型で定義した場合でも使用可能となっています。通常、テンプレート引数は省略して使用します。

利用例#

// (1) 全てのタスクの数を取得
MGL_TRACE("タスクの合計数: %zu", MGL::Task::GetCount());

// (2) 特定の種類のタスクの数を取得 （例として TaskID::EnemyBullet を指定）
MGL_TRACE("EnemyBulletタスクの合計数: %zu", MGL::Task::GetCount(TaskID::EnemyBullet));

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.11

(2)をテンプレート関数に変更し、第1引数に任意の型を指定できるよう変更

Find#

タスクの検索

宣言#

namespace MGL::Task
{
    template <typename TaskIDType>
    STL::vector<WeakNode> Find(TaskIDType identifier) noexcept;
}

テンプレート引数#

typename TaskIDType: タスクの種類を表す型

引数#

TaskIDType identifier: 検索するタスクの種類

戻り値#

MGL::STL::vector < MGL::Task::WeakNode >: 指定したタスクの種類に対応した弱参照タスクノードの配列

説明#

指定された種類のタスクを検索し、その結果を弱参照タスクとして返す関数です。

このテンプレート関数となっており、タスクIDをスコープ付きの列挙型で定義した場合でも使用可能となっています。通常、テンプレート引数は省略して使用します。

より詳しい情報についてはタスクシステムのタスクの検索を参照してください。

利用例#

// EmptyTaskを検索
auto emptyTasks = MGL::Task::Find(TaskID::Empty);

// 検索結果を表示
MGL_TRACE("検索結果: %zu個発見", emptyTasks.size());

// 見つかった全てのタスクノードにアクセス
for (auto weakNode : emptyTasks)
{
    if (auto emptyTask = weakNode.Get<EmptyTask>(); emptyTask != nullptr)
    {
        // ここで emptyTask にアクセス可能
    }
}

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.11

(2)をテンプレート関数に変更し、第1引数に任意の型を指定できるよう変更

NotifyEvent#

タスクへのイベント通知

宣言#

namespace MGL::Task
{
    // (1) 全てのタスクにイベントを通知
    template <typename EventIDType>
    inline void NotifyEvent(
        EventIDType eventID,
        void *argument = nullptr) noexcept;

    // (2) 特定の種類のタスクにイベントを通知
    template <typename TaskIDType, typename EventIDType>
    inline void NotifyEvent(
        TaskIDType identifier,
        EventIDType eventID,
        void *argument = nullptr) noexcept;
}

テンプレート引数#

(1) 全てのタスクにイベントを通知

EventIDType: イベントの種類を表す型

(2) 特定の種類のタスクにイベントを通知

TaskIDType: タスクの種類を表す型
EventIDType: イベントの種類を表す型

引数#

(1) 全てのタスクにイベントを通知

EventIDType eventID: イベントの種類を表す値
void *argument: タスクに渡す引数

(2) 特定の種類のタスクにイベントを通知

TaskIDType identifier: 対象のタスクの種類を表す値
EventIDType eventID: イベントの種類を表す値
void *argument: タスクに渡す引数

説明#

登録中のタスクに対してイベント通知を行うための関数です。 (1)は登録されている全てのタスクに対して、(2)は特定の種類のタスクに対して、それぞれイベント通知を行います。

イベントはイベントの種類を表す値と、必要に応じて通知先に渡す引数をセットで指定します。これらの具体的な定義はアプリケーション側で定義する必要があります。

イベント通知の対象となったタスクはMGL::Task::Node::OnReceiveTaskEventが呼び出され、引数には呼び出し元で指定されたイベントIDと引数へのアドレスが渡されます。デフォルトタスクノードを使用している場合、代わりにMGL::Task::DefaultTaskNode::OnEventが呼び出されます。

タスクシステムにおけるイベント通知の詳細についてはタスクシステムのイベント通知を参照してください。

利用例#

次のような定義が行われていると仮定

// タスクIDの定義
enum class TaskID : MGL::Task::Identifier
{
    Player,     // プレイヤータスク
};

// イベントIDの定義
enum class TaskEvent : MGL::Task::EventIdentifier
{
    Pause,      // 一時停止イベント
}

イベント通知の利用例

// (1) 全てのタスクにイベントを通知
MGL::Task::NotifyEvent(TaskEvent::Pause);

// (2) 特定の種類のタスクにイベントを通知
MGL::Task::NotifyEvent(TaskID::Player, TaskEvent::Pause);

バージョン情報#

MGL 1.0.0

初回リリース

MGL 1.1.11

(2)をテンプレート関数に変更し、第1引数および第2引数に任意の型を指定できるよう変更

MGLドキュメント

MGL::Task

Contents

MGL::Task#

概要#

関数#

Initialize#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Create#

宣言#

テンプレート引数#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Execute#

宣言#

説明#

利用例#

バージョン情報#

関連#

Kill#

宣言#

テンプレート引数#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

DestroyThemAll#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

GetCount#

宣言#

テンプレート引数#

引数#

戻り値#

説明#

利用例#

バージョン情報#

Find#

宣言#

テンプレート引数#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

NotifyEvent#

宣言#

テンプレート引数#

引数#

説明#

利用例#

バージョン情報#

関連#