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

# kmLoadYUVTexture

YUV形式テクスチャデータの読み込み

### 書式

> `KMSTATUS kmLoadYUVTexture( pSurfaceDesc, pTexture, nWidth, nHeight, nFormat, bWaitEndOfDMA )
> PKMSURFACEDESC pSurfaceDesc
> PKMDWORD pTexture
> KMINT32 nWidth
> KMINT32 nHeight
> KMDWORD nFormat
> KMBOOLEAN bWaitEndOfDMA
> `

### 引数

> ppSurfaceDesc | (入力)確保したテクスチャサーフェス構造体へのポインタ
> pTexture | (入力)メインメモリ上のYUV420-data / YUV422-dataを示すポインタ
> nWidth, nHeight | (入力)読み込むテクスチャの数
> nFormat | (入力)読み込むデータの形式
> bWaitEndOfDMA | (入力)データ転送DMAの完了を待つかどうかのフラグ

### 戻り値

> KMSTATUS_SUCCESS | 成功
> KMSTATUS_INVALID_TEXTURE_TYPE | 無効なテクスチャタイプを指定した
> KMSTATUS_INVALID_ADDRESS | pTextureが32バイト境界でない

### 解説

> kmCreateTextureSurface()関数 / kmCreateCombinedTextureSurface()関数 / kmCreateContiguousTextureSurface()関数 / kmCreateFixedTextureArea()関数で確保したフレームバッファメモリ上のテクスチャ領域に、 pTextureが指定するメインメモリ上のYUV420-data/YUV422-dataを、 Non-Twiddled YUV422テクスチャデータに変換して読み込みます。
> 引数pTexture(入力)は、メインメモリ上のYUV420-data / YUV422-dataを示すポインタです。 32バイトアラインしたアドレスを指定してください。 ハードウェアの制約上このアドレスが32バイトアライメントしていない場合はYUVコンバーターは動作しません。 この場合は、KMSTATUS_INVALID_ADDRESSが返されます。

> 引数nWidth, nHeightには、引数nFormat のアドレッシングモードが KM_TEXTURE_YUV_MULTI のとき連続して読み込むテクスチャの数をマクロブロックの数で指定します。 指定できる値は、nWidth、nHeightそれぞれ1から64のいずれかです。 なお、1マクロブロックは 16 x 16 テクセルです。

> 引数nFormat のアドレッシングモードが KM_TEXTURE_YUV_SINGLE のとき読み込むテクスチャのサイズをテクセル数で指定します。

> - 出力を Rectangle フォーマットとして扱う場合、引数Width、引数Height ともに 16, 32, 64, 128, 256, 512, 1024 のいずれかでなければなりません。
> - 出力を Stride フォーマットとして扱う場合、引数Height は 16, 32, 64, 128, 256, 512, 1024 のいずれかでなければなりません。

> 引数nWidth は 32 から 992 の間の、32 の倍数でなければなりません。

> 引数nFormatには、読み込むデータの形式を指定します。 以下の各カテゴリよりそれぞれいずれかを選択し論理和して指定します。

> ■カラーモード

> 定義 | 意味
> KM_TEXTURE_YUV420 | 入力データはYUV420-data形式
> KM_TEXTURE_YUV422 | 入力データはYUV422-data形式

> ■アドレッシングモード

> 定義 | 意味
> KM_TEXTURE_YUV_MULTI | 入力データは複数の16x16 YUV-data
> KM_TEXTURE_YUV_SINGLE | 入力データはひとつのnWidth x nHeight YUV-data

> 引数bWaitEndOfDMAは、 YUVコンバータへのDMAによるデータ転送が完了するのを待つかどうかを指定します。

> 定義 | 意味
> TRUE | DMA転送が終了するまでこの関数は終了しない
> FALSE | DMA転送の終了を待たない

> DMA転送の終了を検知したい場合はコールバック関数 kmSetEndOfYUVCallback()を使用してください。

> タイルアクセラレータに内蔵されている YUV-data converter を使用して変換しながら読み込みます。 YUV-data converter の出力は Non-Twiddled であるため、この関数で指定する読み込み先のテクスチャサーフェスの形式は、以下のいずれかでなければなりません。

> 指定 | 意味
> KM_TEXTURE_RECTANGLE | KM_TEXTURE_YUV422 | 矩形
> KM_TEXTURE_STRIDE | KM_TEXTURE_YUV422 | 矩形(ストライド指定有り)

> 複数の YUV-data を一度に連続して読み込む場合 ( nFormat のアドレッシングモードが KM_TEXTURE_YUV_MULTI の時は、個々のテクスチャのサイズは16x16テクセルでなければなりません。

> この関数で指定する読み込み先のテクスチャサーフェスのサイズ指定にご注意ください。 また、この場合は、読み込み先のテクスチャサーフェスはフレームバッファ上で連続したアドレスに確保していることが必要です。 この場合は必ず kmCreateContiguousTextureSurface()関数を使用して確保したTexture Surfaceを指定してください。 一つの YUV-data を読み込む場合( nFormat のアドレッシングモードが KM_TEXTURE_YUV_SINGLE の時)は、 nHeight は 16, 32, 64, 128, 256, 512, 1024 のいずれかでなければなりません。

> また、nWidth は 32 から 992 の間の、32 の倍数でなければなりません。 ただし、読み込み先テクスチャサーフェスが KM_TEXTURE_RECTANGLE である場合は、 nWidth も 16, 32, 64, 128, 256, 512, 1024 のいずれかでなければなりません。

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

### 参照

> kmCreateTextureSurface() | テクスチャ用サーフェスの確保
> kmCreateCombinedTextureSurface() | 複合テクスチャサーフェスの確保
> kmCreateContiguousTextureSurface() | 連続したアドレス領域へのテクスチャサーフェスの作成
> kmCreateFixedTextureArea() | 固定テクスチャ領域の確保
> kmCreateContiguousTextureSurface() | 連続したアドレス領域へのテクスチャサーフェスの作成
> kmSetEndOfYUVCallback() | YUV終了割り込みコールバック関数の登録

kmLoadYUVTexture

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