Platform SDK: DirectX |
IDirectDraw7::EnumSurfaces メソッドを呼び出すことにより、DirectDraw はさまざまな方法でサーフェスを列挙できる。EnumSurfaces メソッドにより、提供されたサーフェスの記述に適合または不適合であるサーフェスを検索することができる。DirectDraw は、個々の列挙されたサーフェスに対して呼び出す EnumSurfacesCallback を呼び出す。
検索には 2 つの一般的な方法がある。DirectDraw オブジェクトが既に作成しているサーフェスを検索する方法、および DirectDraw オブジェクトがそのとき (サーフェスの記述と利用可能なメモリを与えるとき) に作成できるサーフェスを検索する方法である。メソッドの dwFlags パラメータの組み合わせフラグにより、検索タイプを指定できる。
既存サーフェスの列挙 これは列挙のもっとも一般的なタイプである。dwFlags パラメータで、DDENUMSURFACES_DOESEXIST 検索タイプ フラグと組み合わせフラグの 1 つ (DDENUMSURFACES_MATCH、DDENUMSURFACES_NOMATCH、または DDENUMSURFACES_ALL) の組み合わせを指定する EnumSurfaces を呼び出すと、既存サーフェスを列挙できる。既存サーフェスをすべて列挙している場合、lpDDSD パラメータを NULL に設定できる。または、そのパラメータを検索するサーフェスを記述するために初期化された DDSURFACEDESC2 構造体のアドレスにも設定できる。3 番目のパラメータ (lpContext) は、4 番目のパラメータ (lpEnumSurfacesCallback) に指定する列挙関数へ渡すアドレスに設定する。
次のコードでは、この呼び出しが DirectDraw オブジェクトの既存サーフェスをすべて列挙する場合を説明する。
HRESULT ddrval; ddrval = lpDD->EnumSurfaces(DDENUMSURFACES_DOESEXIST | DDENUMSURFACES_ALL, NULL, NULL, EnumCallback); if (FAILED(ddrval)) return FALSE;
特定の記述に適合する既存サーフェスを検索する場合、DirectDraw では提供されたサーフェスを記述する個々のメンバと、既存サーフェスの個々のメンバを比較して適合を決定する。完全に適合したものだけが列挙される。DirectDraw では、列挙されたサーフェスの参照カウントをインクリメントするので、参照カウントを使用しない場合 (または、処理する場合) は、サーフェスの解放を確認すること。
利用可能なサーフェスの列挙 このタイプの列挙は、既存サーフェスの列挙よりも一般的ではない。しかし、サーフェスを作成しようとする前にサポートされる場合の決定には有用である。この検索を実行するには、IDirectDraw7::EnumSurfaces を呼び出すときに、DDENUMSURFACES_CANBECREATED と DDENUMSURFACES_MATCH フラグを組み合わせる (他のフラグの組み合わせでは無効となる)。呼び出しに使用する DDSURFACEDESC2 構造体は、DirectDraw で使用するサーフェス特性の情報を含むために初期化しなくてはならない。
特別なピクセル フォーマットを使用するサーフェスを列挙するには、DDSURFACEDESC2 構造体の dwFlags メンバに DDSD_PIXELFORMAT フラグを含む。さらに、サーフェスを記述する DDPIXELFORMAT 構造体を初期化して、その dwFlags メンバを要求されるピクセル フォーマット フラグ (DDPF_RGB、DDPF_YUV、または両方) を含むために設定する。他のピクセル フォーマット値は設定しなくてもよい。
DDSURFACEDESC2 構造体に DDSD_HEIGHT フラグと DDSD_WIDTH フラグを含む場合、dwHeight と dwWidth メンバで要求されるディメンジョンを指定できる。これらのフラグを含まない場合は、DirectDraw がプライマリ サーフェスのディメンジョンを使用する。
次のコードでは、この呼び出しが 96 × 96 の RGB や YUV サーフェスに対する有効なサーフェス特性のすべてを列挙する場合を説明する。
DDSURFACEDESC2 ddsd; HRESULT ddrval; ZeroMemory(&ddsd, sizeof(ddsd)); ddsd.dwSize = sizeof(ddsd); ddsd.dwFlags = DDSD_CAPS | DDSD_PIXELFORMAT | DDSD_HEIGHT | DDSD_WIDTH; ddsd.ddpfPixelFormat.dwFlags = DDPF_YUV | DDPF_RGB; ddsd.dwHeight = 96; ddsd.dwWidth = 96; ddrval = lpDD->EnumSurfaces( DDENUMSURFACES_CANBECREATED | DDENUMSURFACES_MATCH, &ddsd, NULL, EnumCallback); if (ddrval != DD_OK) return FALSE;
DirectDraw が利用可能なサーフェスを列挙する場合、実際には、要求された特性を持つ一時的なサーフェスを作成しようとする。その作成が成功すると、次に DirectDraw は作用される特性だけに提供される EnumSurfacesCallback 関数を呼び出す。つまり、一時的なサーフェスへのポインタには、コールバック関数を提供しない。サーフェスが列挙されない場合に、サーフェスがサポートされていないと仮定することはない。DirectDraw が一時的なサーフェスを作成しようとして、呼び出すときにのメモリ制約のために失敗した可能性もある。このため、ドライバが実際にサーフェスをサポートしていても、これらの特性が列挙されないのである。
DirectDraw7.GetSurfacesEnum メソッドを呼び出すことにより、DirectDraw はさまざまな方法でサーフェスを列挙できる。GetSurfacesEnum メソッドにより、提供されたサーフェスの記述に適合または不適合であるサーフェスを検索することができる。このメソッドは、個々のサーフェス記述を照会する DirectDrawEnumSurfaces オブジェクトを作成する。
検索には 2 つの一般的な方法がある。DirectDraw オブジェクトが既に作成しているサーフェスを検索する方法、および DirectDraw オブジェクトがそのとき (サーフェスの記述と利用可能なメモリを与えるとき) に作成できるサーフェスを検索する方法である。メソッドの flags パラメータの組み合わせフラグにより、検索タイプを指定できる。
既存サーフェスの列挙 これは列挙のもっとも一般的なタイプである。flags パラメータで、DDENUMSURFACES_DOESEXIST 検索タイプ フラグと組み合わせフラグの 1 つ (DDENUMSURFACES_MATCH、DDENUMSURFACES_NOMATCH、または DDENUMSURFACES_ALL) の組み合わせを指定する GetSurfacesEnum を呼び出すと、既存サーフェスを列挙できる。既存サーフェスをすべて列挙している場合、desc パラメータを Nothing に設定できる。または、そのパラメータを検索するサーフェスを記述するために初期化された DDSURFACEDESC2 型のアドレスにも設定できる。
次のコードでは、この呼び出しが DirectDraw オブジェクトの既存サーフェスをすべて列挙する場合を説明する。ここでは、dd が有効な DirectDraw7 オブジェクト、ddEnumSurfaces が有効な DirectDrawEnumSurfaces オブジェクトとする。
Set ddEnumSurfaces = dd.GetSurfacesEnum(DDENUMSURFACES_DOESEXIST Or _ DDENUMSURFACES_ALL, ddsd2)
特定の記述に適合する既存サーフェスを検索する場合、DirectDraw では提供されたサーフェスを記述する個々のメンバと、既存サーフェスの個々のメンバを比較して適合を決定する。完全に適合したものだけが DirectDrawEnumSurfaces オブジェクトに埋め込まれる。
利用可能なサーフェスの列挙 このタイプの列挙は、既存サーフェスの列挙よりも一般的ではない。しかし、サーフェスを作成しようとする前にサポートされる場合の決定には有用である。この検索を実行するには、DirectDraw7.GetSurfacesEnum を呼び出すときに、DDENUMSURFACES_CANBECREATED と DDENUMSURFACES_MATCH フラグを組み合わせる (他のフラグの組み合わせでは無効となる)。呼び出しに使用する DDSURFACEDESC2 型は、DirectDraw で使用するサーフェス特性の情報を含むために初期化しなくてはならない。
特別なピクセル フォーマットを使用するサーフェスを列挙するには、DDSURFACEDESC2 型の lFlags メンバに DDSD_PIXELFORMAT フラグを含む。さらに、サーフェスを記述する DDPIXELFORMAT 型を初期化して、その lFlags メンバを要求されるピクセル フォーマット フラグ (DDPF_RGB、DDPF_YUV、または両方) を含むために設定する。他のピクセル フォーマット値は設定しなくてもよい。
DDSURFACEDESC2 型に DDSD_HEIGHT フラグと DDSD_WIDTH フラグを含む場合、lHeight と lWidth メンバで要求されるディメンジョンを指定できる。これらのフラグを含まない場合は、DirectDraw がプライマリ サーフェスのディメンジョンを使用する。
次のコードでは、この呼び出しが 96 × 96 の RGB や YUV サーフェスに対する有効なサーフェス特性のすべてを列挙する場合を説明する。
Dim ddsd As DDSURFACEDESC2 ddsd.lFlags = DDSD_CAPS Or DDSD_PIXELFORMAT Or DDSD_HEIGHT Or DDSD_WIDTH ddsd.ddpfPixelFormat.lFlags = DDPF_YUV Or DDPF_RGB ddsd.lHeight = 96 ddsd.lWidth = 96 Set ddEnumSurfaces = dd.GetSurfacesEnum(DDENUMSURFACES_CANBECREATED Or _ DDENUMSURFACES_MATCH, ddsd)
DirectDraw が利用可能なサーフェスを列挙する場合、実際には、要求された特性を持つ一時的なサーフェスを作成しようとする。その作成が成功すると、次に DirectDraw は DirectDrawEnumSurfaces オブジェクトに作用される特性だけを埋め込む。サーフェスが列挙されない場合に、サーフェスがサポートされていないと仮定することはない。DirectDraw が一時的なサーフェスを作成しようとして、呼び出すときにのメモリ制約のために失敗した可能性もある。このため、ドライバが実際にサーフェスをサポートしていても、これらの特性が列挙されないのである。