MGL::Render::Texture#

概要#

Textureクラスはアプリケーション側からテクスチャを扱うためのクラスです。

宣言#

namespace MGL::Render
{
    class Texture;
}

メンバ情報#

種類	名前	内容	バージョン
関数	コンストラクタ		1.0.0+
関数	Load	テクスチャの同期読み込み	1.0.0+
関数	LoadAsync	テクスチャの非同期読み込み	1.0.0+
関数	Create	テクスチャの生成	1.0.0+
関数	CreateRenderTarget	レンダーターゲットの生成	1.0.0+
関数	GetResource	テクスチャリソースの取得	1.0.0+
関数	IsValid	有効状態の取得	1.0.0+
関数	IsLoading	読み込み中の状態を取得	1.0.0+
関数	GetSize	サイズの取得	1.0.0+
関数	Destroy	テクスチャの破棄	1.0.0+
関数	SetDefaultLoader	デフォルトのテクスチャローダーを設定	1.0.0+
関数	RegisterLoader	テクスチャローダーの登録	1.0.0+
関数	operator bool	bool型へのキャスト	1.0.0+
関数	operator !	否定演算子	1.0.0+

コンストラクタ#

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        // (1) 空のテクスチャクラスを生成
        constexpr Texture() noexcept;

        // (2) テクスチャリソースを直接割り当て
        Texture(SharedTextureResource resource) noexcept;

        // (3) テクスチャキーを指定してファイルから読み込み
        Texture(TextureKey key,
                const File::PathView &imagePath,
                bool isAsync,
                TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (4) テクスチャキーを指定してメモリ上の画像データから読み込み
        Texture(TextureKey key,
                const void *imageData,
                size_t dataSize,
                bool isAsync,
                TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (5) テクスチャキーを指定せずにファイルから読み込み
        Texture(const File::PathView &imagePath,
                bool isAsync,
                TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (6) テクスチャキーを指定せずにメモリ上の画像データから読み込み
        Texture(const void *imageData,
                size_t dataSize,
                bool isAsync,
                TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (7) テクスチャキーで初期化
        Texture(TextureKey key) noexcept;
    };
}

引数#

(1) 空のテクスチャクラスを生成

引数なし

(2) テクスチャリソースを直接割り当て

SharedTextureResource resource: 割り当てるテクスチャリソース

(3) ファイルから読み込んで初期化

const MGL::File::PathView &imagePath: 読み込む画像ファイルのパス
bool isAsync: 非同期読み込みフラグ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(4) メモリ上の画像データから読み込んで初期化

const void *imageData: 読み込む画像データの先頭アドレス
size_t dataSize: 画像データのサイズ
bool isAsync: 非同期読み込みフラグ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(5) テクスチャキーを指定してファイルから読み込み

TextureKey key: 登録するテクスチャキー
const MGL::File::PathView &imagePath: 読み込む画像ファイルのパス
bool isAsync: 非同期読み込みフラグ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(6) テクスチャキーを指定してメモリ上の画像データから読み込み

TextureKey key: 登録するテクスチャキー
const void *imageData: 読み込む画像データの先頭アドレス
size_t dataSize: 画像データのサイズ
bool isAsync: 非同期読み込みフラグ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(7) テクスチャキーで初期化

TextureKey key: 登録済みのテクスチャキー

説明#

テクスチャクラスを初期化するためのコンストラクタです。

(1)は空のテクスチャクラスを生成します。クラスのメンバ変数に持たせる場合など、コンストラクタの実行と初期化処理を分離したい場合はこの方法が最適です。

(2)はテクスチャリソースクラスからテクスチャクラスを生成します。テクスチャリソースクラスはアプリケーション側から直接扱うものでは無いため、主に機能拡張を行う際に使用します。

(3)から(6)は生成と同時にLoadまたはLoadAsyncを実行します。引数のisAsyncにtrueを指定するとLoadAsyncが、falseを指定するとLoadが実行されます。その他の引数は各々の関数に直接渡されるため、そちらを参照してください。

(7)はテクスチャキーで初期化します。既にテクスチャキーを指定して読み込みが行われている場合、明示的に破棄するまではそのキーを用いてテクスチャを取得できます。キーに対応したテクスチャリソースが存在しない場合は無効なテクスチャクラスが生成されます。

利用例#

// 次の画像ファイルのパスとテクスチャキーを定義しているものとする

// 画像ファイルのパス
constexpr const char *kImagePath = "path/to/imagefile";

// パスから生成したテクスチャキー
constexpr auto kTextureKey = MGL::Render::MakeTextureKey(kImagePath);

// (1)の空のテクスチャを生成して読み込み要求を行う例

MGL::Render::Texture texture;

// 同期読み込み
texture.Load(kTextureKey, kImagePath, false);
if (texture)
{
    // 読み込みに成功していればここに到達
    ...
}

// (5)のテクスチャキーとファイルパスを指定した読み込みの例
// この例は先述の(1)の例とほぼ同等の処理になる

MGL::Render::Texture texture(kTextureKey, kImagePath, false);

if (texture)
{
    // 読み込みに成功していればここに到達
    ...
}

// (7)のテクスチャキーを指定した初期化の例
// 既に読み込み済みのテクスチャを別の箇所で取得する際に有効

MGL::Render::Texture texture(kTextureKey);

if (texture)
{
    // 有効なテクスチャキーが取得できていればここに到達
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース

Load#

テクスチャの同期読み込み

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        // (1) ファイルから読み込み
        bool Load(const File::PathView &imagePath,
                  TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (2) メモリ上の画像データから読み込み
        bool Load(const void *imageData,
                  size_t dataSize,
                  TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (3) テクスチャキーを指定してファイルから読み込み
        bool Load(TextureKey key,
                  const File::PathView &imagePath,
                  TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (4) テクスチャキーを指定してメモリ上の画像データから読み込み
        bool Load(TextureKey key,
                  const void *imageData,
                  size_t dataSize,
                  TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (5) テクスチャキーで取得
        bool Load(TextureKey key) noexcept;
    };
}

引数#

(1) ファイルから読み込み

const MGL::File::PathView &imagePath: 読み込む画像ファイルのパス
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(2) メモリ上の画像データから読み込み

const void *imageData: 読み込む画像データの先頭アドレス
size_t dataSize: 画像データのサイズ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(3) テクスチャキーを指定してファイルから読み込み

TextureKey key: 登録するテクスチャキー
const MGL::File::PathView &imagePath: 読み込む画像ファイルのパス
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(4) テクスチャキーを指定してメモリ上の画像データから読み込み

TextureKey key: 登録するテクスチャキー
const void *imageData: 読み込む画像データの先頭アドレス
size_t dataSize: 画像データのサイズ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(5) テクスチャキーで取得

TextureKey key: 登録済みのテクスチャキー

戻り値#

bool: 成功時にtrue、失敗時にfalse

説明#

ファイルまたはメモリ上の画像データからテクスチャを読み込んで初期化します。読み込みは同期的に実行され、完了するまで処理はブロックされます。

(1)と(2)は通常のテクスチャ読み込みです。読み込みに成功した場合、有効なテクスチャリソースが保持されてtrueを返します。読み込みに失敗した場合はfalseが返ります。

(3)と(4)はテクスチャキーを指定した読み込みです。この方法で読み込んだテクスチャは、Destroyを用いて明示的に破棄するまでは登録したキーを経由してテクスチャを取得できるようになります。指定したテクスチャキーが既に登録されている場合、両者は同じものであると扱われ、読み込み処理を行わずに既に登録されたテクスチャリソースで初期化されます。

(5)はテクスチャキーを指定し、登録済みのテクスチャを取得します。指定したテクスチャキーが登録されていない場合は失敗となりfalseが返ります。

loaderKeyは読み込みの際に利用するテクスチャローダーの指定です。省略した場合はSetDefaultLoaderで設定したローダーが使用されます。例外的に異なるテクスチャローダーを使用したい場合はこの引数を指定してください。独自に実装したテクスチャローダーを登録していない場合は常に省略して問題ありません。

利用例#

// 次の画像ファイルのパスとテクスチャキーを定義しているものとする

// 画像ファイルのパス
constexpr const char *kImagePath = "path/to/imagefile";

// パスから生成したテクスチャキー
constexpr auto kTextureKey = MGL::Render::MakeTextureKey(kImagePath);

// (1)のファイルから読み込む例

{
    MGL::Render::Texture texture;

    // ファイルからテクスチャ読み込み
    if (texture.Load(ImagePath))
    {
        // 成功している場合ここに到達する
        ...
    }

    ...
}
// テクスチャキーを指定していないため、textureの寿命が切れた時点でテクスチャは破棄される。

// (3)のテクスチャキーを指定してファイルから読み込む例

{
    MGL::Render::Texture texture;

    // テクスチャキーを指定してファイルからテクスチャ読み込み
    if (texture.Load(kTextureKey, ImagePath))
    {
        // 成功している場合ここに到達する
        ...
    }

    ...
}

// テクスチャキーを指定しているため、textureの寿命が切れてもテクスチャリソースは保持されている。
// この場合、次の(5)の例でテクスチャの取得が行えるようになる。

// (5)のテクスチャキーによる取得

MGL::Render::Texture texture;

// テクスチャキーで取得
if (texture.Load(kTextureKey))
{
    // 先述の(3)の例があらかじめ実行されている場合は成功し、ここに到達する
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース

LoadAsync#

テクスチャの非同期読み込み

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        // (1) ファイルから非同期読み
        bool LoadAsync(const File::PathView &imagePath,
                       TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (2) メモリ上の画像データから非同期読み込み
        bool LoadAsync(const void *imageData,
                       size_t dataSize,
                       TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (3) テクスチャキーを指定してファイルから非同期読み込み
        bool LoadAsync(TextureKey key,
                       const File::PathView &imagePath,
                       TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;

        // (4) テクスチャキーを指定してメモリ上の画像データから非同期読み込み
        bool LoadAsync(TextureKey key,
                       const void *imageData,
                       size_t dataSize,
                       TextureLoaderKey loaderKey = TextureStorage::kDefaultLoaderKey) noexcept;
    };
}

引数#

(1) ファイルから読み込み

const MGL::File::PathView &imagePath: 読み込む画像ファイルのパス
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(2) メモリ上の画像データから読み込み

const void *imageData: 読み込む画像データの先頭アドレス
size_t dataSize: 画像データのサイズ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(3) テクスチャキーを指定してファイルから読み込み

TextureKey key: 登録するテクスチャキー
const MGL::File::PathView &imagePath: 読み込む画像ファイルのパス
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

(4) テクスチャキーを指定してメモリ上の画像データから読み込み

TextureKey key: 登録するテクスチャキー
const void *imageData: 読み込む画像データの先頭アドレス
size_t dataSize: 画像データのサイズ
TextureLoaderKey loaderKey: 読み込みの際に使用するテクスチャローダーのキー。省略時はkDefaultLoaderKey

戻り値#

bool: 読み込みの準備に成功した場合にtrue、失敗にfalse

説明#

ファイルまたはメモリ上の画像データからテクスチャを読み込みます。読み込みは非同期的に実行され、読み込み完了を待たずに関数を抜けて戻り値を返します。

(1)と(2)は通常のテクスチャ読み込みです。読み込みの準備が完了し、正常に読み込み処理が開始された場合はtrueが返ります。テクスチャリソースの生成に失敗したり、システムのスレッドリソースが枯渇している場合などに失敗となり、falseを返します。

関数が成功してtrueを返した場合、読み込み処理が完了するまでIsLoadingがtrueを返すようになります。再びIsLoadingがfalseを返すようになった後、IsValidにて読み込みの成否を確認できます。

テクスチャキーを指定して読み込み要求を行った場合、関数が成功した時点でキーによる取得が可能となりますが、読み込みに失敗した場合はそのタイミングでキーによる取得が不可能となります。

利用例#

// 次の画像ファイルのパスとテクスチャキーを定義しているものとする

// 画像ファイルのパス
constexpr const char *kImagePath = "path/to/imagefile";

// パスから生成したテクスチャキー
constexpr auto kTextureKey = MGL::Render::MakeTextureKey(kImagePath);

// (1)のファイルから非同期読み込みを行う例

MGL::Render::Texture texture;

// 読み込み要求
if (texture.LoadAsync(ImagePath))
{
    // 正常に開始された場合はここに到達
    ...
}

...

// 読み込み中チェック
if (texture.IsLoading())
{
    // 読み込み中の間はここに到達
    ...
}
// テクスチャの有効性のチェック
else if (texture.IsValid())
{
    // 読み込みに成功した場合はここに到達
    ...
}
else
{
    // 読み込みに失敗した場合はここに到達
    ...
}

// (3)のテクスチャキーを指定してファイルから非同期読み込みを行う例

MGL::Render::Texture texture;

// 読み込み要求
if (texture.LoadAsync(kTextureKey, ImagePath))
{
    // 正常に開始された場合はここに到達
    ...
}

// (3)で初期化したテクスチャを別の場所から取得する例

// キーを用いてテクスチャを取得
MGL::Render::Texture texture(kTextureKey);
if (!texture)
{
    // 非同期の読み込みに失敗していたり、そもそも読み込み要求が行われていない場合はここに到達
    ...
}

// 読み込み中チェック
if (texture.IsLoading())
{
    // 読み込み中の間はここに到達
    ...
}
// テクスチャの有効性のチェック
else if (texture.IsValid())
{
    // 読み込みに成功した場合はここに到達
    ...
}
else
{
    // 非同期読み込みを行った場合、失敗時にはtextureそのものが取得できなくなるため、ここには到達しない
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース

Create#

テクスチャの生成

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        // (1) テクスチャの生成
        bool Create(const void *pixelData,
                    PixelFormat pixelFormat,
                    uint32_t width,
                    uint32_t height) noexcept;

        // (2) テクスチャキーを指定してテクスチャを生成
        bool Create(TextureKey key,
                    const void *pixelData,
                    PixelFormat pixelFormat,
                    uint32_t width,
                    uint32_t height) noexcept;
    };
}

引数#

(1) テクスチャの生成

const void *pixelData: ピクセルデータの先頭アドレス
PixelFormat pixelFormat: ピクセルデータのフォーマット
uint32_t width: テクスチャの幅
uint32_t height: テクスチャの高さ

(2) テクスチャキーを指定してテクスチャを生成

TextureKey key: 登録するテクスチャキー
const void *pixelData: ピクセルデータの先頭アドレス
PixelFormat pixelFormat: ピクセルデータのフォーマット
uint32_t width: テクスチャの幅
uint32_t height: テクスチャの高さ

戻り値#

bool: 成功時にtrue、失敗時にfalse

説明#

ピクセルデータを元にテクスチャを生成します。LoadやLoadAsyncとは異なり、テクスチャローダーを経由せず、レンダラが対応しているピクセルフォーマットのデータから直接生成する場合はこちらを使用します。

(1)はメモリ上のピクセルデータを格納しているバッファアドレスを指定し、そのフォーマット、幅、高さを別途指定して生成を行います。この時、関数はpixelDataのアドレスから最大で1ピクセルあたりのバイト数×幅×高さの範囲を読み取ります。ピクセルデータに対して適切でない引数を指定した場合、範囲外にアクセスする可能性があることにご注意ください。

(2)は(1)に加えてテクスチャキーを指定してテクスチャを生成します。この方法で生成テクスチャは、Destroyを用いて明示的に破棄するまでは登録したキーを経由してテクスチャを取得できるようになります。指定したテクスチャキーが既に登録されている場合、この関数は失敗してfalseを返します。

利用例#

// pixelDataを512x512ピクセルの32bit RGBA画像と仮定
const void *pixelData = xxx;

// 空のテクスチャを生成
MGL::Render::Texture texture;

// pixelDataを元にテクスチャを生成
texture.Create(pixelData,
               MGL::Render::PixelFormat::RGBA8_UNorm,
               512,
               512);

バージョン情報#

MGL 1.0.0
- 初回リリース

CreateRenderTarget#

レンダーターゲットの生成

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        // (1) テクスチャキーなし
        bool CreateRenderTarget(uint32_t width, uint32_t height) noexcept;

        // (2) テクスチャキーあり
        bool CreateRenderTarget(TextureKey key, uint32_t width, uint32_t height) noexcept;
    };
}

引数#

(1) テクスチャキーなし

uint32_t width: テクスチャの幅
uint32_t height: テクスチャの高さ

(2) テクスチャキーあり

TextureKey key: 登録するテクスチャキー
uint32_t width: テクスチャの幅
uint32_t height: テクスチャの高さ

戻り値#

bool: 成功時にtrue、失敗時にfalse

説明#

描画先に指定して書き込み可能なテクスチャを生成します。この関数で生成したテクスチャはMGL::Render::Renderer2D::SetRenderTargetにて指定可能となり、主にオフスクリーンレンダリングに利用します。

テクスチャキーを指定して生成されたテクスチャはストレージへと登録され、Destroyを用いて明示的に破棄するまではキーを経由して取得可能となります。指定したテクスチャキーが既に登録されている場合、対応したテクスチャがレンダーターゲットであればそのテクスチャを、そうでなければ失敗としてfalseを返します。

注釈

現時点において、ピクセルフォーマットを指定したレンダーターゲットの生成には対応していません。MGLの標準のレンダラでは、メインのフレームバッファ（Direct3Dではスワップチェーンに登録したビュー、Metalではドローアブル）と同じピクセルフォーマットで生成しています。

利用例#

// レンダーターゲット用のキーを定義
constexpr auto kRenderTargetKey = MGL::Render::MakeTextureKey("rendertarget-name");

// レンダーターゲットの生成の例

MGL::Render::Texture renderTarget;

// 640×480のレンダーターゲットを生成
renderTarget.CreateRenderTarget(kRenderTargetKey, 640, 480);

// レンダーターゲットの利用例

// キーを指定してレンダーターゲットを取得
MGL::Render::Texture renderTarget(kRenderTargetKey);

// 2Dレンダラの描画先に設定
// 以降はこのテクスチャに対して描画が行われる
MGL::Render::Renderer2D renderer;
renderer.SetRenderTarget(renderTarget);

バージョン情報#

MGL 1.0.0
- 初回リリース

GetResource#

テクスチャリソースの取得

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        [[nodiscard]] SharedTextureResource GetResource() const noexcept;
    };
}

戻り値#

SharedTextureResource: このクラスが保持しているテクスチャリソース

説明#

このクラスが保持しているテクスチャリソースを取得します。

テクスチャリソースは主にレンダラ側で利用するテクスチャです。アプリケーション側から直接扱う必要はないため、主に機能拡張向けの関数となります。

この関数はテクスチャリソースが利用可能でない場合にnullptrを返します。具体的には、次に挙げる状態において戻り値がnullptrとなります。

テクスチャリソースのインスタンスを保持していない状態
テクスチャリソースのインスタンスを保持しているが、リソースが利用可能でない状態
LoadAsync実行後、IsLoadingがtrueを返す状態

バージョン情報#

MGL 1.0.0
- 初回リリース
MGL 1.1.13
- 関数の戻り値に[[nodiscard]]属性を付与

IsValid#

有効状態の取得

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        [[nodiscard]] bool IsValid() const noexcept;
    };
}

戻り値#

bool: テクスチャが有効である場合にtrue、そうでなければfalse

説明#

テクスチャの有効状態を取得するための関数です。このクラスがテクスチャリソースを保持しており、かつ利用可能である場合にtrueを返します。

注釈

LoadAsyncによる非同期読み込みを実行した場合、この関数がtrueを返すタイミングはMGL::Render::TextureResourceの継承先クラスの実装に依存するため不定となります。読み込みの完了を取得する場合はIsLoadingを使用してください。

利用例#

// テクスチャキーを定義
constexpr auto kTextureKey = MGL::Render::MakeTextureKey("texture-name");

// テクスチャを取得
MGL::Render::Texture texture(kTextureKey);

// テクスチャの有効状態をチェック
if (texture.IsValid())
{
    // テクスチャが有効であればここに到達
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース
MGL 1.1.13
- 関数の戻り値に[[nodiscard]]属性を付与

IsLoading#

読み込み中の状態を取得

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        [[nodiscard]] bool IsLoading() const noexcept;
    };
}

戻り値#

bool: 読み込み中である場合にtrue、そうでなければfalse

説明#

非同期読み込みを実行後、読み込み処理が実行中であるかを取得するための関数です。この関数がtrueを返す場合は読み込み処理が実行中であるため、テクスチャを利用することはできません。

同期読み込みを行った場合、この関数は常にfalseを返します。

利用例#

// テクスチャキーを定義
constexpr auto kTextureKey = MGL::Render::MakeTextureKey("texture-name");

// テクスチャを取得
MGL::Render::Texture texture(kTextureKey);

if (texture.IsLoading())
{
    // テクスチャが読み込み中であればここに到達
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース
MGL 1.1.13
- 関数の戻り値に[[nodiscard]]属性を付与

GetSize#

サイズの取得

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        [[nodiscard]] Vector2 GetSize() const noexcept;
    };
}

戻り値#

MGL::Vector2: テクスチャのサイズ

説明#

読み込み済みのテクスチャのサイズを取得します。無効なテクスチャに対して呼び出した場合はMGL::Vector2(0.0f, 0.0f)が返ります。

利用例#

MGL::Render::Texture texture(kTextureKey);

auto size = texture.GetSize();  // テクスチャが有効であればそのサイズが、無効であれば(0.0f, 0.0f)が返る

バージョン情報#

MGL 1.0.0
- 初回リリース
MGL 1.1.13
- 関数の戻り値に[[nodiscard]]属性を付与

Destroy#

テクスチャの破棄

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        // (1) 自身を破棄
        bool Destroy() noexcept;

        // (2) テクスチャキーを指定して破棄
        static bool Destroy(TextureKey key) noexcept;
    };
}

引数#

(1) 自身を破棄

引数なし

(2) テクスチャキーを指定して破棄

TextureKey key: 破棄するテクスチャのキー

戻り値#

bool: 成功時にtrue、失敗時にfalse

説明#

テクスチャキーを指定して読み込んだテクスチャを破棄します。この関数を実行することにより、テクスチャキーによるテクスチャの取得は不可能となり、適切なタイミングでテクスチャリソースを破棄します。

(1)は自分自身が保持しているリソースを破棄します。この関数はテクスチャキーを指定して初期化した場合にのみ有効で、テクスチャキーを用いずに初期化したテクスチャに対しては機能せずfalseを返します。

(2)はテクスチャキーを指定して破棄します。この関数はstatic関数であるため、インスタンスを生成せずに利用可能です。

この関数の実行後、テクスチャの有効性は直ちに失われることはなく、全ての参照が失われた時点でテクスチャリソースが破棄されます。

MGLはアプリケーション終了時に登録されている全てのテクスチャリソースを破棄するため、アプリケーション動作中に常駐するリソースに対して明示的にこの関数を呼び出す必要はありません。

利用例#

// テクスチャキーを定義
constexpr auto kTextureKey = MGL::Render::MakeTextureKey("texture-name");

// (1) 自身を破棄

MGL::Render::Texture texture(kTextureKey);

if (texture.Destroy())
{
    // 成功時はここに到達
    ...
}

// (2) テクスチャキーを指定して破棄

if (MGL::Render::Texture::Destroy(kTextureKey))
{
    // 成功時はここに到達
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース

SetDefaultLoader#

デフォルトのテクスチャローダーを設定

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        static void SetDefaultLoader(TextureLoaderKey loaderKey) noexcept;
    };
}

引数#

TextureLoaderKey loaderKey: デフォルトに設定するローダーのキー

説明#

デフォルトのテクスチャローダーを変更します。主に独自にテクスチャローダーを実装した際に、そのローダーをデフォルトで扱いたい場合などに利用します。

コンストラクタ、Load、LoadAsyncの引数loaderKeyを省略、またはkDefaultLoaderKeyを指定した場合、この関数で設定されたローダーを使用します。

利用例#

// テクスチャローダーのキーを定義
constexpr auto kYourLoaderKey = MGL::Render::MakeTextureLoaderKey("YourLoaderName");

// デフォルトのテクスチャローダーを設定
MGL::Render::Texture::SetDefaultLoader(kYourLoaderKey);

バージョン情報#

MGL 1.0.0
- 初回リリース

RegisterLoader#

テクスチャローダーの登録

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        template <class LoaderClass, class... Args>
        constexpr static bool RegisterLoader(TextureLoaderKey loaderKey,
                                             Args... args) noexcept;
    };
}

引数#

LoaderClass: 登録するテクスチャローダーのクラス名
Args: LoaderClassのコンストラクタに渡す引数の宣言
TextureLoaderKey loaderKey: 登録するテクスチャローダーと関連付けるローダーキー
Args... args: LoaderClassのコンストラクタに渡す引数

戻り値#

bool: 成功時にtrue、失敗時にfalse

説明#

テクスチャローダーを登録するためのテンプレート関数です。独自に実装したテクスチャローダーを有効化する際に利用します。

指定したローダーキーが既に使用されている場合は失敗となり、falseが返ります。

利用例#

// 独自のテクスチャローダー"YourTextureLoader"を用意したと仮定
class YourTextureLoader : public MGL::Render::TextureLoader
{
public:
    // ローダーキーの定義
    static constexpr auto kLoaderKey = MGL::Render::MakeTextureLoaderKey("YourLoaderName");

    // コンストラクタ（引数なし）
    YourTextureLoader() noexcept;

    // コンストラクタ（引数あり）
    YourTextureLoader(uint32_t args1, float args2) noexcept;

    ...
}

// 引数を用いない場合の例

MGL::Render::Texture::RegisterLoader<YourTextureLoader>(YourTextureLoader::kLoaderKey);

// 引数を指定する場合の例

MGL::Render::Texture::RegisterLoader<YourTextureLoader>(YourTextureLoader::kLoaderKey,
                                                        0,
                                                        0.0f);

バージョン情報#

MGL 1.0.0
- 初回リリース

operator bool#

bool型へのキャスト

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        explicit operator bool() const noexcept;
    };
}

戻り値#

bool: テクスチャが有効な場合にtrue、そうでない場合はfalse

説明#

クラスをbool型にキャストした際に、テクスチャの有効状態を返すための定義です。変換結果はIsValidの戻り値と同等となります。

利用例#

// テクスチャキーを定義
constexpr auto kTextureKey = MGL::Render::MakeTextureKey("texture-name");

// テクスチャを取得
MGL::Render::Texture texture(kTextureKey);

// テクスチャの有効状態をチェック
if (texture)    // if (texture.IsValid()) と等価
{
    // テクスチャが有効な場合はここに到達
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース

operator !#

否定演算子

宣言#

namespace MGL::Render
{
    class Texture
    {
    public:
        bool operator!() const noexcept;
    };
}

戻り値#

bool: テクスチャが有効な場合にfalse、そうでない場合はtrue

説明#

クラスに否定演算子を適用した際のオペレータです。テクスチャの無効状態を取得する際に使用します。

このオペレータの戻り値は、IsValidやoperator boolの結果を反転させた値と等価です。

利用例#

// テクスチャキーを定義
constexpr auto kTextureKey = MGL::Render::MakeTextureKey("texture-name");

// テクスチャを取得
MGL::Render::Texture texture(kTextureKey);

// テクスチャの無効状態をチェック
if (!texture)    // if (!texture.IsValid()) と等価
{
    // テクスチャが無効な場合はここに到達
    ...
}

バージョン情報#

MGL 1.0.0
- 初回リリース

MGLドキュメント

MGL::Render::Texture

Contents

MGL::Render::Texture#

概要#

宣言#

メンバ情報#

コンストラクタ#

宣言#

引数#

説明#

利用例#

バージョン情報#

関連#

Load#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

LoadAsync#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

Create#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

CreateRenderTarget#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

関連#

GetResource#

宣言#

戻り値#

説明#

バージョン情報#

関連#

IsValid#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

IsLoading#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

関連#

GetSize#

宣言#

戻り値#

説明#

利用例#

バージョン情報#

Destroy#

宣言#

引数#

戻り値#

説明#

利用例#

バージョン情報#

SetDefaultLoader#

宣言#