ホーム › Graphics.DirectDraw › IDirectDraw7

IDirectDraw7

COM

IID15e65ec0-3b9c-11d2-b92f-00609797ea5b継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

アプリケーションは IDirectDraw7 インターフェイスのメソッドを使用して、DirectDraw オブジェクトの作成やシステムレベルの変数の操作を行います。このセクションは IDirectDraw7 インターフェイスのメソッドに関するリファレンスです。

解説(Remarks)

IDirectDraw7 インターフェイスのメソッドは、次のグループに分類できます。

グループ	メソッド
メモリの割り当て	Compact と Initialize
協調レベル	SetCooperativeLevel と TestCooperativeLevel
オブジェクトの作成	CreateClipper、CreatePalette、CreateSurface
デバイスの能力	GetCaps
表示モード	EnumDisplayModes、GetDisplayMode、 GetMonitorFrequency、 RestoreDisplayMode、SetDisplayMode、および WaitForVerticalBlank
表示状態	GetScanLine と GetVerticalBlankStatus
その他	EvaluateMode、 GetAvailableVidMem、 GetDeviceIdentifier、 GetFourCCCodes、および StartModeTest
サーフェス管理	DuplicateSurface、 EnumSurfaces、 FlipToGDISurface、 GetGDISurface、 GetSurfaceFromDC、および RestoreAllSurfaces

IDirectDraw7 インターフェイスは、以前のバージョンよりも柔軟なサーフェス管理を可能にするメソッドを提供することで、以前のバージョンの機能を拡張しています。IDirectDraw7 インターフェイスのサーフェス関連メソッドはいずれも、IDirectDraw2 インターフェイスの対応するメソッドとはわずかに異なるパラメーターを受け取ります。IDirectDraw2 インターフェイスのメソッドが DDSURFACEDESC 構造体を受け取って IDirectDrawSurface3 インターフェイスを取得する箇所では、IDirectDraw7 のメソッドは代わりに DDSURFACEDESC2 構造体を受け取り、IDirectDrawSurface7 インターフェイスを取得します。

IDirectDraw7 では、子オブジェクトの有効期間を定める COM の規則への準拠が改善されています。

IDirectDraw、IDirectDraw2、IDirectDraw4、IDirectDraw7 の各インターフェイスへのポインターを保持する変数を宣言するには、LPDIRECTDRAW、LPDIRECTDRAW2、LPDIRECTDRAW4、LPDIRECTDRAW7 の各データ型を使用します。Ddraw.h ヘッダーファイルは、これらのデータ型を次のコードで宣言しています。


typedef struct IDirectDraw     FAR *LPDIRECTDRAW;
typedef struct IDirectDraw2    FAR *LPDIRECTDRAW2;
typedef struct IDirectDraw4    FAR *LPDIRECTDRAW4;
typedef struct IDirectDraw7    FAR *LPDIRECTDRAW7;

メソッド 27

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT Compact()

このメソッドは現在実装されていません。(IDirectDraw7.Compact)

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY

vtbl 4 HRESULT CreateClipper(DWORD param0, IDirectDrawClipper** param1, IUnknown* param2)

DirectDrawClipper オブジェクトを作成します。

param0	DWORD	in	クリッパー生成オプションを示すフラグ。通常は0を指定する。
param1	IDirectDrawClipper**	out	作成されたクリッパーオブジェクトを受け取る出力ポインタである。
param2	IUnknown*	in	COM集約用の外部IUnknown。通常はNULLを指定する。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY

解説(Remarks)

DirectDrawClipper オブジェクトは DirectDrawSurface にアタッチでき、IDirectDrawSurface7::Blt、IDirectDrawSurface7::BltBatch、IDirectDrawSurface7::UpdateOverlay の各操作で使用できます。

特定の DirectDraw オブジェクトに所有されない DirectDrawClipper オブジェクトを作成するには、DirectDrawCreateClipper 関数を使用します。

vtbl 5 HRESULT CreatePalette(DWORD param0, PALETTEENTRY* param1, IDirectDrawPalette** param2, IUnknown* param3)

この DirectDraw オブジェクトに対して DirectDrawPalette オブジェクトを作成します。

param0	DWORD	in	パレットの能力やビット数を示すDDPCAPS_系フラグである。
param1	PALETTEENTRY*	inout	パレット初期エントリ配列(PALETTEENTRY)へのポインタである。
param2	IDirectDrawPalette**	out	作成されたパレットオブジェクトを受け取る出力ポインタである。
param3	IUnknown*	in	COM集約用の外部IUnknown。通常はNULLを指定する。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED

vtbl 6 HRESULT CreateSurface(DDSURFACEDESC2* param0, IDirectDrawSurface7** param1, IUnknown* param2)

この DirectDraw オブジェクトに対して DirectDrawSurface オブジェクトを作成します。

param0	DDSURFACEDESC2*	inout	作成するサーフェスの構成を記述するDDSURFACEDESC2構造体へのポインタである。
param1	IDirectDrawSurface7**	out	作成されたサーフェス(IDirectDrawSurface7)を受け取る出力ポインタである。
param2	IUnknown*	in	COM集約用の外部IUnknown。通常はNULLを指定する。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_NOALPHAHW
DDERR_NOCOOPERATIVELEVELSET
DDERR_NODIRECTDRAWHW
DDERR_NOEMULATION
DDERR_NOEXCLUSIVEMODE
DDERR_NOFLIPHW
DDERR_NOMIPMAPHW
DDERR_NOOVERLAYHW
DDERR_NOZBUFFERHW
DDERR_OUTOFMEMORY
DDERR_OUTOFVIDEOMEMORY
DDERR_PRIMARYSURFACEALREADYEXISTS
DDERR_UNSUPPORTEDMODE

vtbl 7 HRESULT DuplicateSurface(IDirectDrawSurface7* param0, IDirectDrawSurface7** param1)

DirectDrawSurface オブジェクトを複製します。

param0	IDirectDrawSurface7*	in	複製元となる既存サーフェス(IDirectDrawSurface7)へのポインタである。
param1	IDirectDrawSurface7**	out	複製されたサーフェスを受け取る出力ポインタである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_CANTDUPLICATE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACELOST

解説(Remarks)

DuplicateSurface は、既存の DirectDrawSurface オブジェクトと同じサーフェスメモリを指す新しい DirectDrawSurface オブジェクトを作成します。この複製は、元のオブジェクトと同じように使用できます。サーフェスメモリは、それを参照する最後のオブジェクトが解放された後に解放されます。プライマリサーフェス、3-D サーフェス、暗黙的に作成されたサーフェスは複製できません。

vtbl 8 HRESULT EnumDisplayModes(DWORD param0, DDSURFACEDESC2* param1, void* param2, LPDDENUMMODESCALLBACK2 param3)

DirectDraw オブジェクトを通じてハードウェアが公開している表示モードのうち、指定したサーフェス記述と互換性のあるものをすべて列挙します。

param0	DWORD	in	列挙動作を制御するフラグ(DDEDM_系)である。
param1	DDSURFACEDESC2*	inout	列挙を絞り込む条件を示すDDSURFACEDESC2へのポインタ。NULLで全件となる。
param2	void*	inout	コールバックに渡されるアプリ定義のコンテキストである。NULL可。
param3	LPDDENUMMODESCALLBACK2	in	各表示モードごとに呼ばれる列挙コールバック関数(2版)である。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

IDirectDraw7::EnumDisplayModes は DDSURFACEDESC2 構造体の dwRefreshRate メンバーを列挙します。IDirectDraw::EnumDisplayModes メソッドにはこの機能がありません。IDirectDraw7::SetDisplayMode メソッドを使用して新しいモードのリフレッシュレートを設定する場合は、IDirectDraw7::EnumDisplayModes を使用して dwRefreshRate メンバーを列挙してください。

IDirectDraw7::EnumDisplayModes は、以前のインターフェイスの対応メソッドと異なり、パラメーターとして EnumModesCallback 関数ではなく EnumModesCallback2 関数のアドレスを受け取ります。

vtbl 9 HRESULT EnumSurfaces(DWORD param0, DDSURFACEDESC2* param1, void* param2, LPDDENUMSURFACESCALLBACK7 param3)

指定したサーフェス記述に一致する、既存または作成可能なサーフェスをすべて列挙します。

param0	DWORD	in	列挙対象や動作を制御するフラグ(DDENUMSURFACES_系)である。
param1	DDSURFACEDESC2*	inout	列挙条件を示すDDSURFACEDESC2へのポインタである。NULL可。
param2	void*	inout	コールバックに渡されるアプリ定義のコンテキストである。NULL可。
param3	LPDDENUMSURFACESCALLBACK7	in	各サーフェスごとに呼ばれる列挙コールバック関数(7版)である。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

DDENUMSURFACES_CANBECREATED フラグが設定されている場合、このメソッドは検索条件を満たすサーフェスの一時的な作成を試みます。

DDENUMSURFACES_DOESEXIST フラグを使用すると、列挙されたサーフェスの参照カウントが増加します。サーフェスを使用しない場合は、各列挙の後に必ず IDirectDrawSurface7::Release を使用して解放してください。サーフェスを使用する場合は、不要になった時点で解放してください。

このメソッドは、以前のインターフェイスバージョンの対応メソッドと異なり、EnumSurfacesCallback 関数や EnumSurfacesCallback2 関数ではなく、EnumSurfacesCallback7 関数へのポインターを受け取ります。

vtbl 10 HRESULT FlipToGDISurface()

GDI が書き込むサーフェスをプライマリサーフェスにします。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

解説(Remarks)

ページフリッピングを行うアプリケーションの終了時に FlipToGDISurface を呼び出すと、GDI が書き込む表示メモリが確実に表示されるようにできます。

また、FlipToGDISurface を使用して GDI サーフェスをプライマリサーフェスにすることで、ダイアログボックスなどの通常のウィンドウをフルスクリーンモードで表示できるようにすることもできます。この場合、ハードウェアが DDCAPS2_CANRENDERWINDOWED 能力を備えている必要があります。

FlipToGDISurface はステレオ自動フリップを無効にします。

vtbl 11 HRESULT GetCaps(DDCAPS_DX7* param0, DDCAPS_DX7* param1)

ハードウェアおよびハードウェアエミュレーションレイヤー (HEL) のデバイスドライバーの能力を取得します。

param0	DDCAPS_DX7*	inout	ハードウェアの能力を受け取るDDCAPS構造体へのポインタである。NULL可。
param1	DDCAPS_DX7*	inout	エミュレーション(HEL)の能力を受け取る構造体へのポインタである。NULL可。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

2 つのパラメーターのうち、除外するために NULL に設定できるのは片方のみです。両方を NULL に設定した場合、このメソッドは失敗し、DDERR_INVALIDPARAMS を返します。

vtbl 12 HRESULT GetDisplayMode(DDSURFACEDESC2* param0)

現在の表示モードを取得します。

param0

DDSURFACEDESC2*

inout

現在の表示モード情報を受け取るDDSURFACEDESC2へのポインタである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE

解説(Remarks)

アプリケーションは、後処理で表示モードを復元するために GetDisplayMode が返す情報を保存すべきではありません。代わりに IDirectDraw7::RestoreDisplayMode メソッドを使用して後処理でモードを復元してください。これにより、マルチプロセス環境で発生しうるモード設定の競合を回避できます。

vtbl 13 HRESULT GetFourCCCodes(DWORD* param0, DWORD* param1)

DirectDraw オブジェクトがサポートする 4 文字コード (FOURCC) を取得します。このメソッドは、サポートされているコードの数を取得することもできます。

param0	DWORD*	inout	サポートするFourCCコード数を入出力するポインタである。
param1	DWORD*	inout	FourCCコードを格納する配列へのポインタである。NULLで個数のみ取得する。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

vtbl 14 HRESULT GetGDISurface(IDirectDrawSurface7** param0)

GDI がプライマリサーフェスとして扱っているサーフェスメモリを現在表している DirectDrawSurface オブジェクトを取得します。

param0

IDirectDrawSurface7**

out

現在GDIが描画対象とするプライマリサーフェスを受け取る出力ポインタである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

vtbl 15 HRESULT GetMonitorFrequency(DWORD* param0)

DirectDraw オブジェクトが制御するモニターの周波数を取得します。

param0

DWORD*

inout

現在のモニタのリフレッシュ周波数(Hz)を受け取る出力ポインタである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

vtbl 16 HRESULT GetScanLine(DWORD* param0)

現在モニター上に描画されているスキャンラインを取得します。

param0

DWORD*

inout

現在描画中のスキャンライン番号を受け取る出力ポインタである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS

解説(Remarks)

スキャンラインは 0 から始まる整数として報告されます。返されるスキャンライン値は 0 から n までの範囲で、0 は画面上の最初の可視スキャンライン、n は最後の可視スキャンラインに垂直帰線期間中に発生するスキャンラインを加えたものです。したがって、アプリケーションが 640×480 の解像度で動作し、vblank 中に 12 本のスキャンラインがある場合、このメソッドが返す値の範囲は 0 から 491 になります。

vtbl 17 HRESULT GetVerticalBlankStatus(BOOL* param0)

垂直帰線の状態を取得します。

param0

BOOL*

inout

垂直帰線期間中かどうか(TRUE/FALSE)を受け取る出力ポインタである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

垂直帰線と同期するには、IDirectDraw7::WaitForVerticalBlank メソッドを使用します。

vtbl 18 HRESULT Initialize(GUID* param0)

CoCreateInstance COM 関数を使用して作成された DirectDraw オブジェクトを初期化します。

param0

GUID*

inout

初期化対象ドライバのGUIDへのポインタである。NULLで既定ドライバを使う。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_ALREADYINITIALIZED
DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_NODIRECTDRAWSUPPORT
DDERR_OUTOFMEMORY

このメソッドは、コンポーネントオブジェクトモデル (COM) への準拠のために用意されています。すでに DirectDrawCreate 関数を使用して DirectDraw オブジェクトを作成している場合、このメソッドは DDERR_ALREADYINITIALIZED を返します。CoCreateInstance を使用して DirectDraw オブジェクトを作成する際に IDirectDraw7::Initialize を呼び出さないと、その後に呼び出すいずれのメソッドも DDERR_NOTINITIALIZED を返します。

vtbl 19 HRESULT RestoreDisplayMode()

プライマリサーフェスのディスプレイデバイスハードウェアのモードを、IDirectDraw7::SetDisplayMode メソッドが呼び出される前の状態にリセットします。このメソッドを使用するには排他レベルのアクセスが必要です。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE

vtbl 20 HRESULT SetCooperativeLevel(HWND param0, DWORD param1)

アプリケーションのトップレベルの動作を決定します。

param0	HWND	in	協調レベルを関連付ける対象ウィンドウのハンドルである。
param1	DWORD	in	全画面排他や通常などの協調レベルを示すDDSCL_系フラグである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_EXCLUSIVEMODEALREADYSET
DDERR_HWNDALREADYSET
DDERR_HWNDSUBCLASSED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

解説(Remarks)

このメソッドは、アプリケーションウィンドウを作成したのと同じスレッドから呼び出す必要があります。

アプリケーションは DDSCL_EXCLUSIVE フラグまたは DDSCL_NORMAL フラグのいずれかを設定する必要があります。

他のアプリケーションのパフォーマンスに悪影響を及ぼす可能性のある関数を呼び出すには、DDSCL_EXCLUSIVE フラグを設定する必要があります。

このメソッドと IDirectDraw7::SetDisplayMode メソッドとの相互作用は、それらの IDirectDraw 版とは異なります。

Microsoft Foundation Classes (MFC) を使用する場合、このメソッドに渡すウィンドウハンドルは、派生した子ウィンドウではなく、アプリケーションのトップレベルウィンドウを識別するものでなければなりません。MFC アプリケーションのトップレベルウィンドウハンドルを取得するには、次のコードを使用できます。


HWND hwndTop = AfxGetMainWnd()->GetSafeHwnd();

vtbl 21 HRESULT SetDisplayMode(DWORD param0, DWORD param1, DWORD param2, DWORD param3, DWORD param4)

ディスプレイデバイスハードウェアのモードを設定します。

param0	DWORD	in	設定する表示モードの幅(ピクセル)である。
param1	DWORD	in	設定する表示モードの高さ(ピクセル)である。
param2	DWORD	in	設定する表示モードの色深度(ビット/ピクセル)である。
param3	DWORD	in	リフレッシュレート(Hz)である。0でドライバ既定値を使う。
param4	DWORD	in	モード設定の追加オプションを示すフラグ(DDSDM_系)である。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_GENERIC
DDERR_INVALIDMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

解説(Remarks)

このメソッドは、アプリケーションウィンドウを作成したのと同じスレッドから呼び出す必要があります。

別のアプリケーションが表示モードを変更すると、プライマリサーフェスは失われ、新しい表示モードに合わせてプライマリサーフェスが再作成されるまで、このメソッドは DDERR_SURFACELOST を返します。

以前のバージョンの IDirectDraw インターフェイスでは、このメソッドに dwRefreshRate パラメーターと dwFlags パラメーターは含まれていませんでした。

vtbl 22 HRESULT WaitForVerticalBlank(DWORD param0, HANDLE param1)

アプリケーションが垂直帰線期間と同期するのを支援します。

param0	DWORD	in	待機方法を指定するフラグ(DDWAITVB_系)である。
param1	HANDLE	in	イベント通知方式で用いるイベントハンドルである。NULL可。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

vtbl 23 HRESULT GetAvailableVidMem(DDSCAPS2* param0, DWORD* param1, DWORD* param2)

利用可能な表示メモリの総量と、指定した種類のサーフェスに対して現在空いている表示メモリの量を取得します。

param0	DDSCAPS2*	inout	対象とするメモリ種別を示すDDSCAPS2構造体へのポインタである。
param1	DWORD*	inout	利用可能なビデオメモリの総容量(バイト)を受け取る出力ポインタである。NULL可。
param2	DWORD*	inout	現在空いているビデオメモリ容量(バイト)を受け取る出力ポインタである。NULL可。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

解説(Remarks)

次の C++ の例は、GetAvailableVidMem を使用して、テクスチャマップサーフェスに利用可能な表示メモリの総量と空き容量の両方を求める方法を示しています。

// この例では、lpDD 変数は IDirectDraw7 インターフェイスへの
// 有効なポインターです。
LPDIRECTDRAW7 lpDD;
DDSCAPS2      ddsCaps2; 
DWORD         dwTotal; 
DWORD         dwFree;
HRESULT       hr; 
 
hr = lpDD->QueryInterface(IID_IDirectDraw7, &lpDD); 
if (FAILED(hr))
    return hr; 
 
// 構造体を初期化します。
ZeroMemory(&ddsCaps2, sizeof(ddsCaps2));
 
ddsCaps2.dwCaps = DDSCAPS_TEXTURE; 
hr = lpDD->GetAvailableVidMem(&ddsCaps2, &dwTotal, &dwFree); 
if (FAILED(hr))
    return hr;

サーフェスに DDSCAPS_VIDEOMEMORY フラグが設定されている場合、GetAvailableVidMem は、そのサーフェスを 3-D テクスチャとして使用できるかどうかに応じて異なる量のビデオメモリを返します。サーフェスを 3-D テクスチャに使用できる場合、GetAvailableVidMem は AGP システムにおけるローカルビデオメモリと非ローカルビデオメモリの合計を返します。

GetAvailableVidMem は、現在の表示メモリの状態のスナップショットを提供するにすぎません。空いている表示メモリの量は、サーフェスの作成や解放に伴って変化します。したがって、空きメモリ値は目安としてのみ使用してください。さらに、特定のディスプレイアダプターカードは、2 つの異なるメモリ種別を区別しない場合があります。たとえば、アダプターが z-buffer とテクスチャの格納に表示メモリの同じ部分を使用することがあります。そのため、ある種類のサーフェス (たとえば z-buffer) を割り当てると、別の種類のサーフェス (テクスチャ) に利用可能な表示メモリの量に影響することがあります。したがって、動的な用途 (テクスチャマッピングなど) に利用可能なメモリ量を判断する前に、アプリケーションの固定リソース (フロントバッファーやバックバッファー、z-buffer など) を先に割り当てるのが最善です。

GetAvailableVidMem は、以前のバージョンの DirectX IDirectDraw インターフェイスでは実装されていませんでした。

vtbl 24 HRESULT GetSurfaceFromDC(HDC param0, IDirectDrawSurface7** param1)

GDI デバイスコンテキストハンドルに基づいて、サーフェスの IDirectDrawSurface7 インターフェイスを取得します。

param0	HDC	in	対応するサーフェスを検索する元となるデバイスコンテキスト(HDC)である。
param1	IDirectDrawSurface7**	out	HDCに対応するサーフェスを受け取る出力ポインタである。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_NOTFOUND

解説(Remarks)

このメソッドは、すでに DirectDraw オブジェクトに関連付けられているサーフェスを識別するデバイスコンテキストハンドルに対してのみ成功します。

vtbl 25 HRESULT RestoreAllSurfaces()

DirectDraw オブジェクトに対して作成されたすべてのサーフェスを、作成された順に復元します。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

このメソッドは利便性のために用意されています。実質的には、この DirectDraw オブジェクトによって作成された各サーフェスに対して IDirectDrawSurface7::Restore メソッドを呼び出します。

vtbl 26 HRESULT TestCooperativeLevel()

ウィンドウモードまたはフルスクリーンのアプリケーションについて、DirectDraw デバイスの現在の協調レベルの状態を報告します。

戻り値

メソッドが成功した場合、戻り値は DD_OK であり、呼び出し側アプリケーションが処理を続行できることを示します。

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります (「解説」を参照)。

DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET
DDERR_NOEXCLUSIVEMODE
DDERR_WRONGMODE

解説(Remarks)

このメソッドは、WM_ACTIVATEAPP および WM_DISPLAYCHANGE システムメッセージを、サーフェスの復元や DirectDraw オブジェクトの再作成の通知として使用するアプリケーションに特に役立ちます。DD_OK の戻り値は常にアプリケーションが処理を続行できることを示しますが、エラーコードはアプリケーションが使用する協調レベルに応じて異なる解釈がなされます。

vtbl 27 HRESULT GetDeviceIdentifier(DDDEVICEIDENTIFIER2* param0, DWORD param1)

デバイスドライバーに関する情報を取得します。このメソッドは、慎重に使用すれば、不十分なドライバーやチップセットの動作に対する回避策を実装するために特定のハードウェア構成を認識するのに使用できます。

param0	DDDEVICEIDENTIFIER2*	inout	ドライバ/ハードウェアの識別情報を受け取るDDDEVICEIDENTIFIER2構造体へのポインタである。
param1	DWORD	in	識別情報取得の動作を制御するフラグ(DDGDI_系)である。

戻り値

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

失敗した場合、このメソッドは DDERR_INVALIDPARAMS を返すことがあります。

vtbl 28 HRESULT StartModeTest(SIZE* param0, DWORD param1, DWORD param2)

現在のディスプレイアダプターとモニターの組み合わせに関するリフレッシュレート情報でシステムレジストリを更新するテストを開始します。

param0	SIZE*	inout	テストする解像度を列挙したSIZE配列へのポインタである。
param1	DWORD	in	param0配列に含まれる解像度の個数を指定する。
param2	DWORD	in	モードテストの動作を制御するフラグ(DDSMT_系)である。

戻り値

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

失敗した場合、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_CURRENTLYNOTAVAIL
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOTFOUND
DDERR_TESTFINISHED

DDSMT_ISTESTREQUIRED フラグを指定してこのメソッドを呼び出した場合、次のいずれかの値を返すことがあります。

DDERR_NEWMODE
DDERR_NODRIVERSUPPORT
DDERR_NOMONITORINFORMATION
DDERR_TESTFINISHED

解説(Remarks)

StartModeTest メソッドを IDirectDraw7::EvaluateMode メソッドと組み合わせて使用すると、EDID モニターとディスプレイアダプターの組み合わせが各画面解像度でサポートできる最大リフレッシュレートを判断できます。テストの結果はシステムレジストリに保存され、IDirectDraw7::EnumDisplayModes を DDEDM_REFRESHRATES フラグを設定して呼び出したときの動作に影響します。

具体的には、StartModeTest を呼び出すと、DirectDraw はテスト可能な解像度のセットを確立し、そのセットの最初の解像度に基づいてモードを表示します。その後の IDirectDraw7::EvaluateMode の呼び出しにより、各モードの合否を判定し、テストを次の表示モードへ進めることができます。

StartModeTest は、EDID データを含むモニターでのみ成功します。モニターが EDID 準拠でない場合、StartModeTest はモードを一切テストせずに DDERR_TESTFINISHED を返します。EDID テーブルに 60 Hz を超える値が含まれていない場合、モードはテストされません。100 Hz を超えるリフレッシュレートは、EDID テーブルに 85 Hz を超える値が含まれている場合にのみテストされます。

引数リスト (NULL, 0, 0) で StartModeTest を呼び出すと、StartModeTest は既存のリフレッシュレート情報をレジストリから消去します。

このテストは、lpModesToTest パラメーターと dwNumEntries パラメーターで記述された配列内の解像度だけを表示することを保証するものではありません。たとえば、320×200 の解像度の最大表示可能リフレッシュレートを取得するために 640×480 の解像度が使用されます。

vtbl 29 HRESULT EvaluateMode(DWORD param0, DWORD* param1)

IDirectDraw7::StartModeTest の呼び出し後に使用し、テストが提示する各モードの合否を判定して、テストが完了するまでモードを 1 つずつ進めます。

param0	DWORD	in	テスト結果を伝える評価フラグ(DDEM_系)である。
param1	DWORD*	inout	次のテストまでの残り秒数等のタイムアウト値を受け取る出力ポインタである。

戻り値

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

失敗した場合、または完了時に、このメソッドは次のいずれかのエラー値を返すことがあります。

DDERR_TESTFINISHED
DDERR_NEWMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

解説(Remarks)

EvaluateMode を IDirectDraw7::StartModeTest メソッドと組み合わせて使用すると、EDID モニターとディスプレイアダプターの組み合わせが各画面解像度でサポートできる最大リフレッシュレートを判断できます。

具体的には、IDirectDraw7::StartModeTest を呼び出すと、DirectDraw はテスト可能な解像度のセットを確立し、そのセットの最初の解像度に基づいてモードを表示します。その後の EvaluateMode の呼び出しにより、各モードの合否を判定し、テストを次の表示モードへ進めることができます。このメソッドは、指定された解像度でサポートされる最大のリフレッシュレートから始めて、テスト可能な解像度を 1 つずつ進めます。ある解像度でリフレッシュレートが合格すると、その解像度のより低いリフレッシュレートのテストはスキップされます。

テストが開始されたとき、またはモードの合否が判定されるたびに、DirectDraw は 15 秒のタイムアウトを開始します。アプリケーションは、EvaluateMode を dwFlags 引数に 0 を指定して呼び出すことで、現在のモードの合否を判定せずに残り時間を監視できます。DirectDraw がモードを変更したりテストを終了したりするのは、EvaluateMode が呼び出されたときのみである点に注意してください。ただし、タイムアウト期間が経過した後にアプリケーションが EvaluateMode を呼び出した場合は、dwFlags パラメーターに渡した値に関係なく、現在のモードは不合格になります。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数:

#define global IID_IDirectDraw7 "{15E65EC0-3B9C-11D2-B92F-00609797EA5B}"
#usecom global IDirectDraw7 IID_IDirectDraw7 "{3C305196-50DB-11D3-9CFE-00C04FD930C5}"
#comfunc global IDirectDraw7_Compact                 3
#comfunc global IDirectDraw7_CreateClipper           4 int,sptr,sptr
#comfunc global IDirectDraw7_CreatePalette           5 int,var,sptr,sptr
#comfunc global IDirectDraw7_CreateSurface           6 var,sptr,sptr
#comfunc global IDirectDraw7_DuplicateSurface        7 sptr,sptr
#comfunc global IDirectDraw7_EnumDisplayModes        8 int,var,sptr,sptr
#comfunc global IDirectDraw7_EnumSurfaces            9 int,var,sptr,sptr
#comfunc global IDirectDraw7_FlipToGDISurface        10
#comfunc global IDirectDraw7_GetCaps                 11 var,var
#comfunc global IDirectDraw7_GetDisplayMode          12 var
#comfunc global IDirectDraw7_GetFourCCCodes          13 var,var
#comfunc global IDirectDraw7_GetGDISurface           14 sptr
#comfunc global IDirectDraw7_GetMonitorFrequency     15 var
#comfunc global IDirectDraw7_GetScanLine             16 var
#comfunc global IDirectDraw7_GetVerticalBlankStatus  17 var
#comfunc global IDirectDraw7_Initialize              18 var
#comfunc global IDirectDraw7_RestoreDisplayMode      19
#comfunc global IDirectDraw7_SetCooperativeLevel     20 sptr,int
#comfunc global IDirectDraw7_SetDisplayMode          21 int,int,int,int,int
#comfunc global IDirectDraw7_WaitForVerticalBlank    22 int,sptr
#comfunc global IDirectDraw7_GetAvailableVidMem      23 var,var,var
#comfunc global IDirectDraw7_GetSurfaceFromDC        24 sptr,sptr
#comfunc global IDirectDraw7_RestoreAllSurfaces      25
#comfunc global IDirectDraw7_TestCooperativeLevel    26
#comfunc global IDirectDraw7_GetDeviceIdentifier     27 var,int
#comfunc global IDirectDraw7_StartModeTest           28 var,int,int
#comfunc global IDirectDraw7_EvaluateMode            29 int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDirectDraw7 "{15E65EC0-3B9C-11D2-B92F-00609797EA5B}"
#usecom global IDirectDraw7 IID_IDirectDraw7 "{3C305196-50DB-11D3-9CFE-00C04FD930C5}"
#comfunc global IDirectDraw7_Compact                 3
#comfunc global IDirectDraw7_CreateClipper           4 int,sptr,sptr
#comfunc global IDirectDraw7_CreatePalette           5 int,sptr,sptr,sptr
#comfunc global IDirectDraw7_CreateSurface           6 sptr,sptr,sptr
#comfunc global IDirectDraw7_DuplicateSurface        7 sptr,sptr
#comfunc global IDirectDraw7_EnumDisplayModes        8 int,sptr,sptr,sptr
#comfunc global IDirectDraw7_EnumSurfaces            9 int,sptr,sptr,sptr
#comfunc global IDirectDraw7_FlipToGDISurface        10
#comfunc global IDirectDraw7_GetCaps                 11 sptr,sptr
#comfunc global IDirectDraw7_GetDisplayMode          12 sptr
#comfunc global IDirectDraw7_GetFourCCCodes          13 sptr,sptr
#comfunc global IDirectDraw7_GetGDISurface           14 sptr
#comfunc global IDirectDraw7_GetMonitorFrequency     15 sptr
#comfunc global IDirectDraw7_GetScanLine             16 sptr
#comfunc global IDirectDraw7_GetVerticalBlankStatus  17 sptr
#comfunc global IDirectDraw7_Initialize              18 sptr
#comfunc global IDirectDraw7_RestoreDisplayMode      19
#comfunc global IDirectDraw7_SetCooperativeLevel     20 sptr,int
#comfunc global IDirectDraw7_SetDisplayMode          21 int,int,int,int,int
#comfunc global IDirectDraw7_WaitForVerticalBlank    22 int,sptr
#comfunc global IDirectDraw7_GetAvailableVidMem      23 sptr,sptr,sptr
#comfunc global IDirectDraw7_GetSurfaceFromDC        24 sptr,sptr
#comfunc global IDirectDraw7_RestoreAllSurfaces      25
#comfunc global IDirectDraw7_TestCooperativeLevel    26
#comfunc global IDirectDraw7_GetDeviceIdentifier     27 sptr,int
#comfunc global IDirectDraw7_StartModeTest           28 sptr,int,int
#comfunc global IDirectDraw7_EvaluateMode            29 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。