##### Kamui2 Library - テクスチャ制御関数

# kmLoadTextureBlock

テクスチャデータの分割読み込み

### 書式

> `KMSTATUS kmLoadTextureBlock( pSurfaceDesc, pTexture, nBlockNum, nBlockSize )
> PKMSURFACEDESC pSurfaceDesc
> PKMDWORD pTexture
> KMUINT32 nBlockNum
> KMUINT32 nBlockSize
> `

### 引数

> pSurfaceDesc | (入力)確保したテクスチャサーフェスへのポインタ
> pTexture | (入力)メインメモリ上のテクスチャのピクセルデータ部分を示すポインタ
> nBlockNum | (入力)テクスチャのブロック番号
> nBlockSize | (入力)ブロックのサイズ(バイト)

### 戻り値

> KMSTATUS_SUCCESS | 読み込み成功
> KMSTATUS_INVALID_BLOCKNUMBER | ブロック番号が不正
> KMSTATUS_INVALID_ADDRESS | 指定されたエリア(Surface)は確保されていない
> KMSTATUS_INVALID_TEXTURE_TYPE | 無効なテクスチャタイプを指定した

### 解説

> メインメモリの分割されたテクスチャデータブロックをグラフィックメモリのテクスチャ領域に読み込みます。

> この関数を利用することで、メインメモリ上に大きなワークエリアを確保することなく、サイズの大きなテクスチャを読み込むことができます。 この関数の実行の前に、フレームバッファメモリのテクスチャ領域は、以下の関数で確保しておく必要があります。

> - kmCreateTextureSurface()関数
> - kmCreateCombinedTextureSurface()関数
> - kmCreateContiguousTextureSurface()関数
> - kmCreateFixedTextureArea()

> 引数pSurfaceDescは、確保したテクスチャサーフェス KMSURFACEDESC 型の構造体へのポインタです。

> 引数pTextureは、メインメモリ上のテクスチャのピクセルデータ部分を示すポインタです。 ここで指定するアドレスは、Kamuiテクスチャフォーマットのテクスチャファイルの 先頭アドレス+16で、32バイトアラインしたアドレスを指定してください。 (Kamuiテクスチャのヘッダ部分16バイトをスキップさせます)

> 引数nBlockNumには、テクスチャのブロック番号を 0〜n (n はフォーマット／サイズによる)で指定します。

> 引数nBlockSizeには、ブロックのサイズを32Byte 単位で指定します。 ブロックサイズ(Byte)を32で割った値を指定してください。

> なお、テクスチャ全体のサイズがブロックサイズで割り切れなくても、テクスチャデータは正しく読み込まれます。 ただし、1つのテクスチャを読み込んでいるループの途中でBUFFSIZEの値を変更することはできません。

> この値を途中で変更した場合は、テクスチャの表示正しく行うことができません。 読み込むテクスチャのフォーマット形式、サイズなどは、 引数pSurfaceDesc が指すサーフェスディスクリプタより判断します。 実際のテクスチャのフォーマット形式などが、 引数pSurfaceDescの指すサーフェスディスクリプタの内容と異なっていると表示が正しく行われません。

> メインメモリのテクスチャデータの先頭アドレスを32Byteアライメントでサイズが32Byteの倍数だと、 テクスチャメモリへの転送にDMAを使用して高速な転送が可能となります。 テクスチャの転送にDMAが使用された場合、その終了を待つか否かを選択することができます。 kmSetSystemConfiguration()関数でflagにKM_CONFIGFLAG_NOWAIT_FINISH_TEXTUREDMAを指定した場合は DMA転送の終了を待たずに関数を終了します。

> この場合は、kmQueryFinishLastTextureDMA()関数でDMA転送の終了を確認することができます。 テクスチャロード前に CPU側でメインメモリ上のテクスチャデータを直接書き換えた場合などは、 キャッシュのコヒーレンシ確保のため、キャッシュのパージを行った上でロード関数を実行してください(SH4のocbwb命令の実行)。

> なお、この関数はSmall VQ形式のテクスチャには対応していません。 Small VQ形式のpSurfaceDescを指定した場合には、KMSTATUS_INVALID_TEXTURE_TYPEを返します。

### 用例

>     /* テクスチャを(BUFFSIZE * 32)バイトずつに分けて読み込む */
>     i = 0;
>     while(KMSTATUS_SUCCESS
>     	== kmLoadTextureBlock( &TexSurfaceDesc, pTexture, i++, BUFFSIZE)) {
>     	:
>     }

### 参照

> kmCreateCombinedTextureSurface() | 複合テクスチャサーフェスの確保
> kmCreateContiguousTextureSurface() | 連続したアドレス領域へのテクスチャサーフェスの作成
> kmCreateFixedTextureArea() | 固定テクスチャ領域の確保
> kmCreateTextureSurface() | テクスチャ用サーフェスの確保
> kmQueryFinishLastTextureDMA() | 前回のDMA転送によるテクスチャロードの終了チェック
> kmSetSystemConfiguration() | システム構成の設定

kmLoadTextureBlock

COPYRIGHT © NEC Corporation / © SEGA ENTERPRISES, LTD., 1998-2000