DirectDraw函数、结构参考：IDirectDrawSurface3接口

最新推荐文章于 2015-04-21 10:39:54 发布

xah18

最新推荐文章于 2015-04-21 10:39:54 发布

阅读量4.5k

点赞数

分类专栏： WinCE编程文章标签： windows null struct 工作 exception list

WinCE编程专栏收录该内容

9 篇文章 0 订阅

订阅专栏

应用程序使用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。