3. リソースオブジェクト

リソースオブジェクトを扱う関数は基本的に nn::gd::Resource クラスで定義されています。

nn::gd::Resource クラスでは、リソースオブジェクトの作成と解放、詳細情報の取得、データを書き換えるためのデータポインタの取得を行うことができます。

3.1. テクスチャ 2D リソース

テクスチャ 2D リソースは、テクスチャイメージやカラーバッファなどのように、幅と高さを持つリソースのことです。このリソースは Texture2DResource オブジェクトを介して扱います。

3.1.1. Texture2DResource オブジェクトの作成

Texture2DResource オブジェクトは nn::gd::Resource::CreateTexture2DResource() で作成することができます。

コード 3-1. Texture2DResource オブジェクトの作成
static nnResult nn::gd::Resource::CreateTexture2DResource(
        const nn::gd::Texture2DResourceDescription* description,
        const void* initialData, gdBool autoGenerateMipMapsFromData,
        nn::gd::Texture2DResource** texture2DResource,
        gdBool copyInitialData = GD_TRUE);

リソースの情報は description に指定するデスクリプタクラス(Texture2DResourceDescription)にあらかじめ設定しておきます。デスクリプタクラスに設定する情報の詳細は「3.1.1.2. Texture2DResource オブジェクトのデスクリプタクラス」を参照してください。

ファイルからロードされたテクスチャデータのように初期データを持つリソースを作成する場合、そのデータの先頭アドレスを initialData に指定します。copyInitialDataGD_TRUE が指定されたときは、リソースの作成時に初期データをデスクリプタクラスで指定されたメモリにコピーします。このとき、リソースデータを VRAM に確保する場合は関数内で DMA 転送のコマンドリクエストをコマンドリストに追加しますので、コマンドリストの実行が完了するまで初期データが存在するメモリ領域を書き換えたり解放したりしないでください。copyInitialDataGD_FALSE が指定されたときは、initialData に指定されたアドレスそのままをリソースで使用します。リソースにミップマップデータが含まれる場合は、すべてのデータが格納可能なサイズで確保されていなければならないことに注意してください。また、アドレスのアライメントにも注意が必要です。なお、リソースの解放時にはアプリケーションでメモリを解放しなければなりません。

初期データを持たないリソースを作成する場合は initialData には NULL を指定してください。リソースデータを保持するために必要なサイズのメモリ領域が、デスクリプタクラスで指定されたメモリに確保されます。

autoGenerateMipMapsFromData には、テクスチャデータのミップマップデータを初期データから自動生成する場合に GD_TRUE を指定します。自動生成する場合の注意点については、「3.1.7. ミップマップデータの自動生成」を参照してください。

今後、作成された Texture2DResource オブジェクトへのアクセスには texture2DResource で受け取ったポインタを介して行います。

3.1.1.1. テクスチャをネイティブフォーマットに変換するヘルパー関数

3D モデルに貼り付けるテクスチャのテクスチャオブジェクトを作成する場合、Texture2DResource オブジェクトの作成時に指定する初期データは 3DS のネイティブフォーマットでなければなりません。そのため、Open GL などで使用される標準的なテクスチャを 3DS のネイティブフォーマットに変換するヘルパー関数が nn::gd::Resource::Helper クラスに用意されています。ただし、ヘルパー関数は処理の負荷が高く、ランタイムでの処理には向いていません。

無圧縮テクスチャと圧縮テクスチャで変換に使用するヘルパー関数は異なりますが、対応している変換元のピクセルフォーマット以外に、引数の指定に違いはありません。

コード 3-2. テクスチャをネイティブフォーマットに変換するヘルパー関数
static nnResult nn::gd::Resource::Helper::ConvertTextureResourceToNativeFormat(
        nn::gd::Resource::Format format,
        u32 width, u32 height, const u8* dataSrc, u8* dataDst,
        nn::gd::Resource::NativeFormat* pnativeFormat = NULL);
static nnResult nn::gd::Resource::Helper::ConvertCompressedTextureResourceToNativeFormat(
        nn::gd::Resource::CompressedFormat format,
        u32 width, u32 height, u8* dataSrc, u8* dataDst,
        nn::gd::Resource::NativeFormat* pnativeFormat = NULL);

format には変換元のピクセルフォーマットを指定します。

ConvertTextureResourceToNativeFormat() で指定可能なピクセルフォーマットには以下のものがあります。

  • FORMAT_RGBA_8888
  • FORMAT_RGB_888
  • FORMAT_RGBA_5551
  • FORMAT_RGB_565
  • FORMAT_RGBA_4444
  • FORMAT_LUMINANCE_ALPHA_88
  • FORMAT_HILO_88
  • FORMAT_LUMINANCE_8
  • FORMAT_ALPHA_8
  • FORMAT_LUMINANCE_ALPHA_44
  • FORMAT_LUMINANCE_4
  • FORMAT_ALPHA_4

ConvertCompressedTextureResourceToNativeFormat() で指定可能なピクセルフォーマットには以下のものがあります。

  • FORMAT_ETC1_RGB8

ピクセルフォーマットによっては、デバイスメモリから変換元のデータと同じサイズのバッファを一時的に確保します。また、dataSrcdataDst に同じアドレスを指定した場合は必ず一時的にバッファを確保します。

標準的なテクスチャのフォーマットとネイティブフォーマットの違いについては、「3DS プログラミングマニュアル - グラフィックス基本編」を参照してください。

3.1.1.2. Texture2DResource オブジェクトのデスクリプタクラス

Texture2DResource オブジェクトのデスクリプタクラス(Texture2DResourceDescription)のメンバを紹介し、設定に際しての注意点などを説明します。

コード 3-3. Texture2DResourceDescription クラスの定義
class nn::gd::Texture2DResourceDescription
{
    u32 m_Width;
    u32 m_Height;
    u32 m_CountMipLevels;
    nn::gd::Resource::NativeFormat m_Format;
    nn::gd::Memory::MemoryLayout m_MemLayout;
    nn::gd::Memory::MemoryLocation m_MemLocation;
};
幅(m_Width)

リソースデータの幅をピクセル数で設定します。ミップマップデータを持つテクスチャの場合は、トップレベルのテクスチャデータの幅を指定してください。

高さ(m_Height)

リソースデータの高さをピクセル数で設定します。ミップマップデータを持つテクスチャの場合は、トップレベルのテクスチャデータの高さを指定してください。

ミップマップレベル(m_CountMipLevels)

リソースデータがミップマップデータを持つ場合のミップマップレベルを設定します。ミップマップデータを持たないリソースデータの場合は 1 を指定してください。0 を指定した場合はリソースデータの幅と高さで持ち得る最大のミップマップレベルが設定されます。

ピクセルフォーマット(m_Format)

リソースの使用目的によって指定可能なピクセルフォーマットが異なります。

下表では、使用目的(作成するオブジェクト)をテクスチャデータ(Texture2D オブジェクトまたは TextureCube オブジェクト)、カラーバッファ(RenderTarget オブジェクト)、デプスステンシルバッファ(DepthStencilTarget オブジェクト)に分けて指定可能なピクセルフォーマットを示しています。

表 3-1. 指定可能なピクセルフォーマット
ピクセルフォーマット Texture2D TextureCube RenderTarget DepthStencilTarget
Resource::NATIVE_FORMAT_RGBA_8888 ※1 エラー
Resource::NATIVE_FORMAT_RGB_888 ※1 エラー エラー
Resource::NATIVE_FORMAT_RGBA_5551 ※1 エラー
Resource::NATIVE_FORMAT_RGB_565 ※1 エラー
Resource::NATIVE_FORMAT_RGBA_4444 ※1 エラー
Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_88 エラー エラー
Resource::NATIVE_FORMAT_HILO_88 エラー エラー
Resource::NATIVE_FORMAT_LUMINANCE_8 エラー エラー
Resource::NATIVE_FORMAT_ALPHA_8 エラー エラー
Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_44 エラー エラー
Resource::NATIVE_FORMAT_LUMINANCE_4 エラー エラー
Resource::NATIVE_FORMAT_ALPHA_4 エラー エラー
Resource::NATIVE_FORMAT_ETC1_RGB8 エラー エラー
Resource::NATIVE_FORMAT_ETC1_A4 エラー エラー
Resource::NATIVE_FORMAT_GAS ※2 エラー エラー
Resource::NATIVE_FORMAT_SHADOW ※2 エラー
Resource::NATIVE_FORMAT_DEPTH_16 エラー
Resource::NATIVE_FORMAT_DEPTH_24 エラー
Resource::NATIVE_FORMAT_DEPTH_24_STENCIL_8 エラー

※1 自動ミップマップ生成に対応しています。
※2 ミップマップに対応していません。

メモリレイアウト(m_MemLayout)

Texture2DTextureCube のオブジェクトの作成に使用するリソースオブジェクトや初期データを指定して作成するリソースオブジェクトの場合、メモリレイアウトには Memory::LAYOUT_BLOCK_8 のみが指定可能です。

RenderTargetDepthStencilTarget のオブジェクトの作成に使用するリソースオブジェクトの場合、メモリレイアウトには Memory::LAYOUT_BLOCK_8 または Memory::LAYOUT_BLOCK_32 が指定可能です。

上記以外に使用するリソースオブジェクトであれば、メモリレイアウトに Memory::LAYOUT_LINEAR を指定することができます。

リソースデータを確保するメモリ(m_MemLocation)

リソースデータを保持するために確保するメモリを指定します。Memory::FCRAM(デバイスメモリ)を指定して作成されたリソースオブジェクトは、RenderTarget または DepthStencilTarget のオブジェクトの作成に使用することができません。

表 3-2. リソースデータの確保で指定可能なメモリ
リソースデータの保持に使用するメモリ Texture2D TextureCube RenderTarget DepthStencilTarget
Memory::FCRAM(デバイスメモリ) エラー エラー
Memory::VRAMA(VRAM-A)
Memory::VRAMB(VRAM-B)

3.1.2. Texture2DResource オブジェクトの解放

Texture2DResource オブジェクトの解放は、nn::gd::Resource::ReleaseTexture2DResource() の呼び出しで行われます。オブジェクトの解放と同時に、作成時に確保されたメモリ領域も解放されます。

コード 3-4. Texture2DResource オブジェクトの解放
static nnResult nn::gd::Resource::ReleaseTexture2DResource(
        nn::gd::Texture2DResource* texture2DResource);

3.1.3. Texture2DResource オブジェクトの詳細情報の取得

Texture2DResource オブジェクトに格納されている詳細情報(Texture2DResourceProperties クラス)を nn::gd::Resource::GetTexture2DResourceProperties() で取得することができます。

コード 3-5. Texture2DResource オブジェクトの詳細情報の取得
static nnResult nn::gd::Resource::GetTexture2DResourceProperties(
        const nn::gd::Texture2DResource* texture2DResource,
        nn::gd::Texture2DResourceProperties* properties);

この関数は texture2DResource に指定した、Texture2DResource オブジェクトに格納されている詳細情報へのポインタを properties に返します。取得したポインタを介して、Texture2DResource オブジェクトの内容を書き換えてしまわないように注意してください。

3.1.3.1. Texture2DResource オブジェクトの詳細情報

詳細情報(Texture2DResourceProperties クラス)には、オブジェクトの作成時に指定されたデスクリプタクラスの設定とほぼ同じ内容が格納されています。

コード 3-6. Texture2DResourceProperties クラスの定義
class nn::gd::Texture2DResourceProperties
{
    u32 m_Width;
    u32 m_Height;
    u32 m_CountMipLevels;
    u32 m_PixelSize;
    nn::gd::Resource::NativeFormat m_Format;
    nn::gd::Memory::MemoryLayout m_MemLayout;
    nn::gd::Memory::MemoryLocation m_MemLocation;
    u8* m_MemAddr;

    nn::gd::MipmapResourceInfo GetMipmapAddress(u32 mipmapLevel);
};

ここでは、デスクリプタクラスの設定と異なる可能性のあるメンバ変数と、このクラスにのみ存在するメンバを説明します。

ミップマップレベル(m_CountMipLevels)

デスクリプタで 0 が指定されていた場合は、リソースデータの幅と高さで持ち得る最大のミップマップレベルが設定されています。

ピクセルサイズ(m_PixelSize)

リソースデータのピクセルフォーマットのビット数が設定されています。

リソースデータの先頭アドレス(m_MemAddr)

リソースデータの先頭アドレスが物理アドレスで設定されています。

ミップマップデータのアドレス情報の取得(GetMipmapAddress())

ミップマップレベルを指定して、ミップマップデータのアドレス情報(MipmapResourceInfo クラス)を取得するヘルパー関数が定義されています。

コード 3-7. ミップマップデータのアドレス情報の定義
class nn::gd::MipmapResourceInfo
{
    u32 m_Width;
    u32 m_Height;
    u8* m_MemAddr;
};

ミップマップデータの幅(m_Width)、高さ(m_Height)、データの先頭アドレス(m_MemAddr)が定義されています。

3.1.4. Texture2DResource オブジェクトのデータポインタの取得

リソースデータにアクセスするためのデータポインタを nn::gd::Resource::MapTexture2DResource() で取得することができます。

コード 3-8. Texture2DResource オブジェクトのデータポインタの取得
static nnResult nn::gd::Resource::MapTexture2DResource(
        nn::gd::Texture2DResource* texture2DResource,
        s32 mipLevelIndex, nn::gd::Resource::MapUsage usage, void** data);
static nnResult nn::gd::Resource::UnmapTexture2DResource(
        nn::gd::Texture2DResource* texture2DResource);

texture2DResource に指定した Texture2DResource オブジェクトのリソースデータのうち、mipLevelIndex で指定されたミップマップレベルのテクスチャデータの先頭アドレスが data に返されます。usage には、以下のマッピング方法(リソースデータへのアクセスの種類)を指定します。

表 3-3. データポインタのマッピング方法
定義 マッピング方法 デバイスメモリ VRAM
Resource::MAP_READ_ONLY 読み込みのみ
Resource::MAP_WRITE_ONLY 書き込みのみ エラー
Resource::MAP_READ_WRITE 読み書き エラー
補足:

マッピング方法のチェックはデータポインタの取得時にのみ行われます。MAP_READ_ONLY で取得したデバイスメモリ上のリソースデータに書き込みを行ってもエラーにはなりませんが、マッピングの解除時にキャッシュがフラッシュされません。

VRAM 上のリソースデータに直接アクセスすることはできません。DMA 転送などで、CPU から直接アクセス可能なメモリ上にコピーしてください。

リソースデータへのアクセスが完了したあとは、nn::gd::Resource::UnmapTexture2DResource() でマッピングを解除してください。書き込みを含むマッピング方法でデバイスメモリ上のリソースデータのデータポインタを取得していた場合は、マッピングの解除時にキャッシュのフラッシュが行われます。

3.1.5. リソースデータのクリア(Texture2DResource オブジェクト)

指定した値でリソースデータをクリアすることができます。また、ミップマップデータを持つリソースであれば、クリアするミップマップレベルの範囲を指定することができます。ただし、デバイスメモリ上に確保されているリソースデータはクリアできません

コード 3-9. リソースデータのクリア(Texture2DResource オブジェクト)
static nnResult nn::gd::Memory::ClearTexture2DResource(
        const nn::gd::Texture2DResource* tex2DResource,
        s32 mipLevelIndexStart, s32 mipLevelIndexEnd, const u8 Components[4]);
static nnResult nn::gd::Memory::ClearTexture2DResource(
        const nn::gd::Texture2DResource* tex2DResource,
        s32 mipLevelIndexStart, s32 mipLevelIndexEnd, u32 value);

value で指定する場合はどんなリソースでもクリアしようと試みますが、Components で指定する場合は以下のピクセルフォーマットに限定されます。なお、Components の指定がどのような構成でクリアデータに反映されるかを、右のビットレイアウトに示しています。

図 3-1. クリアで指定可能なピクセルフォーマットとクリア時のデータの構成

NATIVE_FORMAT_RGBA_8888 NATIVE_FORMAT_GAS NATIVE_FORMAT_SHADOW NATIVE_FORMAT_RGBA_4444 NATIVE_FORMAT_RGBA_5551 NATIVE_FORMAT_RGB_888 NATIVE_FORMAT_RGB_565 NATIVE_FORMAT_LUMINANCE_ALPHA_88 NATIVE_FORMAT_LUMINANCE_ALPHA_44 NATIVE_FORMAT_ALPHA_8 NATIVE_FORMAT_ALPHA_4 NATIVE_FORMAT_LUMINANCE_8 NATIVE_FORMAT_LUMINANCE_4 NATIVE_FORMAT_HILO_88

3.1.6. リソースデータの部分コピー(Texture2DResource オブジェクト)

ミップマップレベルと矩形領域を指定して、リソースデータの部分コピーを行うことができます。この関数内で nngxAddBlockImageCopyCommand() を呼び出していますので、フォーマット変換は行われません。実際のコピー処理はコマンドリストの実行時に行われます。

コード 3-10. リソースデータの部分コピー(Texture2DResource オブジェクト)
static nnResult nn::gd::Memory::CopyTextureSubResource(
        const nn::gd::Texture2DResource* source,
        s32 srcMipLevelIndex, const nn::gd::Memory::Rect& rect,
        const nn::gd::Texture2DResource* dest, s32 dstMipLevelIndex,
        s32 destPosX, s32 destPosY);

リソースデータとビューポート(LCD)では原点の位置が異なりますが、この関数ではそれを考慮していますので、矩形領域(rect)やコピー先の座標(destPosXdestPosY)はビューポートの原点を基準に指定してください。

コピー元とコピー先のピクセルサイズが異なる場合はエラー(ResultInvalidTextureFormat())が返されます。

3.1.7. ミップマップデータの自動生成

Texture2DResource オブジェクトのミップマップデータを自動生成することができます。

コード 3-11. ミップマップデータの自動生成
static nnResult nn::gd::Memory::GenerateMipMaps(
        const nn::gd::Texture2DResource* tex2DResource,
        u32 mipLevelSourceIndex, s32 mipLevelLastDestinationIndex);

tex2DResource に指定される Texture2DResource オブジェクトは、生成されるミップマップレベルのリソースデータを保持することができるように作成されていなければなりません。また、以下のフォーマットで作成された Texture2DResource オブジェクトでなければ、ミップマップデータの自動生成を行うことができません。

  • nn::gd::Resource::NATIVE_FORMAT_RGBA_8888
  • nn::gd::Resource::NATIVE_FORMAT_RGBA_5551
  • nn::gd::Resource::NATIVE_FORMAT_RGBA_4444
  • nn::gd::Resource::NATIVE_FORMAT_RGB_888
  • nn::gd::Resource::NATIVE_FORMAT_RGB_565

上記以外のフォーマットの場合は、nn::gd::Resource::CreateTexture2DResourceCastFrom() で事前に NATIVE_FORMAT_RGBA_8888 などにフォーマット変換を行うことでミップマップデータを生成することができます。ただし、ピクセルを構成するビットに違いがあるため、この方法で生成されたミップマップデータが正常であることは保証されていません。

mipLevelSourceIndex から mipLevelLastDestinationIndex までのミップマップレベルのデータが自動生成されます。mipLevelLastDestinationIndex に -1 を指定した場合は、そのリソースの最大のミップマップレベルを指定したことになります。

3.1.7.1. CPU によるミップマップデータの自動生成

nn::gd::Resource::Helper::GenerateMipMapsCPU() の呼び出しでも、ミップマップデータを自動生成することができます。CPU で生成するため、GPU を使用する nn::gd::Memory::GenerateMipMaps() に比べて処理速度は落ちますが、対応するフォーマットが多いことと、最小で幅および高さが 8 ピクセル(GPU を使用した場合はフォーマットにより 32 または 64 ピクセル)のミップマップデータを生成できることが長所となっています。

コード 3-12. CPU によるミップマップデータの自動生成
static nnResult nn::gd::Resource::Helper::GenerateMipMapsCPU(
        nn::gd::Resource::NativeFormat format,
        u32 width, u32 height, const u8* dataSrc, u8* dataDst,
        u32 countMipLevelToGenerate);

format には、以下のフォーマットを指定することができます。

  • nn::gd::Resource::NATIVE_FORMAT_RGBA_8888
  • nn::gd::Resource::NATIVE_FORMAT_RGBA_5551
  • nn::gd::Resource::NATIVE_FORMAT_RGBA_4444
  • nn::gd::Resource::NATIVE_FORMAT_RGB_888
  • nn::gd::Resource::NATIVE_FORMAT_RGB_565
  • nn::gd::Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_88
  • nn::gd::Resource::NATIVE_FORMAT_LUMINANCE_ALPHA_44
  • nn::gd::Resource::NATIVE_FORMAT_LUMINANCE_8
  • nn::gd::Resource::NATIVE_FORMAT_ALPHA_8
  • nn::gd::Resource::NATIVE_FORMAT_HILO_88

width height には元となるリソースデータの幅と高さを指定します。幅および高さは 8 以上、かつ 2 の累乗でなければなりません。

dataSrc には元となるリソースデータの先頭アドレス、dataDst にはミップマップデータの格納先アドレスを指定します。生成されるミップマップデータのすべてが格納できるだけのメモリを確保してください。

countMipLevelToGenerate には生成するミップマップレベルの数を指定します。

3.1.8. Texture2DResource オブジェクトのフォーマット変換

ガステクスチャやシャドウテクスチャ、デプスバッファのように、レンダリングで使用した RenderTarget オブジェクトのリソースデータをテクスチャデータ(Texture2D オブジェクトのリソースデータ)として使用するために、以下の関数で既存の Texture2DResource オブジェクトをほかのフォーマットに変換することができます。

コード 3-13. Texture2DResource オブジェクトのフォーマット変換
static nnResult nn::gd::Resource::CreateTexture2DResourceCastFrom(
        const nn::gd::Texture2DResource* initialTexture2DResource,
        nn::gd::Resource::NativeFormat format,
        nn::gd::Memory::MemoryLayout layout,
        nn::gd::Texture2DResource** texture2DResource);

initialTexture2DResource に指定した Texture2DResource オブジェクトの、ピクセルフォーマットとメモリレイアウトを formatlayout に指定した情報に変更したオブジェクトが texture2DResource に返されます。変換前と変換後のピクセルフォーマットに互換性がない(ピクセルサイズが一致しない)場合はエラーが返されます。

この関数はフォーマットの情報が変更された Texture2DResource オブジェクトを新たに作成します。ただし、フォーマットの変換やデータのコピーは行われず、変換前のオブジェクトは変更されません。また、データが格納されている場所など、変更された情報以外は変換前の情報のままですので、この関数で作成したオブジェクトを介してリソースデータを書き換えた場合には変換前のオブジェクトのリソースデータも書き換わることになります。

3.2. 頂点バッファリソース

頂点バッファリソースは、頂点座標や頂点インデックスなどのように、頂点バッファとして利用するリソースのことです。このリソースは VertexBufferResource オブジェクトを介して扱います。

3.2.1. VertexBufferResource オブジェクトの作成

VertexBufferResource オブジェクトは nn::gd::Resource::CreateVertexBufferResource() で作成することができます。

コード 3-14. VertexBufferResource オブジェクトの作成
static nnResult nn::gd::Resource::CreateVertexBufferResource(
        const nn::gd::VertexBufferResourceDescription* description,
        const void* initialData, nn::gd::VertexBufferResource** buffer,
        gdBool copyInitialData = GD_TRUE);

リソースの情報は description に指定するデスクリプタクラス(VertexBufferResourceDescription)にあらかじめ設定しておきます。デスクリプタクラスに設定する情報の詳細は「3.2.1.1. VertexBufferResource オブジェクトのデスクリプタクラス」を参照してください。

ファイルからロードされた頂点データのように初期データを持つリソースを作成する場合、そのデータの先頭アドレスを initialData に指定します。copyInitialDataGD_TRUE が指定されたときは、リソースの作成時に初期データをデスクリプタクラスで指定されたメモリにコピーします。このとき、リソースデータを VRAM に確保する場合は関数内で DMA 転送のコマンドリクエストをコマンドリストに追加しますので、コマンドリストの実行が完了するまで初期データが存在するメモリ領域を書き換えたり解放したりしないでください。copyInitialDataGD_FALSE が指定されたときは、initialData に指定されたアドレスそのままをリソースで使用しますので、アドレスのアライメントに注意してください。なお、リソースの解放時にはアプリケーションでメモリを解放しなければなりません。

初期データを持たないリソースを作成する場合は initialData には NULL を指定してください。リソースデータを保持するために必要なサイズのメモリ領域が、デスクリプタクラスで指定されたメモリに確保されます。

今後、作成された VertexBufferResource オブジェクトへのアクセスには buffer で受け取ったポインタを介して行います。

3.2.1.1. VertexBufferResource オブジェクトのデスクリプタクラス

VertexBufferResource オブジェクトのデスクリプタクラス(VertexBufferResourceDescription)のメンバを紹介し、設定に際しての注意点などを説明します。

コード 3-15. VertexBufferResourceDescription クラスの定義
class nn::gd::VertexBufferResourceDescription
{
    u32 m_ByteSize;
    nn::gd::Memory::MemoryLocation m_MemLocation;
};
頂点バッファのサイズ(m_ByteSize)

頂点バッファ(リソースデータ)のバイトサイズを設定します。

リソースデータを確保するメモリ(m_MemLocation)

リソースデータを保持するために確保するメモリを指定します。

指定するメモリは Memory::FCRAM(デバイスメモリ)、Memory::VRAMA(VRAM-A)、Memory::VRAMB(VRAM-B)から選択します。

3.2.2. VertexBufferResource オブジェクトの解放

nn::gd::Resource::ReleaseVertexBufferResource() を呼び出すことで、VertexBufferResource オブジェクトの解放が行われます。オブジェクトの解放と同時に、作成時に確保されたメモリ領域も解放されます。

コード 3-16. VertexBufferResource オブジェクトの解放
static nnResult nn::gd::Resource::ReleaseVertexBufferResource(
        nn::gd::VertexBufferResource *buffer); 

3.2.3. VertexBufferResource オブジェクトの詳細情報の取得

VertexBufferResource オブジェクトに格納されている詳細情報(VertexBufferResourceProperties クラス)を nn::gd::Resource::GetVertexBufferResourceProperties() で取得することができます。

コード 3-17. VertexBufferResource オブジェクトの詳細情報の取得
static nnResult nn::gd::Resource::GetVertexBufferResourceProperties(
        const nn::gd::VertexBufferResource* buffer,
        nn::gd::VertexBufferResourceProperties* properties);

この関数は buffer に指定した、VertexBufferResource オブジェクトに格納されている詳細情報へのポインタを properties に返します。取得したポインタを介して、VertexBufferResource オブジェクトの内容を書き換えてしまわないように注意してください。

3.2.3.1. VertexBufferResource オブジェクトの詳細情報

詳細情報(VertexBufferResourceProperties クラス)には、オブジェクトの作成時に指定されたデスクリプタクラスの設定とほぼ同じ内容が格納されています。

コード 3-18. VertexBufferResourceProperties クラスの定義
class nn::gd::VertexBufferResourceProperties
{
    u32 m_ByteSize;
    nn::gd::Memory::MemoryLocation m_MemLocation;
    u8* m_MemAddr;
};

ここでは、このクラスにのみ存在するメンバを説明します。

リソースデータの先頭アドレス(m_MemAddr)

リソースデータの先頭アドレスが物理アドレスで設定されています。

3.2.4. VertexBufferResource オブジェクトのデータポインタの取得

リソースデータにアクセスするためのデータポインタを nn::gd::Resource::MapVertexBufferResource() で取得することができます。

コード 3-19. VertexBufferResource オブジェクトのデータポインタの取得
static nnResult nn::gd::Resource::MapVertexBufferResource(
        nn::gd::VertexBufferResource* buffer,
        nn::gd::Resource::MapUsage usage, void** data);
static nnResult nn::gd::Resource::UnmapVertexBufferResource(
        nn::gd::VertexBufferResource* buffer);

buffer に指定した VertexBufferResource オブジェクトのリソースデータの先頭アドレスが data に返されます。usage には、以下のマッピング方法(リソースデータへのアクセスの種類)を指定します。

表 3-4. データポインタのマッピング方法
定義 マッピング方法 デバイスメモリ VRAM
Resource::MAP_READ_ONLY 読み込みのみ
Resource::MAP_WRITE_ONLY 書き込みのみ エラー
Resource::MAP_READ_WRITE 読み書き エラー
補足:

マッピング方法のチェックはデータポインタの取得時にのみ行われます。MAP_READ_ONLY で取得したデバイスメモリ上のリソースデータに書き込みを行ってもエラーにはなりませんが、マッピングの解除時にキャッシュがフラッシュされません。

VRAM 上のリソースデータに直接アクセスすることはできません。DMA 転送などで、CPU から直接アクセス可能なメモリ上にコピーしてください。

リソースデータへのアクセスが完了したあとは、nn::gd::Resource::UnmapVertexBufferResource() でマッピングを解除してください。書き込みを含むマッピング方法でデバイスメモリ上のリソースデータのデータポインタを取得していた場合は、マッピングの解除時にキャッシュのフラッシュが行われます。

3.2.5. リソースデータの部分コピー(VertexBufferResource オブジェクト)

リソースデータの部分コピーを行うことができます。この関数内で nngxAddBlockImageCopyCommand() を呼び出していますので、実際のコピー処理はコマンドリストの実行時に行われます。

コード 3-20. リソースデータの部分コピー(VertexBufferResource オブジェクト)
static nnResult nn::gd::Memory::CopyVertexBufferSubResource(
        const nn::gd::VertexBufferResource* source,
        u32 sourceOffset, u32 size,
        const nn::gd::VertexBufferResource* dest, u32 destOffset);

sourceOffset sizedestOffset のすべてが 16 の倍数で指定されていなければコピー処理は行われません。