IDirect3DSurface9

IDirect3DSurface9 (d3d9.h) インターフェイスは、アプリケーションがサーフェスを問い合わせたり準備したりするために使用します。

LPDIRECT3DSURFACE9 型および PDIRECT3DSURFACE9 型は、IDirect3DSurface9 インターフェイスへのポインターとして定義されています。

typedef struct IDirect3DSurface9 *LPDIRECT3DSURFACE9, *PDIRECT3DSURFACE9;

IDirect3DSurface9::GetContainer (d3d9.h) メソッドは、親であるキューブテクスチャまたはテクスチャ (ミップマップ) オブジェクトへのアクセスを提供します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。メソッドが失敗した場合、戻り値は D3DERR_INVALIDCALL になることがあります。

サーフェスが CreateRenderTarget、CreateOffscreenPlainSurface、または CreateDepthStencilSurface で作成された場合、そのサーフェスはスタンドアロンとみなされます。この場合、GetContainer はサーフェスの作成に使用された Direct3D デバイスを返します。

呼び出しが成功すると、コンテナーの参照カウントが 1 つ増加します。

以下は、ミップサーフェスの親テクスチャを取得する例です。

    
// Assumes pSurface is a valid IDirect3DSurface9 pointer
void *pContainer = NULL;
IDirect3DTexture9 *pTexture = NULL;
HRESULT hr = pSurface->GetContainer(IID_IDirect3DTexture9, &pContainer);
if (SUCCEEDED(hr) && pContainer)
{
    pTexture = (IDirect3DTexture9 *)pContainer;
}

IDirect3DSurface9::GetDesc (d3d9.h) メソッドは、サーフェスの記述を取得します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。

引数が無効な場合は D3DERR_INVALIDCALL が返されます。

IDirect3DSurface9::LockRect (d3d9.h) メソッドは、サーフェス上の矩形をロックします。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。

メソッドが失敗した場合、戻り値は D3DERR_INVALIDCALL または D3DERR_WASSTILLDRAWING になることがあります。

D3DLOCK_DONOTWAIT フラグが指定されていて、ドライバーがサーフェスをすぐにロックできない場合、IDirect3DSurface9::LockRect は D3DERR_WASSTILLDRAWING を返します。これにより、アプリケーションはドライバーがサーフェスをロックするのを待つ間、CPU サイクルを利用できます。

深度ステンシルサーフェスでロック可能な唯一のフォーマットは D3DFMT_D16_LOCKABLE です。D3DFORMAT を参照してください。

パフォーマンス上の理由から、ダーティリージョンはテクスチャのレベル 0 に対してのみ記録されます。ダーティリージョンは、IDirect3DSurface9::LockRect が D3DLOCK_NO_DIRTY_UPDATE または D3DLOCK_READONLY を指定せずに呼び出されたときに自動的に記録されます。詳細については、IDirect3DDevice9::UpdateTexture を参照してください。

マルチサンプルのバックバッファーはロックできません。

このメソッドは、D3DUSAGE_RENDERTARGET で作成されたテクスチャリソースに含まれるサーフェスからデータを取得できません。そのようなテクスチャは D3DPOOL_DEFAULT メモリに割り当てられる必要があり、ロックできないためです。この場合は、代わりに IDirect3DDevice9::GetRenderTargetData を使用して、テクスチャデータをデバイスメモリからシステムメモリへコピーしてください。

IDirect3DSurface9::UnlockRect (d3d9.h) メソッドは、サーフェス上の矩形のロックを解除します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。メソッドが失敗した場合、戻り値は D3DERR_INVALIDCALL になることがあります。

IDirect3DSurface9::GetDC (d3d9.h) メソッドは、デバイスコンテキストを取得します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。引数が無効な場合は D3DERR_INVALIDCALL が返されます。

次の制限が適用されます。

• IDirect3DSurface9::GetDC は、D3DFMT_R5G6B5、D3DFMT_X1R5G5B5、D3DFMT_R8G8B8、D3DFMT_X8R8G8B8 のフォーマットでのみ有効です。アルファを含むフォーマットはサポートされません。GDI の実装ではアルファチャンネルに対する動作が明確に定義されていないためです。フォーマットの詳細については、D3DFORMAT を参照してください。
• 1 つのサーフェスにつき、同時に返せるデバイスコンテキストは 1 つだけです。
• サーフェスが既にロックされている場合、IDirect3DSurface9::GetDC は失敗します。サーフェスがミップマップまたはキューブマップのメンバーである場合、他のミップマップまたはキューブマップのメンバーがロックされていると IDirect3DSurface9::GetDC は失敗します。
• レンダーターゲットがロック可能として作成されていない限り (バックバッファーの場合は D3DPRESENTFLAG_LOCKABLE_BACKBUFFER フラグ付きで作成されていない限り)、IDirect3DSurface9::GetDC はレンダーターゲットに対して失敗します。
• IDirect3DDevice9::CreateOffscreenPlainSurface で作成されていないサーフェスの場合、IDirect3DSurface9::GetDC は既定プール (D3DPOOL_DEFAULT) のサーフェスに対して失敗します。ただし、そのサーフェスが動的 (D3DUSAGE_DYNAMIC) であるか、ロック可能なレンダーターゲットである場合を除きます。
• IDirect3DSurface9::GetDC は D3DPOOL_SCRATCH のサーフェスに対して失敗します。

• (そのサーフェスを含むスワップチェーンに対して)

IDirect3DSurface9::GetDC は暗黙的なロックを引き起こします。デバイスコンテキストを後で使用するために保持しないでください。解放するには IDirect3DSurface9::ReleaseDC を呼び出します。

ミップマップやキューブマップの各レベルに対して IDirect3DSurface9::GetDC/IDirect3DSurface9::ReleaseDC を呼び出すことは有効です。ただし、最上位レベル以外のすべてのミップレベルではこれらの呼び出しは低速であり、それらのミップレベルに対する GDI 操作はアクセラレートされません。

hdc は Win32 および GDI の機能へのアクセスを提供します。

IDirect3DSurface9::ReleaseDC (d3d9.h) メソッドは、デバイスコンテキストハンドルを解放します。

型: HRESULT

メソッドが成功した場合、戻り値は D3D_OK です。引数が無効な場合は D3DERR_INVALIDCALL が返されます。

hdc は Windows のリソースです。Windows が利用可能なリソースのプールに戻せるよう、使用後は解放する必要があります。

このメソッドは、IDirect3DSurface9::GetDC が返したデバイスコンテキストのみを解放します。それ以外の場合、このメソッドは失敗します。