MGL::Render::TextureStorage#

概要#

TextureStorageクラスはテクスチャの読み込みと管理を行っているクラスです。MGL初期化後に常駐しており、アプリケーション動作中は常にアクセス可能となっています。

注釈

通常はアプリケーション側からこのクラスを直接利用する必要はありません。テクスチャを扱う場合はMGL::Render::Textureクラスを利用してください。

宣言#

namespace MGL::Render
{
    class TextureStorage;
}

型#

種類	名前	内容
型	TextureKey	テクスチャにアクセスするためのキーの型

定数#

名前	内容
kDefaultTextureKeySeed	テクスチャキーを生成するためのシード値

関数・定数式#

種類	名前	内容
定数式	MakeTextureKey	テクスチャキーを生成するための定数式

メンバ情報#

種類	名前	内容
定数	kDefaultLoaderKey	デフォルトのローダー指定用の値
関数	コンストラクタ
関数	Load	テクスチャの同期読み込み
関数	LoadAsync	テクスチャの非同期読み込み
関数	Create	テクスチャの生成
関数	CreateRenderTarget	レンダーターゲットの生成
関数	Get	テクスチャの取得
関数	Destroy	テクスチャの破棄
関数	SetDefaultLoader	デフォルトのテクスチャローダーを設定
関数	RegisterLoader	テクスチャローダーの登録

TextureKey#

テクスチャにアクセスするためのキーの型

宣言#

namespace MGL::Render
{
    enum class TextureKey : uint32_t {};
}

内容#

テクスチャにアクセスするためのキーを表す型です。この型の値はMakeTextureKeyによって生成されます。

kDefaultTextureKeySeed#

テクスチャキーを生成するためのシード値

宣言#

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

説明#

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

詳細はMakeTextureKeyを参照してください。

MakeTextureKey#

テクスチャキーを生成するための定数式

宣言#

namespace MGL::Render
{
    constexpr TextureKey MakeTextureKey(
        const char *key,
        uint32_t defaultHash = kDefaultTextureKeySeed) noexcept;
}

引数#

const char *key: テクスチャキーの生成に使用する文字列
uint32_t seed: キーの生成に使用するシード値。省略時はkDefaultTextureKeySeed

戻り値#

TextureKey: 生成されたテクスチャキー

説明#

テクスチャキーを文字列から生成するための定数式です。

テクスチャキーは読み込み済みのテクスチャを判別するために使用される値です。キーを指定して読み込みまたは生成されたテクスチャは、そのキーを経由することで取得や破棄を行えるようになります。

テクスチャキーを含めたテクスチャの扱い方については、2D描画のテクスチャストレージを参照してください。

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

利用例#

// "texture-name"という文字列からテクスチャキーを生成
auto textureKey = MGL::Render::MakeTextureKey("texture-name");

kDefaultLoaderKey#

デフォルトのローダー指定用の値

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        static constexpr TextureLoaderKey kDefaultLoaderKey = MakeTextureLoaderKey("MGL-DefaultLoader");
    };
}

説明#

デフォルトのテクスチャローダーを指定するための値です。

テクスチャローダーの指定にこの値を使用すると、SetDefaultLoaderで指定したローダーが使用されるようになります。

コンストラクタ#

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        TextureStorage(MGL::STL::unique_ptr<TextureGenerator> generator) noexcept;
    };
}

引数#

MGL::STL::unique_ptr<MGL::Render::TextureGenerator> generator: このクラスが利用するテクスチャジェネレータ

説明#

コンストラクタの引数には、このクラスが使用するテクスチャジェネレータを指定します。テクスチャ生成に関わる部分を外部に移譲することにより、どのレンダラでも共通してこのクラスを利用可能となっています。独自のレンダラを実装する際にはイニシャライザクラス（準備中）を経由し、対応したテクスチャジェネレータを指定してください。

Load#

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

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        // (1) メモリ上の画像データから読み込み
        [[nodiscard]] SharedTextureResource Load(
            const void *imageData,
            size_t dataSize,
            TextureLoaderKey loaderKey = kDefaultLoaderKey) noexcept;

        // (2) 画像ファイルから読み込み
        [[nodiscard]] SharedTextureResource Load(
            const File::PathView &imagePath,
            TextureLoaderKey loaderKey = kDefaultLoaderKey) noexcept;

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

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

    };
}

引数#

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

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

(2) 画像ファイルから読み込み

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

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

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

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

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

戻り値#

SharedTextureResource: テクスチャリソースの共有ポインタ。失敗時にはnullptr

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Texture::Loadの利用を推奨します。

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

(1)と(2)はテクスチャキーを指定しない呼び出しです。この場合は読み込んだテクスチャリソースを呼び出し元で管理する必要があります。

(3)と(4)はテクスチャキーを指定し、そのキーを用いてGetやDestroyの利用が可能となります。指定したキーが既に存在している場合は、読み込みを行わずにそのキーが示すテクスチャリソースを返します。

loaderKeyは読み込みの際に利用するテクスチャローダーの指定です。省略した場合はSetDefaultLoaderで設定したローダーが使用されます。例外的に異なるテクスチャローダーを使用したい場合はこの引数を指定してください。

利用例#

const void *imageData = /* 有効な画像データと仮定 */;
size_t dataSize = /* imageDataのサイズと仮定 */;

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// (1) メモリ上の画像データから読み込み
auto texture1 = storage.Load(imageData, dataSize);

// (2) 画像ファイルから読み込み
auto texture2 = storage.Load("path/to/imagefile");

// (3) メモリ上の画像データからテクスチャキーを指定して読み込み
auto textureKey3 = MGL::Render::MakeTextureKey("texture-3");
auto texture3 = storage.Load(textureKey3, imageData, dataSize);

// (4) 画像ファイルからテクスチャキーを指定して読み込み
auto textureKey4 = MGL::Render::MakeTextureKey("texture-4");
auto texture4 = storage.Load(textureKey4, "path/to/imagefile");

LoadAsync#

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

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        // (1) メモリ上の画像データから読み込み
        [[nodiscard]] SharedTextureResource LoadAsync(
            const void *imageData,
            size_t dataSize,
            TextureLoaderKey loaderKey = kDefaultLoaderKey) noexcept;

        // (2) 画像ファイルから読み込み
        [[nodiscard]] SharedTextureResource LoadAsync(
            const File::PathView &imagePath,
            TextureLoaderKey loaderKey = kDefaultLoaderKey) noexcept;

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

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

    };
}

引数#

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

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

(2) 画像ファイルから読み込み

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

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

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

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

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

戻り値#

SharedTextureResource: テクスチャリソースの共有ポインタ。失敗時にはnullptr

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Texture::LoadAsyncの利用を推奨します。

ファイルまたはメモリ上の画像データからテクスチャを読み込みます。読み込みは非同期的に実行され、読み込み完了を待たずに関数を抜けて戻り値を返します。読み込みが完了し、テクスチャリソースが有効であるかの判断には、戻り値のIsValidとIsLoadingを参照してください。

(1)と(2)はテクスチャキーを指定しない呼び出しです。この場合は読み込んだテクスチャリソースを呼び出し元で管理する必要があります。

loaderKeyは読み込みの際に利用するテクスチャローダーの指定です。省略した場合はSetDefaultLoaderで設定したローダーが使用されます。例外的に異なるテクスチャローダーを使用したい場合はこの引数を指定してください。

利用例#

// 画像ファイルのパスと、そのパスの文字列を元にテクスチャキーを定義
constexpr const char *kImageFilePath = "path/to/imagefile";
constexpr auto kTextureKey = MGL::Render::MakeTextureKey(kImageFilePath);

// 読み込み例

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// 画像ファイルから非同期読み込み
if (storage.LoadAsync(kTextureKey, kImageFilePath) == nullptr)
{
    // 戻り値がnullptrの場合、テクスチャリソースそのものの確保に失敗している。
    // (TextureGenerator::MakeTextureResourceがnullptrを返している）
    ...
}

// 非同期で読み込んだテクスチャリソースを利用する例

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// ストレージからテクスチャを取得
auto texture = storage.Get(kTextureKey);

// 読み込み中チェック
if (texture.IsLoading())
{
    // ここに来ている場合はまだ読み込み中
    ...
}
// テクスチャリソースが有効かチェック
else if (texture.IsValid)
{
    // ここに来ればtextureは利用可能
    ...
}
else
{
    // ここに来ている場合は読み込みに失敗している
    ...
}

Create#

テクスチャの生成

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        // (1) テクスチャキーを用いずに生成
        [[nodiscard]] SharedTextureResource Create(
            const void *pixelData,
            PixelFormat pixelFormat,
            uint32_t width,
            uint32_t height) noexcept;

        // (2) テクスチャキーを指定して生成
        SharedTextureResource 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: 登録するテクスチャキー
const void *pixelData: ピクセルデータの先頭アドレス
PixelFormat pixelFormat: ピクセルデータのフォーマット
uint32_t width: ピクセルデータの幅
uint32_t height: ピクセルデータの高さ

戻り値#

SharedTextureResource: テクスチャリソースの共有ポインタ。失敗時にはnullptr

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Texture::Createの利用を推奨します。

ピクセルデータからテクスチャを生成します。この関数はコンストラクタで指定されたMGL::Render::TextureGeneratorを用いてテクスチャリソースを生成し、MGL::Render::TextureResource::Createを呼び出します。

引数pixelDataにはデコード済みのピクセルデータを、pixelFormatにはそのピクセルフォーマットを指定します。widthとheightはそれぞれ幅と高さです。

(1)はテクスチャキーを指定しない呼び出しです。この場合は生成したテクスチャリソースを呼び出し元で管理する必要があります。

(2)はテクスチャキーを指定し、そのキーを用いてGetやDestroyの利用が可能となります。指定したキーが既に存在している場合は、生成を行わずにそのキーが示すテクスチャリソースを返します。

利用例#

// 次のデータが定義済みと仮定する

// ピクセルデータ
const void *pixelData = /* 512x512 32bit RGBAのピクセルデータと仮定 */;

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

// ピクセルデータからテクスチャを生成する例

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// (1) テクスチャキーを用いずに生成
auto texture1 = storage.Create(pixelData, MGL::Render::PixelFormat::RGBA8_UNorm, 512, 512);

// (2) テクスチャキーを指定して生成
storage.Create(kTexture2, pixelData, MGL::Render::PixelFormat::RGBA8_UNorm, 512, 512);

// (2)で生成したテクスチャを取得する例

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// テクスチャリソースを取得
auto texture2 = storage.Get(kTexture2);

CreateRenderTarget#

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

宣言#

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

        // (2) テクスチャキーあり
        SharedTextureResource 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: ピクセルデータの高さ

戻り値#

SharedTextureResource: テクスチャリソースの共有ポインタ。失敗時にはnullptr

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Texture::CreateRenderTargetの利用を推奨します。

描画対象として書き込み可能なテクスチャを生成します。この関数はコンストラクタで指定されたMGL::Render::TextureGeneratorを用いてテクスチャリソースを生成し、MGL::Render::TextureResource::CreateRenderTargetを呼び出します。

引数のwidthとheightのサイズのレンダーターゲットを生成します。keyを指定した場合、生成したレンダーターゲットをそのキーでテクスチャストレージに登録します。

指定したキーが既に存在している場合は、そのテクスチャリソースがレンダーターゲットとして生成されている場合に限り、生成を行わずにそのキーが示すテクスチャリソースを返します。指定したキーに対応するテクスチャが既に存在していて、そのテクスチャがレンダーターゲットでない場合は失敗となりnullptrが返ります。

利用例#

// レンダーターゲット用のテクスチャキーを生成
auto kRenderTargetKey = MGL::Render::MakeTextureKey("rendertarget-name");

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// レンダーターゲットを生成
auto renderTarget = storage.CreateRenderTarget(kRenderTargetKey, 512, 512);

Get#

テクスチャの取得

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        SharedTextureResource Get(TextureKey key) noexcept;
    };
}

引数#

TextureKey: 登録するテクスチャキー

戻り値#

SharedTextureResource: テクスチャリソースの共有ポインタ。失敗時にはnullptr

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Textureの利用を推奨します。

テクスチャストレージに登録済みのテクスチャリソースを取得します。キーに対応したテクスチャリソースが登録されていない場合、nullptrが返ります。

利用例#

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

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// kTextureKeyで登録されているテクスチャリソースを取得
auto texture = storage.Get(kTextureKey);

Destroy#

テクスチャの破棄

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        bool Destroy(TextureKey key) noexcept;
    };
}

引数#

SharedTextureResource: テクスチャリソースの共有ポインタ。失敗時にはnullptr

戻り値#

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

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Texture::Destroyの利用を推奨します。

引数で指定したテクスチャキーで登録されているテクスチャリソースを削除します。キーに対応したテクスチャリソースが存在しない場合はfalseを返します。

テクスチャリソースは共有ポインタとして管理されているため、この関数を呼び出してもそのリソースが直ちに利用不可能になることはありません。この関数を呼び出した後に、全ての参照が失われたタイミングでテクスチャリソースが破棄されます。ただし、この関数を呼び出した時点でGetによる取得は行えなくなります。

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

利用例#

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

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// kTextureKeyで登録されているテクスチャリソースを破棄
auto texture = storage.Destroy(kTextureKey);

SetDefaultLoader#

デフォルトのローダーを設定

宣言#

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

引数#

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

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Texture::SetDefaultLoaderの利用を推奨します。

テクスチャ読み込みの際にデフォルトで利用するテクスチャローダー（MGL::Render::TextureLoader）のキーを設定します。LoadまたはLoadAsyncの引数loaderKeyを省略、またはkDefaultLoaderKeyを指定した場合、この関数で設定されたローダーを使用します。

利用例#

// テクスチャローダーのキーを定義
constexpr auto kTextureLoaderKey = MGL::Render::MakeTextureLoaderKey("texture-loader-name");

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// kTextureLoaderKeyをデフォルトのローダーに設定
auto texture = storage.SetTextureLoader(kTextureLoaderKey);

RegisterLoader#

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

宣言#

namespace MGL::Render
{
    class TextureStorage
    {
    public:
        bool RegisterLoader(
            TextureLoaderKey loaderKey,
            UniqueTextureLoader loader) noexcept;
    };
}

引数#

TextureLoaderKey loaderKey: 登録するテクスチャローダーのキー
UniqueTextureLoader loader: 登録するテクスチャローダー

戻り値#

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

説明#

注釈

特別な理由がない限り、アプリケーション側からはMGL::Render::Texture::RegisterLoaderの利用を推奨します。

テクスチャローダーを新規に登録し、利用可能にします。この機能により、MGLがテクスチャとして読み込める画像フォーマットをアプリケーション側から拡張可能となります。

登録時に指定したローダーキーをLoadおよびLoadAsyncの引数loaderKeyに指定することにより、そのローダーを用いてテクスチャの読み込みを行うようになります。キーに対応したローダーが既に登録されている場合は失敗し、戻り値にfalseが返ります。

利用例#

// テクスチャストレージを取得
auto &storage = MGL::Render::RendererSet::GetInstance().GetTextureStorage();

// 独自のテクスチャローダー "YourTextureLoader" を新規に登録
storage.RegisterLoader(
    YourTextureLoader::kLoaderKey,  // ローダーキーの指定（クラス側で定数として定義することを推奨）
    MGL::STL::make_unique<YourTextureLoader>()   // ローダーを生成して渡す
);

MGLドキュメント

MGL::Render::TextureStorage

Contents

MGL::Render::TextureStorage#

概要#

宣言#

型#

定数#

関数・定数式#

メンバ情報#

関連#

TextureKey#

宣言#

内容#

関連#

kDefaultTextureKeySeed#

宣言#

説明#

関連#

MakeTextureKey#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

kDefaultLoaderKey#

宣言#

説明#

関連#

コンストラクタ#

宣言#

引数#

説明#

関連#

Load#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

LoadAsync#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Create#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

CreateRenderTarget#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Get#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

Destroy#

宣言#

引数#

戻り値#

説明#

利用例#

関連#

SetDefaultLoader#

宣言#

引数#