MGL::Render::TextureLoader#

概要#

TextureLoaderクラスはテクスチャ読み込みを実装するためのインターフェースクラスです。このクラスを継承したテクスチャローダーをMGLに登録することで、MGLが対応していない形式の画像をテクスチャとして読み込めるようになります。

MGLは標準で次のローダーが実装されています。

名前

内容

対応レンダラ

MetalKitTextureLoader

MetalKitを利用したローダー

Metal

WICTextureLoader

Windows Imaging Componentを利用したローダー

Windows汎用

宣言#

namespace MGL::Render
{
    class TextureLoader;
}

型#

名前

内容

TextureLoaderKey

テクスチャローダーを判別するためのキー

UniqueTextureLoader

テクスチャローダーのユニークポインタ

定数#

名前

内容

kDefaultTextureLoaderKeySeed

ローダーキーを生成するためのシード値

関数・定数式#

種類

名前

内容

定数式

MakeTextureLoaderKey

ローダーキーを生成するための定数式

メンバ情報#

種類

名前

内容

純粋仮想関数

Load

テクスチャの読み込み

TextureLoaderKey#

宣言#

namespace MGL::Render
{
    using TextureLoaderKey = uint32_t;
}

説明#

テクスチャローダーの判別に使用する値を表す型です。この型の値はMakeTextureLoaderKeyによって生成されます。

関連#

UniqueTextureLoader#

宣言#

namespace MGL::Render
{
    using UniqueTextureLoader = MGL::STL::unique_ptr<TextureLoader>;
}

説明#

テクスチャローダーをユニークポインタとして扱うためのエイリアスです。

関連#

kDefaultTextureLoaderKeySeed#

宣言#

namespace MGL::Render
{
    constexpr uint32_t kDefaultTextureLoaderKeySeed = MGL::Hash::kFNV1aDefaultValue32;
}

説明#

ローダーキーの生成に使用するシード値です。ローダーキーの衝突などの問題が生じた場合に備えて定義されている定数であり、通常は参照する必要はありません。

詳細はMakeTextureLoaderKeyの説明を参照してください。

関連#

MakeTextureLoaderKey#

ローダーキーを生成するための定数式です。

宣言#

namespace MGL::Render
{
    constexpr TextureLoaderKey MakeTextureLoaderKey(
        const char *key,
        uint32_t seed = kDefaultTextureLoaderKeySeed) noexcept
}

引数#

const char *key

ローダーキーの生成に使用する文字列

uint32_t seed

キーの生成に使用するシード値。省略時はkDefaultTextureLoaderKeySeed

戻り値#

TextureLoaderKey

生成されたローダーキー

説明#

テクスチャローダーを判別するために使用するローダーキーを文字列から生成します。

ローダーキーはテクスチャローダーの種類を判別するために使用され、MGLにテクスチャローダーを登録する際に同時に指定します。登録されたローダーキーは、テクスチャを読み込む場合などにおいて、使用するローダーの指定に利用します。

キーの生成にはMGL::Hash::FNV1aが使用されます。引数のseedに異なる値を指定すると生成される値も変化するため、衝突などの問題が生じた場合はこの値を指定することで解決される場合があります。引数を省略した場合はkDefaultTextureLoaderKeySeedが指定されるため、この定数を変更することでも衝突の解消を図ることが可能です。

ローダーキーの生成に使用する文字列は、登録済みの他のローダーキーと衝突しない範囲で任意のものが利用できます。先頭に"MGL-"が付く文字列はMGLが利用する可能性があるため避けてください。

利用例#

// "YourTextureLoader"のローダーキーを生成
auto yourLoaderKey = MGL::Render::MakeTextureLoaderKey("YourTextureLoader");

関連#

Load#

テクスチャを読み込む際に呼び出される関数です。

宣言#

namespace MGL::Render
{
    class TextureLoader
    {
    public:
        // (1) ファイルから読み込み
        virtual bool Load(
            TextureResource &textureResource,
            const PathView &path) noexcept = 0;

        // (2) メモリ上のデータから読み込み
        virtual bool Load(TextureResource &textureResource,
            const void *imageData,
            size_t dataSize) noexcept = 0;
    };
}

引数#

(1) ファイルから読み込み
MGL::Render::TextureResource &textureResource

読み込みを要求しているテクスチャリソースの参照

const MGL::File::PathView &path

画像ファイルのパス

(2) メモリ上のデータから読み込み
MGL::Render::TextureResource &textureResource

読み込みを要求しているテクスチャリソースの参照

const void *imageData

メモリ上に展開された画像データ

size_t dataSize

imageDataのサイズ

戻り値#

bool

成功時にtrue、失敗時にfalse

説明#

テクスチャの読み込み要求が行われた際に呼び出される関数です。

引数のtextureResourceは初期化前のテクスチャリソースです。継承先のクラスにおいて、引数で指定されたファイルまたはデータを任意のピクセルフォーマットに変換し、その内容をtextureResourceに反映してください。

(1)の引数pathはマウントされたパスである可能性があります。ファイルのマウントについての詳細はファイルアクセスのディレクトリやファイルのマウント参照してください。

処理に成功した場合はtrueを、失敗した場合はfalseを返してください。

この関数はMGL::Render::TextureStorageが適切なタイミングで呼び出すため、直接呼び出す必要はなく、推奨もされません。

利用例#

// 画像ファイルからテクスチャを読み込む関数の実装例
// メモリから読み込む場合も流れは同じ
virtual bool YourTextureLoader::Load(
        MGL::Render::TextureResource &textureResource,
        const MGL::File::PathView &path) noexcept override
{
    // pathが示す画像ファイルを読み込んでピクセルデータを得る。
    // ここでは次の情報が得られたものと仮定する。
    //
    //  - pixelData:    ピクセルデータ
    //  - pixelFormat:  ピクセルデータのフォーマット
    //  - width:        画像の幅
    //  - height:       画像の高さ

    // テクスチャリソースを生成して結果を返す
    return textureResource.Create(pixelData, pixelFormat, width, height);
}

関連#