IDirectDrawSurface3接口

优质

小牛编辑

144浏览

2023-12-01

返回上级

应用程序使用IDirectDrawSurface3接口的方法来创建DirectDrawSurface对象，并且与系统层变量一起工作。这部分是关于该接口方法的参考。IDirectDrawSurface3接口的函数可以分为以下几组：

分配内存	Initialize
	IsLost
	Restore

隶属页面	AddAttachedSurface
	DeleteAttachedSurface
	EnumAttachedSurfaces
	GetAttachedSurface

位块传送	Blt
	BltBatch
	BltFast
	GetBltStatus

关键色	GetColorKey
	SetColorKey

设备环境	GetDC
	ReleaseDC

换页	Flip
	GetFlipStatus

页面锁定	Lock
	PageLock
	PageUnlock
	Unlock

杂项	GetDDInterface

覆盖	AddOverlayDirtyRect
	EnumOverlayZOrders
	GetOverlayPosition
	SetOverlayPosition
	UpdateOverlay
	UpdateOverlayDisplay
	UpdateOverlayZOrder

页面性能	GetCaps

页面裁剪	GetClipper
	SetClipper

页面描述	GetPixelFormat
	GetSurfaceDesc
	SetSurfaceDesc

页面调色板	GetPalette
	SetPalette

和所有COM接口一样，IDirectDrawSurface3接口由IUnknown接口衍生而来。IUnknown接口支持以下三种方法：

AddRef
QueryInterface
Release

你可以使用LPDIRECTDRAWSURFACE，LPDIRECTDRAWDURFACE2，或LPDIRECTDRAWSURFACE3数据类型来声明一个指向IDirectDrawSurface，IDirectDrawSurface2，或IDirectDrawSurface3接口的指针变量。在Ddraw.h头文件中，用如下代码声明了这三种数据类型。

typedef struct IDirectDrawSurface FAR *LPDIRECTDRAWSURFACE;
typedef struct IDirectDrawSurface2 FAR *LPDIRECTDRAWSURFACE2;
typedef struct IDirectDrawSurface3 FAR *LPDIRECTDRAWSURFACE3;

IDirectDrawSurface3::AddAttachedSurface

返回目录

将一个页面隶属于另一个页面。

HRESULT AddAttachedSurface(

LPDIRECTDRAWSURFACE3 lpDDSAttachedSurface

);

参数：

lpDDSAttachedSurface

将要被隶属的DirectDraw页面的地址。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_CANNOTATTACHSURFACE

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACEALREADYATTACHED

DDERR_SURFACELOST

DDERR_WASSTILLDRAWING

备注：

可以被隶属的页面类型包括：z-缓冲区、alpha通道、和后台缓冲区。某些隶属关系可能会打破另一些隶属关系。例如，一个3-D z-缓冲区一次只能隶属到一个后台缓冲区上去。隶属关系不是双向的，并且一个页面不可能隶属到自身。仿真页面（在系统主存中）不能隶属到一个非仿真页面上去。除非页面是材质图，否则两个隶属关系的页面必须是相同的大小。一个换页页面不能被隶属到另一个相同类型的换页页面上去；然而，将两个不同类型的页面相隶属却是可行的。例如，一个换页z-缓冲区可以被隶属到普通换页页面上去。如果一个非换页页面被隶属到另一个非换页页面上，这两个页面将形成一个换页链。如果一个非换页页面被隶属到一个换页页面上，它就会成为这个换页链的一部分。其它的页面也可以被隶属到这个换页链中，并且每次调用IDirectDrawSurface3::Flip函数将使页面的指向前进一个。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::DeleteAttachedSurface，IDirectDrawSurface3::EnumAttachedSurfaces。

IDirectDrawSurface3::AddOverlayDirtyRect
返回目录

该函数目前尚未完成，还不能使用。

HRESULT AddOverlayDirtyRect(

LPRECT lpRect

);

参数：

lpRect

RECT结构的地址，指定需要被更新的区域。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_UNSUPPORTED

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::UpdateOverlayDisplay

IDirectDrawSurface3::Blt
返回目录

该函数完成一次位块传送（bit block transfer）操作。目前它还不支持带z-缓冲区和alpha混合的位块传送操作（参见alpha通道）。

HRESULT Blt(

LPRECT lpDestRect,

LPDIRECTDRAWSURFACE3 lpDDSrcSurface,

LPRECT lpSrcRect,

DWORD dwFlags,

LPDDBLTFX lpDDBltFx

);

参数：

lpDestRect

一个RECT结构的地址，定义了一个矩形区域的左上和右下点，作为目标页面上将被位块传送的区域。如果该参数是NULL，整个目标页面将被使用。

lpDDSrcSurface

DirectDrawSurface3对象的地址，作为位块操作的源页面。

lpSrcRect

一个RECT结构的地址，定义了一个矩形区域的左上和右下点，作为源页面上将被位块传送的区域。如果该参数是NULL，整个源页面将被使用。

dwFlags

DDBLT_ALPHADEST

使用alpha像素格式信息或隶属于目标页面的alpha通道页面作为该位块传送操作的alpha通道。

DDBLT_ALPHADESTCONSTOVERRIDE

使用DDBLTFX结构的dwAlphaDestConst成员作为该位块传送操作的目标页面的alpha通道。

DDBLT_ALPHADESTNEG

指定目标页面的透明度随着alpha值的增加而增加（0为不透明）。

DDBLT_ALPHADESTSURFACEOVERRIDE

使用DDBLTFX结构的lpDDSAlphaDest成员作为该位块传送操作的目标页面的alpha通道。

DDBLT_ALPHAEDGEBLEND

使用DDBLTFX结构的dwAlphaEdgeBlend成员作为alpha通道，用于围绕关键色图象的边缘。

DDBLT_ALPHASRC

使用alpha像素格式信息或隶属于源页面的alpha通道页面作为该位块传送操作的alpha通道。

DDBLT_ALPHASRCCONSTOVERRIDE

使用DDBLTFX结构的dwAlphaSrcConst成员作为该位块操作的源alpha通道。

DDBLT_ALPHASRCNEG

指定源页面的透明度随着alpha值的增加而增加（0为不透明）。

DDBLT_ALPHASRCSURFACEOVERRIDE

使用DDBLTFX结构的lpDDSAlphaSrchengyuan成员作为该位块传送操作的源alpha通道。

DDBLT_ASYNC

以异步的方式执行该位块传送操作，按照接收命令的先进先出的原则。如果没有可用的空间用于先进先出操作，该调用失败。

DDBLT_COLORFILL

使用DDBLTFX结构的dwFillColor成员作为填充目标页面上的目标矩形区域的颜色。

DDBLT_DDFX

使用DDBLTFX结构的dwDDFX成员来指定该位块传送操作的所使用的效果。

DDBLT_DDROPS

使用DDBLTFX结构的dwDDROPS成员来指定光栅操作模式（ROPS），这些ROP不属于Win32 API。

DDBLT_DEPTHFILL

使用DDBLTFX结构的dwFillDepth成员作为填充目标z-缓冲区页面上的目标矩形区域的深度值。

DDBLT_KEYDEST

使用目标页面的关键色。

DDBLT_KEYDESTOVERRIDE

使用DDBLTFX结构的dckDestColorkey成员作为目标页面的关键色。

DDBLT_KEYSRC

使用源页面的关键色。

DDBLT_KEYSRCOVERRIDE

使用DDBLTFX结构的dckSrcColorkey成员作为源页面的关键色。

DDBLT_ROP

使用DDBLTFX结构的dwROP成员作为该位块传送操作的ROP模式。这些ROP与Win32 API中的定义是一样的。

DDBLT_ROTATIONANGLE

使用DDBLTFX结构的dwRotationAngle成员作为页面的旋转角度。

DDBLT_WAIT

如果位块传送器正忙，延迟DDERR_WASSTILLDRAWING消息的发送，直到位块传送器准备好或发生其它错误时返回。

DDBLT_ZBUFFER

进行带z-缓冲区的位块传送操作，使用的是隶属于源和目标页面的z-缓冲区，并且将DDBLTFX结构的dwZBufferOpCode成员作为z-缓冲区操作符。

DDBLT_ZBUFFERDESTCONSTOVERRIDE

进行带z-缓冲区的位块传送操作，使用DDBLTFX结构的dwZDestConst和dwZBufferOpCode成员分别作为目标z-缓冲区和z-缓冲区操作符。

DDBLT_ZBUFFERDESTOVERRIDE

进行带z-缓冲区的位块传送操作，使用DDBLTFX结构的lpDDSZBufferDest和dwZBufferOpCode成员分别作为目标z-缓冲区和z-缓冲区操作符。

DDBLT_ZBUFFERSRCCONSTOVERRIDE

进行带z-缓冲区的位块传送操作，使用DDBLTFX结构的dwZSrcConst和dwZBufferOpCode成员分别作为源z-缓冲区和z-缓冲区操作符。

DDBLT_ZBUFFERSRCOVERRIDE

进行带z-缓冲区的位块传送操作，使用DDBLTFX结构的lpDDSZBufferSrc和dwZBufferOpCode成员分别作为源z-缓冲区和z-缓冲区操作符。

lpDDBltFx

DDBLTFX结构的地址，包含了光栅操作代码及特效。

返回值：

如果函数调用成功，返回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

备注：

该函数可以是同步执行也可以是异步执行（缺省）的，既可以是从显存到显存、显存到系统主存，也可以是系统主存到显存，或系统主存到系统主存。位块传送操作既可以使用源关键色也可以使用目标关键色。如果源矩形和目标矩形不是相同的大小，该操作还可以缩放图象到合适的大小。

典型的，如果位块传送器正忙并且没有准备好，IDirectDrawSurface3::Blt将立即返回一个错误。调用函数时指定DDBLT_WAIT标志可以完成一次同步的位块传送，该函数将一直等待直到位块传送器准备好或出现另一个错误时才返回。

注意：RECT结构的right和bottom成员是排除边线的，因此，right-left值恰等于矩形区域的宽度值，而不是宽度值-1。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::BltBatch
返回目录

该函数完成一系列的IDirectDrawSurface3::Blt操作，从多个源页面到一个目标页面。这个函数目前尚未完成，还不能使用。

HRESULT BltBatch(

LPDDBLTBATCH lpDDBltBatch,

DWORD dwCount,

DWORD dwFlags

);

参数：

lpDDBltBatch

第一个DDBLTBATCH结构的地址，定义了位块传送操作的各参数。

dwCount

位块传送操作的次数。

dwFlags

该参数目前尚未使用，必须设为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

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::BltFast
返回目录

通过使用源关键色或目标关键色，完成一次源图复制或带透明的位块传送。

HRESULT BltFast(

DWORD dwX,

DWORD dwY,

LPDIRECTDRAWSURFACE3 lpDDSrcSurface,

LPRECT lpSrcRect,

DWORD dwTrans

);

参数：

dwX and dwY

目标页面上将被位块传送的x和y坐标。

lpDDSrcSurface

DirectDraw页面的地址，作为位块传送操作的源页面。

lpSrcRect

一个RECT结构的地址，定义了源页面上的矩形区域的左上和右下点坐标。

dwTrans

传送类型。

DDBLTFAST_DESTCOLORKEY

指定进行一次带透明的位块传送，使用目标页面的关键色。

DDBLTFAST_NOCOLORKEY

指定进行一次普通的复制，不带透明成分。

DDBLTFAST_SRCCOLORKEY

指定进行一次带透明的位块传送，使用源页面的关键色。

DDBLTFAST_WAIT

如果位块传送器正忙，延迟DDERR_WASSTILLDRAWING消息的发送，直到位块传送器准备好或发生其它错误时才返回。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_EXCEPTION

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDRECT

DDERR_NOBLTHW

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

备注：

该函数总是试图以异步的方式进行位块传送，如果硬件支持的话。

该函数只针对显存中的页面工作，并且在操作过程中不能进行裁剪。如果你对一个拥有裁剪区的页面进行该项操作，调用失败，返回DDERR_UNSUPPORTED。

软件执行时，IDirectDrawSurface3::BltFast比IDirectDrawSurface3::Blt能提高10%的操作速度。然而，如果有硬件支持，这两个函数都将使用硬件加速，那么在速度上，这两各函数是没有区别的。

典型的，如果位块传送器正忙或没有准备好，调用IDirectDrawSurface3::BltFast函数将立即返回一个错误。你可以指定DDBLTFAST_WAIT标志，那么，函数将一直等到位图传送器空闲或有其它错误发生时才返回。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::DeleteAttachedSurface
返回目录

解除两个页面之间的隶属关系。被脱离的页面不会被释放。

HRESULT DeleteAttachedSurface(

DWORD dwFlags,

LPDIRECTDRAWSURFACE3 lpDDSAttachedSurface

);

参数：

dwFlags

该参数目前没有使用，只能设为0。

lpDDSAttachedSurface

将被解除隶属关系的DirectDraw页面的地址。如果为NULL，所有相隶属的页面将相互脱离。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_CANNOTDETACHSURFACE

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

DDERR_SURFACENOTATTACHED

备注：

隐含的隶属关系，如由DirectDraw自动生成的而非调用IDirectDrawSurface3::AddAttachedSurface函数生成的，不能被脱离。解除换页链中页面的隶属关系，将改变链中其余页面的地位。例如，如果前台缓冲区从换页链中脱离，链中的下一个页面将成为前台缓冲区，再下一个页面会成为后台缓冲区。如果一个后台缓冲区从链中脱离，链中的下一个页面会成为后台缓冲区。如果一个简单页面从链中脱离，那么链仅仅是缩短了。如果一个换页链中仅有两个页面，当它们被脱离后，链将被销毁，并且两个页面都会返回到它们以前最基本的状态。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::Flip

IDirectDrawSurface3::EnumAttachedSurfaces
返回目录

列举出该页面的所有隶属页面。

HRESULT EnumAttachedSurfaces(

LPVOID lpContext,

LPDDENUMSURFACESCALLBACK lpEnumSurfacesCallback

);

参数：

lpContext

一个用户定义的结构的地址，每列举出一个页面的时候，它将被传递给列举的回调函数。

lpEnumSurfacesCallback

EnumSurfacesCallback回调函数的地址，每列举出一个页面的时候，这个函数将被调用。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::EnumOverlayZOrders
返回目录

列举出在该页面之上的覆盖页面。可以按照从前往后，也可以按照从后往前的顺序。

HRESULT EnumOverlayZOrders(

DWORD dwFlags,

LPVOID lpContext,

LPDDENUMSURFACESCALLBACK lpfnCallback

);

参数：

dwFlags

下列标志之一：

DDENUMOVERLAYZ_BACKTOFRONT

从后往前列举覆盖页面。

DDENUMOVERLAYZ_FRONTTOBACK

从前往后列举覆盖页面。

lpContext

一个用户定义的结构的地址，每列举出一个覆盖页面的时候，它将被传递给列举的回调函数。

lpfnCallback

EnumSurfacesCallback回调函数的地址，每列举出一个页面的时候，这个函数将被调用。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::Flip
返回目录

该函数完成一次换页操作。将与后台缓冲区相关联的页面内存换页成与前台缓冲区页面相关联。

HRESULT Flip(

LPDIRECTDRAWSURFACE3 lpDDSurfaceTargetOverride,

DWORD dwFlags

);

参数：

lpDDSurfaceTargetOverride

换页链中另一个页面的地址，代表换页操作的目标页面。这个页面必须是换页链中的一员。该参数缺省值是NULL，在这种情况下，DirectDraw从换页链中按照前后隶属关系依次换页。

dwFlags

换页的标志选项：

DDFLIP_EVEN

仅当在覆盖页面上显示视频图象时才能使用。新的页面上包含从视频信号的奇数行上传来的数据。该参数不能与DDFLIP_ODD标志同时使用。

DDFLIP_ODD

仅当在覆盖页面上显示视频图象时才能使用。新的页面上包含从视频信号的偶数行上传来的数据。该参数不能与DDFLIP_EVEN标志同时使用。

DDFLIP_WAIT

典型的，如果不使用该标志，因为显示硬件不在状态（因为上一次的换页尚未完成或其它原因）而导致换页操作没能准备好，函数将立即返回DDERR_WASSTILLDRAWING，并且不能完成换页操作。如果设置了该DDFLIP_WAIT标志，可以使该函数在收到从HAL传来的DDERR_WASSTILLDRAWING的消息后继续重试换页操作，除非换页已经成功的完成，或是发生了另一个错误，否则该函数将不会返回。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOFLIPHW

DDERR_NOTFLIPPABLE

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

备注：

这个函数只能被具有DDSCAPS_FLIP和DDSCAPS_FRONTBUFFER标志的页面调用。先前与前台缓冲区相关联的页面内存在换页后与后台缓冲区相关联。lpDDSurfaceTargetOverride参数在很少情况下才被使用，通常，该参数为NULL。

IDirectDrawSurface3::Flip函数总是与显示器的垂直回扫（vertical blank）同步进行。如果页面被指派给了一个视频端口，该函数可更新可见的覆盖页面和视频端口的目标页面。

要得到更多的资料，请参阅“换页页面”。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::GetFlipStatus

IDirectDrawSurface3::GetAttachedSurface
返回目录

获得隶属于该页面的具有指定特性的页面。

HRESULT GetAttachedSurface(

LPDDSCAPS lpDDSCaps,

LPDIRECTDRAWSURFACE3 FAR *lplpDDAttachedSurface

);

参数：

lpDDSCaps

DDSCAPS结构的地址，包含了页面的硬件特性描述。

lplpDDAttachedSurface

返回一个指向IDirectDrawSurface对象的指针地址。该页面符合lpDDSCaps参数所提供的页面特性描述，并且隶属于该页面。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTFOUND

DDERR_SURFACELOST

备注：

隶属关系用于将多个DirectDrawSurface对象合成一个复杂的页面结构，比如，如果页面要支持3-D换页，必须带一个z-缓冲区页面。如果该页面的隶属页面中有多于一个符合条件，则函数调用失败，在这种情况下，应用程序必须使用IDirectDrawSurface3::EnumAttachedSurfaces函数以获得适当的隶属页面。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::GetBltStatus
返回目录

获得位块传送器的状态。

HRESULT GetBltStatus(

DWORD dwFlags

);

参数：

dwFlags

下列标志之一：

DDGBS_CANBLT

询问对该页面的位块传送操作是否能立即开始，如果返回DD_OK，表示位块传送器准备就绪。

DDGBS_ISBLTDONE

询问位块操作是否已经完成，如果返回DD_OK，表明对该页面的位块操作已经完成。

返回值：

如果函数成功，表明位图传送器处于待命状态，返回值是DD_OK。

如果函数失败，返回DDERR_WASSTILLDRAWING表明位块传送器正忙，返回DDERR_NOBLTHW表明位块传送器不存在，或下列值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOBLTHW

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::GetCaps
返回目录

获得页面的特性描述。这些特性与显示设备的特性没有必然的联系。

HRESULT GetCaps(

LPDDSCAPS lpDDSCaps

);

参数：

lpDDSCaps

一个DDSCAPS结构的地址，将被填充页面的硬件特性。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::GetClipper
返回目录

获得隶属于该页面的DirectDrawClipper对象。

HRESULT GetClipper(

LPDIRECTDRAWCLIPPER FAR *lplpDDClipper

);

参数：

lplpDDClipper

指向隶属于该页面的DirectDrawClipper对象的指针的地址，

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCLIPPERATTACHED

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::SetClipper

IDirectDrawSurface3::GetColorKey
返回目录

获得DirectDrawSurface对象的关键色的值。

HRESULT GetColorKey(

DWORD dwFlags,

LPDDCOLORKEY lpDDColorKey

);

参数：

dwFlags

指定要获得哪种关键色。

DDCKEY_DESTBLT

指定要获得位块传送操作中的目标关键色。

DDCKEY_DESTOVERLAY

指定要获得覆盖操作中的目标关键色。

DDCKEY_SRCBLT

指定要获得位块传送操作中的源关键色。

DDCKEY_SRCOVERLAY

指定要获得覆盖操作中的源关键色。

lpDDColorKey

一个DDCOLORKEY结构的地址，将被填充DirectDrawSurface对象的关键色的当前值。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOCOLORKEY

DDERR_NOCOLORKEYHW

DDERR_SURFACELOST

DDERR_UNSUPPORTED

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::SetColorKey

IDirectDrawSurface3::GetDC
返回目录

创建该页面的设备环境句柄，该设备环境与GDI是兼容的。

HRESULT GetDC(

HDC FAR *lphDC

);

参数：

lphDC

返回的设备环境句柄的地址。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_DCALREADYCREATED

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

备注：

该函数暗中的调用了IDirectDrawSurface3::Lock函数的内核以锁定页面内存。该页面一直为锁定状态直到调用了IDirectDrawSurface3::ReleaseDC函数。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::Lock

IDirectDrawSurface3::GetDDInterface
返回目录

获得创建该页面的DirectDraw对象。

HRESULT GetDDInterface(

LPVOID FAR *lplpDD

);

参数：

lplpDD

如果调用成功，将返回一个指向合法的DirectDraw对象的指针的地址。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

备注：

该函数在IDirectDraw接口中无法实现。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::GetFlipStatus
返回目录

指出页面是否已经完成其换页过程。

HRESULT GetFlipStatus(

DWORD dwFlags

);

参数：

dwFlags

下列值之一：

DDGFS_CANFLIP

询问该页面是否能立即进行换页操作，如果可以的话，函数将返回DD_OK。

DDGFS_ISFLIPDONE

询问换页操作是否已经结束，如果是的话，函数将返回DD_OK。

返回值：

如果函数调用成功，返回DD_OK。

函数调用失败，如果页面尚未完成其换页过程，返回DDERR_WASSTILLDRAWING，否则返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_UNSUPPORTED

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::Flip

IDirectDrawSurface3::GetOverlayPosition
返回目录

假设存在一个可见的，活跃的覆盖页面（设置了DDSCAPS_OVERLAY标志），该函数返回该页面的显示坐标。

HRESULT GetOverlayPosition(

LPLONG lplX,

LPLONG lplY

);

参数：

lplX and lplY

x和y坐标变量的地址。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDPOSITION

DDERR_NOOVERLAYDEST

DDERR_NOTAOVERLAYSURFACE

DDERR_OVERLAYNOTVISIBLE

DDERR_SURFACELOST

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::SetOverlayPosition，IDirectDrawSurface3::UpdateOverlay

IDirectDrawSurface3::GetPalette
返回目录

获得与该页面相关联的DirectDrawPalette对象，并递增该调色板对象的引用记录。

HRESULT GetPalette(

LPDIRECTDRAWPALETTE FAR *lplpDDPalette

);

参数：

lplpDDPalette

获得一个与该页面相关联的DirectDrawPalette对象的指针的地址。如果没有任何调色板对象与该页面关联，则该参数返回NULL。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOEXCLUSIVEMODE

DDERR_NOPALETTEATTACHED

DDERR_SURFACELOST

DDERR_UNSUPPORTED

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::SetPalette

IDirectDrawSurface3::GetPixelFormat
返回目录

获得该页面的色彩空间和像素格式。

HRESULT GetPixelFormat(

LPDDPIXELFORMAT lpDDPixelFormat

);

参数：

lpDDPixelFormat

DDPIXELFORMAT结构的地址，将被填充该页面当前的像素和色彩空间的格式的详细信息。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::GetSurfaceDesc
返回目录

获得当前条件下的，描述该页面信息的DDSURFACEDESC结构。

HRESULT GetSurfaceDesc(

LPDDSURFACEDESC lpDDSurfaceDesc

);

参数：

lpDDSurfaceDesc

DDSURFACEDESC结构的地址，将被填充页面当前的描述信息。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

DDSURFACEDESC

IDirectDrawSurface3::Initialize
返回目录

初始化一个DirectDrawSurface对象。

HRESULT Initialize(

LPDIRECTDRAW lpDD,

LPDDSURFACEDESC lpDDSurfaceDesc

);

参数：

lpDD

一个DirectDraw结构的地址，代表DirectDraw对象。

lpDDSurfaceDesc

DDSURFACEDESC结构的地址，将被填充关于页面的相关细节的信息。

返回值：

该函数返回DDERR_ALREADYINITIALIZED。

备注：

提供这个函数是为了与部件对象模型（COM）的协议保持一致性。因为DirectDrawSurface对象在创建好之后就已经被初始化了，所以这个函数总是返回DDERR_ALREADYINITIALIZED。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IUnknown::AddRef，IUnknown::QueryInterface，IUnknown::Release

IDirectDrawSurface3::IsLost
返回目录

判断与一个DirectDrawSurface对象相关联的页面内存是否丢失。

HRESULT IsLost();

返回值：

如果调用成功，返回值是DD_OK，表明页面内存没有被释放。

如果调用失败，返回值可能是下列值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

你可以使用该函数来判断是否应该重新分配页面内存。当一个DirectDrawSurface对象丢失它的页面内存后，大多数函数将返回DDERR_SURFACELOST，并且不进行任何其它操作。

备注：

当显示模式发生改变时，或当另一个应用程序获得对显卡的独占访问模式，并且释放当前被分配到显卡上的所有页面内存时，会发生页面丢失。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::Restore

IDirectDrawSurface3::Lock
返回目录

锁定页面，以获得一个指向页面内存的指针。

HRESULT Lock(

LPRECT lpDestRect,

LPDDSURFACEDESC lpDDSurfaceDesc,

DWORD dwFlags,

HANDLE hEvent

);

参数：

lpDestRect

一个RECT结构的地址，指定将被锁定的页面区域。如果该参数为NULL，整个页面将被锁定。

lpDDSurfaceDesc

一个DDSURFACEDESC结构的地址，将被填充页面的相关信息。指向页面内存的指针将保存在该结构的lpSurface成员中。

dwFlags

DDLOCK_EVENT

该标志目前尚不能使用。

DDLOCK_NOSYSLOCK

如果可能，不使用Win16锁。当锁定的是主页面时，该标志被忽略。

DDLOCK_READONLY

指定被锁定的页面将为只读。

DDLOCK_SURFACEMEMORYPTR

指定返回一个指向指定的矩形区域的合法的内存指针。如果没有指定矩形区域，将返回一个指向页面的指针。这是缺省值。

DDLOCK_WAIT

如果因为位块传送操作正在运行而不能锁定页面，该函数将重试，直到锁定完成或发生其它错误如DDERR_SURFACEBUSY。

DDLOCK_WRITEONLY

指定被锁定的页面将为只写。

hEvent

该参数目前未被使用，必须设为NULL。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_OUTOFMEMORY

DDERR_SURFACEBUSY

DDERR_SURFACELOST

DDERR_WASSTILLDRAWING

备注：

要得到更多关于如何使用该函数的资料，请参阅“直接访问祯缓冲区”。

在获得了页面内存指针之后，你就可以访问页面内存，直到调用了相应的IDirectDrawSurface3::Unlock函数。当页面被解锁，指向页面内存的指针将成为非法。绝对不要调用DirectDraw的blit函数从一个页面锁定的区域进行位块传送操作，否则，将返回DDERR_SURFACEBUSY或DDERR_LOCKEDSURFACES错误。除此之外，当使用一个锁定的显存中的页面时，GDI的blit函数也将失败。

该函数通常导致DirectDraw控制住Win16锁，直到调用IDirectDrawSurface3::Unlock函数。当Win16锁被控制住的时候，GUI（图形用户界面）调试器将无法工作。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::Unlock，IDirectDrawSurface3::GetDC，IDirectDrawSurface3::ReleaseDC

IDirectDrawSurface3::PageLock
返回目录

当使用DMA（直接内存访问）方式进行的系统主存页面之间的位块传送操作正在进行时，该函数阻止该页面被使用。

HRESULT PageLock(

DWORD dwFlags

);

参数：

dwFlags

该参数尚不能使用，必须设为0。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_CANTPAGELOCK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

备注：

你必须调用此函数以对DMA的支持加以利用。如果你不这样做，位块传送操作将使用软件仿真的方式进行。要得到更多的资料，请参阅“使用DMA”。

如果锁定了太多的内存，操作系统的行为能力将受到反面影响。

每个页面都有一个锁定记录，每次调用IDirectDrawSurface3::PageLock后，该记录递增1。每次调用IDirectDrawSurface3::PageUnlock后，该锁定记录递减1。当一个页面的锁定记录达到0时，内存被解锁，并且可重新以被操作系统所使用。

该函数只工作于系统主存页面；它将不能锁定一个显存中的页面或仿真的主页面。如果应用程序对显存页面调用此函数，该函数除了返回DD_OK外，什么也不做。

该函数不能执行于IDirectDraw接口。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::PageUnlock

IDirectDrawSurface3::PageUnlock
返回目录

解锁一个系统主存页面，允许它被使用。

HRESULT PageUnlock(

DWORD dwFlags

);

参数：

dwFlags

该参数尚不能使用，只能设为0。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_CANTPAGEUNLOCK

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTPAGELOCKED

DDERR_SURFACELOST

备注：

该函数不能执行于IDirectDraw接口。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::PageLock

IDirectDrawSurface3::ReleaseDC
返回目录

将先前调用IDirectDrawSurface3::GetDC函数获得的设备环境句柄释放掉。

HRESULT ReleaseDC(

HDC hDC

);

参数：

hDC

设备环境句柄，由先前调用IDirectDrawSurface3::GetDC获得。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_SURFACELOST

DDERR_UNSUPPORTED

备注：

该函数同样也将先前调用IDirectDrawSurface3::GetDC时锁定的页面解锁。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::GetDC

IDirectDrawSurface3::Restore
返回目录

恢复丢失的页面。与DirectDrawSurface对象相关联的页面内存被释放时，会导致页面丢失。

HRESULT Restore();

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_IMPLICITLYCREATED

DDERR_INCOMPATIBLEPRIMARY

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOEXCLUSIVEMODE

DDERR_OUTOFMEMORY

DDERR_UNSUPPORTED

DDERR_WRONGMODE

备注：

该函数恢复曾分配给一个页面的内存，但不能恢复内存的内容。重建丢失的图象以恢复内存内容应该由应用程序来负责。

页面丢失，发生在当显示模式发生改变时，或当另一个应用程序获得对显卡的独占访问模式，并且释放当前被分配到显卡上的所有页面内存时。当一个DirectDrawSurface对象丢失了它的页面内存，许多函数将返回DDERR_SURFACELOST，并且不完成任何其它操作。IDirectDrawSurface3::Restore函数将重新给页面分配内存，并且将它重新依附到DirectDrawSurface对象上。

一个单步的调用此函数能恢复一个DirectDrawSurface对象的所有暗中相关联的页面（后台缓冲区等）。试图调用此函数以恢复一个暗中创建的页面将返回一个错误。IDirectDrawSurface3::Restore不会恢复一个由调用IDirectDrawSurface3::AddAttachedSurface 而产生隶属关系的页面，必须分别调用该函数以恢复它们中的每一个页面。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::IsLost，IDirectDrawSurface3::AddAttachedSurface

IDirectDrawSurface3::SetClipper
返回目录

将一个DirectDrawClipper对象隶属到DirectDrawSurface对象上。

HRESULT SetClipper(

LPDIRECTDRAWCLIPPER lpDDClipper

);

参数：

lpDDClipper

一个DirectDrawClipper对象的地址，将被隶属到DirectDrawSurface对象上。如果该参数为NULL，当前隶属于该DirectDrawSurface对象的DirectDrawClipper对象将被脱离。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_NOCLIPPERATTACHED

备注：

该函数主要应用于被覆盖的页面或将位块传送到主页面的页面。然而，它可以被任何一个页面所使用。在一个DirectDrawClipper对象被隶属到一个页面，并且将一个裁剪表与之联系上之后，DirectDrawClipper对象可以被用做IDirectDrawSurface3::Blt，IDirectDrawSurface3::BltBatch，和IDirectDrawSurface3::UpdateOverlay操作，包括父DirectDrawSurface对象。该函数也可以使当前隶属于该DirectDrawSurface对象的DirectDrawClipper对象脱离。

如果该函数对于同一个页面调用了多次，并且每次都使用同一个DirectDrawClipper对象，该对象的引用记录只会递增一次，后来的调用并不会影响到该DirectDrawClipper对象的引用记录。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::GetClipper

IDirectDrawSurface3::SetColorKey
返回目录

设置DirectDrawSurface对象的关键色的值，如果硬件支持关键色的话。

HRESULT SetColorKey(

DWORD dwFlags,

LPDDCOLORKEY lpDDColorKey

);

参数：

dwFlags

指定要设置哪种关键色：

DDCKEY_COLORSPACE

如果关键色结构中包含了一个色彩空间，设置此标志。如果关键色结构中只包含了单个关键色，则不要设置此标志。

DDCKEY_DESTBLT

指定该关键色为位块传送操作中的目标关键色。

DDCKEY_DESTOVERLAY

指定该关键色为覆盖操作中的目标关键色。

DDCKEY_SRCBLT

指定该关键色为位块传送操作中的源关键色。

DDCKEY_SRCOVERLAY

指定该关键色为覆盖操作中的源关键色。

lpDDColorKey

一个DDCOLORKEY结构的地址，包含了DirectDrawSurface对象的新的关键色的值。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_NOOVERLAYHW

DDERR_NOTAOVERLAYSURFACE

DDERR_SURFACELOST

DDERR_UNSUPPORTED

DDERR_WASSTILLDRAWING

备注：

对于透明位块传送来说，你应该设置目标关键色到目标页面上，设置源关键色到源页面上。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::GetColorKey

IDirectDrawSurface3::SetOverlayPosition
返回目录

改变一个覆盖页面的显示坐标。

HRESULT SetOverlayPosition(

LONG lX,

LONG lY

);

参数：

lX and lY

新的x和y显示坐标。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDPOSITION

DDERR_NOOVERLAYDEST

DDERR_NOTAOVERLAYSURFACE

DDERR_OVERLAYNOTVISIBLE

DDERR_SURFACELOST

DDERR_UNSUPPORTED

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::GetOverlayPosition，IDirectDrawSurface3::UpdateOverlay

IDirectDrawSurface3::SetPalette
返回目录

将一个指定的DirectDrawPalette对象隶属到页面上。页面使用这个调色板用于以后所有的操作。调色板的改变是立即发生的，不用考虑刷新时间。

HRESULT SetPalette(

LPDIRECTDRAWPALETTE lpDDPalette

);

参数：

lpDDPalette

将隶属到页面上的DirectDrawPalette对象的地址。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDPIXELFORMAT

DDERR_INVALIDSURFACETYPE

DDERR_NOEXCLUSIVEMODE

DDERR_NOPALETTEATTACHED

DDERR_NOPALETTEHW

DDERR_NOT8BITCOLOR

DDERR_SURFACELOST

DDERR_UNSUPPORTED

备注：

如果对同一页面和同一调色板多次调用该函数，调色板的引用记录只会递增一次，以后的调用不会影响到调色板的引用记录。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::GetPalette，IDirectDraw2::CreatePalette

IDirectDrawSurface3::SetSurfaceDesc
返回目录

设置页面的特性描述。该函数是IDirectDrawSurface3接口新增的。

HRESULT IDirectDrawSurface3::SetSurfaceDesc(

LPDDSURFACEDESC lpddsd,

DWORD dwFlags

);

参数：

lpddsd

一个DDSURFACEDESC结构的地址，包含了页面新的特性描述。

dwFlags

该参数尚未使用，只能设为0。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDPARAMS

DDERR_INVALIDOBJECT

DDERR_SURFACELOST

DDERR_SURFACEBUSY

DDERR_INVALIDSURFACETYPE

DDERR_INVALIDPIXELFORMAT

DDERR_INVALIDCAPS

DDERR_UNSUPPORTED

DDERR_GENERIC

备注：

目前，该函数只能用于设置存在于系统主存中的显性页面的页面数据和像素格式。这是很有用的，因为它允许页面不需要进行复制而使用与先前页面一样的数据。新的页面内存被客户程序所分配，同样，客户程序也必须释放这些内存。要得到更多关于如何使用该函数的资料，请参阅“更新页面属性”。

不正确的使用该函数，将导致不可预知的行为。DirectDrawSurface对象不会收回那些没有分配的页面内存。因此，当页面内存不再需要时，必须及时收回内存。然而，当该函数被调用时，DirectDraw将释放它原先创建该页面时隐性分配的页面内存。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::Unlock
返回目录

页面解锁。告诉DirectDraw，直接页面访问已经结束。

HRESULT Unlock(

LPVOID lpSurfaceData

);

参数：

lpSurfaceData

要解锁的页面区域的内存地址，是由调用IDirectDrawSurface3::Lock函数时获得的。只有在调用IDirectDrawSurface3::Lock时指定lpDestRect参数为NULL，表示锁定整个页面时，才能给该参数指定NULL。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_GENERIC

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDRECT

DDERR_NOTLOCKED

DDERR_SURFACELOST

备注：

因为对同一个页面多次调用IDirectDrawSurface3::Lock函数以锁定不同的区域是可能的，lpSurfaceData参数将使得IDirectDrawSurface3::Unlock函数与相应的IDirectDrawSurface3::Lock函数对应上。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::Lock

IDirectDrawSurface3::UpdateOverlay
返回目录

重新定位一个覆盖页面，或修改其视觉属性。这些页面在创建时必须提供了DDSCAPS_OVERLAY标志。

HRESULT UpdateOverlay(

LPRECT lpSrcRect,

LPDIRECTDRAWSURFACE3 lpDDDestSurface,

LPRECT lpDestRect,

DWORD dwFlags,

LPDDOVERLAYFX lpDDOverlayFx

);

参数：

lpSrcRect

一个RECT结构的地址，定义了源页面上作为覆盖区域的x、y、宽度和高度。当隐藏一个覆盖层，或指定整个覆盖页面将被使用（该覆盖页面遵循设备驱动所规定的所有边界和大小的限制），该参数可以是NULL。

lpDDDestSurface

指向目标页面（被覆盖的DirectDrawSurface对象）的指针的地址。

lpDestRect

一个RECT结构的地址，定义了目标页面上作为被覆盖区域的x、y、宽度和高度。当要隐藏覆盖层的时候，该参数可以是NULL。

dwFlags

DDOVER_ADDDIRTYRECT

Adds a dirty rectangle to an emulated overlaid surface.

DDOVER_ALPHADEST

使用像素格式的alpha信息，或隶属于目标页面的alpha通道页面，作为该覆盖层的alpha通道。

DDOVER_ALPHADESTCONSTOVERRIDE

使用DDOVERLAYFX结构的dwAlphaDestConst成员作为该覆盖层的目标alpha通道。

DDOVER_ALPHADESTNEG

指定目标页面的透明度随着alpha值的增大而增大（0为不透明）。

DDOVER_ALPHADESTSURFACEOVERRIDE

使用DDOVERLAYFX结构的lpDDSAlphaDest成员作为该覆盖层的alpha通道目标。

DDOVER_ALPHAEDGEBLEND

使用DDOVERLAYFX结构的dwAlphaEdgeBlend成员作为围绕着关键色边缘的图象的alpha通道。

DDOVER_ALPHASRC

使用像素格式的alpha信息，或隶属于源页面的alpha通道页面，作为该覆盖层的源alpha通道。

DDOVER_ALPHASRCCONSTOVERRIDE

使用DDOVERLAYFX结构的dwAlphaSrcConst成员作为该覆盖层的源alpha通道。

DDOVER_ALPHASRCNEG

指定源页面的透明度随着alpha值的增大而增大（0为不透明）。

DDOVER_ALPHASRCSURFACEOVERRIDE

使用DDOVERLAYFX结构的lpDDSAlphaSrc成员作为该覆盖层的alpha通道源。

DDOVER_AUTOFLIP

每当一个视频端口发出VSYNC消息时，自动换页到换页链中的下一个页面。

DDOVER_DDFX

使用lpDDOverlayFx参数的dwDDFX成员来指定特殊的覆盖效果。

DDOVER_HIDE

关闭此覆盖层。

DDOVER_KEYDEST

使用与目标页面相关联的关键色。

DDOVER_KEYDESTOVERRIDE

使用DDOVERLAYFX结构的dckDestColorkey成员作为目标页面关键色。

DDOVER_KEYSRC

使用与源页面相关联的关键色。

DDOVER_KEYSRCOVERRIDE

使用DDOVERLAYFX结构的dckSrcColorkey成员作为源页面的关键色。

DDOVER_SHOW

启用该覆盖层。

lpDDOverlayFx

一个DDOVERLAYFX结构的地址，表示要使用的效果。如果dwFlags 参数没有设置DDOVER_DDFX标志，该参数可以是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

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

IDirectDrawSurface3::UpdateOverlayDisplay
返回目录

The IDirectDrawSurface3::UpdateOverlayDisplay method repaints the rectangles in the dirty rectangle list of all active overlays. This clears the dirty rectangle list. This method is for software emulation only緄t does nothing if the hardware supports overlays.

HRESULT UpdateOverlayDisplay(

DWORD dwFlags

);

参数：

dwFlags

更新的类型。下列标志之一：

DDOVER_REFRESHDIRTYRECTS

Updates the overlay display using the list of dirty rectangles previously constructed for this destination. This clears the dirty rectangle list.

DDOVER_REFRESHALL

Ignores the dirty rectangle list and updates the overlay display completely. This clears the dirty rectangle list.

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_INVALIDSURFACETYPE

DDERR_UNSUPPORTED

备注：

该函数目前尚不能执行。

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::AddOverlayDirtyRect

IDirectDrawSurface3::UpdateOverlayZOrder
返回目录

设置一个覆盖层的z-order（z轴顺序）。

HRESULT UpdateOverlayZOrder(

DWORD dwFlags,

LPDIRECTDRAWSURFACE3 lpDDSReference

);

参数：

dwFlags

下列标志之一：

DDOVERZ_INSERTINBACKOF

在覆盖链中，将该覆盖层置于指定的覆盖层之后。

DDOVERZ_INSERTINFRONTOF

将给覆盖层置于指定的覆盖层之前。

DDOVERZ_MOVEBACKWARD

将该覆盖层置后一位。

DDOVERZ_MOVEFORWARD

将该覆盖层置前一位。

DDOVERZ_SENDTOBACK

将该覆盖层置于最底层。

DDOVERZ_SENDTOFRONT

将该覆盖层置于最高层。

lpDDSReference

一个覆盖页面的地址，作为覆盖链中的参照页面。只有在使用了DDOVERZ_INSERTINBACKOF或DDOVERZ_INSERTINFRONTOF标志后才需要指定该参数。

返回值：

如果函数调用成功，返回DD_OK。

如果函数调用失败，返回值可能是下列错误值之一：

DDERR_INVALIDOBJECT

DDERR_INVALIDPARAMS

DDERR_NOTAOVERLAYSURFACE

快速信息：

Windows NT：适用于4.0或更新版

Windows：适用于Windows 95或更新版

Windows CE：不支持

头文件：ddraw.h

库文件：ddraw.lib

请参阅：

IDirectDrawSurface3::EnumOverlayZOrders

返回目录