Platform SDK: DirectX

サーフェスの列挙

[C++]

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 が一時的なサーフェスを作成しようとして、呼び出すときにのメモリ制約のために失敗した可能性もある。このため、ドライバが実際にサーフェスをサポートしていても、これらの特性が列挙されないのである。

[Visual Basic]

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 が一時的なサーフェスを作成しようとして、呼び出すときにのメモリ制約のために失敗した可能性もある。このため、ドライバが実際にサーフェスをサポートしていても、これらの特性が列挙されないのである。