ホーム › Graphics.DirectDraw › IDirectDrawSurface7

IDirectDrawSurface7

COM

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

公式ドキュメント

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

解説(Remarks)

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

グループ	メソッド
メモリの割り当て	Initialize, IsLost, および Restore
サーフェスのアタッチ	AddAttachedSurface, DeleteAttachedSurface, EnumAttachedSurfaces, および GetAttachedSurface
ビットブロック転送 (BitBlt)	Blt, BltBatch, BltFast, および GetBltStatus
カラーキー	GetColorKey および SetColorKey
デバイスコンテキスト	GetDC および ReleaseDC
フリップ	Flip および GetFlipStatus
サーフェスのロック	Lock, PageLock, PageUnlock, および Unlock
その他	GetDDInterface
オーバーレイ	AddOverlayDirtyRect, EnumOverlayZOrders, GetOverlayPosition, SetOverlayPosition, UpdateOverlay, UpdateOverlayDisplay, および UpdateOverlayZOrder
サーフェスのプライベートデータ	FreePrivateData, GetPrivateData, および SetPrivateData
サーフェスの機能	GetCaps
サーフェスのクリッパー	GetClipper および SetClipper
サーフェスの特性	ChangeUniquenessValue, GetPixelFormat, GetSurfaceDesc, GetUniquenessValue, および SetSurfaceDesc
サーフェスのパレット	GetPalette および SetPalette
テクスチャ	GetLOD, GetPriority, SetLOD, および SetPriority

IDirectDrawSurface7 インターフェイスは、より優れたサーフェス管理と使いやすさを実現するメソッドを提供することで、以前のバージョンのインターフェイスの機能を拡張します。このインターフェイスの多くのメソッドは、以前のバージョンのインターフェイスの対応するメソッドとは若干異なるパラメーターを受け取ります。IDirectDrawSurface3 インターフェイスのメソッドが DDSURFACEDESC 構造体や IDirectDrawSurface3 インターフェイスを受け取る箇所では、IDirectDrawSurface7 のメソッドは代わりに DDSURFACEDESC2 構造体や IDirectDrawSurface7 インターフェイスを受け取ります。

LPDIRECTDRAWSURFACE、LPDIRECTDRAWSURFACE2、LPDIRECTDRAWSURFACE3、LPDIRECTDRAWSURFACE4、または LPDIRECTDRAWSURFACE7 データ型を使用して、さまざまな DirectDrawSurface オブジェクトインターフェイスを指す変数を宣言します。Ddraw.h ヘッダーファイルは、次のコードでこれらのデータ型を宣言します。


typedef struct IDirectDrawSurface     FAR *LPDIRECTDRAWSURFACE;
typedef struct IDirectDrawSurface2    FAR *LPDIRECTDRAWSURFACE2;
typedef struct IDirectDrawSurface3    FAR *LPDIRECTDRAWSURFACE3;
typedef struct IDirectDrawSurface4    FAR *LPDIRECTDRAWSURFACE4;
typedef struct IDirectDrawSurface7    FAR *LPDIRECTDRAWSURFACE7;

メソッド 46

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

vtbl 3 HRESULT AddAttachedSurface(IDirectDrawSurface7* param0)

指定した z バッファーサーフェスをこのサーフェスにアタッチします。

param0

IDirectDrawSurface7*

このサーフェスにアタッチする対象サーフェスのインターフェイスポインタを指定する。

戻り値

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

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

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

解説(Remarks)

AddAttachedSurface は、アタッチされるサーフェスの参照カウントをインクリメントします。IDirectDrawSurface7::DeleteAttachedSurface メソッドを使用すると、明示的にサーフェスのアタッチを解除して参照カウントをデクリメントできます。IDirectDraw7::CreateSurface の 1 回の呼び出しで作成する複合サーフェスとは異なり、このメソッドでアタッチしたサーフェスは自動的には解放されません。アプリケーションがそのようなサーフェスを解放する必要があります。

このメソッドでアタッチできるのは z バッファーサーフェスのみです。

vtbl 4 HRESULT AddOverlayDirtyRect(RECT* param0)

IDirectDrawSurface7::AddOverlayDirtyRect メソッドは現在実装されていません。

param0

RECT*

inout

次のオーバーレイ更新で再描画すべき汚れ矩形領域を指すRECTポインタを指定する。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_UNSUPPORTED

vtbl 5 HRESULT Blt(RECT* param0, IDirectDrawSurface7* param1, RECT* param2, DWORD param3, DDBLTFX* param4)

ビットブロック転送 (bitblt) を実行します。このメソッドは、ビットブロック転送操作中の z バッファリングやアルファブレンディングをサポートしません。

param0	RECT*	inout	転送先サーフェス上の矩形を指すRECTポインタ。NULLでサーフェス全体を対象とする。
param1	IDirectDrawSurface7*	in	転送元サーフェスのインターフェイスポインタ。塗りつぶし等では NULL 可。
param2	RECT*	inout	転送元サーフェス上の矩形を指すRECTポインタ。NULLで元全体を対象とする。
param3	DWORD	in	ブリット動作を制御する DDBLT_ 系フラグの組み合わせを指定する。
param4	DDBLTFX*	inout	カラーキーやエフェクト等の詳細を格納する DDBLTFX 構造体ポインタ。不要時は NULL 可。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

解説(Remarks)

Blt は、同期または非同期のビットブロック転送を実行できます (後者が既定の動作です)。これらのビットブロック転送は、ディスプレイメモリからディスプレイメモリへ、ディスプレイメモリからシステムメモリへ、システムメモリからディスプレイメモリへ、またはシステムメモリからシステムメモリへ行うことができます。ビットブロック転送では、ソースカラーキーおよびデスティネーションカラーキーを使用できます。ソース矩形とデスティネーション矩形のサイズが異なる場合は、任意の拡大または縮小が行われます。

通常、ビットブロック転送機能がビジー状態でビットブロック転送を設定できない場合、Blt は直ちにエラーを返します。同期ビットブロック転送を要求するには、DDBLT_WAIT フラグを指定します。DDBLT_WAIT フラグを含めると、Blt はビットブロック転送を設定できるようになるか、または別のエラーが発生するまで待機してから戻ります。

RECT 構造体は、right メンバーと bottom メンバーが排他的となるように定義されています。したがって、right から left を引いた値は矩形の幅と等しく、幅より 1 小さい値ではありません。

vtbl 6 HRESULT BltBatch(DDBLTBATCH* param0, DWORD param1, DWORD param2)

IDirectDrawSurface7::BltBatch メソッドは現在実装されていません。

param0	DDBLTBATCH*	inout	一括実行する複数ブリット操作を記述した DDBLTBATCH 構造体配列の先頭ポインタ。
param1	DWORD	in	配列に含まれるブリット操作の件数を指定する。
param2	DWORD	in	予約済みで現状は0を指定するフラグ値。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOALPHAHW
DDERR_NOBLTHW
DDERR_NOCLIPLIST
DDERR_NODDROPSHW
DDERR_NOMIRRORHW
DDERR_NORASTEROPHW
DDERR_NOROTATIONHW
DDERR_NOSTRETCHHW
DDERR_NOZBUFFERHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

vtbl 7 HRESULT BltFast(DWORD param0, DWORD param1, IDirectDrawSurface7* param2, RECT* param3, DWORD param4)

ソースカラーキーまたはデスティネーションカラーキーを使用して、ソースコピーのビットブロック転送または透過ビットブロック転送を実行します。

param0	DWORD	in	転送先サーフェス上の左上X座標(ピクセル単位)を指定する。
param1	DWORD	in	転送先サーフェス上の左上Y座標(ピクセル単位)を指定する。
param2	IDirectDrawSurface7*	in	転送元サーフェスのインターフェイスポインタを指定する。
param3	RECT*	inout	転送元サーフェス上の矩形を指すRECTポインタ。NULLで元全体を対象とする。
param4	DWORD	in	DDBLTFAST_ 系の転送フラグ(カラーキー有無や待機指定等)を指定する。

戻り値

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

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

DDERR_EXCEPTION
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

解説(Remarks)

BltFast は、ハードウェアがサポートしている場合は常に非同期ブリット(転送)を試みます。

BltFast はディスプレイメモリサーフェスに対してのみ動作し、ビットブロック転送操作の実行時にクリッピングを行うことはできません。クリッパーがアタッチされたサーフェスに対してこのメソッドを使用すると、呼び出しは失敗し、メソッドは DDERR_UNSUPPORTED を返します。

IDirectDrawSurface7::BltFast のソフトウェア実装は、IDirectDrawSurface7::Blt メソッドより 10 パーセント高速です。ただし、ディスプレイハードウェアを使用する場合、両者の間に速度差はありません。

通常、ビットブロック転送機能がビジー状態でビットブロック転送を設定できない場合、IDirectDrawSurface7::BltFast は直ちにエラーを返します。ただし、ビットブロック転送を設定できるようになるか別のエラーが発生するまでこのメソッドを戻らせたくない場合は、DDBLTFAST_WAIT フラグを使用できます。

vtbl 8 HRESULT DeleteAttachedSurface(DWORD param0, IDirectDrawSurface7* param1)

1 つ以上のアタッチされたサーフェスを取り外します。

param0	DWORD	in	予約済みで0を指定するフラグ値。
param1	IDirectDrawSurface7*	in	このサーフェスからデタッチする対象サーフェスのインターフェイスポインタ。

戻り値

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

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

DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_SURFACENOTATTACHED

解説(Remarks)

DeleteAttachedSurface は、取り外すサーフェスの参照カウントをデクリメントします。取り外すサーフェスの参照カウントが 0 に達すると、そのサーフェスは失われてメモリから削除されます。

IDirectDrawSurface7::AddAttachedSurface メソッドではなく DirectDraw によって形成された暗黙的なアタッチは、取り外すことができません。フリップチェーンからサーフェスを取り外すと、チェーン内の他のサーフェスに影響する場合があります。フロントバッファーがフリップチェーンから取り外されると、チェーン内の次のサーフェスがフロントバッファーになり、そのさらに次のサーフェスがバックバッファーになります。バックバッファーがチェーンから取り外されると、その次のサーフェスがバックバッファーになります。通常のサーフェスがチェーンから取り外されると、チェーンは単に短くなります。フリップチェーンにサーフェスが 2 つしかなく、それらが取り外されると、チェーンは破棄され、両方のサーフェスは以前の指定に戻ります。

vtbl 9 HRESULT EnumAttachedSurfaces(void* param0, LPDDENUMSURFACESCALLBACK7 param1)

このサーフェスにアタッチされているすべてのサーフェスを列挙します。

param0	void*	inout	コールバックへそのまま渡されるアプリ定義のコンテキストポインタ。NULL 可。
param1	LPDDENUMSURFACESCALLBACK7	in	アタッチされた各サーフェスごとに呼ばれる列挙コールバック7関数ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

解説(Remarks)

EnumAttachedSurfaces は、このサーフェスに直接アタッチされているサーフェスのみを列挙します。たとえば、3 つ以上のサーフェスから成るフリップチェーンでは、各サーフェスはフリップチェーン内の次のサーフェスにのみアタッチされているため、列挙されるサーフェスは 1 つだけです。このような構成では、後続の各サーフェスに対して EnumAttachedSurfaces を呼び出すことで、フリップチェーン全体をたどることができます。

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

vtbl 10 HRESULT EnumOverlayZOrders(DWORD param0, void* param1, LPDDENUMSURFACESCALLBACK7 param2)

指定したデスティネーション上のオーバーレイサーフェスを列挙します。オーバーレイは、前面から背面、または背面から前面の順に列挙できます。

param0	DWORD	in	列挙方向を指定する DDENUMOVERLAYZ_ 系フラグ(前面から/背面から)。
param1	void*	inout	コールバックへそのまま渡されるアプリ定義のコンテキストポインタ。NULL 可。
param2	LPDDENUMSURFACESCALLBACK7	in	Zオーダー順に各オーバーレイで呼ばれる列挙コールバック7関数ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

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

vtbl 11 HRESULT Flip(IDirectDrawSurface7* param0, DWORD param1)

DDSCAPS_BACKBUFFER サーフェスに関連付けられているサーフェスメモリを、フロントバッファーサーフェスに関連付けます。

param0	IDirectDrawSurface7*	in	フリップ先として明示するサーフェスのポインタ。通常はNULLで自動選択する。
param1	DWORD	in	DDFLIP_ 系フラグ(垂直帰線待ち等)を指定する。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

解説(Remarks)

IDirectDrawSurface7 では、Flip の既定の動作はアクセラレータの処理完了を待機することです。したがって、既定の条件下では Flip が DDERR_WASSTILLDRAWING を返すことはありません。エラーコードを確認し、フリップ操作が成功するまで待機したくない場合は、DDFLIP_DONOTWAIT フラグを使用します。

Flip は、DDSCAPS_FLIP および DDSCAPS_FRONTBUFFER の機能を持つサーフェスに対してのみ呼び出せます。フロントバッファーに以前関連付けられていたディスプレイメモリは、バックバッファーに関連付けられます。

lpDDSurfaceTargetOverride パラメーターは、バックバッファーがフロントバッファーになるべきバッファーではない、まれなケースで使用します。通常、このパラメーターは NULL です。

Flip は常に垂直帰線と同期します。サーフェスがビデオポートに割り当てられている場合、このメソッドは表示中のオーバーレイサーフェスとビデオポートのターゲットサーフェスを更新します。

vtbl 12 HRESULT GetAttachedSurface(DDSCAPS2* param0, IDirectDrawSurface7** param1)

指定した機能を持つアタッチされたサーフェスを取得し、取得したインターフェイスの参照カウントをインクリメントします。

param0	DDSCAPS2*	inout	取得対象を絞り込むサーフェス能力を指定する DDSCAPS2 構造体ポインタ。
param1	IDirectDrawSurface7**	out	条件に一致したアタッチサーフェスを受け取る出力ポインタの格納先。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST

解説(Remarks)

アタッチは、複数の DirectDrawSurface オブジェクトを、z バッファーを伴う 3-D ページフリップをサポートするために必要な複合構造などの複雑な構造に接続するために使用されます。要求された機能に一致するサーフェスが複数アタッチされている場合、GetAttachedSurface は失敗します。この場合、アプリケーションは IDirectDrawSurface7::EnumAttachedSurfaces メソッドを使用して、アタッチされたサーフェスを取得する必要があります。

vtbl 13 HRESULT GetBltStatus(DWORD param0)

ビットブロック転送 (bitblt) 操作に関するステータスを取得します。

param0

DWORD

問い合わせ種別を指定する DDGBS_ 系フラグ(完了確認/可否確認)。

戻り値

メソッドが成功し、ビットブロック転送機能 (bitbltter) が存在する場合、戻り値は DD_OK です。

失敗した場合、ビットブロック転送機能がビジー状態であれば DDERR_WASSTILLDRAWING を、ビットブロック転送機能が存在しなければ DDERR_NOBLTHW を、あるいは次のいずれかのエラー値を返します。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

vtbl 14 HRESULT GetCaps(DDSCAPS2* param0)

このサーフェスの機能を取得します。これらの機能は、必ずしもディスプレイデバイスの機能に関連するとは限りません。

param0

DDSCAPS2*

inout

サーフェスの能力情報を受け取る DDSCAPS2 構造体ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

IDirectDrawSurface7::GetCaps メソッドは、IDirectDrawSurface3 インターフェイスの対応するメソッドとは異なり、従来の DDSCAPS 構造体ではなく DDSCAPS2 構造体へのポインターを受け取ります。

vtbl 15 HRESULT GetClipper(IDirectDrawClipper** param0)

このサーフェスに関連付けられている DirectDrawClipper オブジェクトを取得し、返されるクリッパーの参照カウントをインクリメントします。

param0

IDirectDrawClipper**

out

サーフェスに関連付けられたクリッパーを受け取る出力ポインタの格納先。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED

vtbl 16 HRESULT GetColorKey(DWORD param0, DDCOLORKEY* param1)

このサーフェスのカラーキー値を取得します。

param0	DWORD	in	取得するカラーキー種別を指定する DDCKEY_ 系フラグ。
param1	DDCOLORKEY*	inout	カラーキー値を受け取る DDCOLORKEY 構造体ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOLORKEY
DDERR_NOCOLORKEYHW
DDERR_SURFACELOST
DDERR_UNSUPPORTED

vtbl 17 HRESULT GetDC(HDC* param0)

このサーフェス用の、GDI 互換のデバイスコンテキストのハンドルを作成します。

param0

HDC*

inout

サーフェスに対応するGDIデバイスコンテキストハンドルを受け取る出力ポインタ。

戻り値

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

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

DDERR_DCALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

解説(Remarks)

GetDC は、IDirectDrawSurface7::Lock メソッドの内部バージョンを使用してサーフェスをロックします。サーフェスは、IDirectDrawSurface7::ReleaseDC メソッドが呼び出されるまでロックされたままになります。

vtbl 18 HRESULT GetFlipStatus(DWORD param0)

このサーフェスがフリップ処理を完了したかどうかに関するステータスを取得します。

param0

DWORD

問い合わせ種別を指定する DDGFS_ 系フラグ(完了確認/可否確認)。

戻り値

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

失敗した場合、サーフェスがフリップ処理を完了していなければ DDERR_WASSTILLDRAWING を、あるいは次のいずれかのエラー値を返すことがあります。

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

vtbl 19 HRESULT GetOverlayPosition(INT* param0, INT* param1)

このサーフェスの表示座標を取得します。このメソッドは、表示中でアクティブなオーバーレイサーフェス (つまり DDSCAPS_OVERLAY フラグが設定されたサーフェス) に対して使用します。

param0	INT*	inout	オーバーレイの現在の左上X座標を受け取る出力ポインタ。
param1	INT*	inout	オーバーレイの現在の左上Y座標を受け取る出力ポインタ。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST

vtbl 20 HRESULT GetPalette(IDirectDrawPalette** param0)

このサーフェスに関連付けられている DirectDrawPalette オブジェクトを取得し、返されるパレットの参照カウントをインクリメントします。

param0

IDirectDrawPalette**

out

サーフェスに関連付けられたパレットを受け取る出力ポインタの格納先。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED

vtbl 21 HRESULT GetPixelFormat(DDPIXELFORMAT* param0)

このサーフェスの色およびピクセル形式を取得します。

param0

DDPIXELFORMAT*

inout

サーフェスのピクセルフォーマット情報を受け取る DDPIXELFORMAT 構造体ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

vtbl 22 HRESULT GetSurfaceDesc(DDSURFACEDESC2* param0)

現在の状態におけるこのサーフェスの記述を取得します。

param0

DDSURFACEDESC2*

inout

サーフェスの寸法やピクセル形式等の記述を受け取る DDSURFACEDESC2 構造体ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

vtbl 23 HRESULT Initialize(IDirectDraw* param0, DDSURFACEDESC2* param1)

DirectDrawSurface オブジェクトを初期化します。

param0	IDirectDraw*	in	このサーフェスを生成した DirectDraw オブジェクトのインターフェイスポインタ。
param1	DDSURFACEDESC2*	inout	初期化に用いるサーフェス記述を格納した DDSURFACEDESC2 構造体ポインタ。

戻り値

このメソッドは DDERR_ALREADYINITIALIZED を返します。

このメソッドは、コンポーネントオブジェクトモデル (COM) に準拠するために提供されています。DirectDrawSurface オブジェクトは作成時に初期化されるため、このメソッドは常に DDERR_ALREADYINITIALIZED を返します。

vtbl 24 HRESULT IsLost()

DirectDrawSurface オブジェクトに関連付けられているサーフェスメモリが解放されたかどうかを判定します。

戻り値

メモリが解放されていない場合、メソッドは成功し、戻り値は DD_OK です。

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

このメソッドを使用すると、サーフェスメモリを再割り当てする必要があるタイミングを判断できます。DirectDrawSurface オブジェクトがサーフェスメモリを失うと、ほとんどのメソッドは DDERR_SURFACELOST を返し、他の処理を行いません。

解説(Remarks)

サーフェスは、グラフィックスアダプターのモードが変更されたとき、またはアプリケーションがグラフィックスアダプターへの排他アクセスを取得し、グラフィックスアダプター上に現在割り当てられているすべてのサーフェスメモリが解放されたときに、そのメモリを失うことがあります。

vtbl 25 HRESULT Lock(RECT* param0, DDSURFACEDESC2* param1, DWORD param2, HANDLE param3)

サーフェスメモリへのポインターを取得します。

param0	RECT*	inout	ロックするサーフェス上の矩形を指すRECTポインタ。NULLで全体をロックする。
param1	DDSURFACEDESC2*	inout	ロック結果(先頭アドレスやピッチ等)を受け取る DDSURFACEDESC2 構造体ポインタ。
param2	DWORD	in	DDLOCK_ 系フラグ(待機方法や読み書き意図)を指定する。
param3	HANDLE	in	イベント駆動用のハンドル。現状は未使用でNULLを指定する。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

解説(Remarks)

IDirectDrawSurface7 では、Lock の既定の動作はアクセラレータの処理完了を待機することです。したがって、既定の条件下では Lock が DDERR_WASSTILLDRAWING を返すことはありません。エラーコードを確認し、ビットブロック転送操作が成功するまで待機したくない場合は、DDLOCK_DONOTWAIT フラグを使用します。

サーフェスメモリのポインターを取得した後は、対応する IDirectDrawSurface7::Unlock メソッドが呼び出されるまで、サーフェスメモリにアクセスできます。サーフェスのロックが解除されると、サーフェスメモリへのポインターは無効になります。

サーフェスのロックされた領域からのビットブロック転送に、DirectDraw のビットブロック転送関数を呼び出さないでください。呼び出した場合、ビットブロック転送は DDERR_SURFACEBUSY または DDERR_LOCKEDSURFACES を返します。GDI のブリット(転送)関数も、ロックされたビデオメモリサーフェスに対して使用すると、何も通知せずに失敗します。

DDLOCK_NOSYSLOCK フラグを含めない限り、Lock は、IDirectDrawSurface7::Unlock メソッドを呼び出すまで DirectDraw に Win16Mutex (Win16Lock とも呼ばれます) を保持させます。Win16Mutex が保持されている間は、GUI デバッガーは動作できません。

vtbl 26 HRESULT ReleaseDC(HDC param0)

IDirectDrawSurface7::GetDC メソッドを使用して以前に取得したデバイスコンテキストのハンドルを解放します。

param0

HDC

GetDCで取得したデバイスコンテキストハンドルを指定して解放する。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_UNSUPPORTED

解説(Remarks)

ReleaseDC は、IDirectDrawSurface7::GetDC メソッドが呼び出されたときに以前ロックされたサーフェスのロックも解除します。

vtbl 27 HRESULT Restore()

失われたサーフェスを復元します。これは、DirectDrawSurface オブジェクトに関連付けられているサーフェスメモリが解放されたときに発生します。

戻り値

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

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

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

解説(Remarks)

Restore は、サーフェスに割り当てられていたメモリを復元しますが、サーフェスが失われる前に存在していた可能性のあるビットマップは再読み込みしません。

サーフェスは、グラフィックスアダプターのモードが変更されたため、またはアプリケーションがグラフィックスアダプターへの排他アクセスを取得し、アダプター上に現在割り当てられているすべてのサーフェスメモリを解放したために、失われることがあります。DirectDrawSurface オブジェクトがサーフェスメモリを失うと、多くのメソッドは DDERR_SURFACELOST を返し、他の機能を実行しません。IDirectDrawSurface7::Restore メソッドは、サーフェスメモリを再割り当てし、それを DirectDrawSurface オブジェクトに再アタッチします。

Restore を 1 回呼び出すと、DirectDrawSurface オブジェクトに関連付けられた暗黙的なサーフェス (バックバッファーなど) が復元されます。暗黙的に作成されたサーフェスを復元しようとすると、エラーになります。Restore は、IDirectDrawSurface7::AddAttachedSurface メソッドを使用して作成された明示的なアタッチをまたいでは機能しません。これらのサーフェスはそれぞれ個別に復元する必要があります。

vtbl 28 HRESULT SetClipper(IDirectDrawClipper* param0)

クリッパーオブジェクトをこのサーフェスにアタッチするか、またはこのサーフェスから削除します。

param0

IDirectDrawClipper*

サーフェスに関連付けるクリッパーのポインタ。NULLで関連付けを解除する。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOCLIPPERATTACHED

解説(Remarks)

クリッパーをサーフェスに初めて設定するとき、SetClipper はクリッパーの参照カウントをインクリメントします。それ以降の呼び出しは、クリッパーの参照カウントに影響しません。lpDDClipper パラメーターに NULL を渡すと、クリッパーはサーフェスから削除され、クリッパーの参照カウントがデクリメントされます。クリッパーを削除しない場合、サーフェス自体が解放されると、サーフェスはクリッパーへの参照を自動的に解放します。COM の規則に従い、アプリケーションは、オブジェクトが不要になったときにクリッパーに対して保持しているすべての参照を解放する必要があります。

SetClipper は主に、プライマリサーフェスにオーバーレイまたはビットブロック転送されるサーフェスで使用されます。ただし、任意のサーフェスで使用できます。DirectDrawClipper オブジェクトがアタッチされ、それにクリップリストが関連付けられると、DirectDrawClipper オブジェクトは、親の DirectDrawSurface オブジェクトが関与する IDirectDrawSurface7::Blt、IDirectDrawSurface7::BltBatch、IDirectDrawSurface7::UpdateOverlay の各操作で使用されます。SetClipper は、DirectDrawSurface オブジェクトの現在の DirectDrawClipper オブジェクトを取り外すこともできます。

vtbl 29 HRESULT SetColorKey(DWORD param0, DDCOLORKEY* param1)

ハードウェアがサーフェス単位のカラーキーをサポートしている場合に、DirectDrawSurface オブジェクトのカラーキー値を設定します。

param0	DWORD	in	設定するカラーキー種別を指定する DDCKEY_ 系フラグ。
param1	DDCOLORKEY*	inout	設定するカラーキー値を格納した DDCOLORKEY 構造体ポインタ。NULLで無効化する。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW
DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

解説(Remarks)

透過ビットブロック転送操作およびオーバーレイでは、デスティネーションサーフェスにデスティネーションカラーを設定し、ソースサーフェスにソースカラーを設定します。

vtbl 30 HRESULT SetOverlayPosition(INT param0, INT param1)

オーバーレイサーフェスの表示座標を変更します。

param0	INT	in	オーバーレイを表示する左上X座標(ピクセル単位)を指定する。
param1	INT	in	オーバーレイを表示する左上Y座標(ピクセル単位)を指定する。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPOSITION
DDERR_NOOVERLAYDEST
DDERR_NOTAOVERLAYSURFACE
DDERR_OVERLAYNOTVISIBLE
DDERR_SURFACELOST
DDERR_UNSUPPORTED

vtbl 31 HRESULT SetPalette(IDirectDrawPalette* param0)

パレットオブジェクトをサーフェスにアタッチします (またはサーフェスから取り外します)。サーフェスは、以降のすべての操作でこのパレットを使用します。パレットの変更は、リフレッシュのタイミングに関係なく直ちに反映されます。

param0

IDirectDrawPalette*

サーフェスに関連付けるパレットのポインタ。NULLで関連付けを解除する。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDSURFACETYPE
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_NOPALETTEHW
DDERR_NOT8BITCOLOR
DDERR_SURFACELOST
DDERR_UNSUPPORTED

解説(Remarks)

SetPalette を呼び出してパレットをサーフェスに初めて設定するとき、SetPalette はパレットの参照カウントをインクリメントします。それ以降の SetPalette の呼び出しは、パレットの参照カウントに影響しません。lpDDPalette パラメーターに NULL を渡すと、パレットはサーフェスから削除され、パレットの参照カウントがデクリメントされます。パレットを削除しない場合、サーフェス自体が解放されると、サーフェスはパレットへの参照を自動的に解放します。COM の規則に従い、アプリケーションは、オブジェクトが不要になったときにパレットに対して保持しているすべての参照を解放する必要があります。

vtbl 32 HRESULT Unlock(RECT* param0)

直接的なサーフェス操作が完了したことを DirectDraw に通知します。

param0

RECT*

inout

ロック解除する矩形を指すRECTポインタ。NULLでサーフェス全体を解除する。

戻り値

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOTLOCKED
DDERR_SURFACELOST

解説(Remarks)

同じサーフェスに対して異なるデスティネーション矩形を指定して IDirectDrawSurface7::Lock を複数回呼び出せるため、lpRect のポインターは IDirectDrawSurface7::Lock メソッドの呼び出しと IDirectDrawSurface7::Unlock メソッドの呼び出しを関連付けます。

vtbl 33 HRESULT UpdateOverlay(RECT* param0, IDirectDrawSurface7* param1, RECT* param2, DWORD param3, DDOVERLAYFX* param4)

オーバーレイサーフェスの位置を変更したり、視覚的な属性を変更したりします。これらのサーフェスには DDSCAPS_OVERLAY フラグが設定されている必要があります。

param0	RECT*	inout	転送元サーフェス上のオーバーレイ矩形を指すRECTポインタ。NULL可。
param1	IDirectDrawSurface7*	in	オーバーレイの転送先サーフェスのポインタ。NULLで非表示にする。
param2	RECT*	inout	転送先サーフェス上の表示矩形を指すRECTポインタ。NULL可。
param3	DWORD	in	DDOVER_ 系フラグ(表示/非表示やカラーキー指定)を指定する。
param4	DDOVERLAYFX*	inout	オーバーレイ効果の詳細を格納する DDOVERLAYFX 構造体ポインタ。不要時はNULL可。

戻り値

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

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

DDERR_DEVICEDOESNTOWNSURFACE
DDERR_GENERIC
DDERR_HEIGHTALIGN
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_INVALIDSURFACETYPE
DDERR_NOSTRETCHHW
DDERR_NOTAOVERLAYSURFACE
DDERR_OUTOFCAPS
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_XALIGN

vtbl 34 HRESULT UpdateOverlayDisplay(DWORD param0)

IDirectDrawSurface7::UpdateOverlayDisplay メソッドは現在実装されていません。

param0

DWORD

オーバーレイ表示を再描画する範囲を指定する DDOVER_REFRESH 系フラグ。

戻り値

このメソッドは現在実装されていません。

vtbl 35 HRESULT UpdateOverlayZOrder(DWORD param0, IDirectDrawSurface7* param1)

オーバーレイの z オーダーを設定します。

param0	DWORD	in	Zオーダー上の挿入位置を指定する DDOVERZ_ 系フラグ。
param1	IDirectDrawSurface7*	in	Zオーダーの基準となる参照サーフェスのポインタ。先頭/末尾指定時はNULL可。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE

vtbl 36 HRESULT GetDDInterface(void** param0)

このサーフェスの作成に使用された DirectDraw オブジェクトへのインターフェイスを取得します。

param0

void**

inout

このサーフェスを生成した DirectDraw オブジェクトを受け取る出力ポインタの格納先。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

vtbl 37 HRESULT PageLock(DWORD param0)

システムメモリへの、またはシステムメモリからのダイレクトメモリアクセス (DMA) 転送を使用するビットブロック転送 (bitblt) 操作の進行中に、システムメモリサーフェスがページアウトされるのを防ぎます。

param0

DWORD

予約済みで0を指定するフラグ値。サーフェスメモリのページングを禁止する。

戻り値

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

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

DDERR_CANTPAGELOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

解説(Remarks)

DMA サポートを利用するには、PageLock を呼び出す必要があります。呼び出さない場合、ビットブロック転送はソフトウェアエミュレーションによって行われます。

ロックされるメモリが多すぎると、オペレーティングシステムのパフォーマンスに悪影響を及ぼす可能性があります。

各サーフェスにはロックカウントが保持されており、そのサーフェスに対して PageLock が呼び出されるたびにインクリメントされます。カウントは IDirectDrawSurface7::PageUnlock が呼び出されるとデクリメントされます。カウントが 0 に達すると、メモリのロックが解除され、オペレーティングシステムによってページングできるようになります。

PageLock はシステムメモリサーフェスに対してのみ動作します。ディスプレイメモリサーフェスやエミュレートされたプライマリサーフェスをページロックすることはありません。アプリケーションがディスプレイメモリサーフェスに対して PageLock を呼び出した場合、このメソッドは DD_OK を返す以外は何も行いません。

IDirectDrawSurface7::PageLock は、IDirectDraw インターフェイスのバージョンでは実装されていませんでした。

vtbl 38 HRESULT PageUnlock(DWORD param0)

システムメモリサーフェスのロックを解除し、ページアウトを可能にします。

param0

DWORD

予約済みで0を指定するフラグ値。PageLockによるページング禁止を解除する。

戻り値

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

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

DDERR_CANTPAGEUNLOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPAGELOCKED
DDERR_SURFACELOST

解説(Remarks)

各サーフェスにはロックカウントが保持されており、そのサーフェスに対して IDirectDrawSurface7::PageLock が呼び出されるたびにインクリメントされます。カウントは PageUnlock が呼び出されるとデクリメントされます。カウントが 0 に達すると、メモリのロックが解除され、オペレーティングシステムによってページングできるようになります。

PageUnlock はシステムメモリサーフェスに対してのみ動作します。ディスプレイメモリサーフェスやエミュレートされたプライマリサーフェスをページアンロックすることはありません。アプリケーションがディスプレイメモリサーフェスに対して PageUnlock を呼び出した場合、このメソッドは DD_OK を返す以外は何も行いません。

IDirectDrawSurface7::PageUnlock は、IDirectDraw インターフェイスのバージョンでは実装されていませんでした。

vtbl 39 HRESULT SetSurfaceDesc(DDSURFACEDESC2* param0, DWORD param1)

既存のサーフェスの特性を設定します。

param0	DDSURFACEDESC2*	inout	差し替えるサーフェス記述(主にメモリポインタ)を格納した DDSURFACEDESC2 構造体ポインタ。
param1	DWORD	in	予約済みで0を指定するフラグ値。

戻り値

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

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

DDERR_INVALIDPARAMS
DDERR_INVALIDOBJECT
DDERR_SURFACELOST
DDERR_SURFACEBUSY
DDERR_INVALIDSURFACETYPE
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDCAPS
DDERR_UNSUPPORTED
DDERR_GENERIC

解説(Remarks)

現在、SetSurfaceDesc を使用して設定できるのは、明示的なシステムメモリサーフェスが使用するサーフェスデータとピクセル形式のみです。これは、以前に割り当てられたバッファーのデータを、コピーせずにサーフェスで使用できるため便利です。新しいサーフェスメモリはクライアントアプリケーションによって割り当てられるため、クライアントアプリケーションがそれを解放する必要もあります。

DirectDrawSurface オブジェクトは、自身が割り当てなかったサーフェスメモリを解放しません。したがって、サーフェスメモリが不要になったときは、それを解放する必要があります。ただし、SetSurfaceDesc を呼び出すと、DirectDraw は、サーフェスの作成時に暗黙的に割り当てた元のサーフェスメモリを解放します。

vtbl 40 HRESULT SetPrivateData(GUID* param0, void* param1, DWORD param2, DWORD param3)

DirectDraw ではなくアプリケーションによる使用を目的としたデータを、サーフェスに関連付けます。データは値渡しされ、1 つのサーフェスに複数のデータセットを関連付けることができます。

param0	GUID*	in	格納するプライベートデータを識別するGUIDを指すポインタ。
param1	void*	inout	サーフェスに関連付けて保存するデータバッファの先頭ポインタ。
param2	DWORD	in	保存するデータのバイトサイズを指定する。
param3	DWORD	in	データ管理方法を示す DDSPD_ 系フラグ(IUnknown格納や揮発性等)。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

解説(Remarks)

DirectDraw は lpData のメモリを管理しません。このバッファーが動的に割り当てられた場合、呼び出し元がメモリを解放する必要があります。

vtbl 41 HRESULT GetPrivateData(GUID* param0, void* param1, DWORD* param2)

このサーフェスに関連付けられているプライベートデータを、指定したバッファーにコピーします。

param0	GUID*	in	取得するプライベートデータを識別するGUIDを指すポインタ。
param1	void*	inout	取得データを受け取るバッファの先頭ポインタ。NULLでサイズ問い合わせのみ行う。
param2	DWORD*	inout	入力でバッファサイズ、出力で実データサイズを受け渡すDWORDポインタ。

戻り値

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

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

DDERR_EXPIRED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA
DDERR_NOTFOUND
DDERR_OUTOFMEMORY

解説(Remarks)

返されるデータが、以前に DDSPD_IUNKNOWNPOINTER フラグを指定して SetPrivateData で設定された IUnknown、またはその派生クラスのいずれかへのポインターである場合、そのインターフェイスは、プライベートデータが返される前に参照カウントがインクリメントされます。

vtbl 42 HRESULT FreePrivateData(GUID* param0)

このサーフェスに関連付けられている、指定したプライベートデータを解放します。

param0

GUID*

解放するプライベートデータを識別するGUIDを指すポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

解説(Remarks)

DirectDraw は、サーフェスが解放されるときにこのメソッドを自動的に呼び出します。

プライベートデータが DDSPD_IUNKNOWNPOINTER フラグを使用して設定されていた場合、FreePrivateData は関連するインターフェイスに対して IUnknown::Release メソッドを呼び出します。

vtbl 43 HRESULT GetUniquenessValue(DWORD* param0)

このサーフェスの現在の一意性値 (uniqueness value) を取得します。

param0

DWORD*

inout

サーフェス内容の変更を検知する一意値を受け取る出力ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

定義されている一意性値は 0 のみで、これはサーフェスが DirectDraw の制御の及ばないところで変化している可能性が高いことを示します。それ以外の一意性値は、以前にキャッシュした一意性値と異なる場合にのみ意味を持ちます。現在の値がキャッシュした値と異なる場合、サーフェスの内容が変更されています。

vtbl 44 HRESULT ChangeUniquenessValue()

このサーフェスの一意性値 (uniqueness value) を手動で更新します。

戻り値

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

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

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

DirectDraw は、サーフェスの内容が変更されるたびに一意性値を自動的に更新します。

vtbl 45 HRESULT SetPriority(DWORD param0)

このテクスチャに、テクスチャ管理の優先度を割り当てます。このメソッドは、管理対象テクスチャに対してのみ成功します。

param0

DWORD

テクスチャ管理時の常駐優先度を指定する。値が大きいほど優先される。

戻り値

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

失敗した場合、戻り値はエラーになります。パラメーターが無効な場合、またはテクスチャが Direct3D によって管理されていない場合、このメソッドは DDERR_INVALIDOBJECT を返します。

解説(Remarks)

SetPriority は、IDirectDrawSurface7 インターフェイスで導入されました。

優先度は、管理対象テクスチャをいつメモリから削除するかを決定するために使用されます。低い優先度が割り当てられたテクスチャは、高い優先度のテクスチャより先に削除されます。2 つのテクスチャの優先度が同じ場合、より最近に使用されたテクスチャがメモリに保持され、もう一方のテクスチャが削除されます。

アプリケーションが優先度を設定および取得できるのは、管理対象テクスチャ (DDSCAPS2_TEXTUREMANAGE フラグを指定して作成されたサーフェス) のみです。管理対象外のテクスチャに対して SetPriority を呼び出すと、SetPriority は失敗し、DDERR_INVALIDOBJECT を返します。

vtbl 46 HRESULT GetPriority(DWORD* param0)

このテクスチャのテクスチャ管理の優先度を取得します。このメソッドは、管理対象テクスチャに対してのみ成功します。

param0

DWORD*

inout

現在のテクスチャ管理優先度を受け取る出力ポインタ。

戻り値

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

解説(Remarks)

アプリケーションが優先度を設定および取得できるのは、管理対象テクスチャ (DDSCAPS2_TEXTUREMANAGE フラグを指定して作成されたサーフェス) のみです。管理対象外のテクスチャに対して GetPriority を呼び出すと、GetPriority は失敗し、DDERR_INVALIDOBJECT を返します。

GetPriority は、IDirectDrawSurface7 インターフェイスで導入されました。

vtbl 47 HRESULT SetLOD(DWORD param0)

管理対象ミップマップサーフェスの最大詳細レベル (LOD) を設定します。このメソッドは、管理対象テクスチャに対してのみ成功します。

param0

DWORD

管理対象ミップマップで使用する最大詳細度レベル(LOD)を指定する。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

アプリケーションがこのメソッドを呼び出せるのは、管理対象テクスチャ (DDSCAPS2_TEXTUREMANAGE フラグを指定して作成されたサーフェス) のみです。管理対象外のテクスチャに対して SetLOD を呼び出すと、SetLOD は失敗し、DDERR_INVALIDOBJECT を返します。

SetLOD は、このチェーン内でローカルビデオメモリに読み込むべき最も詳細なミップマップを Direct3D テクスチャマネージャーに伝えます。たとえば、5 レベルのミップマップチェーンで dwMaxLOD を 2 に設定すると、テクスチャマネージャーは、任意の時点でミップマップレベル 2 から 4 のみをローカルビデオメモリに読み込みます。同様に、チェーン内で最も詳細なミップマップの寸法が 256×256 の場合、最大レベルを 2 に設定すると、ビデオメモリに存在する最大のミップマップの寸法は 64×64 になります。

vtbl 48 HRESULT GetLOD(DWORD* param0)

管理対象ミップマップサーフェスに現在設定されている最大詳細レベル (LOD) を取得します。このメソッドは、管理対象テクスチャに対してのみ成功します。

param0

DWORD*

inout

現在の最大詳細度レベル(LOD)を受け取る出力ポインタ。

戻り値

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

解説(Remarks)

アプリケーションがこのメソッドを呼び出せるのは、管理対象テクスチャ (DDSCAPS2_TEXTUREMANAGE フラグを指定して作成されたサーフェス) のみです。管理対象外のテクスチャに対して GetLOD を呼び出すと、GetLOD は失敗し、DDERR_INVALIDOBJECT を返します。

GetLOD は、このチェーン内でローカルビデオメモリに読み込むべき最も詳細なミップマップを Direct3D テクスチャマネージャーに伝えます。たとえば、5 レベルのミップマップチェーンで、lpdwMaxLOD の変数に値 2 が入っている場合、テクスチャマネージャーは、任意の時点でミップマップレベル 2 から 4 のみをローカルビデオメモリに読み込むことを示します。同様に、チェーン内で最も詳細なミップマップの寸法が 256×256 の場合、lpdwMaxLOD の値 2 は、ビデオメモリに存在する最大のミップマップの寸法が 64×64 であることを意味します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IDirectDrawSurface7 "{06675A80-3B9B-11D2-B92F-00609797EA5B}"
#usecom global IDirectDrawSurface7 IID_IDirectDrawSurface7 "{}"
#comfunc global IDirectDrawSurface7_AddAttachedSurface     3 sptr
#comfunc global IDirectDrawSurface7_AddOverlayDirtyRect    4 var
#comfunc global IDirectDrawSurface7_Blt                    5 var,sptr,var,int,var
#comfunc global IDirectDrawSurface7_BltBatch               6 var,int,int
#comfunc global IDirectDrawSurface7_BltFast                7 int,int,sptr,var,int
#comfunc global IDirectDrawSurface7_DeleteAttachedSurface  8 int,sptr
#comfunc global IDirectDrawSurface7_EnumAttachedSurfaces   9 sptr,sptr
#comfunc global IDirectDrawSurface7_EnumOverlayZOrders     10 int,sptr,sptr
#comfunc global IDirectDrawSurface7_Flip                   11 sptr,int
#comfunc global IDirectDrawSurface7_GetAttachedSurface     12 var,sptr
#comfunc global IDirectDrawSurface7_GetBltStatus           13 int
#comfunc global IDirectDrawSurface7_GetCaps                14 var
#comfunc global IDirectDrawSurface7_GetClipper             15 sptr
#comfunc global IDirectDrawSurface7_GetColorKey            16 int,var
#comfunc global IDirectDrawSurface7_GetDC                  17 sptr
#comfunc global IDirectDrawSurface7_GetFlipStatus          18 int
#comfunc global IDirectDrawSurface7_GetOverlayPosition     19 var,var
#comfunc global IDirectDrawSurface7_GetPalette             20 sptr
#comfunc global IDirectDrawSurface7_GetPixelFormat         21 var
#comfunc global IDirectDrawSurface7_GetSurfaceDesc         22 var
#comfunc global IDirectDrawSurface7_Initialize             23 sptr,var
#comfunc global IDirectDrawSurface7_IsLost                 24
#comfunc global IDirectDrawSurface7_Lock                   25 var,var,int,sptr
#comfunc global IDirectDrawSurface7_ReleaseDC              26 sptr
#comfunc global IDirectDrawSurface7_Restore                27
#comfunc global IDirectDrawSurface7_SetClipper             28 sptr
#comfunc global IDirectDrawSurface7_SetColorKey            29 int,var
#comfunc global IDirectDrawSurface7_SetOverlayPosition     30 int,int
#comfunc global IDirectDrawSurface7_SetPalette             31 sptr
#comfunc global IDirectDrawSurface7_Unlock                 32 var
#comfunc global IDirectDrawSurface7_UpdateOverlay          33 var,sptr,var,int,var
#comfunc global IDirectDrawSurface7_UpdateOverlayDisplay   34 int
#comfunc global IDirectDrawSurface7_UpdateOverlayZOrder    35 int,sptr
#comfunc global IDirectDrawSurface7_GetDDInterface         36 sptr
#comfunc global IDirectDrawSurface7_PageLock               37 int
#comfunc global IDirectDrawSurface7_PageUnlock             38 int
#comfunc global IDirectDrawSurface7_SetSurfaceDesc         39 var,int
#comfunc global IDirectDrawSurface7_SetPrivateData         40 var,sptr,int,int
#comfunc global IDirectDrawSurface7_GetPrivateData         41 var,sptr,var
#comfunc global IDirectDrawSurface7_FreePrivateData        42 var
#comfunc global IDirectDrawSurface7_GetUniquenessValue     43 var
#comfunc global IDirectDrawSurface7_ChangeUniquenessValue  44
#comfunc global IDirectDrawSurface7_SetPriority            45 int
#comfunc global IDirectDrawSurface7_GetPriority            46 var
#comfunc global IDirectDrawSurface7_SetLOD                 47 int
#comfunc global IDirectDrawSurface7_GetLOD                 48 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDirectDrawSurface7 "{06675A80-3B9B-11D2-B92F-00609797EA5B}"
#usecom global IDirectDrawSurface7 IID_IDirectDrawSurface7 "{}"
#comfunc global IDirectDrawSurface7_AddAttachedSurface     3 sptr
#comfunc global IDirectDrawSurface7_AddOverlayDirtyRect    4 sptr
#comfunc global IDirectDrawSurface7_Blt                    5 sptr,sptr,sptr,int,sptr
#comfunc global IDirectDrawSurface7_BltBatch               6 sptr,int,int
#comfunc global IDirectDrawSurface7_BltFast                7 int,int,sptr,sptr,int
#comfunc global IDirectDrawSurface7_DeleteAttachedSurface  8 int,sptr
#comfunc global IDirectDrawSurface7_EnumAttachedSurfaces   9 sptr,sptr
#comfunc global IDirectDrawSurface7_EnumOverlayZOrders     10 int,sptr,sptr
#comfunc global IDirectDrawSurface7_Flip                   11 sptr,int
#comfunc global IDirectDrawSurface7_GetAttachedSurface     12 sptr,sptr
#comfunc global IDirectDrawSurface7_GetBltStatus           13 int
#comfunc global IDirectDrawSurface7_GetCaps                14 sptr
#comfunc global IDirectDrawSurface7_GetClipper             15 sptr
#comfunc global IDirectDrawSurface7_GetColorKey            16 int,sptr
#comfunc global IDirectDrawSurface7_GetDC                  17 sptr
#comfunc global IDirectDrawSurface7_GetFlipStatus          18 int
#comfunc global IDirectDrawSurface7_GetOverlayPosition     19 sptr,sptr
#comfunc global IDirectDrawSurface7_GetPalette             20 sptr
#comfunc global IDirectDrawSurface7_GetPixelFormat         21 sptr
#comfunc global IDirectDrawSurface7_GetSurfaceDesc         22 sptr
#comfunc global IDirectDrawSurface7_Initialize             23 sptr,sptr
#comfunc global IDirectDrawSurface7_IsLost                 24
#comfunc global IDirectDrawSurface7_Lock                   25 sptr,sptr,int,sptr
#comfunc global IDirectDrawSurface7_ReleaseDC              26 sptr
#comfunc global IDirectDrawSurface7_Restore                27
#comfunc global IDirectDrawSurface7_SetClipper             28 sptr
#comfunc global IDirectDrawSurface7_SetColorKey            29 int,sptr
#comfunc global IDirectDrawSurface7_SetOverlayPosition     30 int,int
#comfunc global IDirectDrawSurface7_SetPalette             31 sptr
#comfunc global IDirectDrawSurface7_Unlock                 32 sptr
#comfunc global IDirectDrawSurface7_UpdateOverlay          33 sptr,sptr,sptr,int,sptr
#comfunc global IDirectDrawSurface7_UpdateOverlayDisplay   34 int
#comfunc global IDirectDrawSurface7_UpdateOverlayZOrder    35 int,sptr
#comfunc global IDirectDrawSurface7_GetDDInterface         36 sptr
#comfunc global IDirectDrawSurface7_PageLock               37 int
#comfunc global IDirectDrawSurface7_PageUnlock             38 int
#comfunc global IDirectDrawSurface7_SetSurfaceDesc         39 sptr,int
#comfunc global IDirectDrawSurface7_SetPrivateData         40 sptr,sptr,int,int
#comfunc global IDirectDrawSurface7_GetPrivateData         41 sptr,sptr,sptr
#comfunc global IDirectDrawSurface7_FreePrivateData        42 sptr
#comfunc global IDirectDrawSurface7_GetUniquenessValue     43 sptr
#comfunc global IDirectDrawSurface7_ChangeUniquenessValue  44
#comfunc global IDirectDrawSurface7_SetPriority            45 int
#comfunc global IDirectDrawSurface7_GetPriority            46 sptr
#comfunc global IDirectDrawSurface7_SetLOD                 47 int
#comfunc global IDirectDrawSurface7_GetLOD                 48 sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。