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

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

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

サーフェイスは、1 つあるいは複数のプライベート データ バッファを所有できる。各バッファは、サーフェイスにデータをアタッチするときに指定するグローバル一意識別子 (GUID) で識別される。

プライベート サーフェイス データを格納するには、SetPrivateData を使って、転送元バッファ、データのサイズ、データ用にアプリケーションで定義した GUID へのポインタを渡す。オプションとして、転送元データはコンポーネント オブジェクト モデル (COM) オブジェクトのフォーム内に存在できる。 この場合、オブジェクトの IUnknown インターフェイス ポインタにポインタを渡し、D3DSPD_IUNKNOWNPOINTER フラグを設定する。

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

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

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