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

# kmLoadTexturePart

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

### 書式

> `KMSTATUS kmLoadTexturePart(pSurfaceDesc, pTexture, nOffset, nSize )
> PKMSURFACEDESC pSurfaceDesc
> PKMDWORD pTexture
> KMUINT32 nOffset
> KMUINT32 nSize
> `

### 引数

> pSurfaceDesc | (入力)確保したテクスチャサーフェスの構造体へのポインタ
> pTexture | (入力)メインメモリ上のテクスチャのピクセルデータ部分を示すポインタ
> nOffset | (入力)すでに読み込んだテクスチャのサイズ(テクスチャ全体での、先頭からのオフセット量)
> nSize | (入力)読み込む部分のサイズ(バイト)

### 戻り値

> KMSTATUS_SUCCESS | 成功
> KMSTATUS_INVALID_ADDRESS | nOffsetがテクスチャサイズを越えている
> KMSTATUS_INVALID_TEXTURE_TYPE | 無効なテクスチャタイプを指定した

### 解説

> 確保したフレームバッファメモリ上のテクスチャ領域に、 メインメモリ上のテクスチャデータの一部分から読み込みます。

> テクスチャデータをいくつかの部分に分割して読み込むことができます。 これにより、メインメモリ上に大きなワークエリアを確保することなく、 サイズの大きなテクスチャを読み込むことができます。

> kmCreateTextureSurface()関数 / kmCreateCombinedTextureSurface()関数 / kmCreateContiguousTextureSurface()関数 / kmCreateFixedTextureArea()関数で確保したフレームバッファメモリ上のテクスチャ領域に、 引数pTextureが指定するメインメモリ上のテクスチャデータ(部分)を読み込みます。

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

> 引数nOffsetには、 すでに読み込んだテクスチャのサイズ(テクスチャ全体での、先頭からのオフセット量) をバイト単位で指定します。 ここで指定するサイズは4の倍数でなければなりません。 これは、フレームバッファメモリ上の転送先テクスチャ領域のアドレスを求めるのに使用されます。

> 引数nSizeには、 今回読み込む部分のサイズをバイト単位で指定します。 ここで指定するサイズは4の倍数でなければなりません。

> なお、nSizeが、テクスチャの残りサイズ(= テクスチャサイズ - nOffset)より kmLoadTextureBlock()関数と異なり、一つのテクスチャを、 「サイズの異なる」複数の部分に分けて読み込むことができます。 ただし、今までに読み込んだテクスチャのサイズ(先頭からのオフセット量)は、ユーザー側で管理する必要があります。 たとえば

> nOffset = 0;
> nSize = ***;
> /* pTextureで示される領域に、テクスチャデータの最初のnSizeバイトをロード */
> while(KMSTATUS_SUCCESS == kmLoadTexturePart(...)){
> nOffset = nOffset + nSize;
> nSize = ????;
> /* pTextureで示される領域に、次のnSizeバイトをロード */
> }

> の様に記述してください。 読み込むテクスチャのフォーマット形式、サイズなどは、pSurfaceDescで指定されるサーフェスディスクリプタより判断されます。

> 実際のテクスチャのフォーマット形式などが、pSurfaceDescで指定されるサーフェスディスクリプタの内容と異なっている場合は、表示が不正となります。 システムメモリ側のテクスチャデータの先頭アドレスを32バイトアライメントしていて、 かつサイズが32バイトの倍数である場合、 テクスチャメモリへの転送にDMAを使用します。高速な転送が可能となります。 テクスチャの転送にDMAが使用された場合、その終了を待つか否かを選択することができます。

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

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

### 参照

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

kmLoadTexturePart

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