Microsoft DirectX 8.0 (C++)

プライベート サーフェス データ

サーフェスと共にあらゆる種類のアプリケーション固有データを格納できる。たとえば、ゲームのマップを示すサーフェスには、地域情報を含む場合がある。

サーフェスでは、1 つ以上のプライベート データ バッファを所有できる。各バッファは、サーフェスにデータをアタッチする際に指定する GUID で識別される。

プライベート サーフェス データを格納するには、IDirect3DSurface8::SetPrivateData メソッドを使用する。このメソッドは、転送元バッファ、データのサイズ、データ用にアプリケーションで定義した GUID へのポインタを渡す。随意に、転送元データは COM オブジェクトのフォームに存在できる。この場合、オブジェクトの IUnknown インターフェイス ポインタにポインタを渡し、D3DSPD_IUNKNOWNPOINTER フラグを設定する。

SetPrivateData はデータに対して内部バッファを割り当て、データをコピーする。その後で、転送元バッファまたはオブジェクトを安全に解放できる。内部バッファまたはインターフェイス参照は、IDirect3DSurface8::FreePrivateData の呼び出し時に解放される。サーフェスが解放されると、この処理は自動的に発生する。

サーフェスに対するプライベートデータを取得するには、正確なサイズのバッファを割り当て、SetPrivateData でデータに割り当てられた GUID を渡す IDirect3DSurface8::GetPrivateData メソッドを呼び出さなくてはならない。このバッファを使用するあらゆる動的メモリの解放については、各自で責任を持つ。データが COM オブジェクトの場合、このメソッドは Iunknown ポインタを取得する。

割り当てるバッファのサイズがわからない場合は、最初に SizeOfData にゼロを代入して GetPrivateData を呼び出す。このメソッドが D3DERR_MOREDATA で失敗した場合、バッファに必要なバイト数を SizeOfData に返す。