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から利用可能。

(2)はMGL 1.1.11からテンプレート関数に変更され、それ以前は第1引数の型をMGL::Task::Identifierとして利用可能。

関連#

DestroyThemAll#

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

宣言#

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

戻り値#

size_t

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

説明#

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

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

利用例#

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

バージョン情報#

MGL 1.1.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から利用可能。

(2)はMGL 1.1.11からテンプレート関数に変更され、それ以前は第1引数の型をMGL::Task::Identifierとして利用可能。

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からテンプレート関数に変更され、それ以前は第1引数の型をMGL::Task::Identifierとして利用可能。

関連#

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からテンプレート関数へと変更され、それ以前はTaskIDTypeにMGL::Task::Identifier、EventIDTypeにMGL::Task::EventIdentifierを指定したものとして利用可能。

関連#