 关于 DirectDraw 中文手册

DirectX 编程是现在图形编程特别是游戏编程的热点.而广大的 DirectX 编程爱好者被其帮助文档中的英文所苦,于是民间有不少的爱好者开始自己翻译其手册为中文,然后放在网上让大家共享.然而,由于缺乏组织,很多人都在做着重复的工作,结果浪费了很多的时间和精力.如果把这些自发的力量组织起来,无疑是件很有意义的事.而实现跨地域的组织工作,正是 Internet 的特长.因此我们决定在国际互联网上建立一个站点来专门进行 DirectX 手册的翻译组织工作,然后把翻译过的作品放在我们的主页上让每一个需要的人都可以得到.

您现在使用的是 DirectDraw 部件的中文手册,除了例程部分以及一些6.1版新增的内容我们基本译完了.

这个手册的绝大部分(80%)是我根据DirectX 工作室的站长老王的中文手册整理的,在此我们说声:"谢谢老王!"

我在整理的一开始是根据英文手册逐句仔细校对的,但后来发现这无异于我再重译一遍,因此后来就只整理不校对了.其实整理比较对还要痛苦,因为完全是机械操作.

我只翻译了指南部分,内容不多.翻译到快结束的时候发现了朱春喜&吴佳鲜的版本,参考了一下,同样表示感谢.

中文手册中保留了英文手册中原来所有的链接(这正是整理时最烦人的地方),由于很多链接指向术语表(Glossary),因此虽然没有翻译我也把它加进来了,它也很小.

中文手册的格式本来应该与英文手册完全相同,因为使用了样式表文件.但事实上没有做到,应该是编译的问题.

希望我们的工作能给您带来方便,另一方面我们也需要您的支持.如果您愿意,可以加入我们的翻译阵营,加入的具体方法请看我们的主页.如果您由于时间精力等等的原因不能直接加入进来,您也可以写信告诉我们中文手册中的任何不足和错误,这会是对我们工作的最大支持.

这一版本的最终更新时间是1999年9月15日,如果您要得到更新的版本以及 DirectX 其他部件(现有 Direct3D 立即模式和 Direct3D 保留模式)的中文手册请访问我们的主页:DirectX 中文手册(http://cdirectx.yeah.net).我们的主页上还有其它相关的教程,例程,资源等,一定要来哟!

jfly
1999.9.15


About DirectDraw

关于 DirectDraw

DirectDraw 是 DirectX 应用程序编程接口(API)的一个部件.它使得你可以直接地对显存操作,硬件位图映射(hardware blitter).支持硬件覆盖及换页技术(flipping surface). DirectDraw 提供这些功能的同时保证了对现有基于 Microsoft Windows 的应用程序及设备驱动程序的兼容.

DirectDraw 为你提供了一个直接访问显示设备的软件接口,并同时保证了与 Windows 图形设备接口(GDI)的兼容. DirectDraw 并不是一种高层的图形程序编程接口(API).它为游戏和 Windows 子系统软件,例如 3D 图形包和数字视频编码(codecs),提供了一种设备无关的路径,以获得访问特定的显示设备的某些高级特性的能力。

DirectDraw 可以使用于多种的显示设备.从简单的 SVGA 显示器到提供裁剪,缩放(stretching),和支持非 RGB 颜色格式的高级硬件实现设备.设计这样的接口是为了让你的应用程序能够列举低层硬件的能力,并且对那些支持的硬件加速特性加以利用.那些在硬件设备中不能实现的特性, DirectX 将仿真出来.

DirectDraw 提供了对显存的设备相关访问的设备无关途径.本质上,由 DirectDraw 管理显存.你的应用程序只需要懂得那些一般的关于硬件与设备的知识，比如 RGB 和 YUV 色彩格式和两条光栅线之间的宽距(pitch).在需要利用位转换或操作调色板寄存器时,你不需要为调用过程中的细节而烦恼.使用 DirectDraw, 你可以方便的操作显存,充分的利用不同类型的显示设备的位转换和颜色压缩能力,而不需要依赖于某一种特定的硬件.

DirectDraw 给运行于 Windows 95 和 Windows NT 4.0 或更高版本的计算机提供了一个高性能的的游戏图象引擎.


Why Use DirectDraw?

为什么使用 DirectDraw?

DirectDraw 部件为您, Windows 图形程序员带来了许多强有力的特性:

  • DirectDraw 的硬件抽象层(hardware abstraction layer-HAL)提供了一个统一的接口,通过它,开发者可以直接的操作显示存储器和视频存储器,从系统硬件中获取最大的表现能力.
  • DirectDraw 可以充分评估视频硬件的能力,只要可能,它就会对其某一特性加以利用.例如,如果你的显卡支持硬件 Blit, DirectDraw 就会将位图映射这一操作分派给显卡来完成,极大的提升运行速度.此外,当某硬件不支持某项特性时, DirectDraw 还提供了硬件仿真层(HEL)以完成这项操作.
  • DirectDraw 运行于 Windows95 操作系统之上,从系统所提供的32位内存寻址和平面内存模型中获益. DirectDraw 将视频和系统存储器视为整块的空间,而不是碎片的集合.如果你曾使用过区段偏移寻址,你将很快就喜爱上这种"平面"内存模型.
  • 对于全屏模式的应用程序, DirectDraw 使得多后台缓存(back buffers)的换页(page flipping)操作变得极为容易.要得到更多的信息,参看换页和后台缓存.
  • 支持窗口和全屏模式应用程序的裁剪.
  • 支持 3-D Z 缓存.
  • 支持带 Z 轴方向的硬件辅助覆盖.
  • 可访问图象缩放(stretching)硬件.
  • 可同时访问标准的和增强的显示设备内存区.
  • 其它的特性,包括动态改变调色板,独占访问硬件,和分辨率切换等等.

合理和有效的利用 DirectDraw 的这些特性将使开发者很容易就能够写出比基于标准的 Windows GDI 应用程序,甚至 MS-DOS 应用程序还要优秀的作品.


Getting Started: Basic Graphics Concepts

起步:基本图形概念

这部分提供了对 DirectDraw 图形编程的一个概览.这里提及的每个概念都先给出一个非技术性的总览,然后介绍了 DirectDraw 是怎么支持它的.

想从这部分概览中获益你不需要是个图形编程高手(如果那样的话你完全可以跳过这部分,而到 DirectDraw 核心那部分去查看更详细的内容),只要你熟悉 C 和 C++ 的 Windows 编程,你将不会遇到什么困难.当你读完这部分内容之后,你将对 DirectDraw 图形编程的基本概念获得一致的了解.

请参看以下主题:

  • 设备无关位图(Device-Independent Bitmaps)
  • 画图页面(Drawing Surfaces)
  • 位块传送(Blitting)
  • 翻页和后台缓存(Page Flipping and Back Buffering)
  • 矩形(Introduction to Rectangles)


Device-Independent Bitmaps

设备无关位图(Device-Independent Bitmaps)

Windows 中,当然还包括 DirectX, 都使用设备无关位图 DIB(Device-Independent Bitmap) 作为其最基本的图象文件格式.从本质上说, DIB 是一个包含了图象的各种信息的文件,包括图象的尺寸,使用的颜色个数及其颜色值,还有每个像素的颜色数据等.此外,一个 DIB 中还包含了一些极少使用的参数.象文件压缩类型,重要颜色,还有图象的物理维数等. DIB 文件通常具有".bmp"扩展名,偶尔也会将".dib"作为其扩展名.

因为 DIB 在 Windows 程序设计中是一个非常普遍的问题,在平台 SDK 中已经包含了许多可以在 DirectX 中使用的函数.例如,在下面这个从平台 SDK 的 DirectX APIs 里选取的 Ddutil.cpp 文件中的一个程序定义的函数里我们可以看到联合使用 Win32 和 DirectX 函数装载一个 DIB 位图到 DirectX 表面的例子.

extern "C" IDirectDrawSurface * DDLoadBitmap(IDirectDraw *pdd,
    LPCSTR szBitmap, int dx, int dy)
{
    HBITMAP             hbm;
    BITMAP              bm;
    DDSURFACEDESC       ddsd;
    IDirectDrawSurface *pdds;

    //
    //  This is the Win32 part.
    //  Try to load the bitmap as a resource.
    //  If that fails, try it as a file.
   //
    hbm = (HBITMAP)LoadImage(
            GetModuleHandle(NULL), szBitmap,
            IMAGE_BITMAP, dx, dy, LR_CREATEDIBSECTION);

    if (hbm == NULL)
        hbm = (HBITMAP)LoadImage(
                NULL, szBitmap, IMAGE_BITMAP, dx, dy,
                LR_LOADFROMFILE|LR_CREATEDIBSECTION);

    if (hbm == NULL)
        return NULL;

    //
    // Get the size of the bitmap.
    //
    GetObject(hbm, sizeof(bm), &bm);

    //
    // Now, return to DirectX function calls.
    // Create a DirectDrawSurface for this bitmap.
    //
    ZeroMemory(&ddsd, sizeof(ddsd));
    ddsd.dwSize = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT |DDSD_WIDTH;
    ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
    ddsd.dwWidth = bm.bmWidth;
    ddsd.dwHeight = bm.bmHeight;

    if (pdd->CreateSurface(&ddsd, &pdds, NULL) != DD_OK)
        return NULL;

    DDCopyBitmap(pdds, hbm, 0, 0, 0, 0);

    DeleteObject(hbm);

    return pdds;
}

要得到 DIB 文件更详细的信息,请参看平台 SDK.


Drawing Surfaces

画图页面(Drawing Surfaces)

画图页面接受视频数据在屏幕上最终显示为图像(准确地说,位图).在大多数 Windows 程序中,你通过使用 Win32 的 GetDC 等函数来访问画图页面,这表示你获得设备描述表(device context:DC).在你获得设备描述表之后,你就可以在屏幕上作图了.然而, Win32 作图函数由操作系统中与 DirectX 完全不同的一部分支持,即图形设备接口(GDI). GDI 是为标准 Windows 应用程序在屏幕上作图提供提取层(abstraction layer)的操作系统部件.

GDI 的缺点在于它并不是为高性能的多媒体软件设计的,它是用来设计商业应用程序的,比如字处理器,电子表格等等.通过 GDI 可以访问系统内存的视频缓冲,但不能访问显示内存,也不能充分利用一些显卡提供的特殊性能.简单的说, GDI 对大多数商业程序来说已经远远足够,但对于多媒体或游戏软件来说它就太慢了.

另一方面, DirectDraw 为你提供了描述真正的显示内存的画图页面.这意味着当你使用 DirectDraw 的时候,你可以直接对显卡上的内存读写,这就极大的提高了你的图形程序速度.同时,这些页面表现为连续的内存块,这使得你可以很容易的进行地址操作.

要得到更详细的信息,参看页面.


Blitting

位块传送(Blitting)

blit 是 "Bit block transfer" 的缩写,意即将内存中的数据块从一处传送到另一处.图形程序员使用 Blit 将图像从内存中的一处传送到另一处. Blit 常常被用来做精灵动画(sprite animation),这将在后面提到.

要得到关于 DirectDraw 中位块传送更多的信息,请参看 Blit 到页面.


Page Flipping and Back Buffering

翻页和后台缓存(Page Flipping and Back Buffering)

在多媒体动画,动感游戏等软件中,翻页(Page flipping)是一个相当关键的概念.计算机中的翻页技术与绘画师绘制动画片具有相似之处:绘画师在一叠相同的纸上绘画,在每一张上,绘画师使画面有略微的改动.于是,当你在这一叠纸快速的翻页时,静止的图象便开始运动起来.

DirectDraw 中的翻页与上面这个过程极为相似.首先,你得设置好一个翻页链结构,它由一组 DirectDraw 页面组成,每一个页面都可以被轮流翻页至显示屏幕.当前正好位于显示屏幕的页面,我们称之为主页面(primary surface),其后等待翻页至屏幕的页面,我们称之为后台缓存(Back buffers).应用程序在后台缓存上进行绘图操作,然后将此页面翻页成为主页面,原来的后台缓存就显示在屏幕上了.当操作系统在屏幕上显示图像时,你再对后台缓存进行新的操作.这个过程可以不断持续下去,你的动画就变得快速而高效.

DirectDraw 使得整个翻页(page flipping)的任务十分的简单.你既可以创建一个简单的双缓存翻页链结构(一个主页面和一个后台缓存),也可以创建一个使用起来更为灵活的多后台缓存翻页链结构.要得到更多的信息,请参看 DirectDraw 指南 和 换页(Flipping Surfaces).


Introduction to Rectangles

矩形(Introduction to Rectangles)

在 Windows 编程中,屏幕上的对象都是以一个封闭矩形的形状出现的.矩形的边通常都平行于屏幕,因此一个封闭的矩形可以用两个点来确定,左上角和右下角.绝大多数应用程序使用 RECT 结构来定义一个封闭矩形,用于 blit 操作或碰撞检测(hit detection). RECT 结构定义如下:

typedef struct tagRECT {
    LONG    left;    // This is the top-left corner's x-coordinate.
    LONG    top;     // The top-left corner's y-coordinate.
    LONG    right;   // The bottom-right corner's x-coordinate.
    LONG    bottom;  // The bottom-right corner's y-coordinate.
} RECT, *PRECT, NEAR *NPRECT, FAR *LPRECT;

其中 left 和 top 是左上角的 x, y 轴坐标. right 和 bottom 是右下角的 x, y 轴坐标.请参考如下的示意图:

为了高效性,一致性和易用性,所有的 DirectDraw 的 blit 函数都使用矩形工作.然而,你也可以通过使用透明 blit 来实现非矩形 blit. 要得到更详细的信息,请参看透明 blit(Transparent Blitting).


DirectDraw Architecture

DirectDraw 构架(DirectDraw Architecture)

这部分讨论了 DirectDraw 与 DirectX 其他部件,操作系统,系统硬件之间的关系.请参看以下内容:

  • DirectDraw 构架总览(Architecture Overview for DirectDraw)
  • DirectDraw 对象类型(DirectDraw Object Types)
  • 硬件抽象层(Hardware Abstraction Layer-HAL)
  • 软件仿真(Software Emulation)
  • 系统集成(System Integration)


Architectural Overview for DirectDraw

DirectDraw 构架总览(Architecture Overview for DirectDraw)

多媒体应用程序及游戏需要高表现力的图形引擎. Microsoft 公司通过 DirectDraw, 为广大开发者提供了一个比 GDI 层次更高,功能更强,操作更有效,速度更快的应用程序图象引擎.与此同时,也努力使其保持了设备无关的优良特性. DirectDraw 提供了完成以下关键任务的工具:

  • 管理多页面
  • 直接访问视频内存
  • 换页(Page flipping)
  • 后台缓存(Back buffering)
  • 管理调色板(Palette)
  • 裁剪(Clipping)

除此之外, DirectDraw 允许开发者在应用程序运行期测定显示硬件的特性,然后,充分利用主机硬件设备的加速特性为用户提供可能的最优的显示速度和效果.

与 DirectX 其它组件一样,只要可能, DirectDraw 就会最高程度的利用硬件执行某特定功能,并且让那些该硬件还不支持的特性也能用软件仿真的方式加以实现.设备无关性通常是通过硬件抽象层(HAL:Hardware abstraction layer)实现的,要得到更多的关于 HAL 的资料,请参阅硬件抽象层(HAL).

DirectDraw 是通过基于 COM 的接口提供服务.在最新的版本中,这些接口分别是: IDirectDraw4, IDirectDrawSurface4, IDirectDrawPalette, IDirectDrawClipper, 和 IDirectDrawVideoPort. DirectX 的这些组件是向下兼容的,它们仍然支持旧版本中的所有功能.不存在 IDirectDraw3 接口,接口版本从 IDirectDraw2 跳到 IDirectDraw4.

要得到更多的关于 COM 的概念,以有助于理解和创建 DirectX 应用程序,请参阅 DirectX与部件对象模型(COM).

DirectDraw 对象代表显示适配器,并且通过 IDirectDraw, IDirectDraw2, 和 IDirectDraw4 接口将其方法暴露于开发者.在大多数情况下,开发者使用 DirectDrawCreate 函数创建一个 DirectDraw 对象,但也可以通过使用 CoCreateInstance COM 函数创建之.要得到更多的资料,请参阅用 CoCreateInstance 创建 DirectDraw 对象.

在 DirectDraw 对象创建好之后,你可以通过使用 IDirectDraw4::CreateSurface 方法为该 DirectDraw 对象创建页面.页面代表了位于显示硬件上的内存,但是它既可以存在于视频内存,也可以存在于系统内存中. DirectDraw 还扩展了对调色板,裁剪(主要用于基于窗口的应用程序)和视频端口(Video port)的支持.


DirectDraw Object Types

DirectDraw 对象类型(DirectDraw Object Types)

你可以将 DirectDraw 视为由若干个协同工作的对象所组成,这些对象可以按类型来分类.要得到更多的信息,请参阅 DirectDraw 核心.

以下的文字介绍了 DirectDraw 所使用的对象:

DirectDraw 对象
DirectDraw 对象是 DirectDraw 应用程序的核心.它是你在建立 DirectDraw 应用程序时所要创建的第一个对象,再用它来创建所有其它相关的对象.通过调用 DirectDrawCreate 函数可以创建一个 DirectDraw 对象. DirectDraw 对象通过 IDirectDraw, IDirectDraw2, 和 IDirectDraw4 接口为开发者提供其函数性.要得到更多的资料,请参阅 DirectDraw 对象.
DirectDrawSurface 对象
DirectDrawSurface 对象,通常简称为"页面(Surface)",代表了内存中的一块区域,它存储了可以显示在显示器上的图象数据.通过调用 DirectDraw 对象的 IDirectDraw4::CreateSurface 函数可以创建一个与该 DirectDraw 对象相关联的页面. DirectDrawSurface 对象通过 IDirectDrawSurface, IDirectDrawSurface2, IDirectDrawSurface3, 和 IDirectDrawSurface4 接口为开发者提供其函数性.要得到更多的信息,请参阅页面.
DirectDrawPalette 对象
DirectDrawPalette 对象,通常简称为"调色板(Palette)",代表了一个可以为页面所使用的16或256色的调色板.它包含了一组 RGB 值的索引,用来描述页面上的像素所使用的颜色值.对于像素位深度大于8的页面,不需要使用调色板.通过调用 IDirectDraw4::CreatePalette 函数,可以创建一个 DirectDrawPalette 对象. DirectDrawPalette 对象通过 IDirectDrawPalette 接口为开发者提供其函数性.要得到更多的资料,请参阅调色板.
DirectDrawClipper 对象
DirectDrawClipper 对象，通常简称为"裁剪器(Clipper)",帮助开发者使 Blit(位块传送)操作限定在页面的某一区域内,或不超出页面的边界范围.通过调用 IDirectDraw4::CreateClipper 函数可以创建一个 DirectDrawClipper 对象. DirectDrawClipper 对象通过 IDirectDrawClipper 接口为开发者提供其函数性.要得到更多的资料,请参阅裁剪器.
DirectDrawVideoPort 对象
DirectDrawVideoPort 对象代表了当前某些系统上的视频端口(Vedio port)硬件.这个硬件允许直接的访问帧缓存,而不需要通过 CPU 或使用 PCI 总线.通过对 DirectDRaw 对象调用 QueryInterface 函数(指定 IID_IDDVideoPortContainer 标志符),可以创建一个 DirectDrawVideoPort 对象. DirectDrawVideoPort 对象通过 IDDVideoPortContainer 和 IDirectDrawVideoPort 接口为开发者提供其函数性.要得到更多的资料,请参阅视频端口.


Hardware Abstraction Layer (HAL)

硬件抽象层(Hardware Abstraction Layer)

DirectDraw 通过硬件抽象层(以后简称为HAL)来提供设备无关的特性. HAL 是由设备生产商提供的指定设备的接口, DirectDraw 用来直接操作显示硬件.应用程序从来不会直接与 HAL 打交道,相反,而是与 HAL 所提供的下属函数打交道. DirectDraw HAL 可以以16位,32位或在 Win95 中两者兼而有之的形式执行. HAL 在 WinNT 中通常以32位方式执行. HAL 可以是显示设备驱动程序的一部分,或独立的 DLL,通过驱动程序编写者定义的一个私有接口联系显示驱动.

DirectDraw HAL 是由芯片制造商,板卡生产商或原始设备制造商(OEM)实现的. HAL 只执行硬件有关代码而不进行仿真.如果硬件不能实现某个功能, HAL 不会将其反映在自己的硬件特性中.


Software Emulation

软件仿真(Software Emulation)

当硬件抽象层(HAL)不支持某种特性时, DirectDraw 会试图进行软件仿真.仿真的函数是由硬件仿真层(HEL)提供的. HEL 与 HAL 一样,代表了 DirectDraw 的特性,并且应用程序从来不直接与 HEL 一起工作.结果是, DirectDraw 对硬件的主要特性都提供了透明的支持,而不管这个特性是通过 HAL 硬件支持的还是通过 HEL 软件仿真的.

很显然,软件仿真不能与硬件所提供的特性等效.可以调用 IDirectDraw4::GetCaps 函数以查询硬件支持什么特性.在应用程序初始化的时候检查这些特性,你可以调整应用程序的参数以提供优化的性能.

在有些情况下,硬件特性与软件仿真的组合操作反而会比单纯使用软件仿真效率更低.例如,如果显示设备驱动程序支持 DirectDraw, 但不支持带缩放的 Blit 操作,在从视频内存页面进行带缩放的 Blit 操作时,将导致明显的速度降低.这是因为有些视频内存的速度要比系统内存慢,迫使在访问视频内存页面的时候, CPU 进入等待状态.如果你的应用程序使用硬件不支持的特性,某些时候,在系统内存中创建页面更为合适,这样才能避免 CPU 访问视频内存时的效率损失.

要得到更多的信息,请参阅硬件提取层(HAL).


System Integration

系统集成(System Integration)

下图展示了 DirectDraw, 图形设备接口(GDI),硬件抽象层(HAL)和硬件仿真层(HEL)四者之间的关系.

如上图所示, DirectDraw 对象与 GDI 位于同一层次,都通过一个设备相关的抽象层来直接访问硬件设备.与 GDI 不同的是, DirectDraw 会尽可能的利用硬件的加速特性.如果硬件不支持某特性, DirectDraw 会使用 HEL 试图将该特性进行软件仿真. DirectDraw 可以以设备环境(DC)的形式提供页面内存,使得开发者可以使用 GDI 的函数操作页面对象.


DirectDraw Essentials

DirectDraw 核心(DirectDraw Essentials)

这一部分讨论 DirectDraw 的主要核心内容.相关信息被组织为如下几组:

  • 控制级(Cooperative Levels)
  • 显示模式(Display Modes)
  • DirectDraw 对象(The DirectDraw Object)
  • 页面(Sufaces)
  • 调色板(Palettes)
  • 裁剪器(Clippers)
  • 多显示器系统(Multiple Monitor Systems)
  • 高级 DirectDraw 主题(Advanced DirectDraw Topics)


Cooperative Levels

控制级(Cooperative Levels)

在如下的主题中,介绍了控制级的概念并描述了一些通常会遇到的有用的情景:

  • 关于控制级(Cooperative Levels)
  • 测试控制级(Display Modes)


About Cooperative Levels

关于控制级(About Cooperative Levels)

控制级描述了 DirectDraw 是怎样与显示设备相互作用的,它如何对系统事件产生反应.使用 IDirectDraw4::SetCooperativeLevel 函数可以设置 DirectDraw 的控制级.最主要的是,你使用 DirectDraw 控制级来决定你的应用程序是运行于全屏模式(具有独占的访问视频内存的特性),还是运行于窗口模式.不管怎样, DirectDraw 的控制级具有以下作用:

  • 允许 DirectDraw 使用 Mode X 分辨率.要得到更多的信息,请参阅 Mode X 和 Mode 13 显示模式.
  • 阻止 DirectDraw 释放对显示设备的独占控制,或按 Ctrl+Alt+Del 以重新启动计算机(仅用于独占模式).
  • 允许 DirectDraw 对应用程序进行最小化或最大化控制,作为对系统事件的反应.

普通的控制级表明你的 DirectDraw 应用程序将以窗口的形式运行.在这种控制级下,你将不能改变主页面(primary surface)的调色板,或进行换页(page flipping)操作.

因为 DirectDraw 应用程序可以具有多窗口,所以,在调用 IDirectDraw4::SetCooperativeLevel 设置控制级时,如果应用程序请求了 DDSCL_NORMAL 模式(表明应用程序以普通窗口的形式运行),则不需要提供一个指定窗口的句柄.给窗口句柄参数为 NULL, 所有的窗口都可以被设置为普通的控制级.

当应用程序为全屏并且独占的控制级时,你就可以充分的利用硬件资源了.在这种控制级下,你可以设置自定义和动态的调色板,改变显示器分辨率,紧凑内存,和实现换页操作等.独占模式(也可称为全屏模式)不会妨碍其它的应用程序分配页面内存,也不会阻止它们使用 DirectDraw 或 GDI. 然而,它的确会阻止除了它自己(为活跃状态时)以外的应用程序改变显示模式或调色板.

DirectDraw为全屏,独占的应用程序控制窗口事件,在需要时通过 SetCooperativeLevel 方法向窗口发送 WM_ACTIVATEAPP 消息. DirectDraw 只对顶层窗口发送控制.如果你的应用程序生成的子窗口需要活动的事件消息,你应当使你的子窗体成为子集.

SetCooperativeLevel 函数在内部捆绑了消息进程和一个窗口句柄.如果 SetCooperativeLevel 函数在一个进程中被调用了一次,那么,这个进程就会和一个窗口句柄捆绑起来.如果该函数在同一进程中再次被调用,并且指定了另一个合法的窗口句柄,那么会返回一个 DDERR_HWNDALREADYSET 错误.当 DirectSound 在设置控制级时指定了与 DirectDraw 不同的窗口时,有些应用程序也可能会返回这个错误值,它们必须被设为同一个顶层的窗口句柄.

注意 使用 MFC 的开发者应当注意向 SetCooperativeLevel 方法给出的窗口句柄应当确定为应用程序的顶层窗口,而不是子窗口.要提取你的 MFC 应用程序的顶层窗口句柄,你可以使用如下的代码:

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

参阅,多显示器系统.


Testing Cooperative Levels

测试控制级(Testing Cooperative Levels)

开发人员常常使用 WM_ACTIVATEAPP 和 WM_DISPLAYCHANGE 消息通知应用程序应该恢复或重新生成使用中的页面.有时,应用程序在不需要执行的时候执行了,或者在应该执行的时候没有执行. IDirectDraw4::TestCooperativeLevel 方法使得你有可能获得关于 DirectDraw 对象的控制等级的更多的信息,然后采取适当的步骤继续运行避免发生灾难性的错误.

TestCooperativeLevel 执行成功返回 DD_OK, 如果你的应用程序能够恢复页面那你就继续向下运行.如果失败了,随着你使用的不同的控制级说明了不同的问题:

全屏幕应用程序

全屏幕应用程序将返回 DDERR_NOEXCLUSIVEMODE 错误, 如果它失去了独占设备的访问.比如,用户按下 ALT+TAB 切换到其他应用程序.在这种情况下,可以循环调用 TestCooperativeLevel 直到返回 DD_OK 为止(表示又恢复了独占模式).在循环体内,应用程序应该放弃对 CPU 的占用,以免陷入死循环. Windows 提供了 WaitMessage 或 Sleep Win32 函数来实现这一目标.

任何存在的页面都应该通过调用 IDirectDrawSurface4::Restore 或 IDirectDraw4::RestoreAllSurfaces 来恢复,这样它们的内容将在显示之前被重新装载.

窗口应用程序

窗口应用程序(使用普通控制级)将返回 DDERR_EXCLUSIVEMODEALREADYSET 错误,如果其他应用程序已经取得了独占设备的访问.在这种情况下,在那个应用程序失去独占设备的访问前不应该采取任何行动.这种状况和全屏幕应用程序有点类似;窗口应用程序可以在恢复和重新装载页面前让 TestCooperativeLevel 循环到返回 DD_OK 为止.和前面类似,循环应该放弃对 CPU 的占用,以免发生死循环.

对于窗口应用程序 TestCooperativeLevel 将返回 DDERR_WRONGMODE 错误,如果显示模式改变了.在这种情况下,应用程序在继续执行之前,应当释放并重新生成所有的页面.


Display Modes

这一部分包含了关于 DirectDraw 显示模式的主要信息.讨论了以下的主题:

  • 关于显示模式
  • 测定支持的显示模式
  • 设置显示模式
  • 恢复显示模式
  • Mode X 和 Mode 13 显示模式
  • 支持高分辨率和真彩色


About Display Modes

关于显示模式(About Display Modes)

显示模式指的是显示器的当前设置,描述了显示器的分辨率和位深度,这个信息通常是由显示硬件从主页面传递给显示器的.显示模式是由三个特征定义的:宽,高,位深度.例如,大多数的显示器可以显示宽为640像素,高为480像素的图象,每一个像素的位深度是8.通常我们把这个显示模式称作640x480x8.随着显示模式的尺寸和位深度的增加,它所需要的视频RAM也随之增加.

有两种显示模式:调色板式和非调色板式.对于调色板式显示模式来说,每一个像素的颜色值是以一个相关调色板的索引值来代表.显示模式的位深度决定了调色板中可容纳的颜色数量.举例来说,在8位的调色板显示模式中,每一个像素的值从0到255,该调色板可容纳256个颜色入口.

非调色板式显示模式,就象它的名称所表示的那样,不需要使用调色板.在这种显示模式下,像素的位深度为16,24或32,每个像素分别占用2字节,3字节或4字节,用来描述像素的真实颜色.

主页面,以及在换页链中的所有页面必须符合显示模式的尺寸,位深度和像素格式.要得到更多的信息,请参阅像素格式(Pixel Formats).


Determining Supported Display Modes

测定支持的显示模式(Determining Supported Display Modes)

因为显示硬件(包括显示卡和显示器)的不同,不是所有的显示设备都支持所有的显示模式.要测定某系统所支持的显示模式,应该调用 IDirectDraw4::EnumDisplayModes 函数.设置正确的参数和标志符, EnumDisplayModes 可以列举出该系统所支持的所有的显示模式,或判断是否支持用户所指定的显示模式.该函数的第一个参数 dwFlags 控制该函数的额外选项,在大多数情况下,你应该设置 dwFlags 为0以表明忽略额外的选项.第二个参数 lpDDSurfaceDesc 是一个 DDSURFACEDESC2 结构的地址,包含了要被测定的显示模式信息,通常,该参数被设为 NULL, 以列举出该系统所支持的所有显示模式.第三个参数 lpContext 是你想让 DirectDraw 传递给其回调函数的一个指针,如果在回调函数中不需要任何数据,给该参数值为 NULL. 最后一个参数 lpEnumModesCallback 一个应用程序定义的回调函数的地址,在 DirectDraw 每列举出一个显示模式的时候,该回调函数将被调用.

在调用 EnumDisplayModes 时所提供的回调函数必须符合 EnumModesCallback 函数的原型.每当找到一个硬件所支持的显示模式的时候, DirectDraw 调用该回调函数,并且传递了两个参数.第一个参数是一个 DDSURFACEDESC2 结构的地址,包含了一个支持的显示模式的描述.第二个参数是一个应用程序定义的数据的地址,是在调用 EnumDisplayModes 时所指定的第三个参数.

检查 DDSURFACEDESC2 结构中的值以获得它所描述的显示模式,关键的成员是 dwWidth, dwHeight, 和 ddpfPixelFormat. dwWidth 和 dwHeight 成员代表了显示模式的长和宽, ddpfPixelFormat 成员是一个 DDPIXELFORMAT 结构的地址,它包含了显示模式的位深度信息.

DDPIXELFORMAT 结构不仅包含了显示模式的位深度,还可以告诉你该显示模式是否使用调色板,以及像素格式.如果 dwFlags 成员包含了 PALETTEINDEXED1, DDPF_PALETTEINDEXED2, DDPF_PALETTEINDEXED4 或 DDPF_PALETTEINDEXED8 标志,显示模式的位深度为1,2,4或8,并且每个像素是一个相关调色板的索引.如果 dwFlags 成员包含了 DDPF_RGB 标志,那么该显示模式是非调色板式的,并且它的位深度由 DDPIXELFORMAT 结构中的 dwRGBBitCount 成员所提供.


Setting Display Modes

设置显示模式(Setting Display Modes)

你可以用 IDirectDraw4::SetDisplayMode 来设置显示器的显示模式.该函数的前四个参数用来描述要设置的显示模式的尺寸,位深度以及显示器的刷新率.函数的第五个参数是用来指定额外的选项,目前,唯一可用的标志是 DDSDM_STANDARDVGAMODE, 它将使显示模式被设为 Mode 13, 而不是 Mode X 320x200x8. 如果你要设置另一种分辨率,位深度或 Mode X 模式,不要使用这个参数,并且将其设为0.

尽管你可以指定所需要的显示模式的位深度,但是你不能指定显示硬件的像素格式.要测定显示硬件用于该位深度的 RGB 位掩码,在设置好显示模式之后,调用 IDirectDraw4::GetDisplayMode. 如果当前的显示模式不是基于调色板的,你可以从 dwRBitMask, dwGBitMask 和 dwBBitMask 中获得掩码值来正确的测定 red, green 和 blue 的所在的位.要得到更多的信息,请参阅像素格式掩码.

显示模式可以由多于一个的应用程序改变,只要它们共享同一块显卡.只有当应用程序拥有对 DirectDraw 对象独占的访问,你才可以改变显示模式的位深度.当显示模式被改变的时候,所有的 DirectDrawSurface 对象将丢失它们的页面内存,并且对任何操作不起反应.这时,一个页面的内存必须被重新分配,调用 IDirectDrawSurface4::Restore 函数.

必须重申的是: DirectDraw 的独占模式并不阻止其它的应用程序分配 DirectDrawSurface 对象,也不阻止它们使用 DirectDraw 或 GDI 的函数特性.但是,它确实阻止了其它的应用程序对显示模式或调色板的访问.

注意 你只能从应用程序生成窗口的线程中调用 IDirectDraw4::SetDisplayMode 方法.对于绝大多数的单线程应用程序来讲,这个限制不是问题.


Restoring Display Modes

还原显示模式(Restoring Display Modes)

在应用程序结束的时候,你可以明确的调用 IDirectDraw4::RestoreDisplayMode 函数,使显示器还原到原始的显示模式.如果你使用的是 IDirectDraw4::SetDisplayMode 函数来改变显示模式,并且应用程序具有独占的控制级,那么,当重新设置控制级为普通时,原始的显示模式会自动还原.(这种功能最先在 IDirectDraw2 接口中支持,更新的接口中仍支持.)

如果你使用的是 IDirectDraw 接口,那么你必须明确的调用 RestoreDisplayMode 以还原显示模式.


Mode X and Mode 13 Display Modes

Mode X 与 Mode 13 显示模式(Mode X and Mode 13 Display Modes)

DirectDraw 同时支持 Mode 13 和 Mode X 显示模式.Mode 13是一种线性不可换页的 320x200x8 的基于调色板的显示模式,因为它的16进制 BIOS 模式编号是13,而被广泛的称之为 Mode 13 模式.要得到更多关于它的资料,请参阅 Mode 13 支持. Mode X 是从标准的 VGA Mode 13 模式演化而来的.通过使用 VGA 显示适配器的 EGA 多图象平面系统,它允许开发者使用最多可达 256K 字节的视频内存(而Mode 13仅为64K).

在 Windows 95 系统上, DirectDraw 为所有的显示卡提供了两种 Mode X 模式:320x200x8 和 320x240x8.某些显卡同样也支持线性低分辨率模式.在这种模式中,主页面(primary surface)可以被锁定和直接访问,这在 Mode X 模式中是不可能的.

应用程序在调用 IDirectDraw4::SetCooperativeLevel 函数时,只有使用了 DDSCL_ALLOWMODEX, DDSCL_FULLSCREEN, 和 DDSCL_EXCLUSIVE 标志符,才能使用 Mode X 模式.如果没有指定 DDSCL_ALLOWMODEX 标志符, IDirectDraw4::EnumDisplayModes 将不会列举出 Mode X 模式,并且调用 IDirectDraw4::SetDisplayMode 函数以请求一个 Mode X 模式,将会失败.

Windows 95 和 Windows NT 不直接支持 Mode X 模式,因此,当你的应用程序处于 Mode X 模式时,你将无法使用 IDirectDrawSurface4::Lock 或 IDirectDrawSurface4::Blt 以锁定或 Blit 到主页面(primary surface).你同样也不能对主页面,或 GDI 的屏幕设备环境使用 IDirectDrawSurface4::GetDC 函数. Mode X 模式是在 DDSCAPS2 结构中由 DDSCAPS_MODEX 标志符指定的,该结构是 DDSURFACEDESC2 结构的一部分( DDSURFACEDESC2 结构是由 IDirectDrawSurface4::GetCaps 和 IDirectDraw4::EnumDisplayModes 函数返回的).


Support for High Resolutions and True-Color Bit Depths

支持高分辨率和真彩色(Support for High Resolutions and True-Color Bit Depths)

DirectDraw 支持显示设备驱动所支持的所有屏幕分辨率和色彩位深度. DirectDraw 允许应用程序改变显示模式到计算机显示驱动所支持的任何一个模式,包括24或32位色彩(真彩色)模式.

DirectDraw also supports HEL blitting in true-color surfaces. If the display device driver supports blitting at these resolutions, theDirectDraw 同样也支持对真彩色页面的硬件仿真层(HEL)的 Blit 操作.如果显示设备驱动支持这些分辨率的 Blit 操作,那么硬件 Blitter(hardware blitter)将被用来进行视频内存对视频内存的 Blit 操作.否则, HEL 将被用来完成此项操作.

Windows 95 和 Windows NT 允许用户指定它们所使用的显示器类型. DirectDraw 核对已知的显示模式与已安装的显示器所限制使用的显示模式.如果 DirectDraw 发现所请求的模式与显示器不兼容,对 IDirectDraw4::SetDisplayMode 函数的调用失败.当你调用 IDirectDraw4::EnumDisplayModes 函数时,只有显示器支持的模式才可以被列举出来.


The DirectDraw Object

DirectDraw 对象(The DirectDraw Object)

这部分讨论了 DirectDraw 对象,以及如何通过 IDirectDraw, IDirectDraw2, 或 IDirectDraw4 接口管理他们.讨论了以下主题:

  • 什么是 DirectDraw 对象?
  • IDirectDraw4 的更新
  • 子对象和父对象的生存周期
  • 单进程的多 DirectDraw 对象
  • 使用 CoCreateInstance 创建 DirectDraw 对象


What Are DirectDraw Objects?

什么是 DirectDraw 对象?(What Are DirectDraw Objects?)

DirectDraw 对象是所有 DirectDraw 应用程序的核心,并且与 Direct3D 应用程序形成一个整体.它是你要创建的第一个对象,通过它,你可以创建所有其它相关的对象.典型的,通过调用 DirectDrawCreate 函数可以创建一个 DirectDraw 对象,它代表了 IDirectDraw 接口.如果你想使用该接口的另一个更高级的版本(比如: IDirectDraw4接口),以获得更加优秀的性能,你可以请求获得该接口. (参看获得 IDirectDraw4 接口.) 应注意的是,你可以创建若干个 DirectDraw 对象,每一个都代表了系统已安装的显示设备.

DirectDraw 对象代表显示设备,并且可以利用硬件的加速特性.如果 DirectDraw 对象所实例化的显示设备具有硬件加速,则该对象是硬件加速的.每一特定的 DirectDraw 对象可以管理显示设备及创建页面,调色板,裁剪器对象.例如你可以调用 IDirectDraw4::DirectDrawSurface 方法来创建页面, 或调用 IDirectDraw4::DirectDrawPalette 方法来创建调色板用在页面上.另外, IDirectDraw4 接口用类似的方法创建裁剪器对象.

每次,多于一个的 DirectDraw 对象可以被实例化.最简单的例子是在 Windows 95 系统上使用两台显示器.尽管 Windows 95 并不支持双显示器,但为每一种显示驱动程序配置一个 DirectDraw 硬件抽象层(HAL)是可能的.当缺省的 DirectDraw 对象被实例化时, Windows 95 和 GDI 将使用它所认识的显示驱动程序. Windows 95 和 GDI 不认识的显示驱动程序可与另外一个设备相匹配,独立的 DirectDraw 对象必须通过第二个显示驱动程序的全局唯一标志符(GUID)来创建.这个 GUID 可由 DirectDrawEnumerate 函数获得.

DirectDraw 对象管理它所创建的所有对象.它控制缺省的调色板(如果主页面(primary surface)是8位色彩模式),缺省的关键色(color key),和硬件显示模式.它跟踪哪些资源已经被分配了,以及哪些资源正有待分配.


What's New in IDirectDraw4?

IDirectDraw4 的更新(What's New in IDirectDraw4?)

这部分详细论述了 IDirectDraw4 接口提供的新特性,以及它与先前的版本 IDirectDraw2 接口(没有 IDirectDraw3 接口)的不同. 请参阅一下内容:

  • IDirectDraw4 的新特性
  • 获得 IDirectDraw4 接口

IDirectDraw4 和前作最明显的区别就是如何对页面工作——如何描述页面以及它自动提供了对不同接口的访问.所有跟页面相关的方法在新的接口里参数有了些许的不同.原来在 IDirectDraw2 接口的方法里使用的 DDSURFACEDESC 结构或提取的 IDirectDrawSurface3 接口,在 IDirectDraw4 接口的方法里使用 DDSURFACEDESC2 结构和提取 IDirectDrawSurface4 接口了.

Another behavioral change that IDirectDraw4 introduces affects the lifetimes of child objects with respect to their parent DirectDraw object.要得到更多的信息,请参阅子对象和父对象的生存周期.


New Features in IDirectDraw4

IDirectDraw4 的新特性(New Features in IDirectDraw4)

IDirectDraw4 接口通过增加了一些方法来增强页面管理并使之易用,从而扩展了原先接口的函数性.

IDirectDraw4 接口提供了新的 IDirectDraw4::RestoreAllSurfaces 方法,可以实现仅仅通过一次调用就恢复创建过的所有的页面.

另外,你现在可以通过使用 IDirectDraw4::GetSurfaceFromDC 从 Windows 的设备描述表(device context)中提取 IDirectDrawSurface4 页面接口.


Getting an IDirectDraw4 Interface

获得 IDirectDraw4 接口(Getting an IDirectDraw4 Interface)

DirectX 使用 COM 表明,可以通过提供新的接口而给旧的接口加入新的函数特性,而不影响向下的兼容性. IDirectDraw4 接口取代了原先的 IDirectDraw2 接口.这个新的接口可以通过调用 IUnknown::QueryInterface 方法来获得,如下例所示:

// Create an IDirectDraw4 interface.
LPDIRECTDRAW  lpDD;
LPDIRECTDRAW4 lpDD4;

ddrval = DirectDrawCreate(NULL, &lpDD, NULL);
if(ddrval != DD_OK)
    return;

ddrval = lpDD->SetCooperativeLevel(hwnd,
    DDSCL_NORMAL);
if(ddrval != DD_OK)
    return;

ddrval = lpDD->QueryInterface(IID_IDirectDraw4,
    (LPVOID *)&lpDD4);
if(ddrval != DD_OK)
    return;

上例先创建了一个 DirectDraw 对象,然后再调用 IUnknown::QueryInterface 方法从提取的 IDirectDraw 接口来创建一个 IDirectDraw4 接口.

在获得 IDirectDraw4 接口后,你就可以调用它的方法来充分利用新的特性,增强的功能带来的好处了.因为有些方法可能会因新接口的发布而改动,混合使用一个接口和它的替代者的方法(比如 IDirectDraw2 与 IDirectDraw4 )可能导致意想不到的错误.


Parent and Child Object Lifetimes

子对象和父对象的生存周期(Parent and Child Object Lifetimes)

All objects you'll use in DirectDraw programming梩he DirectDraw object, surfaces, palettes, clippers, and such梠nly exist in memory for as long as another object, such as an application, needs them. The time that passes from the moment when an object is created and placed in memory to when it is released and subsequently removed from memory is known as the object's lifetime. The Component Object Model (COM) followed by all DirectX components dictates that an object must keep track of how many other objects require its services. This number, known as a reference count, determines the object's lifetime. COM also dictates that an object expose the IUnknown::AddRef and IUnknown::Release methods to enable applications to explicitly manage its reference count; make sure you use these methods in accordance to COM rules.

You aren't the only one who is using the IUnknown methods to manage reference counts for objects桪irectDraw objects use them internally, too. When you use the IDirectDraw4 interface (in contrast to IDirectDraw2 or IDirectDraw) to create a "child" object like a surface, the child uses the IUnknown::AddRef method of the "parent" DirectDraw object to increment the parent's reference count.

When your application no longer needs an object, call the Release method to decrement its reference count. When the count reaches zero, the object is removed from memory. When a child object's reference count reaches zero, it calls the parent's IUnknown::Release method to indicate that there is one less object who will be needing the parent's services.

Implicitly allocated objects, such as the back-buffer surfaces in a flipping chain that you create with a single IDirectDraw4::CreateSurface call, are automatically deallocated when their parent DirectDrawSurface object is released. Also, you can only release a DirectDraw object from the thread that created the application window. For single-threaded applications, this restriction obviously doesn't apply, as there is only one thread. If your application created a primary flipping chain of two surfaces (created by a single CreateSurface call) that used an attached DirectDrawClipper object, the code to release these objects safely might look like:

// For this example, the g_lpDDraw, g_lpDDSurface, and
// g_lpDDClip are valid pointers to objects.
void ReleaseDDrawObjects(void)
{
    // If the DirectDraw object pointer is valid,
    // it should be safe to release it and the objects it owns.
    if(g_lpDDraw)
    {
        // Release the DirectDraw object. (This call wouldn't
        // be safe if the children were created through IDirectDraw2
        // or IDirectDraw. See the following note for
        // more information)
        g_lpDDraw->Release(), g_lpDDraw = NULL;

        // Now, release the clipper that is attached to the surfaces.
        if(g_lpDDClip)
            g_lpDDClip->Release(), g_lpDDClip = NULL;

        // Now, release the primary flipping chain. Note
        // that this is only valid because the flipping
        // chain surfaces were created with a single
        // CreateSurface call. If they were explicitly
        // created and attached, then they must also be
        // explicitly released.
        if(g_lpDDSurface)
            g_lpDDSurface->Release(), g_lpDDSurface = NULL;
    }
}

Note Earlier versions of the DirectDraw interface (IDirectDraw2 and IDirectDraw, to be exact) behave differently than the most recent interface. When using these early interfaces, DirectDraw automatically releases all child objects when the parent itself is released. As a result, if you use these older interfaces, the order in which you release objects is critical. In this case, you should release the children of a DirectDraw object before releasing the DirectDraw object itself (or not release them at all, counting on the parent to do cleanup for you). Because the DirectDraw object releases the child objects, if you release the parent before the children, you are very likely to incur a memory fault for attempting to dereference a pointer that was invalidated when the parent object released its children.

Some older applications relied on the automatic release of child objects and neglected to properly release some objects when no longer needed. At the time, this practice didn't cause any negative side effects, however doing so when using the IDirectDraw4 interface might result in memory leaks.


Multiple DirectDraw Objects per Process

单进程的多 DirectDraw 对象(Multiple DirectDraw Objects per Process)

DirectDraw 允许一个进程在需要的时候,可以任意多次的调用 DirectDrawCreate 函数.每次调用后,返回一个唯一的与设备无关的接口.每一个 DirectDraw 对象可以随心所欲的使用,在对象与对象之间没有相互依赖的关系.每个对象的行为就象它是由一个唯一的进程创建的.

因为 DirectDraw 对象之间是不相互依赖的,由一个特定的 DirectDraw 对象创建的 DirectDrawSurface, DirectDrawPalette 和 DirectDrawClipper 对象不应该与其它的 DirectDraw 对象一起使用,因为这些对象会在它的 DirectDraw 对象销毁时而自动被释放.如果它们与其它的 DirectDraw 对象一起使用,调用它们的函数将在它们被销毁时退出.

例外的是, DirectDrawClipper 对象是由 DirectDrawCreateClipper 函数创建的.这些对象与任何特定的 DirectDraw 对象是没有关系的,可以与一个或多个 DirectDraw 对象一起使用.


Creating DirectDraw Objects by Using CoCreateInstance

使用 CoCreateInstance 创建 DirectDraw 对象(Creating DirectDraw Objects by Using CoCreateInstance)

除了用常规的 DirectDrawCreate 方法创建一个 DirectDraw 对象外,你还可以使用 CoCreateInstance 函数,再调用 IDirectDraw4::Initialize 来创建一个 DirectDraw 对象.以下的例程片段描述了这个方法的各步骤.

  1. 在程序的最开始调用 CoInitialize 来初始化 COM 对象,参数为 NULL.
    if (FAILED(CoInitialize(NULL)))
    return FALSE;
  2. 然后,调用 CoCreateInstance 和 IDirectDraw4::Initialize 来创建 DirectDraw 对象.
    ddrval = CoCreateInstance(&CLSID_DirectDraw,
    NULL, CLSCTX_ALL, &IID_IDirectDraw4, &lpdd);
if(!FAILED(ddrval))
    ddrval = IDirectDraw4_Initialize(lpdd, NULL);

    在 CoCreateInstance 函数中,第一个参数 CLSID_DirectDraw 是 DirectDraw 驱动对象类的类标志符, IID_IDirectDraw4 参数指定了要创建的特定的 DirectDraw 对象,最后的 lpdd 参数接收创建的对象.如果调用成功,这个函数返回一个没有初始化的对象.

  3. 在你使用这个 DirectDraw 对象之前,你必须调用 IDirectDraw4::Initialize. 在此之后,你就可以操作和释放该对象,就象它是用 DirectDrawCreate 创建的一样.如果在使用之前,你没有调用 Initialize, 将产生 DDERR_NOTINITIALIZED 错误.

在关闭应用程序之前,请使用 CoUninitialize 来关闭 COM.

CoUninitialize();


Surfaces

这一部分包含了关于 DirectDrawSurface 对象的信息.讨论了以下主题:

  • 页面的基本概念
  • 创建页面
  • 换页
  • Blit 到页面
  • 页面丢失及恢复页面
  • COM Reference Count Semantics for Surfaces
  • 列举页面
  • 更新页面属性
  • 直接访问页面内存
  • Gamma 和色彩控制
  • 覆盖页面
  • 压缩纹理页面
  • 页面私有数据
  • 页面特征值
  • 使用非本地视频缓冲页面
  • 转换色彩和格式
  • 页面和设备描述


Basic Concepts of Surfaces

页面的基本概念(Basic Concepts of Surfaces)

这一部分包含了与 DirectDrawSurface 对象的基本概念有关的信息.讨论了以下的主题:

  • 什么是页面?
  • 页面接口
  • 宽度和宽距
  • 关键色
  • 像素格式


What Are Surfaces?

什么是页面?(What Are Surfaces?)

页面,或被我们称作 DirectDrawSurface 对象,代表了内存里的一个连续的线性的数据区.这个数据区可以被代表显示硬件的 DirectDraw 对象所识别和确认.通常, DirectDrawSurface 对象被置于显卡上的视频内存中,而这并不是绝对的.除非明确的指定是在视频内存还是系统内存中创建 DirectDrawSurface 对象, DirectDraw 可以将其放置在其中任一位置,条件是这样可以获得最佳性能. DirectDrawSurface 对象可以从显卡上的特效处理器上获得好处,不仅仅是通常意义上的加快处理速度,而是可以与系统 CPU 并行工作,以达到最优的效率和速度.

调用 IDirectDraw4::CreateSurface 函数可以创建若干类型的 DirectDrawSurface 对象,包括单页面对象, 复杂页面(complex surface)-换页链,或三维页面. CreateSurface 函数创建我们所请求的页面或换页链,并且返回指向主页面(primary surface)的 IDirectDrawSurface4 接口的指针,通过该接口可以暴露 DirectDrawSurface 对象的函数性.

IDirectDrawSurface3 接口通过 Blit 方法可以使你间接的访问页面内存,例如: IDirectDrawSurface4::BltFast 函数. DirectDrawSurface 对象可以创建 Windows 的 GDI 设备环境句柄(HDC),这样,就可以允许使用 Win32 的 API 函数来访问代表 DirectDrawSurface 对象的页面. GDI 识别这些 HDC(设备环境句柄),如果它们存在于视频内存中,那么就可以获得硬件的加速特性.除此之外,你还可以使用 IDirectDrawSurface4 接口的函数直接访问页面内存.例如:可以使用 IDirectDrawSurface4::Lock 函数锁定页面内存,并且获得指向该页面上相应区域(用户指定的矩形区域)的内存区的地址.视频内存上的地址可以指向可见的祯缓存(存储了当前显示画面的缓冲区,也称作主页面),也可以是不可见的缓存(离屏页面或覆盖页面(overlay surfaces)).不可见的缓存通常被置于视频内存中,但是如果是受硬件限制或 DirectDraw 正以仿真模式运行,它也可以被置于系统内存中. IDirectDrawSurface4 接口还扩展了另外一些函数,比如可以用来设置或获得调色板的函数,专门用于某特定类型页面的函数(如换页链或覆盖页面).

从下面这个例图中,你可以看到所有的 DirectDrawSurface 页面对象都是由 DirectDraw 对象创建的,并且与调色板协同工作.尽管每一个页面对象都可以被分配一个调色板,除了像素格式的位深度小于等于8的主页面以外,调色板并不总是必须的.


Surface Interfaces

页面接口(Surface Interfaces)

DirectDrawSurface 对象是通过 IDirectDrawSurface, IDirectDrawSurface2, IdirectDrawSurface3 和 IDirectDrawSurface4 接口来暴露其函数性的.接口的每一个新的版本与旧的版本相比,除了提供所有原有的函数并且扩充其功能之外,还提供了一些新的方法.

当你通过调用 IDirectDraw4::CreateSurface 方法(或 IDirectDraw4 接口的其他生成方法)创建一个页面时,你获得了一个指向页面的 IDirectDrawSurface4 接口的指针.这和以前版本的 DirectX 不同.使用以前版本的 CreateSurface 方法,你获得的是一个指向页面的 IDirectDrawSurface 接口的指针.如果你要使用不同版本的函数性,你就要查询.当你使用 IDirectDraw4 接口时这不是一个问题.你可以自由地查询你选择的接口的页面的函数性.


Width vs. Pitch

宽度和宽距(Width vs. Pitch)

尽管宽度(width)和宽距(pitch)被随便地讨论,但它们具有重要的(和明显不同的)意义.因此,你应该理解它们各自不同的意思,以及如何解释 DirectDraw 用来描述它们的数值.

DirectDraw 使用 DDSURFACEDESC2 结构来容纳描述页面的信息.这一结构被定义为容纳关于页面的尺寸的信息,以及这些尺寸如何被表现在内存中.这一结构使用 dwHeight 和 dwWidth 成员来描述页面的逻辑尺寸.这两个成员都以像素为单位.因此,对同一个 640×480 的页面来说不论它是8位的调色板页面还是24位的 RGB 页面 dwHeight 和 dwWidth 的值是一样的.

DDSURFACEDESC2 结构通过 lPitch 成员容纳了关于一个页面如何表现在内存中的信息. lPitch 成员的值描述了页面内存的宽距(也被称为 stride).宽距是相邻的两个位图线的起始在内存中的距离, 以字节(byte)为单位.因为宽距是以字节而不是以像素为单位的,一个 640×480×8 的页面会和一个同样尺寸但不同像素格式的页面有大不相同的宽距值.另外,宽距的值有时还反映了 DirectDraw 隐藏的高速缓存的字节,因此简单地认为宽距等于宽度乘以每个像素的字节数是危险的.通过以下的图示你更容易看清宽度和宽距的区别.

此图中,前台缓存(front buffer)和后台缓存(back buffer)都是 640×480×8,而高速缓存(Cache)是 384×480×8.

当你直接访问页面内存时宽距的值是有用的.例如,当你调用了 IDirectDrawSurface4::Lock 方法之后, DDSURFACEDESC2 结构的 lpSurface 成员包含了页面锁定区域的左上角的像素的地址,而 lPitch 成员是页面的宽距.你可以通过给页面指针增加或减少几个像素的字节数来水平地访问像素.也可以通过给当前的页面指针加上或减去宽距值来向上或向下移动.

当你直接访问页面时,注意保持在按页面尺寸分配好的内存内,而不要跑到表现为高速缓存的内存里.另外,当你只锁定页面的一部分时,你必须保持在页面锁定的矩形里.不按这些方针办事,会得到不可预知的结果.当你直接渲染到页面内存里时,要一直使用从 Lock 方法(或 IDirectDrawSurface4::GetDC 方法)返回的宽距值.不要假设宽距仅仅由显示模式决定.如果你的应用程序在某些显示适配器上发生显示混乱,这多半是因为你使用错误造成的.

要得到更多的信息,请参阅直接访问页面内存.


Color Keying

关键色(Color Keying)

DirectDraw 支持带源或目标关键色的 Blit 操作和覆盖页面.这个关键色可以是单个的颜色值,也可以是一个颜色范围.关键色使得你可以有选择地把一幅图像显示在另一幅上,也就是说只有前台矩形的特定颜色的像素被显示,或后台矩形的特定颜色的像素被覆盖.

通过调用 IDirectDrawSurface4::SetColorKey 方法,可以设置一个单一的或一个范围的源关键色或目标关键色.

要得到关于关键色的更多的信息,请参阅以下主题:

  • 覆盖页面关键色
  • 透明 Blit


Pixel Formats

像素格式(Pixel Formats)

像素格式规定了页面内存中的每个像素的数据是怎样进行编码的. DirectDraw 使用 DDPIXELFORMAT 结构来描述各式各样的像素格式. DDPIXELFORMAT 结构中的成员包含了各种像素格式相互区别的以下几个显著的特点:

  • 像素格式是基于调色板的还是非调色板式的
  • 如果是非调色板式,像素是RGB,还是YUV格式
  • 位深度
  • 位掩码

你可以通过调用 IDirectDrawSurface4::GetPixelFormat 函数获得关于当前页面的像素格式的信息.


Creating Surfaces

创建页面(Creating Surfaces)

DirectDrawSurface 对象代表了一个通常是驻留在显存内的页面,如果显存被用完或被明确地指定它也可以存在于系统内存里.

调用 IDirectDraw4::CreateSurface 方法可以创建一个对象,也可以同时创建多个页面(一个复杂页面(complex surface)). 调用该 CreateSurface时,你需要指明页面的尺寸,是单个页面还是复杂页面,所采用的像素格式(如果页面将不使用索引调色板).所有这些描述信息存储在一个 DDSURFACEDESC2 结构中,在调用 CreateSurface 函数时你需要提供它的地址.如果硬件不支持所请求的特性,或资源已经被分配给另一个 DirectDrawSurface 对象,调用将失败.

要创建单个的页面或若干个页面其实是一项并不复杂的工作,只需要少许的几行代码即可.主要有以下五种类型的页面可以被创建:

  • 创建主页面
  • 创建离屏页面
  • 创建复杂页面和换页链
  • 创建超宽页面
  • 创建客户内存页面

在缺省的情况下,除了客户内存页面,DirectDraw 试图在本地的视频内存中创建页面.如果恰好没有足够的本地(local)视频内存来容纳要创建的页面的话,DirectDraw 将试图使用非本地(non-local)的视频内存(在某些装备了AGP设备的系统上),如果仍旧无法实现,那么DirectDraw将只能将其创建于系统内存中.当然,在调用 IDirectDraw4::CreateSurface 函数时,你也可以在相关的 DDSCAPS2 结构中指定适当的标志符向 DirectDraw 明确的表明你想将页面置于哪种类型的内存中.


Creating the Primary Surface

创建主页面(Creating the Primary Surface)

主页面(primary surface)代表的是在显示器的当前可见屏幕,它在页面描述中具有 DDSCAPS_PRIMARYSURFACE 标志符.对于每一个 DirectDraw 对象来说,你只可能拥有一个主页面.

当你创建一个主页面时,记住主页面的大小以及像素格式暗中符合当前的显示模式.因此,创建主页面时一定不能自己指定页面尺寸或像素格式,否则,调用将失败,并且返回 DDERR_INVALIDPARAMS 错误,哪怕你使用的值符合当前显示的模式.

以下的例子显示了如何来填充 DDSURFACEDESC2 结构的成员以创建主页面.

DDSURFACEDESC2 ddsd;
ddsd.dwSize = sizeof(ddsd);

// Tell DirectDraw which members are valid.
ddsd.dwFlags = DDSD_CAPS;

// Request a primary surface.
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;

在创建完主页面后,你就可以通过调用 IDirectDrawSurface4::GetSurfaceDesc 方法来提取关于页面尺寸和像素格式的信息了.

请参阅,显示模式.


Creating an Off-Screen Surface

创建离屏页面(Creating an Off-Screen Surface)

离屏页面通常被用来存储位图,用于以后将位图图象 Blit 到主页面或后台缓存上.你必须指定你所要创建的离屏页面的大小,这是通过包含进 DDSC_WIDTH 和 DDSD_HEIGHT 标志符,并且给 dwWidth 和 dwHeight 成员填充正确的参数完成的.除此之外,你还必须在相关的 DDSCAPS2 结构中包含进 DDSCAPS_OFFSCREENPLAIN 标志符以表明创建的是一离屏页面.

在缺省的情况下, DirectDraw 在视频内存中创建离屏页面,除非视频内存容量不够,那么 DirectDraw 将会把离屏页面置于系统内存中.你可以在 DDSCAPS2 结构的 dwCaps 成员中包含进 DDSCAPS_SYSTEMMEMORY 或 DDSCAPS_VIDEOMEMORY 标志符,以明确的表明你希望将页面置于何处.如果不能在你指定的地方创建页面,方法将调用失败,并且返回错误.

下面的例子展示了如何来创建一个离屏页面:

DDSURFACEDESC2 ddsd;
ddsd.dwSize = sizeof(ddsd);

// Tell DirectDraw which members are valid.
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;

// Request a simple off-screen surface, sized
// 100 by 100 pixels.
//
// (This assumes that the off-screen surface we are about
// to create will match the pixel format of the
// primary surface.)
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
ddsd.dwHeight = 100;
ddsd.dwWidth = 100;

除此之外,你也可以创建一个像素格式与主页面不同的离屏页面.然而,在这种情况下,有一个缺点——该离屏页面将被限制于系统内存中.下面的例程片段展示了如何准备 DDSURFACEDESC2 结构的各成员,以用于创建一个8位的调色板式页面(假定当前的显示模式不是8位格式).

ZeroMemory(&ddsd, sizeof(ddsd));
ddsd.dwSize  = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT;
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN | DDSCAPS_SYSTEMMEMORY;
ddsd.dwHeight = 100;
ddsd.dwWidth  = 100;
ddsd.ddpfPixelFormat.dwSize  = sizeof(DDPIXELFORMAT);
ddsd.ddpfPixelFormat.dwFlags = DDPF_RGB | DDPF_PALETTEINDEXED8;

// Set the bit depth for an 8-bit surface, but DO NOT
// specify any RGB mask values. The masks must be zero
// for a palettized surface.
ddsd.ddpfPixelFormat.dwRGBBitCount = 8;

在 DirectX 以前的版本中,离屏页面的宽度的最大值被限制于主页面的宽度值之内.而从 DirectX 5.0 版开始,你可以随心所欲的创建任何宽度的离屏页面,如果显示硬件能够承受的话.在请求一个超宽离屏页面时,要小心的是,如果显存不能够容纳该页面,页面将被置于系统内存中.如果你明确的指定在视频内存中创建超宽页面,而硬件又无法承受的话,调用失败.要得到更多的信息,请参阅创建超宽页面.


Creating Complex Surfaces and Flipping Chains

创建复杂页面和换页链(Creating Complex Surfaces and Flipping Chains)

你还可以创建复杂页面,它同样也是由一步调用 IDirectDraw4::CreateSurface 函数所创建的.如果你在调用 CreateSurface 函数时,在页面描述中设置了 DDSCAPS_COMPLEX 标志符, DirectDraw 除了创建你所指明要创建的页面之外,还将暗中的为你创建一个或多个附加页面.对复杂页面的管理与对单页面的管理基本上是没有区别的:一步调用 IDirectDraw::Release 函数释放所有的页面,以及一步调用 IDirectDrawSurface4::Restore 函数恢复所有页面.然而,这些暗中创建的页面不能被脱离.要得到更多的信息,请参阅 IDirectDrawSurface4::DeleteAttachedSurface.

你所能创建的最常用的复杂页面之一就是换页链(flipping chain).通常,一个换页链是由一个主页面(primary surface)以及隶属于它的若干个后台缓存(back buffers)组成. DDSCAPS_FLIP 标志符表明页面是一个换页链的一部分.创建一个换页链的页面描述中,同样必须包含进 DDSCAPS_COMPLEX 标志符.

下面的例子展示了如何创建一个主页面换页链.

DDSURFACEDESC2 ddsd2;
ddsd2.dwSize = sizeof(ddsd2);

// Tell DirectDraw which members are valid.
ddsd2.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;

// Request a primary surface with a single
// back buffer
ddsd2.ddsCaps.dwCaps = DDSCAPS_COMPLEX | DDSCAPS_FLIP |
DDSCAPS_PRIMARYSURFACE;
ddsd2.dwBackBufferCount = 1;

上面的例程构造了一个双缓冲区换页(double-buffered flip)环境——单步调用 IDirectDrawSurface4::Flip 函数可以交换主页面和后台缓存.如果给 DDSURFACEDESC2 结构的 dwBackBufferCount 成员设置了2,将会创建两个后台缓存,在每次调用 Flip 函数时,主页面将在三个页面间循环,这就构成了一个三缓冲区换页(triple-buffered flip)环境.要得到更多的信息,请参阅换页.

注意 如果要创建一个作为 3-D 渲染目标的换页链,请在页面描述中加入 DDSCAPS_3DDEVICE 标志,以及 DDSCAPS_COMPLEX 和 DDSCAPS_FLIP 标志.

不同于 IDirectDraw3 接口及更早的接口所暴露的 CreateSurface 方法,你不能用 IDirectDraw4::CreateSurface 来隐含地创建一个附有 depth-buffer 的由渲染目标页面组成的换页链. IDirectDraw4::CreateSurface 方法所接受的 DDSURFACEDESC2 结构不容纳一个区域来指明一个 depth-buffer bit depth. 因此,应用程序必须先明确地创建一个 depth-buffer 页面,然后把它附属给一个后台缓存渲染目标页面.要得到更多的信息,请参阅 Depth Buffers.


Creating Wide Surfaces

创建超宽页面(Creating Wide Surfaces)

DirectDraw 允许你在显存中创建超宽离屏页面(页面的宽度大于主页面).这只在显示设备支持超宽页面的情况下才能实现.

要检查 DirectDraw 是否支持超宽页面,调用 IDirectDraw4::GetCaps 函数,检查你所提供的第一个 DDCAPS 结构的 dwCaps2 成员中是否存在 DDCAPS2_WIDESURFACES 标志.如果存在,表明你可以创建超宽页面.

如果你试图在视频内存中创建一个宽度大于主页面的页面,而 DDCAPS2_WIDESURFACES 标志并不存在,函数调用将失败,并且返回一个 DDERR_INVALIDPARAMS 错误.注意即使标志存在,如果页面太大了调用仍有可能失败.

超宽页面通常被用来支持系统内存页面,视频端口页面,和可执行缓存.


Creating Client Memory Surfaces

创建客户内存页面(Creating Client Memory Surfaces)

Client memory surfaces are simply DirectDrawSurface objects that use system memory that your application has previously allocated to hold image data. Creating such a surface isn't common, but it isn't difficult to do and it can be useful for applications that need to use DirectDraw surface features on existing memory buffers.

Like creating all surfaces, DirectDraw needs information about the dimensions of the surface (measured in pixels) and the surface pitch (measured in bytes), as well as the surface's pixel format. However, unlike creating other types of surfaces, this information doesn't tell DirectDraw how you want the surface to be created, it tells DirectDraw how you've already created it. You set these characteristics, plus the memory address of the buffer you've allocated, in the DDSURFACEDESC2 structure you pass to the IDirectDraw4::CreateSurface method.

A client memory surfaces works just like a normal system-memory surface, with the exception that DirectDraw does not attempt to free the surface memory when it's no longer needed; freeing client allocated memory is the application's responsibility.

The following example shows how you might allocate memory and create a DirectDrawSurface object for a 64×64 pixel 24-bit RGB surface:

// For this example, g_lpDD4 is a valid IDirectDraw4 interface pointer.

#define WIDTH  64 // in pixels
#define HEIGHT 64
#define DEPTH  3  // in bytes (3bytes == 24 bits)

    HRESULT hr;
    LPVOID  lpSurface  = NULL;
    HLOCAL  hMemHandle = NULL;
    DDSURFACEDESC2 ddsd2;
    LPDIRECTDRAWSURFACE4 lpDDS4;

    // Allocate memory for a 64 by 64, 24-bit per pixel buffer.
    // REMEMBER: The application is responsible for freeing this
    //           buffer when it is no longer needed.
    if (lpSurface = malloc((size_t)WIDTH*HEIGHT*DEPTH))
        ZeroMemory(lpSurface, (DWORD)WIDTH*HEIGHT*DEPTH);
    else
        return DDERR_OUTOFMEMORY;

    // Initialize the surface description.
    ZeroMemory(&ddsd2, sizeof(DDSURFACEDESC2));
    ZeroMemory(&ddsd2.ddpfPixelFormat, sizeof(DDPIXELFORMAT));
    ddsd2.dwSize = sizeof(ddsd2);
    ddsd2.dwFlags = DDSD_WIDTH | DDSD_HEIGHT | DDSD_LPSURFACE |
                    DDSD_PITCH | DDSD_PIXELFORMAT;
    ddsd2.dwWidth = WIDTH;
    ddsd2.dwHeight= HEIGHT;
    ddsd2.lPitch  = (LONG)DEPTH * WIDTH;
    ddsd2.lpSurface = lpSurface;

    // Set up the pixel format for 24-bit RGB (8-8-8).
    ddsd2.ddpfPixelFormat.dwSize = sizeof(DDPIXELFORMAT);
    ddsd2.ddpfPixelFormat.dwFlags= DDPF_RGB;
    ddsd2.ddpfPixelFormat.dwRGBBitCount = (DWORD)DEPTH*8;
    ddsd2.ddpfPixelFormat.dwRBitMask    = 0x00FF0000;
    ddsd2.ddpfPixelFormat.dwGBitMask    = 0x0000FF00;
    ddsd2.ddpfPixelFormat.dwBBitMask    = 0x000000FF;

    // Create the surface
    hr = g_lpDD4->CreateSurface(&ddsd2, &lpDDS4, NULL);
    return hr;


Flipping Surfaces

DirectDraw 里的任何页面都可以构造为换页页面(flipping surfaces).一个换页页面是位于内存里的任何一个可以在前台缓存(front buffer)和后台缓存(back buffer)之间交换的页面,这个换页环境就是我们所称的换页链(flipping chain).通常,前台缓存指的就是主页面(primary surface),当然,这并不是绝对的.

典型的,当你调用 IDirectDrawSurface4::Flip 函数以请求一次换页操作,指向主页面和后台缓存的指针相互交换.这就是说,换页的操作,是通过交换显示设备用来代表页面内存的指针,而不是通过相互复制页面的实际内存来完成的.但是,也有例外的时候,那就是当 DirectDraw 以仿真的方式进行换页操作时,在这种情况下,它所做的就是简单的相互复制页面内存.只有在后台缓存不能容纳进视频内存,或硬件不支持 DirectDraw 的时候, DirectDraw 才会以仿真的方式进行换页操作,当然,这只是极其少见的情况.当换页链中包含了一个主页面和一个以上的后台缓存时,在换页操作中,指向它们的指针将按前后顺序依次转换.如下图所示:

隶属到 DirectDraw 对象上的其它类型的页面,只要不是换页链中的一部分,在调用 Flip 函数过程中都不会受到任何影响.

请牢记, DirectDraw 进行换页,是通过交换指向 DirectDrawSurface 对象的指针.而不是交换 DirectDrawSurface 对象本身.这意味着,在任何类型的换页方案中,如果你想将图象 Blit 到后台缓存,你所使用的始终是同一个 DirectDrawSurface 对象,而不用去考虑原先的后台缓存已经换页到哪儿了.同样的,你应该始终使用主页面作为 Flip 函数的调用者,以完成一次换页操作,而不用去管最开始的主页面换页到哪儿了.

当换页对象是可见的页面,比如主页面换页链或一个可见的覆盖页面换页链,进行换页的 Flip 函数与系统 CPU 是异步执行的.这就是说,在这些可见的页面上,调用 Flip 函数,它只是简单的告诉显示硬件该进行换页了,并不需要等待换页操作在硬件设备中实际完成后才返回.这是因为显示硬件(显示器)只有在完成一次垂直刷新后才能进行一次换页.所以, Flip 函数调用成功,并不意味着换页已经完成,在实际的换页操作进行之前,对即将成为主页面的后台缓存是不能锁定和进行 Blit 操作的,如果在这时调用以下这些函数,调用将失败,并且返回 DDERR_WASSTILLDRAWING 的错误,如 IDirectDrawSurface4::Lock, IDirectDrawSurface4::Blt, IDirectDrawSurface4::BltFast, 或 IDirectDrawSurface4::GetDC. 但是,对于三缓冲区换页环境,最后一个后台缓存仍是可用的.


Blitting to Surfaces

Blit 到页面(Blitting to Surfaces)

这部分讨论了如何把像素从一个页面拷贝到另一个页面或从一个页面的一部分复制到另一部分.

请参看一下主题:

  • Blit 基础
  • 用 BltFast 函数 Blit
  • 用 Blt 函数 Blit
  • Blit 时间控制
  • 透明 Blit
  • 色彩填充
  • Blit 到多窗口


Blitting Basics

Blit 基础(Blitting Basics)

Two methods are available for copying images to a DirectDraw surface: IDirectDrawSurface4::Blt and IDirectDrawSurface4::BltFast. (A third method, IDirectDrawSurface4::BltBatch, is not implemented in this version of DirectX.) These methods are called on the destination surface and receive the source surface as a parameter. The destination and source surfaces can be one and the same, and you don't have to worry about overlap桪irectDraw takes care to preserve all source pixels before overwriting them.

Of the two implemented methods, Blt is the more flexible and BltFast is the faster梑ut only if there is no hardware blitter. You can determine the blitting capabilities of the hardware from the DDCAPS structure obtained in the lpDDDriverCaps parameter of the IDirectDraw4::GetCaps method. If the dwCaps member contains DDCAPS_BLT, the hardware has at least minimal blitting capabilities.


Blitting with BltFast

用 BltFast 函数 Blit(Blitting with BltFast)

When using IDirectDrawSurface4::BltFast, you supply a valid rectangle in the source surface from which the pixels are to be copied (or NULL to specify the entire surface), and an x-coordinate and y-coordinate in the destination surface. The source rectangle must be able to fit in the destination surface with its top left corner at that point, or the call will fail with a return value of DDERR_INVALIDRECT. BltFast cannot be used on surfaces that have an attached clipper.

No stretching, mirroring, or other effects can be performed when using BltFast.

BltFast Example

The following example copies pixels from an offscreen surface, lpDDSOffOne, to the primary surface, lpDDSPrimary. The flags ensure that the operation will take place as soon as the blitter is free, and that transparent pixels in the source image will not be copied. (For more information on the meaning of these flags, see Blit Timing and Transparent Blitting .)

lpDDSPrimary->BltFast(
        100, 200,    // Upper left xy of destination
        lpDDSOffOne, // Source surface
        NULL,        // Source rectangle = entire surface
        DDBLTFAST_WAIT | DDBLTFAST_SRCCOLORKEY );


Blitting with Blt

用 Blt 函数 Blit(Blitting with Blt)

When using the IDirectDrawSurface4::Blt method, you supply a valid rectangle in the source surface (or NULL to specify the entire surface), and a rectangle in the destination surface to which the source image will be copied (again, NULL means the rectangle covers the entire surface). If a clipper is attached to the destination surface, the bounds of the destination rectangle can fall outside the surface and clipping will be performed. If there is no clipper, the destination rectangle must fall entirely within the surface or else the method will fail with DDERR_INVALIDRECT. (For more information on clipping, see Clippers.)

Scaling

The Blt method automatically rescales the source image to fit the destination rectangle. If resizing is not your intention, for best performance you should make sure that your source and destination rectangles are exactly the same size, or else use IDirectDrawSurface4:BltFast. (See Blitting with BltFast.)

Hardware acceleration for scaling depends on the DDFXCAPS_BLT* flags in the dwFXCaps member of the DDCAPS structure for the device. If, for example, a device has the DDFXCAPS_BLTSTRETCHXN capability but not DDFXCAPS_BLTSTRETCHX, it can assist when the x-axis of the source rectangle is being multiplied by a whole number but not when non-integral (arbitrary) scaling is being done.

Devices might also support arithmetic scaling, which is scaling by interpolation rather than simple multiplication or deletion of pixels. For instance, if an axis was being increased by one-third, the pixels would be recolored to provide a closer approximation to the original image than would be produced by the doubling of every third pixel on that axis.

Applications cannot control the type of scaling done by the driver, except by setting the DDBLTFX_ARITHSTRETCHY flag in the dwDDFX member of the DDBLTFX structure passed to Blt. This flag requests that arithmetic stretching be done on the y-axis. Arithmetic stretching on the x-axis and arithmetic shrinking are not currently supported in the DirectDraw API, but a driver may perform them by default.

Other Effects

If you do not require any special effects other than scaling when using Blt, you can pass NULL as the lpDDBltFx parameter. Otherwise you can choose among a variety of effects specified in a DDBLTFX structure. Among these, color fills and mirroring are supported by the HEL, so they are always available. Most other effects depend on hardware support.

For a complete view of the effects capabilities of the HEL, run the DDraw Caps utility supplied with the DirectX Programmer's Reference and select HEL FX Caps from the HEL menu. For an explanation of the various flags, see DDCAPS. You can also check HEL capabilities within your own application by using the IDirectDraw4::GetCaps method.

When you specify an effect that requires a value in one of the members of the DDBLTFX structure passed to the IDirectDrawSurface4::Blt method, you must also include the appropriate flags in the dwFlags parameter to show which members of the structure are valid.

Some effects require only the setting of a flag in the dwFlags member of DDBLTFX. One of these is DDBLTFX_NOTEARING. You can use this flag when you are blitting animated images directly to the front buffer, so that the blit is timed to coincide with the screen refresh and the possibility of tearing is minimized. Mirroring and rotation are also set by using flags.

Blitting effects include the standard raster operations (ROPs) used by GDI functions such as BitBlt. The only ROPs supported by the HEL are SRCCOPY (the default), BLACKNESS, and WHITENESS. Hardware support for other ROPs can be examined in the DDCAPS structure for the driver. If you wish to use any of the standard ROPS with the Blt method, you flag them in the dwROP member of the DDBLTFX structure.

The dwDDROP member of the DDBLTFX structure is for specifying ROPs specific to DirectDraw. However, no such ROPs are currently defined.

Alpha and Z Values

Opacity and depth values are not currently supported in DirectDraw blits. If alpha values are stored in the pixel format, they simply overwrite any alpha values in the destination rectangle. Values from alpha buffers and z-buffers are ignored. The members of the DDBLTFX structure that have to do with alpha channels and z-buffers (members whose names begin with "dwAlpha" and "dwZ"), and the corresponding flags for Blt, are not used. The same applies to the DDBLTFX_ZBUFFERBASEDEST and DDBLTFX_ZBUFFERRANGE flags in the dwDDFX member of the DDBLTFX structure.

Although z-buffers are currently used only in Direct3D applications, you can use IDirectDrawSurface4::Blt to set the depth value for a z-buffer surface, by setting the DDBLT_DEPTHFILL flag. For more information, see Clearing Depth Buffers.

For an overview of the use of alpha channels and z-buffers in Direct3D, see the following topics:

  • Alpha States
  • What Are Depth Buffers?

Blt Example

The following example, in which it is assumed that lpDDS is a valid IDirectDrawSurface4 pointer, creates a symmetrical image within the surface by mirroring a rectangle from left to right:

RECT     rcSource, rcDest;
DDBLTFX  ddbltfx;

ZeroMemory(&ddbltfx, sizeof(ddbltfx));
ddbltfx.dwSize = sizeof(ddbltfx);
ddbltfx.dwDDFX = DDBLTFX_MIRRORLEFTRIGHT;

rcSource.top = 0; rcSource.left = 0;
rcSource.bottom = 100; rcSource.right = 200;
rcDest.top = 0; rcDest.left = 201;
rcDest.bottom = 100; rcDest.right = 401;

HRESULT hr = lpDDS->Blt(&rcDest,
                        lpDDS,
                        &rcSource,
                        DDBLT_WAIT | DDBLT_DDFX,
                        &ddbltfx);


Blit Timing

Blit 时间控制(Blit Timing)

When you copy pixels to a surface using either IDirectDrawSurface4::Blt or IDirectDrawSurface4::BltFast, the method might fail with DDERR_WASSTILLDRAWING because the hardware blitter was not ready to accept the command.

If your application has no urgent business to perform while waiting for the blitter to come back into a state of readiness, you can specify the DDBLT_WAIT flag in the dwFlags parameter of Blt, or the equivalent DDBLTFAST_WAIT flag for BltFast. The flag causes the method to wait until the blit can be handed off to the blitter (or until an error other than DDERR_WASSTILLDRAWING occurs).

Blt accepts another flag, DDBLT_ASYNC, that takes advantage of any hardware FIFO (first in, first out) queuing capabilities.


Transparent Blitting

透明 Blit(Transparent Blitting)

This section discusses the theory and practice of using transparent blitting to copy parts of a rectangular image selectively, using source and destination color keys.

The concepts are introduced in the following topic:

  • What Is Transparent Blitting?

Information about the implementation of transparent blitting in DirectDraw is contained in the following topics:

  • Color Key Format
  • Setting Color Keys
  • Blitting with Color Keys


What Is Transparent Blitting?

什么是透明 Blit?(What Is Transparent Blitting?)

Transparent blitting enables you to create the illusion of nonrectangular blits when animating sprites. A sprite image is usually nonrectangular, but blits are always rectangular, so every pixel within the sprite's bounding rectangle becomes part of the data transfer. With transparent blitting, each pixel that is not part of the sprite image is treated as transparent when the blitter is moving the image to its destination, so that it does not overwrite the color in that pixel on the background image.

The artist creating the sprite chooses an arbitrary color or range of colors to be used as the transparency color key. This is typically a single uncommon color that the artist doesn't use for anything but transparency, and it is used to fill in all parts of the sprite rectangle that are not part of the desired image. At run time you set the color key for the surface containing the sprite. (If you wish, you can automatically set it to the color of the pixel in the upper left corner of the image.) Subsequent blits can take advantage of that color key, ignoring the pixels that match it. This type of color key is known as a source color key.

You can also use a color key on the destination surface, provided the hardware supports destination color keying. This destination color key is used for pixels that can be overwritten by a sprite. For example, the artist might be working on a foreground image that sprites are supposed to pass behind, such as the wall of a room with a window to the outside. The artist chooses an arbitrary color梠ne that isn't used elsewhere in the image梩o represent the sky outside the window. When you set this color key for the destination surface and then blit a sprite to that surface, the sprite's pixels will overwrite only pixels that are using the destination color key. In the example, the sprite appears only in the window, but not on the wall or window frame. As a result, the sprite seems to be outside the room.

Source and destination color keys can be combined. In the example, the sprite could use a source color key so that its entire bounding rectangle does not block out the sky background.


Color Key Format

关键色格式(Color Key Format)

A color key is described in a DDCOLORKEY structure. If the color key is a single color, both members of this structure should be assigned the same value. Otherwise the color key is a range of colors.

Color keys are specified using the pixel format of a surface. If a surface is in a palettized format, the color key is given as an index or a range of indices. If the surface's pixel format is specified by a FOURCC code that describes a YUV format, the YUV color key is specified by the three low-order bytes in both the dwColorSpaceLowValue and dwColorSpaceHighValue members of the DDCOLORKEY structure. The lowest order byte contains the V data, the second lowest order byte contains the U data, and the highest order byte contains the Y data.

Some examples of valid color keys follow:

8-bit palettized mode

// Palette entry 26 is the color key.
dwColorSpaceLowValue = 26;
dwColorSpaceHighValue = 26;

24-bit true-color mode

// Color 255,128,128 is the color key.
dwColorSpaceLowValue = RGBQUAD(255,128,128);
dwColorSpaceHighValue = RGBQUAD(255,128,128);

FourCC YUV mode

// Any YUV color where Y is between 100 and 110
// and U or V is between 50 and 55 is transparent.
dwColorSpaceLowValue = YUVQUAD(100,50,50);
dwColorSpaceHighValue = YUVQUAD(110,55,55);

Support for a range of colors rather than a single color is hardware-dependent. Check the dwCKeyCaps member of the DDCAPS structure for the hardware. The HEL does not support color ranges.

Some hardware supports color ranges only for YUV pixel data, which is usually video. The transparent background in video footage (the "blue screen" against which the subject was photographed) might not be a single pure color, so a range of colors in the color key is desirable.


Setting Color Keys

设置关键色(Setting Color Keys)

You can set the source or destination color key for a surface either when creating it or afterwards.

To set a color key or keys when creating a surface, you assign the appropriate color values to one or both of the ddckCKSrcBlt and ddckCKDestBlt members of the DDSURFACEDESC2 structure that is passed to IDirectDraw4::CreateSurface. To enable the color key for blitting, you must also include one or both of DDSD_CKSRCBLT or DDSD_CKDESTBLT in the dwFlags member.

To set a color key for an existing surface you use the IDirectDrawSurface4::SetColorKey method. You specify a key in the lpDDColorKey parameter and set either DDCKEY_SRCBLT or DDCKEY_DESTBLT in the dwFlags parameter to indicated whether you are setting a source or destination key. If the DDCOLORKEY structure contains a range of colors, you must also set the DDCKEY_COLORSPACE flag. If this flag is not set, only the dwColorSpaceLowValue member of the structure is used.


Blitting with Color Keys

用关键色 Blit(Blitting with Color Keys)

If you want to use color keys for surfaces when calling the IDirectDrawSurface4::BltFast method, you must set one or both of the DDBLTFAST_SRCCOLORKEY or DDBLTFAST_DESTCOLORKEY flags in the dwTrans parameter.

In order to use colors keys when calling IDirectDrawSurface4:Blt, you pass one or both of the DDBLT_KEYSRC or DDBLT_KEYDEST flags in the dwFlags parameter. Alternatively, you can put the appropriate color values in the ddckDestColorkey and ddckSrcColorkey members of the DDBLTFX structure that is passed to the method through the lpDDBltFx parameter. In this case you must also set the DBLT_KEYSRCOVERRIDE or DDBLT_KEYDESTOVERRIDE flag, or both, in the dwFlags parameter, so that the selected keys are taken from the DDBLTFX structure rather than from the surface properties.


Color Fills

色彩填充(Color Fills)

In order to fill all or part of a surface with a single color, you can use the IDirectDrawSurface4::Blt method with the DDBLT_COLORFILL flag. This technique allows you to quickly erase an area or draw a solid-colored background.

The following example fills an entire surface with the color blue, after obtaining the numerical value for blue from the pixel format:

/* It is assumed that lpDDS is a valid pointer to
   an IDirectDrawSurface4 interface. */

HRESULT ddrval;
DDPIXELFORMAT ddpf;

ddpf.dwSize = sizeof(ddpf);
if (SUCCEEDED(lpDSS->GetPixelFormat(&ddpf))
{
    DDBLTFX ddbltfx;

    ddbltfx.dwSize = sizeof(ddbltfx);
    ddbltfx.dwFillColor = ddpf.dwBBitMask; // Pure blue

    ddrval = lpDDS->Blt(
        NULL,        // Destination is entire surface
        NULL,        // No source surface
        NULL,        // No source rectangle
        DDBLT_COLORFILL, &ddbltfx);

    switch(ddrval)
    {
        case DDERR_WASSTILLDRAWING:
            .
            .
            .
        case DDERR_SURFACELOST:
            .
            .
            .
        case DD_OK:
            .
            .
            .
        default:
    }
}


Blitting to Multiple Windows

Blit 到多窗口(Blitting to Multiple Windows)

你可以使用一个 DirectDraw 对象和一个 DirectDrawClipper 对象 Blit 到由运行于普通控制级的应用程序创建的若干个窗口中.要得到更多的信息,请参阅对多窗口使用裁剪器.

创建多个 DirectDraw 对象,并且让它们 Blit 到相互的主页面的作法是不推荐的.


Losing and Restoring Surfaces

页面丢失及恢复页面(Losing and Restoring Surfaces)

当代表页面内存的 DirectDrawSurface 对象被不得已的释放时,与该对象相关联的页面内存也会被释放.当一个 DirectDrawSurface 对象丢失其页面内存的时候,它的许多函数将返回 DDERR_SURFACELOST, 并且不进行任何其它操作.

页面可能被丢失是因为:显示设备(显示器)显示模式的改变,或另一个应用程序获得了对显卡的独占访问模式,并且释放了显卡上当前被分派其它应用程序的所有页面内存.对页面调用 IDirectDrawSurface4::Restore 方法可以为这些丢失了内存的页面重新分配内存,并且将这些内存与 DirectDrawSurface 对象联系上.如果你的应用程序使用不止一个页面,你可以通过调用 IDirectDraw4::RestoreAllSurfaces 方法将所有的页面一次恢复.

重建内存并不会使被丢失的以前存在于该页面上的图象重新显现出来,因此,你必须亲手重新绘制所有的图象.


COM Reference Count Semantics for Surfaces

Being built upon COM means that DirectDraw follows certain rules that employ reference counts to manage object lifetimes. For a conceptual overview, see the COM documentation; a DirectDraw-centered discussion of the topic is found in Parent and Child Object Lifetimes.

By COM rules, when an interface pointer is copied by setting it to another variable or passing to another object, that copy represents another reference to the object, and therefore the IUnknown::AddRef method of the interface must be called to reflect the change. Not only should you follow COM reference counting rules when working with DirectDraw objects, but you should become familiar with the situations in which DirectDraw internally updates reference counts. Some DirectDraw methods梞ostly those involving complex surface flipping chains梐ffect the reference counts of the surfaces involved, while methods involving clippers or palettes affect the reference counts of those objects. Knowing about these situations can make the difference in your application's stability and can prevent memory leaks. This section presents information divided into the following topics:

  • When Reference Counts Will Change
  • Reference Counts for Complex Surfaces
  • Releasing Surfaces

Note: There are some things to remember about the reference count of the DirectDraw object, in addition to the relationships discussed in this section. For more information, see Parent and Child Object Lifetimes in The DirectDraw Object.


When Reference Counts will Change

There are several DirectDraw methods that affect the reference count of a surface, and a few that affect other objects you can associate with a surface. You can think of these situations as "surface-only changes" and "cross-object changes":

Surface-only changes
Surface-only changes, as the name states, only affect the reference count of a surface object. For example, you might use the IDirectDraw4::EnumSurfaces to enumerate the current surfaces that fit a particular description. When the method invokes the callback function that you provide, it passes a pointer to an IDirectDrawSurface4 interface, but it increments the reference count for the object before your application receives the pointer. It's your responsibility to release the object when you are finished with it. This will typically be at the end of your callback routine, or later if you choose to keep the object.

Most other surface-only changes affect the reference counts of complex surfaces, such as a flipping chain. Reference counts are a little more tricky for complex surfaces, because (in most cases) DirectDraw treats a complex surface as if it was a single object, even though it is a set of surfaces. In short, the IDirectDrawSurface4::GetAttachedSurface and IDirectDrawSurface4::AddAttachedSurface methods increment reference counts of surfaces, and IDirectDrawSurface4::DeleteAttachedSurface decrements the reference count. These methods don't affect the counts of any surfaces attached to the current surface. See the references for these methods and Reference Counts for Complex Surfaces for a additional details.

Cross-object changes
Cross-object reference count changes occur when you create an association between a surface and another object that performs a task for the surface, such as a clipper or a palette.

The IDirectDrawSurface4::SetClipper and IDirectDrawSurface4::SetPalette methods increment the reference count of the object being attached. After they are attached, the surface manages them; if the surface is released, it automatically releases any objects it is using. (For this reason, some applications release the interface for the object after these calls succeed. This is a perfectly valid practice.)

Once a clipper or palette is attached to a surface, you can call the IDirectDrawSurface4::GetClipper and IDirectDrawSurface4::GetPalette methods to retrieve them again. Because these methods return a copy of an interface pointer, they implicitly increment the reference count for the object being retrieved. When you're done with the interfaces, don't forget to release them梩he objects that the interfaces represent won't disappear so long as the surface they are attached to still holds a reference to them.


Reference Counts for Complex Surfaces

The methods you use to manipulate a complex surface like a flipping chain all use surface interface pointers, and therefore they all affect the reference counts of the surfaces. Because a complex surface is really a series of single surfaces, the reference count relationships require a little more consideration. As you might expect, the IDirectDrawSurface4::GetAttachedSurface method returns the surface interface for a surface attached to the current surface. It does this after incrementing the reference count of the interface being retrieved; it's up to you to release the interface when you no longer need it. The IDirectDrawSurface4::AddAttachedSurface method attaches a new surface to the current one. Similarly, AddAttachedSurface increments the count for the surface being attached. You would use the IDirectDrawSurface4::DeleteAttachedSurface method to remove the surface from the chain and implicitly decrease its reference count.

What isn't immediately clear about these methods is that they don't affect the reference counts of the other objects that make up the complex surface. The GetAttachedSurface method simply increments the reference count of the surface it's retrieving, it doesn't affect the counts of the surfaces on which it depends. (The same situation applies to an explicit call to IUnknown::AddRef.) This means that the reference count for primary surface in a complex surface can reach zero before its subordinate surfaces reach zero. When the primary surface reference count reaches zero, all other surfaces attached to it are released regardless of their current reference counts. (It's like a tree: if you cut the base, the whole thing falls. In this case, the primary surface is the base.) Attempts to access subordinate surfaces after the primary surface has been deallocated will result in memory faults.

To avoid problems, make sure that your application has released all subordinate surface references before attempting to release the primary surface. It might be helpful to track the references you application holds, only accessing subordinate surface interfaces when you're sure that you also hold a reference the primary surface.


Releasing Surfaces

Like all COM interfaces, you must release surfaces by calling their IDirectDrawSurface4::Release method when you no longer need them.

Each surface you individually create must be explicitly released. However, if you implicitly created multiple surfaces with a single call to IDirectDraw4::CreateSurface, such as a flipping chain, you need only release the front buffer. In this case, any pointers you might have to back buffer surfaces are implicitly released and can no longer be used.

Explicitly releasing a back buffer surface doesn't affect the reference count of the other surfaces in the chain.


Enumerating Surfaces

列举页面(Enumerating Surfaces)

By calling the IDirectDraw4::EnumSurfaces method you can request that DirectDraw enumerate surfaces in various ways. The EnumSurfaces method enables you to look for surfaces that fit, or don't fit, a provided surface description. DirectDraw calls a EnumSurfacesCallback that you include with the call for each enumerated surface.

There are two general ways to search梱ou can search for surfaces that the DirectDraw object has already created, or for surfaces that the DirectDraw object is capable of creating at the time (given the surface description and available memory). You specify what type of search you want by combining flags in the method's dwFlags parameter.

Enumerating existing surfaces

This is the most common type of enumeration. You enumerate existing surfaces by calling EnumSurfaces, specifying a combination of the DDENUMSURFACES_DOESEXIST search-type flag and one of the matching flags (DDENUMSURFACES_MATCH, DDENUMSURFACES_NOMATCH, or DDENUMSURFACES_ALL) in the dwFlags parameter. If you're enumerating all existing surfaces, you can set the lpDDSD parameter to NULL, otherwise set it to the address of an initialized DDSURFACEDESC2 structure that describes the surface for which you're looking. You can set the third parameter, lpContext, to an address that will be passed to the enumeration function you specify in the fourth parameter, lpEnumSurfacesCallback.

The following code fragment shows what this call might look like to enumerate all of a DirectDraw object's existing surfaces.

    HRESULT ddrval;
    ddrval = lpDD->EnumSurfaces(DDENUMSURFACES_DOESEXIST |
                                DDENUMSURFACES_ALL, NULL, NULL,
                                EnumCallback);
    if (FAILED(ddrval))
        return FALSE;

When searching for existing surfaces that fit a specific description, DirectDraw determines a match by comparing each member of the provided surface description to those of the existing surfaces. Only exact matches are enumerated. DirectDraw increments the reference counts of the enumerated surfaces, so make sure to release a surface if you don't plan to use it (or when you're done with it).

Enumerating possible surfaces

This type of enumeration is less common than enumerating existing surfaces, but it can be helpful to determine if a surface is supported before you attempt to create it. To perform this search, combine the DDENUMSURFACES_CANBECREATED and DDENUMSURFACES_MATCH flags when you call IDirectDraw4::EnumSurfaces (no other flag combinations are valid). The DDSURFACEDESC2 structure you use with the call must be initialized to contain information about the surface characteristics that DirectDraw will use.

To enumerate surfaces that use a particular pixel format, include the DDSD_PIXELFORMAT flag in the dwFlags member of the DDSURFACEDESC2 structure. Additionally, initialize the DDPIXELFORMAT structure in the surface description and set its dwFlags member to contain the desired pixel format flags桪DPF_RGB, DDPF_YUV, or both. You need not set any other pixel format values.

If you include the DDSD_HEIGHT and DDSD_WIDTH flags in the DDSURFACEDESC2 structure, you can specify the desired dimensions in the dwHeight and dwWidth members. If you exclude these flags, DirectDraw uses the dimensions of the primary surface.

The following code fragment shows what this call could look like to enumerate all valid surface characteristics for 96×96 RGB or YUV surfaces:

    DDSURFACEDESC2 ddsd;
    HRESULT        ddrval;
    ZeroMemory(&ddsd, sizeof(ddsd));

    ddsd.dwSize  = sizeof(ddsd);
    ddsd.dwFlags = DDSD_CAPS | DDSD_PIXELFORMAT |
                   DDSD_HEIGHT | DDSD_WIDTH;
    ddsd.ddpfPixelFormat.dwFlags = DDPF_YUV | DDPF_RGB;
    ddsd.dwHeight = 96;
    ddsd.dwWidth  = 96;

    ddrval = lpDD->EnumSurfaces(
                     DDENUMSURFACES_CANBECREATED | DDENUMSURFACES_MATCH,
                     &ddsd, NULL, EnumCallback);
    if (ddrval != DD_OK)
        return FALSE;

When DirectDraw enumerates possible surfaces, it actually attempts to create a temporary surface that has the desired characteristics. If the attempt succeeds, then DirectDraw calls the provided EnumSurfacesCallback function with only the characteristics that worked; it does not provide the callback function with pointer to the temporary surface. Do not assume that a surface isn't supported if it isn't enumerated. DirectDraw's attempt to create a temporary surface could fail due to memory constraints that exist at the time of the call, resulting in those characteristics not being enumerated, even if the driver actually supports them.


Updating Surface Characteristics

更新页面属性(Updating Surface Characteristics)

你可以通过调用 IDirectDrawSurface4::SetSurfaceDesc 函数来更新一个现存页面的属性.有了这个函数,你可以更改页面的像素格式,还可以使该 DirectDrawSurface 对象指针重定位,使其指向一块应用程序已经明确分配了的系统内存.这是很有用的,因为它使得你的页面可以直接使用一个已经存在的缓冲区的数据,而不用进行复制操作.新的页面内存是由客户程序所分配,同样的,这些内存也必须由客户程序释放掉.

在调用 IDirectDrawSurface4::SetSurfaceDesc 函数时, lpddsd 参数必须是一个 DDSURFACEDESC2 结构的地址,描述了新的页面内存并且提供了指向该内存的指针.在这个结构中,你只能设置 dwFlags 成员为反映了页面内存的地址,大小,宽距(pitch),和像素格式的标志符.因此, dwFlags 只能是以下标志符的集合: DDSD_WIDTH, DDSD_HEIGHT, DDSD_PITCH, DDSD_LPSURFACE, 和 DDSD_PIXELFORMAT.

在向这个结构中填充数据之前,你必须为新的页面分配内存.你所分配的内存的大小是非常重要的,它不仅要能容纳满足页面的宽度(width)和高度所需要的内存,还必须能够容纳页面的宽距(pitch),宽距必须是 QWORD(8位)的倍数.应该注意的是,宽距是以字节为单位,而非像素.

When setting surface values in the structure, the lpSurface member is a pointer to the memory you allocated and the dwHeight and dwWidth members describe the surface dimensions in pixels. If you specify surface dimensions, you must fill the lPitch member to reflect the surface pitch as well. Pitch must be a DWORD multiple. Likewise, if you specify pitch, you must also specify a width value. Lastly, the ddpfPixelFormat member describes the pixel format for the surface. With the exception of the lpSurface member, if you don't specify a value for these members, the method defaults to using the value from the current surface.

在向此结构中填充数据的时候, lpSurface 成员是一个指向你刚分配的内存的指针,并且 dwHeight 和 dwWidth 成员描述了页面的大小(以像素为单位).如果你指定了页面的大小,你还必须填充 lPitch 成员以反映页面宽距的大小.宽距必须是 DWORD 的倍数.同样的,如果你指定了宽距,你还必须为其指定一个宽度值.最后, ddpfPixelFormat 成员描述了页面的像素格式.如果你没有给这些成员指定新的值,那么,方法将使用当前页面的原始值,只有 lpSurface 成员是例外.

在使用 IDirectDrawSurface4::SetSurfaceDesc 方法的过程中,你还应当注意到这样一些细节,当然,它们只是常识.举例来说, DDSURFACEDESC2 结构的 lpSurface 成员必须是一个指向系统内存的合法的指针(方法目前还不支持指向视频内存的指针).同样, dwWidth 和 dwHeight 成员的值不能为0.最后一点,你不能重新标示主页面或换页链中的任何页面.

你可以将同一块内存设置给若干个 DirectDrawSurface 对象,但是,你必须注意到,这块内存被所有的页面对象所使用,它不会因为某一个页面的释放而被释放掉.

不正确的使用 SetSurfaceDesc 函数将导致不可预知的行为.因为 DirectDrawSurface 对象不会释放并不是它分配的页面内存,因此,当页面内存不再需要的时候,将其及时的释放掉是你的责任.但是,不管怎样,当 SetSurfaceDesc 函数被调用的时候, DirectDraw 将释放掉该页面在创建的时候被暗中分配的原始的页面内存.


Accessing Surface Memory Directly

直接访问页面内存(Accessing Surface Memory Directly)

一个 DirectDrawSurface 对象允许应用程序通过调用 IDirectDrawSurface4::Lock 锁定页面以获得对这帧缓存或离屏页面内存的直接的访问.当应用程序调用这个函数的时候,需要给 lpDestRect 参数提供一个指向 RECT 结构的指针,描述了页面中你所想要直接访问的矩形区域.如果应用程序需要访问整个页面,设置这个参数为 NULL 即可.两个线程或进程可以同时锁定同一个页面上的若干个矩形区域,条件是这些矩形区域没有相互重叠.

如果 Lock 函数调用成功的话,将填充一个 DDSURFACEDESC2 结构,描述了你要正确的访问页面内存所需要的所有信息.如果页面的像素格式与主页面(primary surface)的不一样,该结构中还包含了关于页面的宽距(pitch)(或 stride)和像素格式的信息.当应用程序结束了对页面内存的访问,可以调用 IDirectDrawSurface4::Unlock 以解锁页面.

当你锁定了一个页面,你就可以对页面内存中的数据进行直接的操作.以下介绍了一些小技巧,可以避免在页面被锁定的过程中,直接向页面内存进行绘图的时候发生的绝大多数一般的错误:

  • 决不要假想页面的宽距(pitch)为一恒定值,每次调用 IDirectDrawSurface4::Lock 函数的时候都要检查返回信息中的宽距值.这个值的改变可以有各种各样的原因,包括页面内存在内存中的位置,显卡的类型,甚至是 DirectDraw 引擎的版本. 要得到更多的信息,请参阅宽度和宽距.
  • 确保你要进行 Blit 操作的目标页面是没有被锁定的.如果对一个锁定的页面调用 DirectDraw 的 Blit 方法,调用将失败,并且返回 DDERR_SURFACEBUSY 或 DDERR_LOCKEDSURFACES 错误.相似的,如果对视频内存中一个锁定的页面调用了 GDI 的 Blit 函数,调用也将失败,但不会返回错误值.
  • 在页面被锁定时,尽量减少你的程序的执行活动.在一个页面被锁定时, DirectDraw 通常控制住 Win16 锁(Win16Mutex 或 Win16Lock),于是使得对页面内存的访问得以安全的进行. Win16 锁使对 GDI 和 USER 动态链接库(DLL)的访问串行化,在 IDirectDrawSurface4::Lock 和 IDirectDrawSurface4::Unlock 函数的调用过程中,暂停执行 Windows. IDirectDrawSurface4::GetDC 函数含蓄的调用了 Lock 函数,并且 IDirectDrawSurface4::ReleaseDC 函数含蓄的调用了 Unlock 函数.
  • 对齐复制到显示存储器.(Windows 95 和 Windows 98 使用了一个页错误处理器 Vflatd.386 文件,来为具有堆交换存储器的显示卡实现虚拟的平面帧缓冲区.该处理器允许这些显示设备为 DirectDraw 提供线性帧缓冲区.如果复制是跨存储堆的,非对齐复制到显示存储器会导致系统挂起.)

除非你在调用 Lock 函数时使用了DDLOCK_NOSYSLOCK 标志,锁定页面通常导致 DirectDraw 控制住 Win16 锁.在 Win16 锁被控制期间,所有其它的应用程序,包括 Windows 系统,都会暂停执行.因为这个原因,标准的调试器在此期间都不可能工作,只有内核(kenerl)调试器仍可以正常工作. DirectDraw 在锁定页面时通常都会控制 Win16 锁.

如果在你调用 IDirectDrawSurface4::Lock 函数的时候,对于该页面的一次 Blit 操作还在进行之中,函数将立即返回一个错误值.要防止这种情况的发生,可以在调用此函数的过程中指定 DDLOCK_WAIT 标志,以表明该函数将等待,直到成功的获得锁定之后才返回.

主页面锁定的部分有可能影响到光标的显示.如果光标和被锁住的矩形交叉,在锁定期间它将被隐藏.如果不交叉,它将被冻结.如果整个页面被锁定,以上两种效果都不会出现.


Gamma and Color Controls

Gamma 和色彩控制(Gamma and Color Controls)

This section contains information about the gamma and color control interfaces used with DirectDrawSurface objects. Information is organized into the following topics:

  • What Are Gamma and Color Controls?
  • Using Gamma Controls
  • Using Color Controls

Note You should not attempt to use both the IDirectDrawGammaControl and IDirectDrawColorControl interfaces on a single surface. Their effects are undefined when used together.


What are Gamma and Color Controls?

什么是Gamma和色彩控制?(What are Gamma and Color Controls)

Through the gamma and color control interfaces, DirectDrawSurface objects enable you to change how the system displays the contents of the surface, without affecting the contents of the surface itself. You can think of these controls as very simple filters that DirectDraw applies to the data as it leaves a surface before being rendered on the screen. Surface objects implement the IDirectDrawGammaControl and IDirectDrawColorControl interfaces which expose methods to adjust how the surface's contents are filtered. You can retrieve a pointer to either interface by using the IUnknown::QueryInterface method of the target surface, specifying the IID_IDirectDrawGammaControl or IID_IDirectDrawColorControl reference identifiers.

Gamma controls, represented by the IDirectDrawGammaControl interface, make it possible for you to dynamically change how a surface's individual red, green, and blue levels map to the actual levels that the system displays. By setting gamma levels, you can cause the user's screen to flash colors梤ed when the user's character is shot, green when they pick up a new item, and so on梬ithout blitting new images to the frame buffer to achieve the effect. Or, you might adjust color levels to apply a color bias to the images in the frame buffer. Although this interface is similar to the color control interface, this one is the easiest to use, making it the best choice for game applications. For details, see Using Gamma Controls.

The IDirectDrawColorControl interface allows you to control color in a surface much like the color controls you might find on a television. The similarity between IDirectDrawColorControl and the actual controls on a TV is no mistake梩his interface is most appropriate for adjusting how broadcast video looks in an overlay surface, so it makes sense that it should provide similar control over colors. You can use color controls to allow a user to change video characteristics such as hue, saturation, contrast, and several others. For more information, see Using Color Controls.


Using Gamma Controls

使用 Gamma 控制(Using Gamma Controls)

The IDirectDrawGammaControl interface, which you retrieve by querying the surface with the IID_IDirectDrawGammaControl reference identifier, allows you to manipulate ramp levels that affect the red, green, and blue color components of pixels from the surface before they are sent to the digital-to-analog converter (DAC) for display. Although all surface types support the IDirectDrawGammaControl interface, you are only allowed to adjust gamma on the primary surface. Attempts to call IDirectDrawGammaControl::GetGammaRamp or IDirectDrawGammaControl::SetGammaRamp on a surface other than the primary surface will fail.

In the following topics, this section describes the general concept of ramp levels, and provides information about working with those levels through the methods of IDirectDrawGammaControl:

  • About Gamma Ramp Levels
  • Detecting Gamma Ramp Support
  • Setting and Retrieving Gamma Ramp Levels


About Gamma Ramp Levels

关于 Gamma Ramp 等级(About Gamma Ramp Levels)

A gamma ramp in DirectDraw is a term used to describe a set of values that map the level of a particular color component (red, green, blue) for all pixels in the frame buffer to new levels that are received by the digital-to-analog converter (DAC) for display on the monitor. The remapping is performed by way of three simple look-up tables, one for each color component.

Here's how it works: DirectDraw takes a pixel from the frame buffer, and looks at it in terms of its individual red, green, and blue color components. Each component is represented by a value from 0 to 65535. DirectDraw takes the original value, and uses it to index into an 256-element array (the ramp), where each element contains a value that replaces the original one. DirectDraw performs this "look-up and replace" process for each color component of each pixel within the frame buffer, thereby changing the final colors for all of the on-screen pixels.

It's handy to visualize the ramp values by graphing them. The left graph of the two following graphs shows a ramp that doesn't modify colors at all, and the right graph shows a ramp that imposes a negative bias to the color component to which it is applied.

The array elements for the graph on the left would contain values identical to their index (0 in the element at index 0, and 65535 at index 255). This type of ramp is the default, as it doesn't change the input values before they're displayed. The right graph is a little more interesting; its ramp contains values that range from 0 in the first element to 32768 in the last element, with values ranging relatively uniformly in between. The effect is that the color component that uses this ramp appears muted on the display. You are not limited to using linear graphs; if your application needs to assign arbitrary mapping, it's free to do so. You can even set the entries to all zeroes to leech a particular color component completely from the display.


Detecting Gamma Ramp Support

测试 Gamma Ramp 支持(Detecting Gamma Ramp Support

You can determine whether the hardware supports dynamic gamma ramp adjustment by calling the IDirectDraw4::GetCaps method. After the call, if the DDCAPS2_PRIMARYGAMMA flag is present in the dwFlags2 member of the associate DDCAPS structure, the hardware supports dynamic gamma ramps. DirectDraw does not attempt to emulate this feature, so if the hardware doesn't support it, you can't use it.


Setting and Retrieving Gamma Ramp Levels

设置和检索 Gamma Ramp 等级(Setting and Retrieving Gamma Ramp Levels)

Gamma ramp levels are effectively look-up tables that DirectDraw uses to map the frame buffer color components to new levels that will be displayed. For more information, see About Gamma Ramp Levels. You set and retrieve ramp levels for the primary surface by calling the IDirectDrawGammaControl::SetGammaRamp and IDirectDrawGammaControl::GetGammaRamp methods. Both methods accept two parameters, but the first parameter is reserved for future use, and should be set to zero. The second parameter, lpRampData, is the address of a DDGAMMARAMP structure. The DDGAMMARAMP structure contains three 256-element arrays of WORDs, one array each to contain the red, green, and blue gamma ramps.

You can include the DDSGR_CALIBRATE value when calling the IDirectDrawGammaControl::SetGammaRamp to invoke the calibrator when setting new gamma levels. Calibrating gamma ramps incurs some processing overhead, and should not be used frequently. Setting a calibrated gamma ramp will provide a consistent and absolute gamma value for the viewer, regardless of the display adapter and monitor.

Not all systems support gamma calibration. To determine if gamma calibration is supported, call IDirectDraw4::GetCaps, and examine the dwCaps2 member of the associated DDCAPS structure after the method returns. If the DDCAPS2_CANCALIBRATEGAMMA capability flag is present, then gamma calibration is supported.

When setting new ramp levels, keep in mind that that the levels you set in the arrays are only used when your application is in full-screen, exclusive mode. Whenever your application changes to normal mode, the ramp levels are set aside, taking effect again when the application reinstates full-screen mode. In addition, remember that you cannot set ramp levels for any surface other than the primary.

Note Those very familiar with the Win32� API might wonder why DirectDraw exposes an interface like IDirectDrawGammaControl, when Win32 offers the GetDeviceGammaRamp and SetDeviceGammaRamp functions for the same surfaces. Although the Win32 API includes these functions, they do not always succeed on all Windows platforms like the methods of the IDirectDrawGammaControl interface.


Using Color Controls

使用色彩控制(Using Color Controls)

You set and retrieve surface color controls through the IDirectDrawColorControl interface, which can be retrieved by querying the DirectDrawSurface object using the IID_IDirectDrawColorControl reference identifier.

Color control information is represented by a DDCOLORCONTROL structure, which is used with both methods of the interface, IDirectDrawColorControl::SetColorControls and IDirectDrawColorControl::GetColorControls. The first structure member, dwSize, should be set to the size of the structure, in bytes, before you use it. How you use the next member, dwFlags, depends on whether you are setting or retrieving color controls. If you are setting new color controls, set dwFlags to a combination of the appropriate flags to indicate which of the other structure members contain valid data that you've set. However, when retrieving color controls, you don't need to set the dwFlags before using it梚t will contain flags telling you which members are valid after the IDirectDrawColorControl::GetColorControls method returns.

The remaining DDCOLORCONTROL structure members can contain values that describe the brightness, contrast, hue, saturation, sharpness, gamma, and whether color is used. Note that the structure contains information about gamma correction. This is a single gamma value that affects overall brightness, and it should not be confused with the gamma adjustment features provided through the IDirectDrawGammaControl interface.


Overlay Surfaces

覆盖页面(Overlay Surfaces)

该节包含了关于 DirectDraw 支持覆盖页面的信息.讨论了以下主题:

  • 覆盖页面概览
  • DDCAPS 的重要成员和标志
  • 源和目标矩形
  • 边界和大小限制
  • 最小和最大缩放系数
  • 覆盖页面关键色
  • 覆盖页面的定位
  • 创建覆盖页面
  • 覆盖页面的 Z 序
  • 覆盖页面的换页

要得到更多的关于执行覆盖页面的信息,请参阅教程六:使用覆盖页面.


Overlay Surface Overview

覆盖页面概览(Overlay Surface Overview)

覆盖页面,通常也被称作重叠页面或覆盖层,是一种需要特定的硬件支持的页面.覆盖页面通常被用于显示实时视频,视频录制,或静止的位图于主页面之上,而不需要进行 Blit 操作到主页面上或用任何方法改变主页面的内容.覆盖页面完全是由硬件支持的, DirectDraw 支持由显示设备驱动程序报告的任何一种特性. DirectDraw 不支持以软件仿真的方式实现覆盖页面.

可以用一张透明的塑料片来比喻一个覆盖页面,你可以将它放在显示器屏幕前,并且在上面进行绘图.同样的道理,当覆盖页面位于显示器屏幕的上层时,你可以同时看到覆盖页面和主页面的内容,当你将覆盖页面挪开时,主页面的内容不会发生任何改动.实际上,正如前面提到的那样,一个覆盖页面的执行机制与一张透明的塑料片基本上是一样的.当你要显示一个覆盖页面的时候,你要告诉设备驱动程序在哪儿和怎样去显示这个覆盖页面.当显示设备在显示器上绘制扫描线的时候,它会检查主页面上的每一个像素的位置,来判断该处是否应该让覆盖页面可见.如果是的话,显示设备从覆盖页面上取得该处的像素颜色,并且显示出来.整个过程如下图所示:

通过这个方法,显示适配器在显示屏幕上产生了一个由主页面和覆盖页面合成的图象,并且在提供透明和缩放特效的同时,不用修改任何一个源页面的内容.这个合成的页面被注入视频数据流中,直接显示在屏幕上.因为这是一个悬空(on the fly-我们暂且这么称呼它)的操作过程,并且像素的转换是在硬件层中完成的,所以对用户来说,在显示覆盖页面的过程中,并没有可以察觉的时间损失.除此之外,这个方法还允许将具有不同的像素格式的主页面和覆盖页面合成起来.

你可以通过调用 IDirectDraw4::CreateSurface 函数创建一个覆盖页面,在相应的 DDSCAPS2 结构中指定 DDSCAPS_OVERLAY 标志符.覆盖页面只能存在于视频内存中,所以,你还必须包含 DDSCAPS_VIDEOMEMORY 标志符.与创建其它类型的页面一样,通过包含进适当的标志符,你可以创建一个单独的覆盖页面,或一个由若干个覆盖页面组成的换页链.


Significant DDCAPS Members and Flags

DDCAPS 结构中的重要成员和标志(Significant DDCAPS Members and Flags)

通过调用 IDirectDraw4::GetCaps 方法,你可以获得关于 DirectDraw 支持的覆盖页面特性的信息.该函数将描述了所有这些特性的信息填充到一个 DDCAPS 结构中.

当报告硬件特性时,如果硬件对某特定类型的限制加以实施,设备驱动程序会在 DDCAPS 结构的 dwCaps 成员中设置相应的标志符来表明.在获得驱动程序的能力之后,检查 dwCaps 成员中的标志符,以判断硬件实施了哪些限制. DDCAPS 结构中包含了九个描述了硬件对覆盖页面的限制信息的成员.下面的这张表列出了与覆盖页面相关的成员及其相应的标志符:
Member | Flag
dwMaxVisibleOverlays | This member is always valid
dwCurrVisibleOverlays | This member is always valid
dwAlignBoundarySrc | DDCAPS_ALIGNBOUNDARYSRC
dwAlignSizeSrc | DDCAPS_ALIGNSIZESRC
dwAlignBoundaryDest | DDCAPS_ALIGNBOUNDARYDEST
dwAlignSizeDest | DDCAPS_ALIGNSIZEDEST
dwAlignStrideAlign | DDCAPS_ALIGNSTRIDE
dwMinOverlayStretch | DDCAPS_OVERLAYSTRETCH
dwMaxOverlayStretch | DDCAPS_OVERLAYSTRETCH

dwMaxVisibleOverlays 和 dwCurrVisibleOverlays 成员携带了硬件设备可以显示的覆盖页面的最大个数,以及其中的多少个可以同时被显示出来的数据.

除此之外,硬件设备将覆盖页面矩形的位置和大小限制反映在 dwAlignBoundarySrc, dwAlignSizeSrc, dwAlignBoundaryDest, dwAlignSizeDest 和 dwAlignStrideAlign 成员中.这些成员中的值表明了在显示覆盖页面的时候,你必须怎样控制源和目标矩形的大小和位置.要得到更多的信息,请参阅源和目标矩形及边界和大小限制.

同样,硬件将缩放系数反映在 dwMinOverlayStretch 和 dwMaxOverlayStretch 成员中.要得到更多的信息,请参阅最小和最大缩放系数.


Source and Destination Rectangles

源和目标矩形(Source and Destination Rectangles)

要显示一个覆盖页面,调用覆盖页面的 IDirectDrawSurface4::UpdateOverlay 函数,在 dwFlags 参数中指定 DDOVER_SHOW 标志.该方法需要你在 lpSrcRect 和 lpDestRect 参数中指定源和目标矩形.源矩形描述了将显示在主页面上的覆盖页面的区域.要请求该方法使用整个页面,设置 lpSrcRect 参数为 NULL 即可.目标矩形描述了在主页面上将被用来显示覆盖页面的区域.

源和目标矩形不需要是同样的大小.通常,你所设置的目标矩形是小于或者大于源矩形的,那么在显示出覆盖页面的时候,硬件将会自动的将其进行缩小或放大.

要成功的显示覆盖页面,你可能需要调整源矩形和目标矩形的大小和位置.这是否必要,取决于你的设备驱动所强加的限制.要得到更多的信息,请参阅边界和大小限制及最小和最大缩放系数.


Boundary and Size Alignment

边界和大小限制(Boundary and Size Alignment)

由于不同的硬件的能力所限,在显示覆盖页面的时候,某些设备驱动对源和目标矩形的位置和大小强加了一些限制.要找出某个设备受到了哪些限制,调用 IDirectDraw4::GetCaps 函数,并且在 DDCAPS 的 dwCaps 成员中检查那些与覆盖页面相关的标志.下面的表展示了表明边界和大小限制的的成员极其标志:
Category | Flag | Member
Boundary (position) restrictions | DDCAPS_ALIGNBOUNDARYSRC | dwAlignBoundarySrc
 | DDCAPS_ALIGNBOUNDARYDEST | dwAlignBoundaryDest
Size restrictions | DDCAPS_ALIGNSIZESRC | dwAlignSizeSrc
 | DDCAPS_ALIGNSIZEDEST | dwAlignSizeDest

有两种类型的限制:边界限制和大小限制.每一种限制都是以像素为单位(而不是以字节为单位),并且可以提供给源和目标矩形.同样,这些限制会因为覆盖页面和主页面的像素格式的不同而不同.

边界限制影响的是你可以放置一个源或目标矩形的位置. dwAlignBoundarySrc 和 dwAlignBoundaryDest 成员所报告的值分别告诉你应如何对齐相应的矩形的左上角.矩形左上角的 x 坐标(RECT 结构的 left 成员)必须是所报告的该限制值的整数倍.

大小限制影响的是你可以设置一个源或目标矩形的合法的大小.dwAlignSizeSrc 和 dwAlignSizeDest 成员所报告的值分别告诉你应如何对齐相应矩形的宽度(以像素为单位).源或目标矩形的宽度必须是这个所报告的值的整数倍.如果你按照最小的缩放系数缩放一个矩形,还必须保证缩放后的矩形仍是满足大小限制的.在缩放完成后,用上舍入的方法(只取不舍)调整矩形的的宽度,而不是下舍入,这样才能保证满足最小缩放系数.要得到更多的信息,请参阅最小和最大缩放系数.


Minimum and Maximum Stretch Factors

最小和最大缩放系数(Minimum and Maximum Stretch Factors)

由于硬件的能力所限,某些设备对于覆盖页面从源矩形到目标矩形 Blit 操作的缩放比例存在一定的限制. DirectDraw 将这种限制称之为缩放系数.要获得设备缩放系数的数据,在你调用 IDirectDraw4::GetCaps 函数后, DDCAPS 结构中将会设置 DDCAPS_OVERLAYSTRETCH 标志.应该注意的是,缩放系数是按照实际数值的 1000 倍给出的,所以, 1300 实际上表示缩放系数为 1.3(750 表示 0.75).

对于那些对覆盖页面的缩放不存在限制的设备来说,最小和最大缩放系数的值都被设为0.

最小缩放系数报告的是目标矩形必须至少是源矩形的宽度乘以该最小缩放系数值.如果最小缩放系数比 1000 大,那么,你所指定的目标矩形必须比源矩形大.举例来说,如果设备报告的最小缩放系数是 1300,你必须保证目标矩形的宽度至少是源目标矩形宽度的 1.3 倍.同样,最小缩放系数小于 1000 表明目标矩形可以比源矩形小.

最大缩放系数报告了目标矩形必须至多是源矩形的宽度乘以该最大缩放系数.举例来说,如果最大缩放系数为 2000,你可以指定目标矩形的大小至多是源矩形大小的两倍.如果最大缩放系数小于 1000,那么,你总是必须使目标矩形比源矩形要小,才能正常的实现覆盖页面.

覆盖页面在进行完缩放操作之后,目标矩形还必须满足设备所需要的大小和位置限制.因此,先将目标矩形进行缩放,然后再进行大小和位置的调整是一个好主意.要得到更多的资料,请参阅边界和大小限制.

硬件不需要你对目标矩形的高度进行调整.你可以增加一个目标矩形的高度来保证显示正常的外观比例,而不会产生负面影响.


Overlay Color Keys

覆盖页面关键色(Overlay Color Keys)

与其它类型的页面一样,覆盖页面使用了源和目标关键色,以控制完成在不同页面间的透明 Blit 操作.因为覆盖页面本身在 Blit 操作时是不可见的,因此,当你调用 IDirectDrawSurface4::UpdateOverlay 函数的时候,需要一个另外的方法来控制该覆盖页面是如何被显示到主页面之上的.这种要求是通过覆盖页面的关键色来满足的.覆盖页面的关键色,与其它 Blit 相关的关键色一样,被分为源关键色和目标关键色,可以通过 IDirectDrawSurface4::SetColorKey 函数来设置.(要得到更多的信息,请参阅设置关键色)使用 DDCKEY_SRCOVERLAY 或 DDCKEY_DESTOVERLAY 标志来指定是源关键色还是目标关键色.覆盖页面可以使 Blit 操作,覆盖页面关键色,以及覆盖页面显示操作同时正常的进行,两种类型的关键色不会发生相互冲突.

IDirectDrawSurface4::UpdateOverlay 函数使用覆盖页面的源关键色来指定在覆盖页面上哪些像素被视为透明,以使在这些像素覆盖下的主页面的内容可以被显示出来.同样的,该函数还使用覆盖页面的目标关键色来指定在主页面上哪些部分可以被覆盖页面所占据.产生的这些视觉效果与由 Blit 相关的关键色所产生的是一样的.


Positioning Overlay Surfaces

覆盖页面的定位(Positioning Overlay Surfaces)

在调用 IDirectDrawSurface4::UpdateOverlay 函数初始化显示一个覆盖页面之后,你可以通过调用 IDirectDrawSurface4::SetOverlayPosition 函数来重新定位覆盖页面的目标矩形.

必须保证你所指定的位置要满足硬件设备所强加的边界限制.要得到更多的资料,请参阅 边界和大小限制.同时,也要记住 SetOverlayPosition 函数不会帮你进行裁剪操作,函数中使用的坐标值如果有可能使你的覆盖页面超出目标页面的边缘,将会导致该函数调用失败,返回一个 DDERR_INVALIDPOSITION 错误.


Creating Overlay Surfaces

创建覆盖页面(Creating Overlay Surfaces)

与其它的页面一样,通过调用 IDirectDraw4::CreateSurface 函数可以创建一个覆盖页面,条件是必须在 DDSCAPS2 结构中指定 DDSCAPS_OVERLAY 标志.

对覆盖页面的支持随显示设备的不同而存在着巨大的差异.因此,绝对不要认为存在一个被绝大多数硬件设备所支持的像素格式,必须作好准备与各种各样不同的像素格式打交道.通过调用 IDirectDraw4::GetFourCCCodes 函数,你可以得到设备驱动所支持的有关非 RGB 格式的信息.

当你创建一个覆盖页面的时候,先试着创建一个被大多数设备所认可的像素格式,如果失败,再试着使用其它的格式,这种方法是比较好的.

你可以创建一个覆盖页面换页链.要得到更多的信息,请参阅创建复杂页面和换页链.


Overlay Z-Orders

覆盖页面的 Z 序(Overlay Z-Orders)

覆盖页面在 DirectDraw 中被认为是位于屏幕上所有内容的最上一层,但是,当你需要显示多个覆盖页面的时候,你需要有一个办法来组织这些页面.为此, DirectDraw 支持覆盖 Z 序(overlay z-ordering),来管理这些覆盖页面层次关系和相互裁减.Z 序值代表了从主页面到观察者之间的一个抽象的距离.这些值的可能范围是从 0,紧靠着主页面的一层,直到 40 亿,最靠近观察者的一层,并且没有任何两个覆盖页面可以共享同一个 Z 序值.通过调用 IDirectDrawSurface4::UpdateOverlayZOrder 可以设置一个覆盖页面的 Z 序.

目标关键色(destination color keys)只受主页面(primary surface)的影响,而不会受到被另一个覆盖页面所覆盖的覆盖页面的影响.源关键色(source color keys)作用于覆盖页面,而不考虑该覆盖页面是否被设置了Z轴次序.

没有指定 Z 序的覆盖页面,其 Z 序被默认为0.没有指定 Z 序的多个覆盖页面间的层次关系是不可预知的,当它们被映射到主页面上时,会产生混乱.

一个 DriectDraw 对象不能跟踪由另一个应用程序显示的覆盖页面的 Z 序.

注意 你可以通过在 WM_KILLFOCUS 消息中调用 UpdateOverlayZOrder 来确定多个覆盖页面的裁剪次序.当你收到这个消息时,通过调用 UpdateOverlayZOrder 方法,把其 dwFlags 参数设置为 DDOVERZ_SENDTOBACK 就可以把你的覆盖页面的 Z 序设置为最接近的.


Flipping Overlay Surfaces

覆盖页面的换页(Flipping Overlay Surfaces)

和其它各类型的页面一样,你可以创建覆盖页面的换页链.在创建好一个覆盖页面的换页链之后,你可以通过调用 IDirectDrawSurface4::Flip 方法实现换页.要得到更多的信息,请参阅换页.

利用覆盖页面的软件视频解码在调用 Flip 函数实现换页的时候,可以使用 DDFLIP_ODD 和 DDFLIP_EVEN 标志,以利用减少运动噪声的特性.如果设备驱动支持奇偶(odd-even)隔行换页,在获取设备驱动能力后 DDCAPS 结构中将会被设置 DDCAPS2_CANFLIPODDEVEN 标志.如果是这样的话,那么,在调用 IDirectDrawSurface4::UpdateOverlay 函数时,你可以包含进 DDOVER_BOB 标志,以告知设备驱动你希望它使用 BOB(摆动)算法来使运动噪声达到最小.随后,在你调用 Flip 函数实现换页时,你可以带上 DDFLIP_ODD 或 DDFLIP_EVEN 标志,设备驱动将会自动的调整覆盖页面的源矩形来补偿不稳定的噪声.

获取设备驱动能力时,如果驱动设备没有设置 DDCAPS2_CANFLIPODDEVEN 标志,那么,指定了 DDOVER_BOB 标志的 UpdateOverlay 函数调用将会失败.

要得到更多的关于Bob算法的信息,请参阅普通视频噪声的解决方案.


Compressed Texture Surfaces

压缩纹理页面(Compressed Texture Surfaces)

A surface can contain a bitmap to be used for texturing 3-D objects. When creating the surface you must specify the DDSCAPS_TEXTURE flag in the dwFlags member of the DDSCAPS structure.

For more information on the use of textures in Direct3D Immediate Mode, see Textures.

In order to reduce the amount of memory consumed by textures, DirectDraw supports the compression of texture surfaces.

Some Direct3D devices support compressed texture surfaces natively. On such devices, once you have created a compressed surface and loaded the data into it, the surface can be used in Direct3D just like any other texture surface. Direct3D handles decompression when the texture is mapped to a 3-D object.

Other devices do not support compressed texture surfaces natively. When using such devices, you may still find it useful to use compressed surfaces to represent textures on disk or for textures that are loaded into memory but not currently being used. You can use DirectDraw to convert the compressed textures to an uncompressed format before giving the texture to Direct3D.

For more information on texture compression in DirectDraw, see the following topics:

  • Creating Compressed Textures
  • Decompressing Compressed Textures
  • Transparency in Blits to Compressed Textures
  • Compressed Texture Formats

For information on using compressed textures in Direct3D Immediate Mode, see Texture Compression.


Creating Compressed Textures

生成纹理压缩(Creating Compressed Textures)

To describe a compressed texture surface in the DDSURFACEDESC2 structure when creating the surface, you must include the following steps:

  • Specify the DDSCAPS_TEXTURE flag in the dwFlags member of the DDSCAPS structure, just as you would for any texture.
  • Set the dwFourCC member of the DDPIXELFORMAT structure to one of the DXT codes described later.
  • Include DDPF_FOURCC in the dwFlags member of DDPIXELFORMAT. Do not set the DDPF_RGB flag.
  • Specify a width and height that are a multiple of 4 pixels.

There are two ways to load image data into a compressed texture surface:

  • Create a regular RGB or ARGB surface and load a normal bitmap into it, then use IDirectDrawSurface4::Blt or IDirectDrawSurface4::BltFast to blit from the uncompressed surface to the compressed surface. DirectDraw does the compression for you.
  • Load the compressed data from a file and copy it directly into the surface memory. (See Accessing Surface Memory Directly.) You can create and convert compressed texture (DDS) files using the DirectX Texture Tool (Dxtex.exe) supplied with the Programmer's Reference. You can also create your own DDS files and either copy the data from compressed surfaces or else use your own routines to convert regular bitmap data to one of the compressed formats.

Note When you call IDirectDrawSurface4::Lock or IDirectDrawSurface4::GetSurfaceDesc on a compressed surface, the DDSD_LINEARSIZE flag is set in the dwFlags member of the DDSURFACEDESC structure, and the dwLinearSize member contains the number of bytes allocated to contain the compressed surface data. The dwLinearSize parameter resides in a union with the lPitch parameter, so these parameters are mutually exclusive, as are the flags DDSD_LINEARSIZE and DDSD_PITCH.

The advantage of this behavior is that an application can copy the contents of a compressed surface to a file without having to calculate for itself how much storage is required for a surface of a particular width and height in the specific format.

The following table shows the five types of compressed textures. For more information on how the data is stored (you need to know this only if you are writing your own compression routines) see Compressed Texture Formats.

FOURCC | Description | Alpha premultiplied?
DXT1 | Opaque / one-bit alpha | n/a
DXT2 | Explicit alpha | Yes
DXT3 | Explicit alpha | No
DXT4 | Interpolated alpha | Yes
DXT5 | Interpolated alpha | No

Note When you blit from a non-premultiplied format to a premultiplied format, DirectDraw scales the colors based on the alpha values. Blitting from a premultiplied format to a non-premultiplied format is not supported. If you try to blit from a premultiplied-alpha source to a non-premultiplied-alpha destination, the method will return DDERR_INVALIDPARAMS. If you blit from a premultiplied-alpha source to a destination that has no alpha, the source color components, which have been scaled by alpha, will be copied as is.


Decompressing Compressed Textures

解压缩纹理压缩(Decompressing Compressed Textures)

As with compressing a texture surface, decompressing a compressed texture is performed through DirectDraw blitting services. The HEL performs decompressing blits between system memory surfaces, so these always supported. Likewise, the HEL always performs blits for compressed managed textures (the DDSCAPS2_TEXTUREMANAGE capability). For other situations, the restrictions discussed in the following paragraphs apply.

If the driver supports the creation of compressed video-memory surfaces, then the driver can also perform decompressing blits from a compressed video-memory surface to an uncompressed video or system memory surface, so long as the destination surface has the DDSCAPS_OFFSCREENPLAIN capability.

Blits from compressed system-memory surfaces to uncompressed video-memory surfaces are largely unsupported and should not be attempted, even when the driver supports compressed textures. This does not mean that it is impossible to decompress a compressed system-memory surface and move its contents into a video memory surface; it merely requires an additional step:

To decompress a system memory surface into video memory:

  1. Create an uncompressed, offscreen-plain, surface in system memory of the desired dimensions and pixel format.
  2. Blit from the compressed system-memory surface to the uncompressed system-memory surface. (The DirectDraw HEL performs decompression in this case.)
  3. Blit the uncompressed surface to the uncompressed video-memory surface.


Transparency in Blits to Compressed Textures

压缩纹理的 Blit 透明度(Transparency in Blits to Compressed Textures)

DirectDraw provides a special trick for creating compressed textures with alpha from plain RGB surfaces. If a source color key is provided on the source RGB surface, DirectDraw assigns an alpha value of 0 to all pixels of that color in the destination. This technique is especially useful for creating DXT1 textures, since they effectively have only 1 bit of alpha information per pixel.

Note There are no flags that control this behavior. If you do not want any transparency in your compressed texture, do not set a source color key on the source surface.


Compressed Texture Formats

压缩纹理格式(Compressed Texture Formats)

This section contains information on the internal organization of compressed texture formats. You don't need these details in order to use compressed textures, because DirectDraw handles conversion to and from compressed formats. However, you might find this information useful if you want to operate on compressed surface data directly.

DirectDraw uses a compression format that divides texture maps into 4x4 texel blocks. If the texture contains no transparency (is opaque), or if the transparency is specified by a one-bit alpha, an 8-byte block represents the texture map block. If the texture map does contain transparent texels, using an alpha channel, a 16-byte block represents it.

These two types of format are discussed in the following sections:

  • Opaque and One-bit Alpha Textures
  • Textures with Alpha Channels

Note Any single texture must specify that its data is stored as 64 or 128 bits per group of 16 texels. If 64-bit blocks梩hat is, format DXT1梐re used for the texture, it is possible to mix the opaque and one-bit alpha formats on a per-block basis within the same texture. In other words, the comparison of the unsigned integer magnitude of color_0 and color_1 is performed uniquely for each block of 16 texels.

When 128-bit blocks are used, then the alpha channel must be specified in either explicit (format DXT2 or DXT3) or interpolated mode (format DXT4 or DXT5) for the entire texture. Note that as with color, once interpolated mode is selected then either 8 interpolated alphas or 6 interpolated alphas mode can be used on a block-by-block basis. Again the magnitude comparison of alpha_0 and alpha_1 is done uniquely on a block-by-block basis.


Opaque and One-bit Alpha Textures

不透明和单比特 Alpha 纹理(Opaque and One-bit Alpha Textures)

Texture format DXT1 is for textures that are opaque or have a single transparent color.

For each opaque or one-bit alpha block, two 16-bit values (RGB 5:6:5 format) and a 4x4 bitmap with 2-bits-per-pixel are stored. This totals 64 bits for 16 texels, or 4-bits-per-texel. In the block bitmap, there are two bits per texel to select between the four colors, two of which are stored in the encoded data. The other two colors are derived from these stored colors by linear interpolation.

The one-bit alpha format is distinguished from the opaque format by comparing the two 16-bit color values stored in the block. They are treated as unsigned integers. If the first color is greater than the second, it implies that only opaque texels are defined. This means four colors will be used to represent the texels. In four-color encoding, there are two derived colors and all four colors are equally distributed in RGB color space. This format is analogous to RGB 5:6:5 format. Otherwise, for one-bit alpha transparency, three colors are used and the fourth is reserved to represent transparent texels.

In three-color encoding, there is one derived color and the fourth two-bit code is reserved to indicate a transparent texel (alpha information). This format is analogous to RGBA 5:5:5:1, where the final bit is used for encoding the alpha mask.

The following piece of pseudo-code illustrates the algorithm for deciding whether three- or four-color encoding is selected:

if (color_0 > color_1)
{
    // Four-color block: derive the other two colors.
    // 00 = color_0, 01 = color_1, 10 = color_2, 11 = color_3
    // These two bit codes correspond to the 2-bit fields
    // stored in the 64-bit block.
     color_2 = (2 * color_0 + color_1) / 3;
     color_3 = (color 0 + 2 * color_1) / 3;
}
else
{
    // Three-color block: derive the other color.
    // 00 = color_0,  01 = color_1,  10 = color_2,
    // 11 = transparent.
    // These two bit codes correspond to the 2-bit fields
    // stored in the 64-bit block.
     color_2 = (color_0 + color_1) / 2;
     color_3 = transparent;
}

The following tables show the memory layout for the 8-byte block. It is assumed that the first index corresponds to the y-coordinate and the second corresponds to the x-coordinate. For example, Texel[1][2] refers to the texture map pixel at (x,y) = (2,1).

Here is the memory layout for the 8-byte (64-bit) block:

Word address | 16-bit word
0 | Color_0
1 | Color_1
2 | Bitmap Word_0
3 | Bitmap Word_1

Color_0 and Color_1 (colors at the two extremes) are laid out as follows:

Bits | Color
4:0 (LSB) | Blue color component
10:5 | Green color component
15:11 | Red color component

Bitmap Word_0 is laid out as follows:

Bits | Texel
1:0 (LSB) | Texel[0][0]
3:2 | Texel[0][1]
5:4 | Texel[0][2]
7:6 | Texel[0][3]
9:8 | Texel[1][0]
11:10 | Texel[1][1]
13:12 | Texel[1][2]
15:14 (MSB) | Texel[1][3]

Bitmap Word_1 is laid out as follows:

Bits | Texel
1:0 (LSB) | Texel[2][0]
3:2 | Texel[2][1]
5:4 | Texel[2][2]
7:6 | Texel[2][3]
9:8 | Texel[3][0]
11:10 | Texel[3][1]
13:12 | Texel[3][2]
15:14 (MSB) | Texel[3][3]

Example of Opaque Color Encoding

As an example of opaque encoding, we will assume that the colors red and black are at the extremes. We will call red color_0 and black color_1. There will be four interpolated colors that form the uniformly distributed gradient between them. To determine the values for the 4x4 bitmap, the following calculations are used:

00 ? color_0
01 ? color_1
10 ? 2/3 color_0 + 1/3 color_1
11 ? 1/3 color_0 + 2/3 color_1

Example of One-bit Alpha Encoding

This format is selected when the unsigned 16-bit integer, color_0, is less than the unsigned 16-bit integer, color_1. An example of where this format could be used is leaves on a tree to be shown against a blue sky. Some texels could be marked as transparent while three shades of green are still available for the leaves. Two of these colors fix the extremes, and the third color is an interpolated color.

The bitmap encoding for the colors and the transparency is determined using the following calculations:

00 ? color_0
01 ? color_1
10 ? 1/2 color_0 + 1/2 color_1
11   ?   Transparent


Textures with Alpha Channels

Alpha 通道纹理(Textures with Alpha Channels)

There are two ways to encode texture maps that exhibit more complex transparency. In each case, a block that describes the transparency precedes the 64-bit block already described. The transparency is either represented as a 4x4 bitmap with four bits per pixel (explicit encoding), or with fewer bits and linear interpolation analogous to what is used for color encoding.

The transparency block and the color block are laid out as follows:

Word Address | 64-bit Block
3:0 | Transparency block
7:4 | Previously described 64-bit block

Explicit Texture Encoding

For explicit texture encoding (DXT2 and DXT3 formats), the alpha components of the texels that describe transparency are encoded in a 4x4 bitmap with 4 bits per texel. These 4 bits can be achieved through a variety of means such as dithering or by simply using the 4 most significant bits of the alpha data. However they are produced, they are used just as they are, without any form of interpolation.

Note DirectDraw's compression method uses the 4 most significant bits.

The following tables illustrate how the alpha information is laid out in memory, for each 16-bit word.

This is the layout for Word 0:

Bits | Alpha
3:0 (LSB) | [0][0]
7:4 | [0][1]
11:8 | [0][2]
15:12 (MSB) | [0][3]

This is the layout for Word 1:

Bits | Alpha
3:0 (LSB) | [1][0]
7:4 | [1][1]
11:8 | [1][2]
15:12 (MSB) | [1][3]

This is the layout for Word 2:

Bits | Alpha
3:0 (LSB) | [2][0]
7:4 | [2][1]
11:8 | [2][2]
15:12 (MSB) | [2][3]

This is the layout for Word 3:

Bits | Alpha
3:0 (LSB) | [3][0]
7:4 | [3][1]
11:8 | [3][2]
15:12 (MSB) | [3][3]

Three-Bit Linear Alpha Interpolation

The encoding of transparency for the DXT4 and DXT5 formats is based on a concept similar to the linear encoding used for color. Two 8-bit alpha values and a 4x4 bitmap with three bits per pixel are stored in the first eight bytes of the block. The representative alpha values are used to interpolate intermediate alpha values. Additional information is available in the way the two alpha values are stored. If alpha_0 is greater than alpha_1, then six intermediate alpha values are created by the interpolation. Otherwise, four intermediate alpha values are interpolated between the specified alpha extremes. The two additional implicit alpha values are 0 (fully transparent) and 255 (fully opaque).

The following pseudo-code illustrates this algorithm:

// 8-alpha or 6-alpha block?
if (alpha_0 > alpha_1) {
     // 8-alpha block:  derive the other 6 alphas.
    // 000 = alpha_0, 001 = alpha_1, others are interpolated
    alpha_2 = (6 * alpha_0 + alpha_1) / 7;      // bit code 010
    alpha_3 = (5 * alpha_0 + 2 * alpha_1) / 7;  // Bit code 011
    alpha_4 = (4 * alpha_0 + 3 * alpha_1) / 7;  // Bit code 100
    alpha_5 = (3 * alpha_0 + 4 * alpha_1) / 7;  // Bit code 101
    alpha_6 = (2 * alpha_0 + 5 * alpha_1) / 7;  // Bit code 110
    alpha_7 = (alpha_0 + 6 * alpha_1) / 7;      // Bit code 111
  }
else {  // 6-alpha block:  derive the other alphas.
    // 000 = alpha_0, 001 = alpha_1, others are interpolated
    alpha_2 = (4 * alpha_0 + alpha_1) / 5;      // Bit code 010
    alpha_3 = (3 * alpha_0 + 2 * alpha_1) / 5;  // Bit code 011
    alpha_4 = (2 * alpha_0 + 3 * alpha_1) / 5;  // Bit code 100
    alpha_5 = (alpha_0 + 4 * alpha_1) / 5;      // Bit code 101
    alpha_6 = 0;                                // Bit code 110
    alpha_7 = 255;                              // Bit code 111
}

The memory layout of the alpha block is as follows:

Byte | Alpha
0 | Alpha_0
1 | Alpha_1
2 | [0][2] (2 LSBs), [0][1], [0][0]
3 | [1][1] (1 LSB), [1][0], [0][3], [0][2] (1 MSB)
4 | [1][3], [1][2], [1][1] (2 MSBs)
5 | [2][2] (2 LSBs), [2][1], [2][0]
6 | [3][1] (1 LSB), [3][0], [2][3], [2][2] (1 MSB)
7 | [3][3], [3][2], [3][1] (2 MSBs)


Private Surface Data

页面私有数据(Private Surface Data)

You can store any kind of application-specific data with a surface. For example, a surface representing a map in a game might contain information about terrain.

A surface can have more than one private data buffer. Each buffer is identified by a GUID which you supply when attaching the data to the surface.

To store private surface data, you use the IDirectDrawSurface4::SetPrivateData method, passing in a pointer to the source buffer, the size of the data, and an application-defined GUID for the data. Optionally, the source data can exist in the form of a COM object; in this case, you pass a pointer to the object's IUnknown interface pointer and you set the DDSPD_IUNKNOWNPOINTER flag. Another flag, DDSPD_VOLATILE, indicates that the data being attached to the surface is valid only as long as the contents of the surface do not change. (See Surface Uniqueness Values.)

SetPrivateData allocates an internal buffer for the data and copies it. You can then safely free the source buffer or object. The internal buffer or interface reference is released when IDirectDrawSurface4::FreePrivateData is called. This happens automatically when the surface is freed.

To retrieve private data for a surface, you must allocate a buffer of the correct size and then call the IDirectDrawSurface4::GetPrivateData method, passing the GUID that was assigned to the data by SetPrivateData. You are responsible for freeing any dynamic memory you use for this buffer. If the data is a COM object, this method retrieves the IUnknown pointer.

If you don't know how big a buffer to allocate, first call GetPrivateData with zero in *lpcbBufferSize. If the method fails with DDERR_MOREDATA, it returns the necessary number of bytes in *lpcbBufferSize.


Surface Uniqueness Values

页面特征值(Surface Uniqueness Values)

The uniqueness value of a surface allows you to determine whether the surface has changed. When DirectDraw creates a surface, it assigns a uniqueness value, which you can retrieve and store by using the IDirectDrawSurface4::GetUniquenessValue method. Then, whenever you need to determine whether the surface has changed, you call the method again and compare the new value against the old one. If it's different, the surface has changed.

The actual value returned by GetUniquenessValue is irrelevant, unless it is 0. DirectDraw assigns this value to a surface when it knows that the surface might be changed by some process beyond its control. When GetUniquenessValue returns 0, you know only that the state of the surface is indeterminate.

To force the uniqueness value for a surface to change, an application can use the IDirectDrawSurface4::ChangeUniquenessValue method. This method could be called, for example, by an application or component that changed the private data for a surface without changing the surface itself, and wished to notify some other process of the change. Most applications, however, never need to change the uniqueness value.


Using Non-local Video Memory Surfaces

使用非本地视频缓冲页面(Using Non-local Video Memory Surfaces)

DirectDraw supports the Accelerated Graphics Port (AGP) architecture for creating surfaces in non-local video memory. On AGP-equipped systems, DirectDraw will use non-local video memory if local video memory is exhausted or if non-local video memory is explicitly requested, depending on the type of AGP implementation that is in place.

Currently, there are two implementations of the AGP architecture, known as the "execute model" and the "DMA model." In the execute model implementation, the display device supports the same features for non-local video memory surfaces and local video memory surfaces. As a result, when you retrieve hardware capabilities by calling the IDirectDraw4::GetCaps method, the blit-related flags in the dwNLVBCaps, dwNLVBCaps2, dwNLVBCKeyCaps, dwNLVBFXCaps, and dwNLVBRops members of the DDCAPS structure will be identical to those for local video memory. Under the execute model, if local video memory is exhausted, DirectDraw will automatically fall back on non-local video memory unless the caller specifically requests otherwise.

In the DMA model implementation, support for blitting and texturing from non-local video memory surfaces is limited. When the display device uses the DMA model, the DDCAPS2_NONLOCALVIDMEMCAPS flag will be set in the dwCaps2 member when you retrieve device capabilities. In the DMA model, the blit-related flags included in the dwNLVBCaps, dwNLVBCaps2, dwNLVBCKeyCaps, dwNLVBFXCaps, and dwNLVBRops members of the DDCAPS structure describe the features that are supported; these features will often be a smaller subset of those supported for local video memory surfaces. Under the DMA model, when local video memory is exhausted, DirectDraw will automatically fall back on non-local video memory for texture surfaces only, unless the caller had explicitly requested local video memory. Texture surfaces are the only types of surfaces that will be treated this way; all other types of surfaces cannot be created in non-local video memory unless the caller explicitly requests it.

DMA model implementations vary in support for texturing from non-local video memory surfaces. If the driver supports texturing from non-local video memory surfaces, the D3DDEVCAPS_TEXTURENONLOCALVIDMEM flag will be set when you retrieve the 3-D device's capabilities by calling the IDirect3DDevice3::GetCaps method.


Converting Color and Format

转换色彩和格式(Converting Color and Format)

Non-RGB surface formats are described by four-character codes (FOURCC). If an application calls the IDirectDrawSurface4::GetPixelFormat method to request the pixel format, and the surface is a non-RGB surface, the DDPF_FOURCC flag will be set and the dwFourCC member of the DDPIXELFORMAT structure will be valid. If the FOURCC code represents a YUV format, the DDPF_YUV flag will also be set and the dwYUVBitCount, dwYBitMask, dwUBitMask, dwVBitMask, and dwYUVAlphaBitMask members will be valid masks that can be used to extract information from the pixels.

If an RGB format is present, the DDPF_RGB flag will be set and the dwRGBBitCount, dwRBitMask, dwGBitMask, dwBBitMask, and dwRGBAlphaBitMask members will be valid masks that can be used to extract information from the pixels. The DDPF_RGB flag can be set in conjunction with the DDPF_FOURCC flag if a nonstandard RGB format is being described.

During color and format conversion, two sets of FOURCC codes are exposed to the application. One set of FOURCC codes represents the capabilities of the blitting hardware; the other represents the capabilities of the overlay hardware.

For more information, see Four Character Codes (FOURCC).


Surfaces and Device Contexts

页面和设备描述(Surfaces and Device Contexts)

It is often convenient to mix-and-match DirectDraw and GDI services to manipulate the contents of DirectDraw surfaces. DirectDraw offers methods to enable GDI to access DirectDraw surfaces through device contexts, and to retrieve a surface given the surface's device context. This section contains the follows topics that describe these features in detail:

  • Retrieving the Device Context for a Surface
  • Finding a Surface with a Device Context


Retrieving the Device Context for a Surface

为页面取得设备描述(Retrieving the Device Context for a Surface)

If you want to modify the contents of a DirectDraw surface object by using GDI functions, you must retrieve a GDI-compatible device context handle. This could be useful if you wanted to display text in a DirectDraw surface by calling the DrawText Win32 function, which accepts a handle to a device context as a parameter. It is possible to retrieve a GDI-compatible device context for a surface by calling the IDirectDrawSurface4::GetDC method for that surface. The following example shows how this might be done:

// For this example the lpDDS4 variable is a valid pointer
// to an IDirectDrawSurface4 interface.

    HDC     hdc;
    HRESULT HR;

    hr = lpDDS4->GetDC(&hdc);
    if(FAILED(hr))
        return hr;

    // Call DrawText, or some other GDI
    // function here.

    lpDDS4->ReleaseDC(hdc);

Note that the code calls the IDirectDrawSurface4::ReleaseDC method when the surface's device context is no longer needed. This step is required, because the IDirectDrawSurface4::GetDC method uses an internal version of the IDirectDrawSurface4::Lock method to lock the surface. The surface remains locked until the IDirectDrawSurface4::ReleaseDC method is called.


Finding a Surface with a Device Context

利用设备描述查找页面(Finding a Surface with a Device Context)

You can retrieve a pointer to a surface's IDirectDrawSurface4 interface from the device context for the surface by calling the IDirectDraw4::GetSurfaceFromDC method. This feature might be very useful for component applications or ActiveX� controls, that are commonly given a device context to draw into at run-time, but could benefit by exploiting the features exposed by the IDirectDrawSurface4 interface.

A device context might identify memory that isn't associated with a DirectDraw object, or the device context might identify a surface for another DirectDraw object entirely. The latter case is most likely to occur on a system with multiple monitors. If the device context doesn't identify a surface that wasn't created by that DirectDraw object, the method fails, returning DDERR_NOTFOUND.

The following sample code shows what a very simple scenario might look like:

    // For this example, the hdc variable is a valid
    // handle to a video memory device context, and the
    // lpDD4 variable is a valid IDirectDraw4 interface pointer.

    LPDIRECTDRAWSURFACE4 lpDDS4;
    HRESULT hr;

    hr = lpDD4->GetSurfaceFromDC(hdc, &lpDDS4);
    if(SUCCEEDED(hr)) {
        // Use the surface interface.
    }
    else if(DDERR_NOTFOUND == hr) {
        OutputDebugString("HDC not from this DirectDraw surface\n");
    }


Palettes

调色板(Palettes)

这部分讨论了关于 DirectDrawPalette 对象的信息.讨论了以下主题:

  • 什么是调色板?
  • 调色板的种类
  • 对非主页面设置调色板
  • 共享调色板
  • 调色板动画


What Are Palettes?

基于调色板的页面需要调色板才能真正有意义的显示出来.一个基于调色板的页面,通常也被称作一个"色彩索引"页面,仅仅是一些数字的集合,其中的每一个数字代表一个像素.每一个数字的值都对应于一个色彩表(color table)中的项,这个表告诉 DirectDraw 对这个像素使用什么样的颜色. DirectDrawPalette 对象,通常简称为"调色板",给你提供了一个及其方便的途径来管理调色板.那些使用16位或更高位像素格式的页面并不使用调色板.

提供 DirectDrawPalette 对象是为了拥有直接操作 16 和 256 色调色板的特性(一个 DirectDrawPalette 对象通常与一个 DirectDrawSurface 对象相依属).一个 DirectDrawPalette 对象保留了一个从 0 到 255 的 256 色调色板的入口;它不保留 16 色调色板的任何入口.它允许直接对色彩表(color table)的直接操作.一个色彩表是一系列颜色值(典型的是 RGB 三个一组).这个表可以包含 16 或 24 位的 RGB 色彩入口,代表与每一个索引相对应的颜色.对 16 色调色板来说,色彩表可以包含另一个 256 色调色板的索引.调色板被材质图,离屏页面(off-screen surfaces),覆盖页面(overlay surfaces)所支持,它们并不需要与主页面(primary surface)拥有同样的调色板.

你可以通过调用 IDirectDraw4::CreatePalette 函数来创建一个调色板.该函数将返回一个指向 IdirectDrawPalette 接口的调色板对象的指针.你可以使用该接口的函数来操作调色板入口,获得关于调色板对象能力的信息,或初始化该对象(如果你用 CoCreateInstance 函数创建它).

你可以通过调用 IDirectDrawSurface4::SetPalette 函数将一个调色板连接到一个页面上.一个调色板可以被连接到若干个页面.

DirectDrawPalette 对象为一个 8 位的调色板保留了从 0 到 255 的入口,除非你指定了 DDPCAPS_ALLOW256 标志请求所有这些入口都可以被你所用.

通过调用 IDirectDrawPalette::GetEntries, 应用程序可以获得这些表的入口,并且可以通过 IDirectDrawPalette::SetEntries 改变这些入口.这个函数有一个 dwFlags 参数,指定对于调色板的改动是否立即生效.

SDK 中的 Ddutil.cpp 源文件包含了一些关于操作调色板的唾手可得的应用程序定义的函数(非库函数).要得到更多的信息,请参阅源文件中的 DDLoadPalette 函数.


Palette Types

调色板的种类(Palette Types)

DirectDraw 支持1位(2个入口),2位(4个入口),4位(16个入口),和8位(256个入口)的调色板.一个调色板只能依附于符合其像素格式的页面.例如,一个由 DDPCAPS_1BIT 标志创建的2入口(2-entry)的调色板只能被依附于一个由 DDPF_PALETTEINDEXED1 标志创建的1位(1-bit)页面.

除此之外,你可以创建一个不包含色彩表的调色板,这就是索引调色板(indexed palettes).一个索引调色板是指:一个索引调色板的色彩表(color table)是一个2,4,16,256字节的序列,每一个字节是另一个调色板的索引.

要创建一个索引调色板,在调用 IDirectDraw4::CreatePalette 时指定 DDPCAPS_8BITENTRIES 标志.例如,要创建一个 4 位的索引调色板,指定 DDPCAPS_4BIT 和 DDPCAPS_8BITENTRIES. 当你创建一个索引调色板,传递一个指向一系列字节的指针,而不是一个指向 PALETTEENTRY结构的指针.当你使用 IDirectDraw4::CreatePalette 时,必须将一个指向字节组的指针转换成 LPPALETTEENTRY 类型.

注意在 Blit 操作的过程中, DirectDraw 不会解除索引调色板,而使其成为普通调色板.


Setting Palettes on Nonprimary Surfaces

对非主页面设置调色板(Setting Palettes on Nonprimary Surfaces)

调色板可以依属于任何一种基于调色板的页面(主页面,后台缓存(back buffer),离屏平面,或材质图).只有那些被依属到主页面(primary surfaces)的调色板才能对系统调色板(system palette)产生影响.注意到这一点是很重要的: DirectDraw 位图映射决不会导致色彩转换,任何依属于源或目标页面的调色板在位图映射中被忽略.

非主页面调色板可以被 Direct3D 应用程序所使用.


Sharing Palettes

共享调色板(Sharing Palettes)

调色板可以被多个页面所共享.同一个调色板可以设置给一个换页链的前台缓存(front buffer)和后台缓存(back buffer),或在多个材质页面中共享.当应用程序调用 IDirectDrawSurface4::SetPalette 使一个调色板依属于一个页面,页面将递增该调色板的引用记录(reference count).当页面的引用记录达到 0 时,页面将递减依属于它的该调色板的引用记录.除此之外,如果通过 IDirectDrawSurface4::SetPalette 使调色板脱离页面,则该调色板的引用记录将减1.

注意 如果对同一页面反复调用 IDirectDrawSurface4::SetPalette 以脱离同一调色板,则该调色板的引用记录只会递减一次.后来的调用不会影响调色板的引用记录.


Palette Animation

调色板动画(Palette Animation)

调色板动画指的是:用修改隶属于一个页面的调色板的方法来实现显示页面色彩的变化,而不是通过实际修改页面的内容来实现页面的变化.为了这个目的,调色板动画给你提供了一个不需要改变页面内容,改变页面所显示的图象的途径,而只会产生很少的消耗.

有两种方法可以直接实现调色板动画:

  • 修改调色板的入口
  • 在两个调色板之间切换

使用第一个方法,改变为实现动画所需要改变颜色的调色板入口.这种方法,你可以通过调用 IDirectDrawPalette::SetEntries 来实现调色板的重置.

第二个方法需要两个 DirectDrawPalette 对象.应用程序通过轮流将两个 DirectDrawPalette 与 DirectDrawSurface 对象相依属,来实现动画.这种方法,你可以通过调用 IDirectDrawSurface4::SetPalette 来实现.

没有一种技术会使硬件产生激烈反应,所以,你可以随心所欲的选择适合于你的程序的那种.

要得到特定的信息,以及如何实现调色板动画的例子,请参阅教程五:动态改变调色板.


Clippers

裁剪器(Clippers)

这一部分包含了关于 DirectDrawClipper 对象的信息.讨论了以下主题:

  • 什么是裁剪器
  • 裁剪清单
  • 共享裁剪器对象
  • 独立的裁剪器对象
  • 用 CoCreateInstance 创建裁剪器对象
  • 对系统鼠标使用裁剪器
  • 对多窗口使用裁剪器


What Are Clippers?

什么是裁剪器(What Are Clippers?)

裁剪器,或 DirectDrawClipper 对象,限定你的 Blit 操作到一个指定的页面区域.一个裁剪器对象拥有一个或多个裁剪清单.一个裁剪清单是一个或一系列封闭的矩形,描述了页面上的一个或一系列矩形区域,只有在该区域内才允许 Blit.(请参阅:裁剪清单)

裁剪清单是一个颇有价值的工具.它们最通常的作用是阻止你的应用程序在 Blit 操作时,超出屏幕的边界.举例来说,想象一个子图形从屏幕的一边逐渐进入屏幕.你不会想让你的子图形是突然出现在屏幕上的,你想让它从屏幕的边上一点一点的出现.如果没有裁剪器对象,你应该需要在程序中加入一个逻辑判断和运算,逐步修改 Blit 操作的参数,以保护那些超出屏幕边缘的页面内存,如果没有这些逻辑操作的话,你的应用程序会产生内存访问异常(memory access violations)的错误.

下面的插图展示了这种类型的裁剪:

你可以使用裁剪器对象来指定目标页面的特定区域为可写的. DirectDraw 在这些区域中裁剪 Blit 操作,以保护那些指定裁剪矩形以外的区域不被改写.

下面的例图展示了这种类型的裁剪:


Clip Lists

裁剪清单(Clip Lists)

一个裁剪清单包含一个或多个以像素为坐标的 RECT 结构, DirectDraw 用 DirectDrawClipper 对象来管理裁剪表.一个 DirectDrawClipper 对象可以被依附于任何一个页面.

IDirectDrawSurface4::Blt 方法仅把数据拷贝到裁剪清单中的矩形里.例如,如果页面的左上角不被包含在裁剪清单的矩形里,而应用程序 Blit 到被裁剪的页面的整个区域里; DirectDraw 将会有效地进行两个 Blit 操作,第一个开始于页面的左上角,第二个开始于页面的高度的中部,如下图所示.

你可以手工地管理一个页面的裁剪清单,也可以让 DirectDraw 自动地为主页面(primary surface)管理它.

要自己管理裁剪清单,应该以 RGNDATA 结构的形式创建一个矩形列表并把它传给 IDirectDrawClipper::SetClipList 方法.

要让 DirectDraw 为一个主页面管理裁剪清单,你应该通过调用 IDirectDrawClipper::SetHWnd 方法,指明目标窗口的句柄,把裁剪器附属给一个窗口(即使是全屏窗口).这可以把裁剪区域设置为与窗体的客户区相同并让窗体改变大小,被覆盖或去除覆盖时自动更新裁剪清单.

如果你使用窗口句柄设置一个裁剪器,那么你不可以另外设置矩形.

仅仅当覆盖硬件支持裁剪操作同时目标关键色(destination color keying)不激活时,支持覆盖页面的裁剪操作.


Sharing DirectDrawClipper Objects

共享裁剪器对象(Sharing DirectDrawClipper Objects)

DirectDrawClipper 对象可以被多个页面所共享.例如,同一个 DirectDrawClipper 对象可以被设置到一个换页链的前台缓存(front buffer)和后台缓存(back buffer)上.当应用程序使用 IDirectDrawSurface4::SetClipper, 将一个 DirectDrawClipper 对象依属到一个页面,则页面将递增该 DirectDrawClipper 对象的引用记录(reference count).当页面的引用记录达到 0 时,页面将递减 DirectDrawClipper 对象的引用记录.除此之外,如果调用 IDirectDrawSurface4::SetClipper, 并使其裁剪接口指针为 NULL, 则 DirectDrawClipper 对象将从页面上分离,其引用记录也将递减 1.

注意 如果在同一页面多次调用 IDirectDrawSurface3::SetClipper 以依属同一个 DirectDrawClipper 对象,则它的引用记录只会递增一次.以后的调用不会影响到该对象的引用记录.


Independent DirectDrawClipper Objects

独立的裁剪器对象(Independent DirectDrawClipper Objects)

你可以创建不直接属于任何特定 DirectDraw 对象的 DirectDrawClipper 对象.这些 DirectDrawClipper 对象可以被多个 DirectDraw 对象所共享.驱动无关(Driver-independent)的 DirectDrawClipper 对象是用 DirectDraw 的新函数 DirectDrawCreateClipper 创建的.应用程序可以在任何 DirectDraw 对象创建之前调用此函数.

因为 DirectDraw 对象不拥有这些 DirectDrawClipper 对象,所以它们不会在应用程序的 DirectDraw 对象被释放时自动被释放.如果应用程序没有明确的释放这些 DirectDrawClipper 对象, DirectDraw 引擎将在应用程序结束时释放它们.

你仍然可以使用 IDirectDraw4::CreateClipper 函数创建 DirectDrawClipper 对象.这些 DirectDrawClipper 对象会在创建它们的 DirectDraw 对象被释放时,被自动释放.


Creating DirectDrawClipper Objects with CoCreateInstance

用 CoCreateInstance 创建裁剪器对象(Creating DirectDrawClipper Objects with CoCreateInstance)

DirectDrawClipper 对象拥有 COM 所支持的全部类功能.除了使用标准的 DirectDrawCreateClipper 和 IDirectDraw4::CreateClipper 创建一个 DirectDrawClipper 对象外,你同样可以使用 CoGetClassObject 来获得一个类对象,然后再调用 CoCreateInstance, 或者直接调用 CoCreateInstance 来创建它.下面的例子展示了如何使用 CoCreateInstance 和 IDirectDrawClipper::Initialize 来创建一个 DirectDrawClipper 对象.

ddrval = CoCreateInstance(&CLSID_DirectDrawClipper,
    NULL, CLSCTX_ALL, &IID_IDirectDrawClipper, &lpClipper);
if (!FAILED(ddrval))
    ddrval = IDirectDrawClipper_Initialize(lpClipper,
        lpDD, 0UL);

在 CoCreateInstance 调用中,第一个参数 CLSID_DirectDrawClipper 是 DirectDrawClipper 对象类的类标志符, IID_IDirectDrawClipper 参数指名了当前所支持的接口, lpClipper 参数指向返回的 DirectDrawClipper 对象.

在使用这种类机制创建 DirectDrawClipper 后,应用程序必须调用 IDirectDrawClipper::Initialize 来初始化该对象,否则该对象无法使用. dwFlags 参数的值是 0UL, 在这种情况下该值为 0, 因为现在还没有可以支持的标志符.在这个例子中, lpDD 是拥有该 DirectDrawClipper 对象的 DirectDraw 对象.然而,你也可以提供 NULL 值,这将创建一个独立的 DirectDrawClipper 对象(这相当于使用 DirectDrawCreateClipper 函数来创建一个 DirectDrawClipper 对象).

在关闭应用程序之前,用 CoUninitialize 函数来关闭 COM.


Using a Clipper with the System Cursor

对系统鼠标使用裁剪器(Using a Clipper with the System Cursor)

DirectDraw 应用程序通常需要为用户提供一个鼠标指针.对于全屏独占模式的应用程序来说,如果使用了换页操作,那么要实现鼠标指针的唯一选择是使用子图,通过接受由 DirectInput 设备或由 Windows 鼠标消息传来的数据控制子图的移动.然而,任何应用程序,只要没有使用换页操作,仍然是可以使用 Windows 系统的缺省鼠标指针的.

当你使用系统的鼠标指针时,在某些情况下,当你在 Blit 到主页面的某些区域时,你将沦为图形杂点的牺牲品.这些图形杂点象鼠标指针那样出现在屏幕上,就好象是系统留下的.

通过阻止鼠标指针图象在 Blit 操作过程中"挡道", 一个 DirectDrawClipper 对象可以防止这样的杂点出现.这也是一个相对而言较简单的解决办法.步骤是这样的:首先,调用 IDirectDraw4::CreateClipper 创建一个 DirectDrawClipper 对象;然后,通过调用 IDirectDrawClipper::SetHWnd 函数将你的应用程序的窗口句柄连接到该裁剪器对象上.一旦一个裁剪器对象被连接到一个窗口后,任何后续的对主页面进行的 Blit 操作(通过调用 IDirectDrawSurface4::Blt 函数)将不会出现任何鼠标杂点.

注意 IDirectDrawSurface4::BltFast 函数,以及它的 IDirectDrawSurface, IDirectDrawSurface2 和 IdirectDrawSurface3 接口的版本,将不能对隶属于页面的裁剪器进行操作.


Using a Clipper with Multiple Windows

对多窗口使用裁剪器(Using a Clipper with Multiple Windows)

你可以使用一个单独的 DirectDrawClipper 对象,对由单独的应用程序创建的多个窗口进行 Blit 操作.

这个方法是这样的.首先,创建一个单独的 DirectDraw 对象以及一个主页面.然后,创建一个 DirectDrawClipper 对象,并且将它连接到你的主页面上(通过调用 IDirectDrawSurface4::SetClipper 函数).要使 Blit 操作仅限于窗口的客户区,在 Blit 到主页面之前,将该窗口的句柄设置给该裁剪器(通过调用 IDirectDrawClipper::SetHWnd 函数).只要你需要 Blit 到另一个窗口的客户区,再次调用 IDirectDrawClipper::SetHWnd 函数,将另一个窗口的句柄设置给裁剪器.

创建多个 DirectDraw 对象,并且让它们 Blit 到相互的主页面是不推荐的做法.上面所介绍的技术提供了一个有效和可靠的 Blit 到多客户区的方法,针对的是单独的 DirectDraw 对象.


Multiple Monitor Systems

多显示器系统(Multiple Monitor Systems)

Windows 98 和 Windows 2000 可以支持在一个单独的系统中存在多个显示设备和显示器.多显示器架构(通常简称为"MultiMon")使操作系统使用两个或多个显示设备和显示器来建立一个逻辑桌面成为可能.举例来说,在一个有两台显示器的系统中,用户可以在其中的任何一个显示器上显示他的应用程序,或者将窗口从一个窗口中拖到另一个窗口中. DirectDraw 支持这项技术,允许应用程序在多显示系统中直接访问多个显示设备硬件.

注意 如果一个非全屏的 DirectDraw 应用程序创建于缺省的设备上,同时不直接渲染到主页面上,它将可以自动地在多显示器系统中工作,用户也可以把这个窗口从一个显示器拖到另一个显示器上.然而,只有这个窗口使用主显示设备, DirectDraw 才能发挥硬件的加速特性.因此,推荐 DirectDraw 应用程序为多显示器系统专门设计为每个显示器独立地管理 DirectDraw 对象和页面.要得到更多的信息,请参阅多显示器系统中的显示设备与加速特性.

这部分包含了关于在支持多显示器的系统上使用 DirectDraw 的信息.讨论了以下主题:

  • 在多显示器系统中列举显示设备
  • 多显示器系统上的 DirectDraw 对象
  • 焦点窗口和设备窗口
  • 多显示器系统中的显示设备与加速特性
  • 利用多显示器调试全屏幕 DirectDraw 程序

Multimon.h 头文件使在 Windows 98 多显示器系统下编译的源代码能够在使用不支持多显示器系统的操作系统的机器中顺利的编译和执行.

以下的例程演示了在 DirectDraw 中使用多显示器::

  • Stretch2 Sample
  • Stretch3 Sample
  • Multimonitor Space Donuts Sample


Enumerating Devices on MultiMon Systems

在多显示器系统中列举显示设备(Enumerating Devices on MultiMon Systems)

使用 DirectDrawEnumerateEx 函数可以列举出在多显示器系统中的各显示设备,指定一个标志来决定哪种类型的 DirectDraw 设备可以被列举出来.该函数每列举出一个设备,就调用一次应用程序定义的 DDEnumCallbackEx 型回调函数.

The DirectDrawEnumerateEx function is supported on Windows 98 and Windows 2000 operating systems. It is available in Ddraw.lib for applications compiled under DirectX 6.0 and later versions. Applications that statically link to the function will always run under DirectX 6.0 and later, and will always run under any version of DirectX on Windows 98 and Windows 2000. Such applications will fail if run on previous versions of DirectX under Windows 95.

DirectDrawEnumerateEx 函数被Windows 98 和 Windows 2000 所支持.可以在 DirectX6.0 或更晚的版本下编译通过.静态链结的应用程序可以在 windows 98 和 Windows 2000 下在任何版本的 DirectX 下执行,但不能在 Windows 95 下的早期 DirectX 下运行.

If your application needs to run on versions of DirectX older than DirectX 5.0, it should use GetProcAddress to see if DirectDrawEnumerateEx is available. The following example shows one way you can do this:

如果你的应用程序需要在比 DirectX 5.0 老的 DirectX 下运行,你应该先使用 GetProcAddress 来看 DirectDrawEnumerateEx 行不行.请看下面的例子:

    HINSTANCE h = LoadLibrary("ddraw.dll");

    // If ddraw.dll doesn't exist in the search path,
    // then DirectX probably isn't installed, so fail.
    if (!h)
        return FALSE;

    // Note that you must know which version of the
    // function to retrieve (see the following text).
    // For this example, we use the ANSI version.
    LPDIRECTDRAWENUMERATEEX lpDDEnumEx;
    lpDDEnumEx = (LPDIRECTDRAWENUMERATEEX) GetProcAddress(h,"DirectDrawEnumerateExA");

    // If the function is there, call it to enumerate all display
    // devices attached to the desktop, and any non-display DirectDraw
    // devices.
    if (lpDDEnumEx)
        lpDDEnumEx(Callback, NULL,
            DDENUM_ATTACHEDSECONDARYDEVICES |
            DDENUM_NONDISPLAYDEVICES
            );
    else
    {
        /*
         * We must be running on an old version of DirectDraw.
         * Therefore MultiMon isn't supported. Fall back on
         * DirectDrawEnumerate to enumerate standard devices on a
         * single-monitor system.
         */
        DirectDrawEnumerate(OldCallback,NULL);

        /* Note that it could be handy to let the OldCallback function
         * be a wrapper for a DDEnumCallbackEx.
         *
         * Such a function would look like:
         *    BOOL FAR PASCAL OldCallback(GUID FAR *lpGUID,
         *                                LPSTR pDesc,
         *                                LPSTR pName,
         *                                LPVOID pContext)
         *    {
         *         return Callback(lpGUID,pDesc,pName,pContext,NULL);
         *    }
         */
    }

    // If the library was loaded by calling LoadLibrary(),
    // then you must use FreeLibrary() to let go of it.
    FreeLibrary(h);

上面的例程代码可以在运行期或装载期为连接到Ddraw.dll的应用程序所用.

应该注意的是,你必须获得 DirectDrawEnumerateEx 函数的地址 ANSI 或 Unicode 版本中的哪一个,依赖于你的应用程序的字符串类型.当声明相应的回调函数时,为字符串参数使用 LPTSTR 数据类型.如果你声明了 _UNICODE 符号, LPTSTR 数据类型在编译时使用 Unicode 字符串,否则使用 ANSI 字符串.通过使用 LPTSTR 数据类型,该函数能够正常工作,而不论你的应用程序使用的是什么样的字符串.


DirectDraw Objects on Multiple Monitors

多显示器系统上的 DirectDraw 对象(DirectDraw Objects on Multiple Monitors)

Windowed DirectDraw applications written for the null or default display driver will work on MultiMon systems, but in applications optimized for MultiMon you will want to create a separate DirectDraw object for each device, using the GUID returned in the enumeration callback. (See Enumerating Devices on MultiMon Systems.)

Avoid setting the cooperative level multiple times on a MultiMon system. If you need to switch from full-screen to normal mode, it is best to create a new DirectDraw object.

It is good practice to release all DirectDraw objects at the same time. If you release only the secondary device or devices, the primary device goes back to its original desktop mode, but only the taskbar is redrawn and the DirectDraw primary surface is still present. You cannot draw to this surface without first releasing the DirectDraw object and then re-creating it.


Focus and Device Windows

焦点窗口与设备窗口(Focus and Device Windows)

Each DirectDraw application that uses one or more monitors in full-screen exclusive mode must have a single focus window, which is the window that receives keyboard input.

Each device that is to hold a full-screen DirectDraw surface must be represented by a DirectDraw object and a device window. The device window is the one that is sized to fit the window and is put on top of all other windows.

For single-monitor applications, there is no distinction between the device and focus window. They are one and the same.For multiple-monitor applications, however, you need to set a device window for each monitor, and you have to let each DirectDraw object know about the application's focus window. The focus window can also serve as the device window for one of the monitors. Other device windows should be children of the focus window so that the application does not minimize when the user clicks on one of them.

See also:

  • Setting the Focus Window
  • Setting Device Windows


Setting the Focus Window

设置焦点窗口(Setting the Focus Window)

To set the focus window, you call the IDirectDraw4::SetCooperativeLevel method for each of the DirectDraw objects. You pass in a window handle (normally the application window handle) and set the DDSCL_SETFOCUSWINDOW flag, as in the following example:

/* It is presumed that lpDD is a valid IDirectDraw interface pointer,
   and that hWnd is a valid window handle. */

HRESULT ddrval = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_SETFOCUSWINDOW );

The focus window must be the same for all devices.


Setting Device Windows

设置设备窗口(Setting Device Windows)

There are two ways to set a device window:

  • Create a window yourself and pass its handle to the IDirectDraw4::SetCooperativeLevel method of the DirectDraw object representing the monitor, setting the DDSCL_SETDEVICEWINDOW, DDSCL_FULLSCREEN, and DDSCL_EXCLUSIVE flags. This creates a full-screen window and sets it as the device window for the monitor. Your application will receive mouse messages for the window, and you are responsible for destroying the window at the appropriate time. The window you pass to SetCooperativeLevel should be either the focus window (possible only if it is on the same device) or a child of the focus window.
  • Let DirectDraw create the window. You pass the focus window handle to SetCooperativeLevel and set the DDSCL_CREATEDEVICEWINDOW, DDSCL_FULLSCREEN, and DDSCL_EXCLUSIVE flags. DirectDraw creates a default device window that is a child of the focus window. It manages this window and will destroy it at the appropriate time. Your application will not receive any mouse messages for the window.

The following example sets an existing device window for the DirectDraw object represented by lpDD.

/* It is presumed that lpDD is a valid IDirectDraw interface pointer,
   and that hWnd is the handle to an appropriate device window. */

HRESULT hr = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_SETDEVICEWINDOW | DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN );

The following example sets a default device window created by DirectDraw. In this case, hWnd is the handle to the existing focus window.

HRESULT hr = lpDD->SetCooperativeLevel( hWnd,
        DDSCL_CREATEDEVICEWINDOW | DDSCL_EXCLUSIVE | DDSCL_FULLSCREEN );

Although a focus window can be a device window, you cannot set a window as both the focus window and a device window with a single call to SetCooperativeLevel. You must first set it as the focus window and then set it as a device window. However, it is possible to set a focus window and a default device window on the same device with a single call to SetCooperativeLevel. The following example shows how this can be done:

HRESULT hr = lpDD->SetCooperativeLevel(
        hwndFocus,
        DDSCL_SETFOCUSWINDOW | DDSCL_FULLSCREEN |
        DDSCL_EXCLUSIVE | DDSCL_CREATEDEVICEWINDOW);

In this example, an existing window (probably the application window) is set as the focus window, and DirectDraw creates a default device window.


Devices and Acceleration in MultiMon Systems

多显示器系统中的显示设备与加速特性(Devices and Acceleration in MultiMon Systems)

Full-screen exclusive mode DirectDraw objects will take advantage of hardware acceleration regardless of whether they are running on the primary device or on a secondary device. However, they cannot use built-in support for spanning graphics operations across display devices. It is the application's responsibility to perform operations on the appropriate device.

When the normal cooperative level is set, DirectDraw uses hardware acceleration only when the window is wholly within the display area of the primary device. When a window straddles two or more monitors, all blits are done in emulation and performance can be significantly slower. This is necessarily the case, because hardware buffers cannot blit to a display surface controlled by another piece of hardware.

As long as you create the DirectDraw object for the null device梩hat is, pass NULL to DirectDrawCreate as the lpGUID parameter桪irectDraw will blit to the entire window regardless of where it is located. However, if the device is created by its actual GUID, this is not the case, and blit operations that cross an edge of the primary surface will be clipped (if you are using a clipper) or will fail, returning DDERR_INVALIDRECT.

Note When you are blitting to a window in a MultiMon application, negative coordinates are valid when the logical location of the secondary monitor is to the left of the primary monitor.

To get the best performance in a windowed MultiMon application, you need to create a DirectDraw object for each device, maintain off-screen surfaces in parallel on each device, keep track of which part of the window resides on each device, and perform separate blits to each device.


Debugging Full-Screen DirectDraw Applications with MultiMon

利用多显示器调试全屏幕 DirectDraw 程序(Debugging Full-Screen DirectDraw Applications with MultiMon)

It is possible to use a multimonitor system rather than remote debugging in order to step through code while debugging a full-screen DirectDraw application.

You should use the primary monitor for your development environment and the secondary monitor for the DirectDraw output. Also, you need to change a registry setting through the DirectX property sheet in Control Panel. On the DirectDraw page, click Advanced Settings and select the Enable Multi-Monitor Debugging checkbox. This setting will prevent DirectDraw from minimizing your application when it loses focus.

Under Windows 98, you cannot step through code when a surface is locked. For more information, see Accessing Surface Memory Directly.


Advanced DirectDraw Topics

高级 DirectDraw 主题(Advanced DirectDraw Topics)

这部分是对 DirectDraw 总览的补充,提供了关于高级 DirectDraw 问题的信息.讨论了以下主题:

  • 对 Mode 13 的支持
  • 从 DMA 中获益
  • 在窗口模式下使用调色板
  • 视频端口
  • 获得换页和 Blit 操作的状态
  • 测定显示硬件的能力
  • 在显存中储存位图
  • 三缓冲
  • DirectDraw 应用程序和窗口风格
  • 将真彩色匹配到帧缓冲区的色彩空间
  • 以全屏模式显示窗口


Mode 13 Support

对 Mode 13 的支持(Mode 13 Support)

这部分包含了关于 DirectDraw 支持 Mode 13 图形模式的信息.讨论了以下的主题:

  • 关于 Mode 13 模式
  • 设置 Mode 13 模式
  • Mode 13 模式与页面特性
  • 使用 Mode 13 模式


About Mode 13

关于 Mode 13 模式(About Mode 13)

DirectDraw 支持线性非换页的 320x200 的 8 位调色板显示模式,人们对它使用更为广泛的名称是 Mode 13. 它是 16 进制 BIOS 模式编号. DirectDraw 将这种模式视为一种 Mode X 模式,但是它们之间又有着重要的区别,这是由 Mode 13 模式的物理性质所强加的.


Setting Mode 13

设置 Mode 13 模式(Setting Mode 13)

Mode 13 模式与 Mode X 模式拥有一样的被列举和模式设置的行为特性.如果 DDSCL_ALLOWMODEX 标志被传给 IDirectDraw4::SetCooperativeLevel 函数, DirectDraw 将只会列举出 Mode 13 模式.

你可以象列举其它显示模式那样列举出 Mode 13 模式,但是你必须在调用 IDirectDraw4::EnumDisplayModes 函数之前做一次页面能力的检测.要完成这一步,调用 IDirectDraw4::GetCaps 函数,并且检查 DDSCAPS2 结构中的 DDSCAPS_STANDARDVGAMODE 标志.如果该标志不存在,表示不支持 Mode 13 模式,那么,试图带 DDEDM_STANDARDVGAMODES 标志的列举将会失败,返回一个 DDERR_INVALIDPARAMS 错误.

EnumDisplayModes 函数现在支持一个新的列举标志 DDEDM_STANDARDVGAMODES, 它会让 DirectDraw 除了列举出 320x200x8 的 Mode X 模式外,还可以列举出 Mode 13 模式.同样, IDirectDraw4::SetDisplayMode 函数也有一个新的标志 DDSDM_STANDARDVGAMODE, 为了将显示模式设置成 Mode 13 模式而不是 320x200x8 的 Mode X 模式,你必须传递此标志.

注意:有些显示卡提供了线性加速的 320x200x8 模式.在这种显示卡上, DirectDraw 将不会列举出 Mode 13 模式,而列举出线性模式.在这种情况下,如果你试图通过将 DDSDM_STANDARDVGAMODE 标志传递给 SetDisplayMode 函数而设置显示模式为 Mode 13, 函数会调用成功,但是使用了线性模式.这是低分辨率模式替换 Mode X 模式的一个相似的方式.


Mode 13 and Surface Capabilities

Mode 13 与页面特性(Mode 13 and Surface Capabilities)

当 DirectDraw 调用一个应用程序定义的 EnumModesCallback 回调函数,相应 DDSURFACEDESC 结构或 DDSURFACEDESC2 结构的 ddsCaps 成员包含了反映正被列举模式的标志.在 Mode X 模式中,它会是 DDSCAPS_MODEX, 在 Mode 13 模式中,它会是 DDSCAPS_STANDARDVGAMODE. 这些标志是相互排斥的.如果没有任何一个标志被设置,那么,该模式是线性加速的.这些特征同样可应用于由调用 IDirectDraw4::GetDisplayMode 函数获得的标志。


Using Mode 13

使用 Mode 13 模式(Using Mode 13)

因为 Mode 13 是线性模式, DirectDraw 可以给应用程序提供对帧缓冲区的直接访问.与 Mode X 模式不一样,你可以调用 IDirectDrawSurface4::Lock, IDirectDrawSurface4::Blt, 和 IDirectDrawSurface4::BltFast 函数直接访问主页面.

当使用 Mode 13 模式时, DirectDraw 支持一种模拟的 IDirectDrawSurface4::Flip 函数,这是通过将后台缓存的内容直接复制到主页面来实现的.你可以自己编写这些代码,使用 Blt 或 BltFast 函数复制一个后台缓存中的矩形区域到主页面上.

有一个有关 Loack 和 Mode 13 的误解.尽管 DirectDraw 允许对 Mode 13 VGA 帧缓冲区的直接线性访问,但绝不要认为该缓冲区的地址总是 0xA0000, 因为 DirectDraw 可以返回一个指向的地址并不是 0xA0000 的帧缓冲区的别名虚拟内存指针.同样,绝不要认为 Mode 13 页面的宽矩(Pitch)是 320, 因为支持 320x200x8 加速的显示卡很可能会使用不同的宽矩值.


Taking Advantage of DMA Support

从 DMA 支持中获益(Taking Advantage of DMA Support)

本节包含了关于如何从设备对 DMA(直接内存访问)的支持中获益,以提高完成特定任务的运行效果.讨论了以下主题:

  • 关于 DMA 设备支持
  • 对 DMA 支持的检测
  • 典型的 DMA 方案
  • 使用 DMA


About DMA Device Support

关于 DMA 设备支持(About DMA Device Support)

某些显示卡可以完成在系统RAM页面中的Blit或其它操作，这些操作一般被称为“直接内存访问（DMA：Direct Memory Access）”。你可以利用DMA支持来加速某些集合操作。举例来说，你可以利用系统设备对DMA的支持，完成一次从系统RAM到显示RAM的Blit操作，而与此同时，处理器正在准备下一帧。为了使用这个功能，你必须承担一些责任，以下将对此进一步详细探讨。


Testing for DMA Support

对 DMA 支持的检测(Testing for DMA Support)

在使用 DMA 操作之前，你必须检测系统设备是否支持 DMA 操作，如果支持的话，支持的程度如何。首先调用 IDirectDraw4::GetCaps 函数查询设备能力，然后检查相应 DDCAPS 结构的 dwCaps 成员中是否存在 DDCAPS_CANBLTSYSMEM 标志。如果该标志存在的话，表示显示设备支持DMA。

如果你已知道显示设备支持 DMA，你还需要知道显示设备支持的程度如何。这可以通过检查另一些结构成员来完成，它们提供了有关从系统内存到视频内存，视频内存到系统内存，以及系统内存到系统内存的 Blit 操作的 DMA 特性。这些特性由 12 个 DDCAPS 结构的成员提供，它们依照 Blit 操作的 DMA 方式来命名。下面的表展示了这些成员。
System-to-video | Video-to-system | System-to-system
dwSVBCaps | dwVSBCaps | dwSSBCaps
dwSVBCKeyCaps | dwVSBCKeyCaps | dwSSBCKeyCaps
dwSVBFXCaps | dwVSBFXCaps | dwSSBFXCaps
dwSVBRops | dwVSBRops | dwSSBRops

举例来说，系统内存到视频内存的 Blit 特性标志由 dwSVBCaps, dwSVBCKeyCaps, dwSVBFXCaps 和 dwSVBRops 成员提供。类似的，视频内存到系统内存的 Blit 特性是由 “dwVSB” 打头的成员提供；系统内存到系统内存的Blit特性是由 “dwSSB” 打头的成员提供。检查存在于这些成员中的标志，可以确定硬件对Blit操作的DMA方式的支持程度。

就这些成员的Blit类型来说，这些成员中的标志与在 dwCaps, dwCKeyCaps, 和 dwFXCaps 成员中 Blit 相关的标志是一致的。例如， dwSVBCaps 成员中包含了常规的 Blit 操作特性，你可以在 dwCaps 成员中找到同样的标志。同样， dwSVBRops, dwVSBRops, 和 dwSSBRops 成员中也提供了有关特定类型的 Blit 的光栅操作（Raster operation）的光栅操作码。

从这些成员可以检测到的特性中，有一个关键的特性，用来表明系统对异步 DMA Blit 操作的支持。如果显示设备支持页面间的异步 DMA Blit 操作，那么 DDCAPS_BLTQUEUE 标志会被设置在 dwSVBCaps, dwVSBCaps, 和 dwSSBCaps 成员中（一般来说，你将看到的是从系统内存到视频内存页面的最好的支持）。如果该标志不存在，表明系统并不报告支持异步 DMA Blit 操作。


Typical Scenarios for DMA

典型的 DMA 方案(Typical Scenarios for DMA)

从系统内存到视频内存的 SRCCOPY（光栅操作码之一，表示“复制”）传送是被硬件支持的最基本的 Blit 操作类型。因此，该操作最典型的用法是将系统内存页面中的数据传送到视频内存的页面中，以备后用。系统内存到视频内存的 DMA 传送与 CPU 控制的传送（比如：HEL 的 Blit）一样快速，但是又具有极大的利用价值，因为它们可以与主 CPU 进行并行的操作。


Using DMA

使用 DMA(Using DMA)

硬件的 Blit 操作使用的是物理内存地址，而不是虚拟地址，后者是应用程序的本地地址。某些设备驱动要求你提供页面的物理内存地址。这种机制是由 IDirectDrawSurface4::PageLock 函数实现的。如果设备驱动不需要进行页锁定（Page locking），当你调用 IDirectDraw4::GetCaps 函数以测定硬件特性时，返回值中将会被设置 DDCAPS2_NOPAGELOCKREQUIRED 标志。

锁定一个页面可以阻止系统将该页面的物理内存给其它的进程使用，并且保证该页面的物理内存地址始终保持不变，直到调用了相应的 IDirectDrawSurface4::PageUnlock 函数。如果设备驱动需要进行页锁定，那么， DirectDraw 将只能允许系统内存中页面的 DMA 操作，该页面是被应用程序锁定的。如果在这种情况下，你不调用 IDirectDrawSurface4::PageLock 函数， DirectDraw 将会使用软件仿真的方式来完成 Blit 操作。应该注意的是：锁定大块的系统内存将会导致 Windows 系统运行阻塞。因此强烈建议，如果你的应用程序不是运行于全屏独占模式，那么，不要调用 IDirectDrawSurface4::PageLock 函数以锁定大块的系统内存，而且，当应用程序最小化时，必须及时将这些页面解锁，当然，当应用程序恢复最大化时，你可以再次锁定页面。

管理页锁定的任务完全落在应用程序开发者手中， DirectDraw 绝不会来插手来锁定或解锁一个页面。而且，决定究竟将多少页面内存锁定才不会对系统运行产生严重的负面影响，也是对开发者的一项考验。


Using DirectDraw Palettes in Windowed Mode

在窗口模式下使用 DirectDraw 调色板(Using DirectDraw Palettes in Windowed Mode)

当应用程序为独占（全屏）模式时， IDirectDrawPalette 接口的函数拥有直接写硬件的能力。然而，当应用程序处于非独占（窗口）模式时， IDirectDrawPalette 接口的调用的是 GDI 的调色板函数句柄来与其它应用程序协同工作。

对以下主题的讨论，我们假使桌面是 8 位调色板模式，并且你已经创建了一个主页面(primary surface)和一个标准的窗口。

  • 窗口模式的调色板入口类型
  • 在窗口模式下创建调色板
  • 在窗口模式下设置调色板入口


Types of Palette Entries in Windowed Mode

窗口模式的调色板入口类型(Types of Palette Entries in Windowed Mode)

与全屏模式的应用程序不同，窗口模式的应用程序必须与其它的应用程序共享桌面调色板。这就给开发者带来了一些困难，如怎样修改调色板入口，以及如何才能安全的修改等。用于 DirectDrawPalette 对象和 GDI 的 PALETTEENTRY 结构中，包含了一个 peFlags 成员，它携带了系统如何解释 PALETTEENTRY 结构的描述信息。

peFlags 成员描述了调色板入口的三种类型,在以下主题中讨论：

  • Windows静态入口
  • 动态入口
  • 非动态入口

Windows静态入口

在窗口模式中， Windows 保留了调色板的前 10 个（0到9）和后 10 个（246到255）共 20 个入口，将它们作为系统保留色来显示窗口，如：菜单条、菜单文字、窗口边框、按钮底色等。为了使你的应用程序与系统保持一致的外观，以及避免破坏其它的应用程序，你有必要保护主页面调色板的这些入口。通常，开发者调用 Win32 的 GetSystemPaletteEntries 函数获得系统调色板的入口，然后，在将用户定制的调色板指派给主页面之前，将系统调色板中这 20 个保留入口的值明确的匹配给该定制调色板。在定制调色板中复制系统调色板的入口项在应用程序初始化时可以正常工作，但如果用户更改了桌面的配色方案，它会变得无法使用。

要避免你的调色板在用户更改了配色方案之后变得面目全非，你可以通过提供一个指向系统调色板的引用，而不是直接指定一个颜色值来保护这些被保留的入口。用这种方法，不管系统对某一个保留入口使用什么样的颜色，你的定制调色板将总会符合系统颜色，而且不需要做任何更新工作。在 peFlags 成员中使用 PC_EXPLICIT 标志，使你将定制调色板的入口直接指向一个系统调色板成为可能。当你使用这个标志，系统将不会再认为其它的成员中包含颜色信息，你应该设置 peRed 成员的值为系统调色板的一个索引，并且将其它成员的值设为 0。

举例来说，如果你想要确保你定制调色板的保留入口与系统调色板相一致，你应该使用如下的代码：

// Set the first and last 10 entries to match the system palette.
PALETTEENTRY pe[256];
ZeroMemory(pe, sizeof(pe));
for(int i=0;i<10;i++){
    pe[i].peFlags  = pe[i+246].peFlags = PC_EXPLICIT;
    pe[i].peRed = i;
    pe[i+246].peRed = i+246;
}

你可以强迫 Windows 仅保留使用调色板入口的第一项和最后一项（0和255），方法是调用 Win32 的 SetSystemPaletteUse 函数。在这种情况下，你应该设置 0 号与 255 号 PALETTEENTRY 结构入口为 PC_EXPLICIT。

动态入口

对相应的 PALETTEENTRY 结构设置 PC_RESERVED 标志，表示调色板入口为动态的， Windows 将不会允许任何其它的应用程序将它们的逻辑调色板映射到这个物理入口中。因此，只有你的应用程序能够修改这个入口的颜色值，实现调色板动画，而其它的应用程序却无法修改它。

非动态入口

对相应的 PALETTEENTRY 结构设置 PC_NOCOLLAPSE 标志，表示该调色板入口为普通、非动态的调色板入口。 PC_NOCOLLAPSE 标志通知 Windows 不要用另一些已经分配了的物理调色板入口来替换该入口。


Creating a Palette in Windowed Mode

在窗口模式下创建调色板(Creating a Palette in Windowed Mode)

下面的例程演示了如何在非独占模式（既窗口模式）下创建一个 DirectDraw 调色板。为了让你的调色板能够正常工作，一个关键的任务是你要在 PALETTEENTRY 结构中设置 256 个入口中的每一个入口，然后将其提交给 IDirectDraw4::CreatePalette 函数。

LPDIRECTDRAW4        lpDD; // Assumed to be initialized previously
PALETTEENTRY         pPaletteEntry[256];
int                  index;
HRESULT              ddrval;
LPDIRECTDRAWPALETTE2 lpDDPal;

// First set up the Windows static entries.
for (index = 0; index < 10 ; index++)
{
    // The first 10 static entries:
    pPaletteEntry[index].peFlags = PC_EXPLICIT;
    pPaletteEntry[index].peRed = index;
    pPaletteEntry[index].peGreen = 0;
    pPaletteEntry[index].peBlue = 0;

    // The last 10 static entries:
    pPaletteEntry[index+246].peFlags = PC_EXPLICIT;
    pPaletteEntry[index+246].peRed = index+246;
    pPaletteEntry[index+246].peGreen = 0;
    pPaletteEntry[index+246].peBlue = 0;
}

// Now set up private entries. In this example, the first 16
// available entries are animated.
for (index = 10; index < 26; index ++)
{
    pPaletteEntry[index].peFlags = PC_NOCOLLAPSE|PC_RESERVED;
    pPaletteEntry[index].peRed = 255;
    pPaletteEntry[index].peGreen = 64;
    pPaletteEntry[index].peBlue = 32;
}

// Now set up the rest, the nonanimated entries.
for (; index < 246; index ++) // Index is set up by previous for loop
{
    pPaletteEntry[index].peFlags = PC_NOCOLLAPSE;
    pPaletteEntry[index].peRed = 25;
    pPaletteEntry[index].peGreen = 6;
    pPaletteEntry[index].peBlue = 63;
}

// All 256 entries are filled. Create the palette.
ddrval = lpDD->CreatePalette(DDPCAPS_8BIT, pPaletteEntry,
    &lpDDPal,NULL);


Setting Palette Entries in Windowed Mode

在窗口模式下设置调色板入口(Setting Palette Entries in Windowed Mode)

在 IDirectDraw4::CreatePalette 函数中应用于 PALETTEENTRY 结构的规则，同样适用于 IDirectDrawPalette::SetEntries 函数。典型的做法是，保存住你一开始创建的 PALETTEENTRY 结构数组，以后你就不必每次都重建它。在必要的时候，你可以修改这个组中的个别项，然后调用 IDirectDrawPalette::SetEntries 函数以更新调色板。

在大多数情况下，如果你的应用程序运行于窗口模式，你就不应该去触动任何一个 Windows 静态入口，否则，后果是你所无法预知的。

对于调色板动画，通常你需要修改的只是 PALETTEENTRY 结构数组的一个子集，然后将这些子集入口提交给 IDirectDrawPalette::SetEntries 函数，这些入口必须具有 PC_NOCOLLAPSE 和 PC_RESERVED 标志。试图对其它的入口进行调色板动画，后果同样是不可预知的。

下面的例程演示了如何在非独占模式（窗口）下进行调色板动画。

LPDIRECTDRAW        lpDD;        // Already initialized
PALETTEENTRY pPaletteEntry[256]; // Already initialized
LPDIRECTDRAWPALETTE lpDDPal;     // Already initialized
int                 index;
HRESULT             ddrval;
PALETTEENTRY        temp;

// Animate some entries. Cycle the first 16 available entries.
// They were already animated.
temp = pPaletteEntry[10];
for (index = 10; index < 25; index ++)
{
    pPaletteEntry[index] = pPaletteEntry[index+1];
}
pPaletteEntry[25] = temp;

// Set the values. Do not pass a pointer to the entire palette entry
// structure, but only to the changed entries.
ddrval = lpDDPal->SetEntries(
    0,                      // Flags must be zero
    10,                     // First entry
    16,                     // Number of entries
    & (pPaletteEntry[10])); // Where to get the data


Video-Ports

DirectDraw video-port extensions are a low-level programming interface, not intended for mainstream multimedia programmers. The target customer is the video-streaming software industry, which creates products like DirectShow�. Developers who want to include video playback in their software can make use of video-port extensions. However, for most software, a high-level programming interface like the one provided by DirectShow is recommended for greater ease of use.

This section contains information about DirectDrawVideoPort objects. The following topics are discussed:

  • What Are Video Ports?
  • Video-Port Technology Overview
  • About DirectDraw Video-Port Extensions
  • Video Frames and Fields
  • HREF, VREF, and Connections
  • Vertical Blanking Interval Data
  • Auto-Flipping
  • Solutions to Common Video Artifacts
  • Solving Problems Caused by Half-Lines
  • Exploiting Hardware Features


What Are Video Ports?

A DirectDrawVideoPort object represents the video-port hardware found on some display adapters. Generally, a video-port object controls how the video-port hardware applies a video signal it receives from a video decoder directly to the frame buffer.

More than one channel of video can be controlled by creating as many DirectDrawVideoPort objects as is required. Because each channel can be separately enumerated and configured, the video hardware for each channel does not need to be identical.

For more information, see Video-Port Technology Overview.


Video-Port Technology Overview

A video port is hardware on a display device that enables direct access to a surface within the frame buffer, bypassing the CPU and PCI bus. Direct frame buffer access makes it possible to efficiently play live or recorded video without creating noticeable load on the CPU. Once in a surface, an image can be displayed on the screen as an overlay, used as a Direct3D texture, or accessed by the CPU for capture or other processing. The following paragraphs provide general information about the components that make up the technology and how they work.

Data Flow

In a machine equipped with a video port, data in a video stream can flow directly from a video source through a video decoder and the video port to the frame buffer. These components often exist together on a display adapter, but can be on separate hardware components that are physically connected to one another. An example of this data flow is provided in the following illustration.

Video source

In the scope of video-port technology, a video source is strictly a hardware video input device, such as a Zoom Video port, MPEG codec, or other hardware source. These sources broadcast signals in a variety of formats, including NTSC, PAL, and SECAM through a physical connection to a video decoder.

Video Decoder

A video decoder is also a hardware component. The video decoder's job is to decipher the information provided by the video source and send it to the video port in an agreed upon connection format. The decoder possesses a physical connection to the video port, and exposes its services through a stream class minidriver. The decoder is responsible for sending video data and clock and sync information to the video port.

Video port

Like the other components in the data flow path, the video port is a piece of hardware. The video port exists on the display adapter's VGA chip and has direct access to the frame buffer. It receives information sent from the decoder, processes it, and places it in the frame buffer to be displayed. During processing, the video port can manipulate image data to provide scaling, shrinking, color control, or cropping services.

Frame Buffer

The frame buffer accepts video data as provided by the video port. Once received, applications can programmatically manipulate the image data, blit it to other locations, or show it on the display using an overlay (the most common use).


About DirectDraw Video-Port Extensions

DirectDraw has been extended to include the DirectDrawVideoPort object, which takes advantage of video-port technology and provides its services through the IDDVideoPortContainer and IDirectDrawVideoPort interfaces.

DirectDrawVideoPort objects do not control the video decoder, because it provides services of its own, nor does DirectDraw control the video source; it is beyond the scope of the video port. Rather, a DirectDrawVideoPort object represents the video port itself. It monitors the incoming signal and passes image data to the frame buffer, using parameters set though its interface methods to modify the image, perform flipping, or carry out other services.

The IDDVideoPortContainer interface, which you can retrieve by calling the IDirectDraw4::QueryInterface method, provides methods to query the hardware for its capabilities and create video-port objects. You create a video-port object by calling the IDDVideoPortContainer::CreateVideoPort method. Video-port objects expose their functionality through the IDirectDrawVideoPort interface, enabling you to manipulate the video-port hardware itself. Using these interfaces, you can examine the video-port's capabilities, assign an overlay surface to receive image data, start and stop video playback, and set hardware parameters to manipulate image data for cropping, color control, scaling, or shrinking effects.

DirectDraw video-port extensions provide for multiple video ports on the same machine by allowing you to create multiple DirectDrawVideoPort objects. There is no requirement that multiple video ports on a machine be identical梕ach port is separately enumerated and configured separately, regardless of any hardware differences that might exist.

In keeping with the general philosophy of DirectX, this technology gives programmers low-level access to hardware features while insulating them from specific hardware implementation details. It is not a high-level API.


Video Frames and Fields

Video can be interlaced or non-interlaced. When a video signal is interlaced, each video frame is made of two fields of image data. Each field is a collection of every other scan line in an image, starting with the first or second scan line. The first field, referred to as the odd field (or field 1), contains the data for the first scan line and skips every other scan line to the end of the image. Similarly, the even field (or field 2), carries every other scan line starting with the second. The "even-ness" or "odd-ness" of a field is referred to as its field polarity.

When video is not interlaced, each field contains all of a frame's scan lines. Typically, video signals are sent at a rate of 30 frames per second; in the case of interleaved video, this means the rate is 60 fields per second.

The fields that make up a frame do not always reflect the same moment in time. For example, if the frames are separated by 1/30 of a second then the two fields of a frame may be separated by 1/60 of a second. Because a television displays each field individually, no two fields are simultaneously visible, and the difference between fields adds to the illusion of movement.


HREF, VREF, and Connections

When a monitor or other display device is displaying an image, it typically scans down the screen, creating an image from left to right, top to bottom. (Sometimes, the device makes two passes down the screen to create a single image; this type of display is called an interlaced display.) The video stream contains signals that instruct the display device when a new line or new screen is to be drawn.

The terms HREF and VREF, also known as hsync and vsync, are the signals within the video stream that tell a display device what to do and when to do it. The HREF signals that a new line is to be drawn and the VREF signals a new screen.

For instance, imagine you're working with a video signal intended for the world's smallest monitor. The monitor only has 4 scan lines. (This is not at all realistic, of course, but it's simple.) On an oscilloscope, the HREF and VREF signals would look somewhat like the following illustration.

In the preceding illustration, both HREF and VREF signals are "active high," meaning that they are considered active when in a heightened state (when the waves go up). There is no standard for these signals. In some cases, places where the waves go down ("low" states) might signal an active HREF or VREF, or sometimes one will be active high and the other active low. Although the preceding illustration is only an imaginary example, note that there are lots of HREF signals for each VREF. This is because for each new screen, there are several scan lines. Of course, in a real video signal for a real broadcast, you would see hundreds of HREFs for a single VREF.

HREF signals, VREF signals, and video data are carried across physical data lines from the decoder to the video port. In many cases, a number of lines are reserved for video data, and others are dedicated to carrying HREF and VREF signals. However, there is no standard for how these data lines are used.

A connection is a protocol that a video port or decoder uses to define how it uses these data lines. Video ports and video decoders will support a variety of connections. DirectDraw video-port extensions use globally-unique identifiers (GUIDs) to identify each type of connection. You can query for the connections that the video port supports by calling the IDDVideoPortContainer::GetVideoPortConnectInfo method. You create a DirectDrawVideoPort object that supports a given connection by calling the IDDVideoPortContainer::CreateVideoPort method.

Keep in mind that the video decoder is outside the scope of DirectDraw video-port extensions, and exposes its supported connections through an interface of its own. By enumerating the connections that the video-port supports and comparing the results with the connections supported by the decoder, you can negotiate a common connection (or "language") that both components understand.


Vertical Blanking Interval Data

In broadcast video, a small period of time elapses between video frames, during which a display device refreshes its display for the next frame. This period of time is called the Vertical Blanking Interval (VBI). Instead of sitting idle during the VBI, broadcast video encodes data in the first twenty-one scan lines of a video frame and sends these lines during the VBI. This data is often used for closed captioning or time-stamping, but can be used for other purposes.

DirectDraw video-port extensions enable you to divert data contained with the VBI to a surface, bypass scaling of VBI data, and automatically flip between VBI surfaces in a flipping chain. Once data is in a surface, you can directly access the surface's memory as needed.

For more information, see Auto-Flipping.


Auto-Flipping

To avoid tearing images when refreshing the screen between frames, DirectDrawVideoPort objects can automatically flip their target overlay surfaces in response to VREF signals. To use this service, the target surface you set to the video-port object with the IDirectDrawVideoPort::SetTargetSurface method must be the first surface in a flipping chain of overlay surfaces. Then, to begin playing the video sequence, call the IDirectDrawVideoPort::StartVideo method, specifying the DDVP_AUTOFLIP flag in the dwVPFlags member of the associated DDVIDEOPORTINFO structure. The video-port object will flip to the next surface in the flipping chain for each VREF signal it receives. If the video port is interleaving fields, it will flip once for every two VREF signals it receives.

If you are using auto-flipping and want to direct VBI data to separate auto-flipped surfaces, you must have the same number of VBI surfaces as you do standard video surfaces.


Solutions to Common Video Artifacts

Several problems are inherent in displaying broadcast video on display devices other than televisions. This section briefly discusses some common problems, then describes how DirectDraw video-port extensions tries to solve them.

NTSC Interlaced Display and Interleaved Memory

An NTSC signal broadcasts video at an approximate rate of 30 frames, or 60 fields, per second. Like a frame, a field in an NTSC signal is independent of the other field in a frame and can contain different image data. For more information on this behavior, see Video Frames and Fields.

The problems caused by the independence of fields within a frame become apparent when two fields are interleaved for display. In video with a lot of movement, the two fields of a single frame will contain images that don't match each other, resulting in motion artifacts.

One way that developers have tried to work around this behavior is by discarding one of the fields. This solution causes a loss in image quality by roughly one-half, but provides acceptable results for some purposes. Another method frequently used is to display fields individually, stretching each vertically by a factor of two when it is displayed. This provides better image quality, but because fields are offset by one pixel in the y-direction, the result is an animation that "jitters" up and down as it plays.

DirectDraw video-port extensions can employ two, more advanced, techniques for improving image quality, known as "Bob" and "Weave." Both are supported by the DirectDraw overlay surfaces that are used with video-port extensions.

The first algorithm, Bob, is very similar to the method of displaying each field in a frame individually. However, for each field, the overlay's source rectangle is adjusted to accommodate for any jittering effects. Effectively, the source rectangle bounces up and down in time with the fields, negating the jittering on the screen. The following illustration depicts this process.

The Weave algorithm provides the best image quality for material that originates from film by exploiting a common technique used in the video industry for converting motion pictures to television. Unlike Bob, a video-port object does not Weave by itself; you must combine the default overlay behavior of displaying both fields simultaneously with kernel mode video transport (provided with Windows 2000 and Windows 98) to implement the algorithm.

Here is a synopsis of the algorithm, provided for completeness. Motion pictures capture video at a rate of 24 frames per second. When converting a motion picture for television, technicians use a technique called 3:2 pulldown to convert the frame rate to the 30 frames per second required for television broadcasts. This technique involves inserting a redundant field for every four true fields in the video stream to come up with the required number of fields.

When you weave, you are reversing this process. You detect when 3:2 pulldown is being used, removing any redundant fields to restore the original motion-picture frames. The fields that make up the restored frames can then be interleaved in memory without risk of motion artifacts. Occasionally, the pattern of redundant frames will change due to edits within the original film or reel breaks. You must monitor when these changes occur and update the behavior to adjust for the new pattern.

By default, an overlay surface displays both fields simultaneously. This works well if you're implementing the Weave algorithm, but prevents the video port from using the Bob algorithm. You can programmatically change how the overlay treats video data by calling the IDirectDrawSurface4::UpdateOverlay method. The flags you include in the dwFlags parameter determine the overlay's behavior: if you include the DDOVER_BOB flag, the video port will use the Bob algorithm; if you don't, it displays both fields. Note that by simply displaying both fields simultaneously, the resulting video will show motion artifacts.


Solving Problems Caused by Half-Lines

Some video decoders output a half line of meaningless data at the beginning of the even field. If this extra line is written to the frame buffer, the resulting image will appear garbled. In some cases, the video-port hardware is capable of sensing and discarding this data before writing it to the frame buffer.

You can determine if a video port is capable of discarding this data when retrieving connection information with the IDDVideoPortContainer::GetVideoPortConnectInfo method. If the video port cannot discard half-lines, the DDVPCONNECT_HALFLINE flag will be specified in the dwFlags member of the associated DDVIDEOPORTCONNECT structure for each supported connection.

If the video port is unable to discard half-lines, you have two options: you can discard one of the fields, or you can work around the hardware's limitations by making some adjustments in how you create the video-port object and display images with the target overlay surface

Here's how to work around the problem. When creating the video-port object by calling the IDDVideoPortContainer::CreateVideoPort method, include the DDVPCONNECT_INVERTPOLARITY flag in the dwFlags member of the associated DDVIDEOPORTCONNECT structure. This causes the video port to invert the polarity of the fields in the video stream, treating even fields like odd fields and vice versa. Once reversed, the half-line preceding even fields will be written to the frame buffer as the first scan line of each frame. To remove the unwanted data, adjust the source rectangle of the overlay surface used to display the image down one pixel by calling the IDirectDrawVideoPort::StartVideo method with the necessary coordinates. Note that this technique requires that you allocate one extra line in the surface containing the even field.


Exploiting Hardware Features

Video-port hardware often supports special features for adjusting color, shrinking or zooming images, handling VBI data, or skipping fields. The HAL provides information about these features by using flags in the DDVIDEOPORTCAPS structure. You retrieve the capabilities of a machine's video-port hardware by calling the IDDVideoPortContainer::EnumVideoPorts method.

To exploit these features for playback, you use the IDirectDrawVideoPort::StartVideo method, which uses a DDVIDEOPORTINFO structure to request that hardware features be used to modify image data before placing it in the frame buffer or for display. By setting values and flags in this structure, you can specify the source rectangle used with the overlay surface, indicate cropping regions, request hardware scaling, and set pixel formats.

DirectDrawVideoPort objects do not emulate video-port hardware services.


Getting the Flip and Blit Status

获得换页和 Blit 操作的状态(Getting the Flip and Blit Status)

当你调用 IDirectDrawSurface3::Flip 函数,你所期望的结果是将主页面(primary surface)与后台缓存(back buffer)进行交换.然而,这个函数调用并不一定都会成功,而且如果成功也并不是说就会立即进行换页的,举例来说,如果上一次的换页操作还没有完毕或没有成功,那么这次调用的换页函数将返回一个名为 DDERR_WASSTILLDRAWING 的错误.对于这个问题,仅仅依靠该函数本身的一个较为简单的解决办法是:用 While 循环反复调用 IDirectDrawSurface4::Flip 函数,直到返回 DD_OK 为止.还应注意的一点是,即使 IDirectDrawSurface4::Flip 函数调用成功,也不是说马上就能进行换页,换页被显示系统安排在显示器的下一次垂直回扫发生的时候进行,这就是说,换页一定是与显示器的刷新同步进行的.

An application that waits until the DDERR_WASSTILLDRAWING value is not returned is very inefficient. Instead, you could create a function in your application that calls the IDirectDrawSurface4::GetFlipStatus method on the back buffer to determine if the previous flip has finished.

一个应用程序等待不返回 DDERR_WASSTILLDRAWING 值是很低效的.你可以对后台缓存调用 IDirectDrawSurface4::GetFlipStatus 方法来判定前一次换页操作有没有结束.

如果前一次换页没有结束并返回 DDERR_WASSTILLDRAWING ,你的应用程序可以利用下一次检测前的时间来完成其他的任务.否则,你进行下一个换页操作.请看下例:

while(lpDDSBack->GetFlipStatus(DDGFS_ISFLIPDONE) ==
    DDERR_WASSTILLDRAWING);

    // Waiting for the previous flip to finish. The application can
    // perform another task here.

ddrval = lpDDSPrimary->Flip(NULL, 0);

类似的,你可以使用 IDirectDrawSurface4::GetBltStatus 方法以检测一个 Blit 操作是否完成.因为 IDirectDrawSurface4::GetBltStatus 与 IDirectDrawSurface4::GetFlipStatus 返回都很快,你可以周期性地调用它们,而只有很少的速度损失.


Determining the Capabilities of the Display Hardware

测定显示硬件的能力(Determining the Capabilities of the Display Hardware)

DirectDraw 使用软件仿真的方式来实现那些用户的显示硬件不支持的 DirectDraw 函数.为了加速你的 DirectDraw 应用程序的图象显示,你应该在创建了 DirectDraw 对象之后,测定用户显示硬件的能力,然后指挥你的应用程序尽可能的利用这些能力.

通过调用 IDirectDraw4::GetCaps 函数可以测定这些能力.不是所有的需要硬件支持的特性都可以由软件仿真出来.如果你想要利用那些只有某些高级显示设备才能支持的特性,在你的用户没有装备这些硬件设备时,你必须给他们提供一个可以选择的方案.


Storing Bitmaps in Display Memory

在显存中储存位图(Storing Bitmaps in Display Memory)

从显存到显存的 Blitting 操作通常比从系统内存到显存更有效.因此,你应该在显存中储存尽可能多的用于显示的图象.

目前,绝大多数显示适配器(显卡)都可以在容纳主页面(primary surface)及其后台缓存(back buffer)之后还有一些富余.调用 IDirectDraw4::GetAvailableVidMem 函数以判定显存中全部的及可用的内存来储存位图.其中, lpdwTotal 参数表示显存的总量减去主页面以及驱动设备所占用的任何缓冲.而 pdwFree 参数表示可以被分配给页面的空闲显存.


Triple Buffering

三缓冲(Triple Buffering)

在某些情况下,那就是,当显示适配器拥有足够的内存,那么,你就可以使用三缓冲区(Triple Buffering)来加速你的应用程序的显示速度.三缓冲区使用一个主页面(primary surface)和两个后台缓存(back buffers).下面的例子演示了如何初始化一个三缓冲区方案:

// The lpDDSPrimary and lpDDSBack variables are globally
// declared, uninitialized LPDIRECTDRAWSURFACE4 variables.
//
// The lpDD variable is a pointer to an IDirectDraw4 interface

DDSURFACEDESC2 ddsd;
ZeroMemory (&ddsd, sizeof(ddsd));

// Create the primary surface with two back buffers.
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE |
    DDSCAPS_FLIP | DDSCAPS_COMPLEX;
ddsd.dwBackBufferCount = 2;
ddrval = lpDD->CreateSurface(&ddsd, &lpDDSPrimary, NULL);

// If we successfully created the flipping chain,
// retrieve pointers to the surfaces we need for
// flipping and blitting.
if(ddrval == DD_OK)
{
    // Get the surface directly attached to the primary (the back buffer).
    ddsd.ddsCaps.dwCaps = DDSCAPS_BACKBUFFER;
    ddrval = lpDDSPrimary->GetAttachedSurface(&ddsd.ddsCaps,
        &lpDDSBack);
    if(ddrval != DD_OK) ;
        // Display an error message here.
}

你不需要关心三缓冲区换页链中的每一个页面.你只需要保持住指向主页面和紧接主页面的一个后台缓存的指针就可以了.指向主页面的指针用来在换页链中进行换页,指向后台缓存页面的指针用来进行 blit 操作.要得到更多的信息,请参阅换页.

三缓冲区允许你可以不用等到换页操作结束后,才能向后台缓存绘制图象.从而使换页成为一种非同步的事件.如果你只使用一个后台缓存(back buffer),那么在等待 IDirectDrawSurface4::Flip 函数返回 DD_OK 前,你的应用程序将让这些空闲的时间白白浪费掉.


DirectDraw Applications and Window Styles

DirectDraw 应用程序和窗口风格(DirectDraw Applications and Window Styles)

如果你的 DirectDraw 应用程序是运行于窗口模式的,你可以用任何窗口风格来创建你的窗口.然而,全屏独占模式的 DirectDraw 应用程序的窗口不能设置有 WS_EX_TOOLWINDOW 风格,否则可能会遭遇到不可预知的行为. WS_EX_TOOLWINDOW 风格原是阻止一个窗口成为顶层窗口,而在 DirectDraw 的全屏独占模式应用程序中,这却是必须的.

为了正确的显示,全屏独占模式的应用程序最好带有 WS_EX_TOPMOST 扩展窗口风格和 WS_VISIBLE 基本窗口风格.这些风格使得 DirectDraw 应用程序成为所有窗口的上层窗口,并且阻止 GDI 写向主页面.

下面的例子演示了在全屏独占模式的应用程序中如何正确的初始化一个窗口.

////////////////////////////////////////////////////////
// Register the window class, display the window, and init
// all DirectX and graphic objects.
////////////////////////////////////////////////////////
BOOL WINAPI InitApp(INT nWinMode)
{
    WNDCLASSEX wcex;

    wcex.cbSize           =    sizeof(WNDCLASSEX);
    wcex.hInstance        =    g_hinst;
    wcex.lpszClassName    =    g_szWinName;
    wcex.lpfnWndProc      =    WndProc;
    wcex.style            =    CS_VREDRAW|CS_HREDRAW|CS_DBLCLKS;
    wcex.hIcon            =    LoadIcon (NULL, IDI_APPLICATION);
    wcex.hIconSm          =    LoadIcon (NULL, IDI_WINLOGO);
    wcex.hCursor          =    LoadCursor (NULL, IDC_ARROW);
    wcex.lpszMenuName     =    MAKEINTRESOURCE(IDR_APPMENU);
    wcex.cbClsExtra       =    0 ;
    wcex.cbWndExtra       =    0 ;
    wcex.hbrBackground    =    GetStockObject (NULL_BRUSH);

    RegisterClassEx(&wcex);

    g_hwndMain = CreateWindowEx(
                        WS_EX_TOPMOST,
                        g_szWinName,
                        g_szWinCaption,
                        WS_VISIBLE|WS_POPUP,
                        0,0,CX_SCREEN,CY_SCREEN,
                        NULL,
                        NULL,
                        g_hinst,
                        NULL);

    if(!g_hwndMain)
        return(FALSE);

    SetFocus(g_hwndMain);
    ShowWindow(g_hwndMain, nWinMode);
    UpdateWindow(g_hwndMain);

    return TRUE;
}


Matching True RGB Colors to the Frame Buffer's Color Space

将真彩色匹配到帧缓冲区的色彩空间(Matching True RGB Colors to the Frame Buffer's Color Space)

当显示设备不是处于 24 位真彩模式时,应用程序需要知道一个真彩 RGB 颜色是怎样映射到一个帧缓冲区的色彩空间中去的.举例来说,如果你正在编写一个可运行于 8, 16 或 24 位显示模式的应用程序,在设置关键色或用 Blit 进行单色填充的时候,你所提供的颜色值必须与该页面当前的色彩空间相一致,也就是与帧缓冲区的色彩空间一致.这就是说,如果你的应用程序运行于 8 位色彩模式,那么你必须提供一个调色板索引;如果运行于 16 位色彩模式,你必须提供一个相应的 16 位值;如果运行于 24 位真彩模式,你必须提供一个 24 位值.用户可以选择他所期望的显示模式,那么你的程序就必须可以根据当前的显示模式,将一个特定的颜色值(通常是真彩 24 位值)映射到正确的色彩空间中去.

尽管 DirectDraw 不会为你自动完成颜色匹配的任务,但是仍有许多方法来解决如何把你的关键色映射到帧缓冲区中去.这些方法是比较复杂的.在绝大多数情况下,你可以使用 GDI 内建的色彩匹配服务,加上 DirectDraw 的直接帧缓冲区访问,来解决将一个 24 位颜色值匹配到不同的色彩空间中去.实际上, DirectX SDK 中的 Ddutil.cpp 源文件包含了一个 DDColorMatch 函数,用它就可以完成任何色彩空间的匹配工作.它的工作原理十分巧妙,你并不需要了解每一种色彩空间的格式,它用的是"埋种子"的方法,其步骤如下:

  1. 取页面左上角(坐标为0,0)的像素值.
  2. 调用 Win32 的 SetPixel 函数,用 COLORREF 结构来描述你的 24 位 RGB 颜色,将该色设置给页面左上角.
  3. 使用 DirectDraw 锁定页面,取得指向帧缓冲区内存的指针.
  4. 从帧缓冲区中获得真实的颜色值,将页面解锁.
  5. 使用 SetPixel 函数还原页面左上角像素颜色为原始值.

DDColorMatch 函数的速度并不是很快,这是因为它调用了 Win32 的 GetPixel 和 SetPixel 函数.然而,它提供了一个可靠和值得信赖的方法来求解颜色在不同的 RGB 色彩空间中是如何映射的.

注意 Because the SetPixel GDI function only accepts a COLORREF structure on input, this technique only works for matching RGB 888 colors to the frame buffer's pixel format. If your application needs to match colors of another pixel format, you should translate them to RGB 888 before using this technique or query the primary surface for its pixel format and match colors manually.


Displaying a Window in Full-Screen Mode

以全屏模式显示窗口(Displaying a Window in Full-Screen Mode)

In full-screen mode, DirectDraw has exclusive control over the display. As a result, dialog boxes and other windows created through GDI are not normally visible. However, by using special techniques you can incorporate a Windows dialog box, HTML Help, or any other kind of window in your application.

The FSWindow Sample illustrates how a dialog box can be displayed and updated in a full-screen application, and how mouse clicks and keystrokes work just as if the dialog box were being displayed by GDI.

In FSWindow, the dialog box is created and "shown" as an ordinary dialog window:

hWndDlg = CreateDialog(g_hInstance,
        MAKEINTRESOURCE(IDD_DIALOG_SAMPLE),
        hWnd, (DLGPROC) SampleDlgProc);
ShowWindow(hWndDlg, SW_SHOWNORMAL);

Of course, at this point the dialog box is shown only on the hidden GDI surface. It does not appear on the primary surface, which is controlled by DirectDraw.

If the hardware capabilities include DDCAPS2_CANRENDERWINDOWED (see DDCAPS), displaying and updating the dialog box is easy. The application simply calls the IDirectDraw4::FlipToGDISurface method, which makes the GDI surface the primary surface. From now on, all updates to the dialog box will be displayed automatically, because GDI is now rendering directly to the front buffer. The application continues rendering to the back buffer, and on each pass through the rendering loop the contents of the back buffer are blitted to the front buffer by DirectDraw. The dialog box is not overwritten because the front buffer is clipped to the application window, and the dialog box is obscuring part of that window.

The following code, from the FSWindow_Init function, creates the clipper, associates it with the application window, and brings the GDI surface to the front:

if (ddObject->CreateClipper(0, &ddClipper, NULL) == DD_OK)
    ddClipper->SetHWnd(0, hwndAppWindow);
ddObject->FlipToGDISurface();

Then, in the FSWindow_Update function, the following code blits the rendered contents of the back buffer to the clipping region:

ddFrontBuffer->SetClipper(ddClipper);
ddFrontBuffer->Blt(NULL, ddBackBuffer, NULL, DDBLT_WAIT, NULL);

Note that because the GDI surface is the primary surface, Windows continues displaying the mouse cursor. (This would not be the case, however, if the application were using DirectInput with the mouse device at the exclusive cooperative level.)

For hardware that does not have the DDCAPS2_CANRENDERWINDOWED capability, the process of displaying and updating a window in full-screen mode is somewhat more complicated. In this case, the application is responsible for obtaining the image of the window created by GDI and blitting it to the back buffer after the full-screen rendering has been done. The entire back buffer is then flipped to the front in the usual way.

The FSWindow sample provides two different methods for accessing the display memory of the window, depending on whether the content is static or dynamic. The method for static content is faster because it involves blitting from a memory device context rather than a screen device context. This method should be used for windows that do not change, such as informational dialog boxes. (Remember, though, that unless you manually update the bitmap in response to events, even basic animations such as a button press will not be visible to the user.)

If the content is static, FSWindow calls the CreateBMPFromWindow function when the window is initialized. This function creates a bitmap and blits the contents of the window into it. The bitmap handle is stored in the global variable hwndFSWindowBMP. Whenever the primary surface is about to be updated, this bitmap is blitted to the back buffer, as follows:

if (FSWindow_IsStatic)
{
    hdcMemory = CreateCompatibleDC(NULL);
    SelectObject(hdcMemory, hwndFSWindowBMP);
    BitBlt(hdcBackBuffer, x, y, cx, cy, hdcMemory, 0, 0, SRCCOPY);
    DeleteDC(hdcMemory);
}

If, on the other hand, the content of the window is dynamic, the following code is executed. It blits the image directly from the GDI surface (represented by the hdcScreen device context) to the back buffer.

BitBlt(hdcBackBuffer, x, y, cx, cy, hdcScreen, x, y, SRCCOPY);

The coordinates represent the position and dimensions of the window on the GDI surface, as retrieved through a call to GetWindowRect.

When the FSWindow application is running on hardware that does not have the DDCAPS2_CANRENDERWINDOWED capability, it does not use the GDI surface, so Windows cannot display the mouse cursor. The application takes over this task by obtaining information about the cursor and displaying it on the back buffer just before the flip.


DirectDraw Tutorials

DirectDraw 指南

这部分包含了一系列的指南,每一个指南都一步步的介绍了如何实现一个简单的 DirectDraw 应用.这些指南使用了很多这个 SDK 所附带的例程.这些例成演示了如何建立和使用 DirectDraw 来实现以下常见的任务:

  • 指南 1: DirectDraw 基础
  • 指南 2: 在后台缓存装载位图
  • 指南 3: 从离屏页面传送位图
  • 指南 4: 关键色和位图动画
  • 指南 5: 动态改变调色板
  • 指南 6: 使用覆盖页面

这些指南中的一些例程使用的是老版本的 IDirectDraw 和 IDirectDrawSurface 接口.如果你要升级这些例程应先使用 DirectX5.0 的接口查询来查找新的接口.另外,你必须为那些的接口的所有升级的方法改变适当的参数.

注意 指南中的这些例程都是用 C++ 写的.如果你要使用 C 编译器,你必须为这些文件作适当的改变才能编译成功.至少,你需要为接口函数添加 vtable 和 this 指针.


Tutorial 1: The Basics of DirectDraw

指南 1: DirectDraw 基础

要使用 DirectDraw,你要先创建一个 DirectDraw 对象的实例,它代表了计算机的显示适配器.接着你就可以通过接口函数来管理这个对象.另外,你还需要创建一个或更多 DirectDrawSurface 对象来使你的应用程序能显示图形.

要演示以上内容, SDK 中的 DDEx1 例程执行了以下几步:

  • 步骤 1: 创建一个 DirectDraw 对象
  • 步骤 2: 确定应用程序的行为
  • 步骤 3: 改变显示模式
  • 步骤 4: 创建换页页面
  • 步骤 5: 着色到页面
  • 步骤 6: 写到页面
  • 步骤 7: 换页
  • 步骤 8: 释放 DirectDraw 对象

注意 要在你的应用程序中成功地使用 GUID, 你必需要么在所有的 include 和 define 语句前先定义 INITGUID, 要么连接到 Dxguid.lib 库.你只要在你的源文件的一个模块中定义 INITGUID 就行了.


Step 1: Creating a DirectDraw Object

步骤 1: 创建一个 DirectDraw 对象

要创建一个 DirectDraw 对象的实例,你的应用程序要象 DDEx1 例程中的 doInit 函数那样先使用 DirectDrawCreate 函数. DirectDrawCreate 包含三个参数. 第一个参数获得了一个代表显示设备的全局唯一标识符(GUID). 这个 GUID 在大多数情况下被设为 NULL, 表示 DirectDraw 使用系统缺省的显示驱动. 第二个参数包含了 DirectDraw 创建以后的指针的地址. 第三个参数留作将来的扩展之用只能为 NULL.

下面的例子演示了如何创建一个 DirectDraw 对象以及确定是否创建成功:

ddrval = DirectDrawCreate(NULL, &lpDD, NULL);
if(ddrval == DD_OK)
{
    // lpDD 是一个可用的 DirectDraw 对象.
}
else
{
    // DirectDraw 对象不能被创建.
}


Step 2: Determining the Application's Behavior

步骤 2: 确定应用程序的行为

在你能够改变显示率之前, 你必须至少为 IDirectDraw::SetCooperativeLevel 函数的 dwFlags 参数指定 DDSCL_EXCLUSIVE 和 DDSCL_FULLSCREEN 标志. 这使得你的应用程序能完全控制显示设备,而其它应用程序不能共享之.另外, DDSCL_FULLSCREEN 标志设置应用程序为独占(全屏)模式. 你的应用程序覆盖了整个桌面,而且只有你的应用程序能够写到屏幕上. 然而桌面仍然是可用的.(要看独占模式的应用程序下的桌面,执行 DDEx1 然后按 ALT+ TAB.)

以下的例子演示了如何使用 SetCooperativeLevel 函数:

HRESULT      ddrval;
LPDIRECTDRAW lpDD;     // 已用 DirectDrawCreate 创建

ddrval = lpDD->SetCooperativeLevel(hwnd, DDSCL_EXCLUSIVE |
    DDSCL_FULLSCREEN);
if(ddrval == DD_OK)
{
    // 独占模式成功.
}
else
{
    // 独占模式不成功.
    // 应用程序仍可运行.
}

如果 SetCooperativeLevel 没有返回 DD_OK,你仍然可以运行你的程序.然而程序将不能取得独占模式,并且有可能不能实现你所需要的功能.在这种情况下,你也许应该显示信息让用户来决定退出还是继续.

如果你设置全屏,独占的控制等级,你必须把你的应用程序的窗口句柄传递给 SetCooperativeLevel 来允许 Windows 确定你的应用程序是否异常终止.例如,如果发生了一个一般保护(GP)错误而 GDI 换页到 后台缓存(back buffer),使用者将不能返回 Windows 屏幕.要防止这种现象的发生, DirectDraw 提供了一个在后台运行的进程来捕获发向 window 的消息. DirectDraw 使用这些消息来测定何时应用程序终止.然而这一特性强加了一些限制.你不得不指明为你的应用程序获取消息的窗口句柄,这意味着,如果你创建另一个窗口,你必须确定你指明了活动窗口.否则,你将会遇到问题,包括 GDI 的不可预知的行为,或你按了 ALT + TAB 而没有响应.


Step 3: Changing the Display Mode

步骤 3:改变显示模式

在你设置了应用程序的行为之后,你就能使用 IDirectDraw::SetDisplayMode 函数来改变显示分辨率.以下的例子演示了如何把显示模式设为 640×480×8 bpp:

HRESULT      ddrval;
LPDIRECTDRAW lpDD;  // 已创建

ddrval = lpDD->SetDisplayMode(640, 480, 8);
if(ddrval == DD_OK)
{
    // 显示模式改变成功.
}
else
{
    // 显示模式不能被改变.
    // 这种模式不被支持或
    // 另一个程序取得了独占模式.
}

当你设置显示模式时,你应该确定如果用户的硬件不能支持更高的显示模式,你的应用程序将恢复到被大数显示适配器所支持的模式. 例如,你的可以把应用程序制作为把 640×480×8 作为一个后备显示模式来运行与所有支持它的系统上.

注意 如果显示适配器不能被设置到想要的分辨率 IDirectDraw::SetDisplayMode 将返回一个 DDERR_INVALIDMODE 错误值.应此,在设置显示模式前你应该使用 IDirectDraw::EnumDisplayModes 函数来确定用户的显示适配器的性能.


Step 4: Creating Flipping Surfaces

步骤 4:创建换页页面

在你设置了显示模式之后,你应该创建页面来安放你的应用程序.因为 DDEx1 例子使用了 IDirectDraw::SetCooperativeLevel 函数设置成独占(全屏)模式,你就能创建换页的页面.你如果使用 SetCooperativeLevel 把模式设置为 DDSCL_NORMAL, 你将只能创建位块传送的页面.创建换页页面(flipping surfaces)需要以下步骤:

  • 定义页面参数
  • 创建页面


Defining the Surface Requirements

定义页面参数

创建换页页面(flipping surfaces)的第一步是在一个 DDSURFACEDESC 结构中定义页面参数.以下的例子演示了结构的定义以及创建换页页面所需的标志.

// 创建带有一个后台缓存的主页面.
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_CAPS | DDSD_BACKBUFFERCOUNT;
ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE |
    DDSCAPS_FLIP | DDSCAPS_COMPLEX;

ddsd.dwBackBufferCount = 1;

在这个例子中, dwSize 成员被设为 DDSURFACEDESC 结构的大小.者可以预防任何 DirectDraw 函数返回不可用成员错误. (dwSize 成员是为 DDSURFACEDESC 结构将来的扩展提供的.)

dwFlags 成员确定了 DDSURFACEDESC 结构中的哪一个成员将被填充有效信息.对于 DDEx1 例子, dwFlags 被设置为指明你要使用 DDSCAPS 结构(DDSD_CAPS)以及你要创建一个后台缓存(back buffer)(DDSD_BACKBUFFERCOUNT).

在这个例子中 dwCaps 成员指出这些标志将在 DDSCAPS 结构中使用.在这种情况下,它指明了一个主页面(primary surface)(DDSCAPS_PRIMARYSURFACE),一个换页页面(flipping surface)(DDSCAPS_FLIP),和一个复杂页面(complex surface)(DDSCAPS_COMPLEX).

最后,这个例子指明了一个后台缓存.后台缓存是背景和精灵将被实际写入的地方.然后后台缓存被换页到主页面.在 DDEx1 例子中,后台缓存的个数被设为 1.然而,你可以创建显存所允许的个数的后台缓存.要得到关于创建一个或更多后台缓存的信息,请参阅三缓冲(Triple Buffering).

页面内存可以是显示内存或系统内存.如果显存不够 DirectDraw 使用系统内存(例如,如果你在只有 1M 显存的显示适配器上指明超过一个后台缓存(back buffer)).你也可以通过设置 DDSCAPS 结构的 dwCaps 成员为 DDSCAPS_SYSTEMMEMORY 或 DDSCAPS_VIDEOMEMORY 指明只用系统内存或显示内存.(如果你指明 DDSCAPS_VIDEOMEMORY,而创建页面的有用显存不够, IDirectDraw::CreateSurface 将返回一个 DDERR_OUTOFVIDEOMEMORY 错误.)


Creating the Surfaces

创建页面

在 DDSURFACEDESC 结构被填充后,你可以使用它和由 DirectDrawCreate 函数创建的指向 DirectDraw 对象的指针 lpDD,来调用 IDirectDraw::CreateSurface 函数,如下所示:

ddrval = lpDD->CreateSurface(&ddsd, &lpDDSPrimary, NULL);
if(ddrval == DD_OK)
{
    // lpDDSPrimary 指向新页面.
}
else
{
    // 页面未创建.
    return FALSE;
}

lpDDSPrimary 参数将指向如果 CreateSurface 调用成功返回的主页面(primary surface).

在指向主页面的指针可用后,你可以使用 IDirectDrawSurface3::GetAttachedSurface 函数来提取一个指向后台缓存(back buffer)的指针,如下所示:

ddscaps.dwCaps = DDSCAPS_BACKBUFFER;
ddrval = lpDDSPrimary->GetAttachedSurface(&ddcaps, &lpDDSBack);
if(ddrval == DD_OK)
{
    // lpDDSBack 指向后台缓存.
}
else
{
    return FALSE;
}

通过提供主页面(primary surface)的地址以及使用 DDSCAPS_BACKBUFFER 标志设置特性值, 如果 IDirectDrawSurface3::GetAttachedSurface 调用成功 lpDDSBack 参数将指向后台缓存(back buffer).


Step 5: Rendering to the Surfaces

步骤 5:着色到页面

在一个主页面(primary surface)和一个后台缓存(back buffer)被创建之后, DDEx1 例子通过使用标准的 Windows GDI 函数向主页面和后台缓存着色了一些文本,如下所示:

if (lpDDSPrimary->GetDC(&hdc) == DD_OK)
{
    SetBkColor(hdc, RGB(0, 0, 255));
    SetTextColor(hdc, RGB(255, 255, 0));
    TextOut(hdc, 0, 0, szFrontMsg, lstrlen(szFrontMsg));
    lpDDSPrimary->ReleaseDC(hdc);
}

if (lpDDSBack->GetDC(&hdc) == DD_OK)
{
    SetBkColor(hdc, RGB(0, 0, 255));
    SetTextColor(hdc, RGB(255, 255, 0));
    TextOut(hdc, 0, 0, szBackMsg, lstrlen(szBackMsg));
    lpDDSBack->ReleaseDC(hdc);
}

这个例子使用了 IDirectDrawSurface3::GetDC 函数来获得设备描述句柄,同时它内在地琐定了页面.如果你不使用需要设备描述句柄的 Windows 函数, 你可以使用 IDirectDrawSurface3::Lock 和 IDirectDrawSurface3::Unlock 函数来锁定和解锁后台缓存(back buffer).

锁定页面内存(不论整个页面或一部分页面)使得你的应用程序和系统位块传送器不能同时获得对主页面的访问.这预防了由于你的应用程序正在写向页面内存而引发的错误.另外,在主页面被解锁前你的应用程序不能换页.

在页面解锁后,这个例子使用标准的 Windows GDI 函数: SetBkColor 来设置背景颜色, SetTextColor 来选择放在背景上的文本的颜色, 以及 TextOut 来把文本和背景颜色打印在页面上.

在文本被写到缓存后,这个例子使用 IDirectDrawSurface3::ReleaseDC 函数来解锁页面和释放句柄.一旦你的应用程序结束写向后台缓存(back buffer),你必须调用 IDirectDrawSurface3::ReleaseDC 或 IDirectDrawSurface3::Unlock,视你的程序而定.在页面被解锁前你的应用程序不能换页.

典型的,你写向后台缓存,然后换页到主页面(primary surface)以被显示.对于 DDEx1,在第一次换页前没有明显的延迟,所以 DDEx1 在初始函数中写向主缓存来预防显示页面前的延迟. 就如你在这个指南后面的步骤中将要看到的那样, DDEx1 只在 WM_TIMER 期间写向后台缓存.通常你只在初始函数或标题页中写向主页面.

注意 在通过使用 IDirectDrawSurface3::Unlock 解锁页面后,页面内存的指针是不可用的. 你必须重新使用 IDirectDrawSurface3::Lock 来获得一个可用的页面内存的指针.


Step 6: Writing to the Surface

步骤 6:写向页面

DDEx1 中 WM_TIMER 消息的前一半专门写向后台缓存(back buffer),如下所示:

case WM_TIMER:
    // 换页.
    if(bActive)
    {
        if (lpDDSBack->GetDC(&hdc) == DD_OK)
        {
            SetBkColor(hdc, RGB(0, 0, 255));
            SetTextColor(hdc, RGB(255, 255, 0));
            if(phase)
            {
                TextOut(hdc, 0, 0, szFrontMsg, lstrlen(szFrontMsg));
                phase = 0;
            }
            else
            {
                TextOut(hdc, 0, 0, szBackMsg, lstrlen(szBackMsg));
                phase = 1;
            }
            lpDDSBack->ReleaseDC(hdc);
        }

调用 IDirectDrawSurface3::GetDC 函数的那行代码锁定后台缓存(back buffer)来预备写操作. SetBkColor 和 SetTextColor 函数设置背景和文本的颜色.

接着, phase 变量决定了应该写主缓存消息还是后台缓存消息. 如果 phase 等于 1,将写主页面(primary surface)消息,同时 phase 被设为 0.如果 phase 等于 0,将写后台缓存消息,同时 phase 被设为 1.注意,其实两种情况下消息都是写到后台缓存里的.

在消息被写到后台缓存后,后台缓存被使用 IDirectDrawSurface3::ReleaseDC 函数解锁.


Step 7: Flipping the Surfaces

步骤 7:换页

在页面内存解锁后,你就可以使用 IDirectDrawSurface3::Flip 函数来换页后台缓存(back buffer)到主页面(primary surface)了,如下所示:

while(1)
{
    HRESULT ddrval;
    ddrval = lpDDSPrimary->Flip(NULL, 0);
    if(ddrval == DD_OK)
    {
        break;
    }
    if(ddrval == DDERR_SURFACELOST)
    {
        ddrval = lpDDSPrimary->Restore();
        if(ddrval != DD_OK)
        {
            break;
        }
    }
    if(ddrval != DDERR_WASSTILLDRAWING)
    {
        break;
    }
}

在这个例子里, lpDDSPrimary 参数指明了主页面(primary surface) 和与之关联的后台缓存(back buffer). 当调用 IDirectDrawSurface3::Flip 后,前后页面被交换(只改变了页面的指针,数据并未实际移动). 如果换页成功返回 DD_OK,程序从 while 循环跳出.

如果换页返回 DDERR_SURFACELOST,可以尝试使用 IDirectDrawSurface3::Restore 函数来恢复页面.如果恢复成功,程序跳回 IDirectDrawSurface3::Flip 调用并再次尝试.如果恢复不成功,程序从循环跳出,并返回一个错误.

注意 当你调用 IDirectDrawSurface3::Flip, 换页并不立即完成,而是在系统发生下一次垂直空扫时.如果前一次换页还未发生, IDirectDrawSurface3::Flip 返回 DDERR_WASSTILLDRAWING.在这个例子里, IDirectDrawSurface3::Flip 持续调用直到返回 DD_OK.


Step 8: Deallocating the DirectDraw Objects

步骤 8: 释放 DirectDraw 对象

当你按 F12 时, DDEx1 程序在退出前执行 WM_DESTROY 消息.这个消息调用 finiObjects 函数,它包含了所有的 IUnknown::Release 调用,如下所示:

static void finiObjects(void)
{
    if(lpDD != NULL)
    {
        if(lpDDSPrimary != NULL)
        {
            lpDDSPrimary->Release();
            lpDDSPrimary = NULL;
        }
        lpDD->Release();
        lpDD = NULL;
    }
} // finiObjects

程序检查 DirectDraw 对象(lpDD)和 DirectDrawSurface 对象(lpDDSPrimary)的指针是否不等于 NULL. 然后 DDEx1 调用 IDirectDrawSurface3::Release 函数把 DirectDrawSurface 对象的 引用计数(reference count)减 1.因为这使得引用计数变为 0, DirectDrawSurface 对象被释放. DirectDrawSurface 指针通过值被设为 NULL 而被释放.然后,程序调用 IDirectDraw::Release 把 DirectDraw 对象的引用计数减为 0,释放 DirectDraw 对象.它的指针同样通过值被设为 NULL 而被释放.


Tutorial 2: Loading Bitmaps on the Back Buffer

指南 2: 在后台缓存装载位图

这个指南中的例子(DDEx2)是对指南1中的例子 DDEx1 的扩展. DDEx2 包含了把一个位图文件装载到后台缓存(back buffer)的功能.这个新的功能以如下几步演示:

  • 步骤 1:创建调色板
  • 步骤 2:设置调色板
  • 步骤 3:把位图装载到后台缓存
  • 步骤 4:换页

如同在 DDEx1 中, doInit 是 DDEx2 程序的初始函数.尽管 DirectDraw 初始化代码在 DDEx2 中和 DDEx1 中看起来不太一样, 但本质上是一样的,除了以下的片断:

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)
    goto error;

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval != DD_OK)
    goto error;

//装载一幅位图到后台缓存.
ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval != DD_OK)
    goto error;


Step 1: Creating the Palette

步骤 1:创建调色板

DDEx2 首先通过使用如下代码把调色板装载到一个结构中:

lpDDPal = DDLoadPalette(lpDD, szBackground);

if (lpDDPal == NULL)
    goto error;

例子函数 DDLoadPalette 是 \Dxsdk\Sdk\Samples\Misc 目录的 Ddutil.cpp 文件中的 DirectDraw 公共函数中的一个.大多数 SDK 中的 DirectDraw 例程都使用了这个文件.本质上,它包含了从资源或文件中装载位图和调色板的函数.为了避免在例程文件中使用重复代码,这些函数被放到一个可以重复使用的文件中.请确定在你余下的 DDExn 例子中都包含了编译 Ddutil.cpp 文件.

对于 DDEx2, DDLoadPalette 例子函数从 Back.bmp 文件创建了一个 DirectDrawPalette 对象. DDLoadPalette 例子函数决定了是创建调色板的文件或资源是否存在.如果不,它创建一个缺省调色板.对于 DDEx2,它从位图文件中提取调色板的信息并把它储存在 ape 所指向的结构中.

DDEx2 然后创建了一个 DirectDrawPalette 对象,如下的例子所示:

pdd->CreatePalette(DDPCAPS_8BIT, ape, &ddpal, NULL);
return ddpal;

当 IDirectDraw2::CreatePalette 函数返回, ddpal 参数指向 DirectDrawPalette 对象,该对象然后被 DDLoadPalette 函数返回.

ape 是一个指向包含了被线性地组织的 2, 4, 16, 或 256 个入口的结构的指针.入口的个数由 CreatePalette 函数的 dwFlags 参数决定.再此例中, dwFlags 参数被设为 DDPCAPS_8BIT,表示结构中有 256 个入口.每个入口包含 4 个字节(一个红色通道，一个绿色通道，一个蓝色通道，和一个标志位).


Step 2: Setting the Palette

步骤 2:设置调色板

在你创建调色板之后,你通过对主页面(primary surface) 调用 IDirectDrawSurface3::SetPalette 函数把指针传给 DirectDrawPalette 对象(ddpal),如下例所示:

ddrval = lpDDSPrimary->SetPalette(lpDDPal);

if(ddrval != DD_OK)
    // SetPalette 失败.

在你调用 IDirectDrawSurface3::SetPalette 之后, DirectDrawPalette 对象和 DirectDrawSurface 对象相关联.任何时候你要改变调色板,你只需简单地创建一个新调色板然后重新设置一下.(尽管这个指南使用这些步骤,也有其他方法来改变调色板,将在以后的例子中看到.)


Step 3: Loading a Bitmap on the Back Buffer

步骤 3:把位图装载到后台缓存

在 DirectDrawPalette 对象和 DirectDrawSurface 对象相关联之后, DDEx2 通过以下的代码把 Back.bmp 位图装载到后台缓存(back buffer):

// 装载一个位图到后台缓存.
ddrval = DDReLoadBitmap(lpDDSBack, szBackground);

if(ddrval != DD_OK)
    // 装载失败.

DDReLoadBitmap 是 Ddutil.cpp 中的另一个例子函数.它从一个文件或资源中巴位图装载到一个已存在的 DirectDraw 页面. (你也可以使用 DDLoadBitmap 来创建一个页面然后装载位图到这个页面.要得到更多的信息,请参阅指南 5:动态改变调色板.)对于 DDEx2, 它把 szBackground 所指的 Back.bmp 文件装载到 lpDDSBack 所指的后台缓存(back buffer). DDReLoadBitmap 函数调用 DDCopyBitmap 函数把文件拷贝到后台缓存并把它拉伸到合适的大小.

DDCopyBitmap 函数把位图拷到内存里,并使用 GetObject 函数获得位图的尺寸.然后使用如下代码获得将要存放位图的后台缓存的尺寸:

// 获得页面尺寸.
ddsd.dwSize = sizeof(ddsd);
ddsd.dwFlags = DDSD_HEIGHT | DDSD_WIDTH;
pdds->GetSurfaceDesc(&ddsd);

ddsd 值是一个指向 DDSURFACEDESC 结构的指针.这个结构存放 DirectDraw 对象的当前描述.在这里, DDSURFACEDESC 分别通过 DDSD_HEIGHT 和 DDSD_WIDTH 成员描述了页面的高度和宽度(width).调用 IDirectDrawSurface3::GetSurfaceDesc 函数然后使用合适的值装载结构.对于 DDEx2,高是 480 宽是 640.

DDCopyBitmap 例子函数锁定页面并把位图复制到后台缓存(back buffer),通过使用 StretchBlt 函数合适地拉伸(stretching)或压缩位图,如下例所示:

if ((hr = pdds->GetDC(&hdc)) == DD_OK)
{
    StretchBlt(hdc, 0, 0, ddsd.dwWidth, ddsd.dwHeight, hdcImage, x, y,
        dx, dy, SRCCOPY);
    pdds->ReleaseDC(hdc);
}


Step 4: Flipping the Surfaces

步骤 4:换页

DDEx2 例子中的换页(Flipping surfaces)本质上 DDEx1 指南(参阅指南 1: DirectDraw 基础)中的一样除了如果页面丢失(DDERR_SURFACELOST),位图必须在使用 DDReLoadBitmap 函数恢复页面后重新装载到后台缓存(back buffer).


Tutorial 3: Blitting from an Off-Screen Surface

指南 3: 从离屏页面传送位图

指南2中的例子(DDEx2)提取一幅位图并把它放到后台缓存(back buffer)里,然后在后台缓存和主页面缓存间换页.这并不是显示位图的实际途径.这个指南中的例子(DDEx3)通过包含各存放了一个位图的两个离屏页面(偶数屏一个,奇数屏一个)扩展了 DDEx2 的性能.它使用 IDirectDrawSurface3::BltFast 函数把一个 离屏页面(off-screen surface)的内容拷贝到一个后台缓存, 然后换页缓存再把下一个离屏页面拷贝到后台缓存.

DDEx3 中所演示的新的功能如下几步所示:

  • 步骤 1:创建离屏页面
  • 步骤 2:装载位图到离屏页面
  • 步骤 3:从离屏页面位块传送到后台缓存


Step 1: Creating the Off-Screen Surfaces

步骤 1:创建离屏页面

以下是 DDEx3 中 doInit 例子函数里增加的用来创建两个离屏缓存的代码:

// 创建一个离屏位图.
ddsd.dwFlags = DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH;
ddsd.ddsCaps.dwCaps = DDSCAPS_OFFSCREENPLAIN;
ddsd.dwHeight = 480;
ddsd.dwWidth = 640;
ddrval = lpDD->CreateSurface(&ddsd, &lpDDSOne, NULL);
if(ddrval != DD_OK)
{
    return initFail(hwnd);
}

// 创建另一个离屏位图.
ddrval = lpDD->CreateSurface(&ddsd, &lpDDSTwo, NULL);
if(ddrval != DD_OK)
{
    return initFail(hwnd);
}

dwFlags 成员指明了程序将使用 DDSCAPS 结构,它将设置缓存的高度和宽度(width).页面将是一个光面的离屏缓存,正如 DDSCAPS 结构中设置的 DDSCAPS_OFFSCREEN 标志所指出的.高度和宽度在 DDSURFACEDESC 结构里分别设为 480 和 640.然后用 IDirectDraw::CreateSurface 函数创建页面.

因为两个离屏缓存是一样大小的,创建第二个缓存时只需使用不同名称的指针再调用一次 IDirectDraw::CreateSurface.

你可以通过在 DDSCAPS 结构中设置 DDSCAPS_SYSTEMMEMORY 或 DDSCAPS_VIDEOMEMORY 来指明离屏缓存放在系统内存还是显示内存里.通过把位图保存在显存里,你可以加快离屏页面(off-screen surfaces)和后台缓存(back buffer)之间的传输速度.这在使用位图动画时将显得更为重要.然而,如果你为离屏缓存指明了 DDSCAPS_VIDEOMEMORY 标志但没有足够的可用显存来存放整个位图,在你试图创建页面时将会产生一个 DDERR_OUTOFVIDEOMEMORY 错误.


Step 2: Loading the Bitmaps to the Off-Screen Surfaces

步骤 2:装载位图到离屏页面

在创建了两个离屏页面(off-screen surfaces)之后, DDEx3 使用 InitSurfaces 例子函数从 Frntback.bmp 文件把位图装载到页面上. InitSurfaces 函数使用了 Ddutil.cpp 中的 DDCopyBitmap 例子函数转载了两幅位图,如下例所示:

// 装载位图资源.
hbm = (HBITMAP)LoadImage(GetModuleHandle(NULL), szBitmap,
    IMAGE_BITMAP, 0, 0, LR_CREATEDIBSECTION);

if (hbm == NULL)
    return FALSE;

DDCopyBitmap(lpDDSOne, hbm, 0, 0,   640, 480);
DDCopyBitmap(lpDDSTwo, hbm, 0, 480, 640, 480);
DeleteObject(hbm);

return TRUE;

如果你在微软的画笔或什么其他作图程序中观看 Frntback.bmp 文件,你可以看到位图包含两个屏幕,一个在另一个上面. DDCopyBitmap 函数在屏幕的交汇点处把位图分为两个.另外,它把第一幅位图装载到第一个离屏页面(off-screen surface)(lpDDSOne)第二幅位图装载到第二个离屏页面(lpDDSTwo).


Step 3: Blitting the Off-Screen Surfaces to the Back Buffer

步骤 3:从离屏页面位块传送到后台缓存

WM_TIMER 消息中包含了写到页面和换页(flipping surfaces)的代码.对于 DDEx3,它包含了以下的代码来选择合适的离屏页面(off-screen surface)和把它位块传送到后台缓存:

rcRect.left = 0;
rcRect.top = 0;
rcRect.right = 640;
rcRect.bottom = 480;
if(phase)
{
    pdds = lpDDSTwo;
    phase = 0;
}
else
{
    pdds = lpDDSOne;
    phase = 1;
}
while(1)
{
    ddrval = lpDDSBack->BltFast(0, 0, pdds, &rcRect, FALSE);
    if(ddrval == DD_OK)
    {
        break;
    }
}

phase 变量决定了把哪个离屏页面位块传送到后台缓存(back buffer).然后调用 IDirectDrawSurface3::BltFast 函数把选定的离屏页面位块传送到后台缓存,从坐标(0, 0)开始, 即左上角.指向 RECT 结构的 rcRect 定义了要传送的离屏页面的左上和右下角.最后一个参数设为 FALSE(或 0), 表示不使用什么特殊的传输标志.

鉴于你的程序的需要,你可以使用 IDirectDrawSurface3::Blt 函数或 IDirectDrawSurface::BltFast 函数来从离屏缓存传送位块.如果你执行的位块传送是从显存中的离屏缓存,你应该使用 IDirectDrawSurface3::BltFast. 尽管你不能从在显示适配器上使用硬件传送(hardware blitter)的系统上获得速度提升,但可以在使用硬件仿真的系统上节省 10% 的时间.因此,你应该对所有从显存位块传送到显存的显示操作使用 IDirectDrawSurface3::BltFast.如果你的位块传送是从系统内存或需要特殊的硬件标志,你必须使用 IDirectDrawSurface3::Blt.

在离屏页面(off-screen surface)被装载到后台缓存(back buffer)之后,后台缓存和主页面(primary surface)之间使用和前面的指南中基本一样的方法换页.


Tutorial 4: Color Keys and Bitmap Animation

指南 4: 关键色和位图动画

指南3中的例子(DDEx3)显示了一个在把位图传送到后台缓存(back buffer)之前如何把它放置到离屏缓存中的一个简单方法. 这个指南中的例子(DDEx4)使用了前面的指南中描述过的方法把一个背景和一系列的精灵装载到一个离屏页面(off-screen surface)中.然后使用 IDirectDrawSurface3::BltFast 函数把部分离屏页面复制到后台缓存,从而产生了一个简单的位图动画.

DDEx4 使用的位图文件, All.bmp,包含一个背景和60个黑底的系列红色旋转圆环. DDEx4 例子包含了新的函数来为旋转圆环精灵设置关键色(color key).然后从离屏页面拷贝合适的精灵到后台缓存.

DDEx4 中演示的新的功能如以下步骤所示:

  • 步骤 1:设置关键色
  • 步骤 2:创建一个简单动画


Step 1: Setting the Color Key

步骤 1:设置关键色

在 doInit 例子函数中除了其它 DirectDraw 例子所具有的功能, DDEx4 例子包含了为精灵设置关键色(color key)的代码.关键色是一种被用来设为透明的颜色值.当系统包含了一个硬件位块传送器(hardware blitter),矩形中除了和关键色所设置的值一样的像素所有像素都被位块传送过去,从而在页面上产生了一个非矩形的精灵.以下的代码显示了 DDEx4 重视如何设置关键色的:

// 为这幅位图设置关键色(黑色).
DDSetColorKey(lpDDSOne, RGB(0,0,0));

return TRUE;

你可以通过调用 DDSetColorKey 例子函数为你想要的颜色设置 RGB 值来选择关键色.黑色的 RGB 值是 (0, 0, 0). DDSetColorKey 函数调用 DDColorMatch 函数(两个函数都在 Ddutil.cpp 中). DDColorMatch 函数存贮了 lpDDSOne 页面上的位图 (0, 0) 处像素的颜色值.然后它把 (0, 0) 处的像素的颜色值设为你提供的颜色值.最后,它使用每个像素可用的比特数掩盖了这个颜色值(it masks the value of the color with the number of bits per pixel that are available).在这之后,原来的颜色被放回 (0, 0), 然后函数调用把精确的关键色值返回给 DDSetColorKey.返回完成后,关键色值被放在 DDCOLORKEY 结构的 dwColorSpaceLowValue 成员里.它也被复制给 dwColorSpaceHighValue 成员.然后调用 IDirectDrawSurface3::SetColorKey 设置关键色.

你可能已经注意到在 DDSetColorKey 和 DDColorMatch 中引用了 CLR_INVALID.如果你在 DDEx4 中调用 DDSetColorKey 时以 CLR_INVALID 为关键色(color key),位图左上角 (0, 0) 处的像素将被用作关键色.如同 DDEx4 位图所显示的,这没有什么意义因为 (0, 0) 处像素的颜色是灰色的阴影.然而,如果你要看看如何使用 (0, 0) 处的像素为关键色,用作图程序打开 All.bmp 位图文件然后把 (0, 0) 处的像素该为黑色.请确定你保存了这个改变(这不太容易看见).然后把 DDEx4 中调用 DDSetColorKey 的代码行改为如下:

DDSetColorKey(lpDDSOne, CLR_INVALID);

重新编译 DDEx4, 并确定资源定义文件也重新编译了以保证使用了新的位图(要做到这一点,你可以简单地在 Ddex4.rc 文件中加入然后删去一个空格).然后 DDEx4 例子将使用 (0, 0) 处的像素(现在被改为黑色)作为关键色.


Step 2: Creating a Simple Animation

步骤 2:创建一个简单动画

DDEx4 例程使用 updateFrame 函数来创建一个简单的动画,使用了 All.bmp 位图文件里的红色圆环.动画包含以三角形放置的三个圆环它们以不同的速度旋转.这个例程使用 Win32 GetTickCount 函数来比较从上一次调用以来经过了多少毫秒从而决定是否重画某个精灵.随后使用 IDirectDrawSurface3::BltFast 函数先把背景从离屏页面(off-screen surface)(lpDDSOne)传送到后台缓存(back buffer),然后利用你先前设置的用来决定哪种颜色透明的关键色(color key)把位图传送到后台缓存.在精灵传送到后台缓存之后, DDEx4 调用 IDirectDrawSurface3::Flip 函数在后台缓存和主页面(primary surface)之间换页.

注意当你使用 IDirectDrawSurface3::BltFast 从离屏页面传送背景时, dwTrans 参数指定了传送类型为 DDBLTFAST_NOCOLORKEY. 这表明进行普通的位块传送.稍后的,当传送红色圆环到后台缓存时, dwTrans 参数被设为 DDBLTFAST_SRCCOLORKEY.这表明在 lpDDSOne 所指的缓存中将进行带透明关键色的位块传送.

在这个例程里,在每次调用 updateFrame 函数时整个背景都要重画.优化这个例程的一种方法是只重画旋转圆环时改变的那部分背景.因为圆环精灵的位置和矩形的尺寸从未改变,你可以很简单的改变 DDEx4 例程进行优化.


Tutorial 5: Dynamically Modifying Palettes

指南 5: 动态改变调色板

这个指南所讲述的例程(DDEx5)是对指南4中的例程(DDEx4)的改进. DDEx5 演示了如何在程序运行时动态改变调色板入口. DDEx5 中所演示的这种新的功能分为以下几步所示:

  • 步骤 1:装载调色板入口
  • 步骤 2:旋转调色板


Step 1: Loading the Palette Entries

步骤 1:装载调色板入口

DDEx5 中以下的代码使用 All.bmp 文件下半部分(包含圆环的那部分)的值装载调色板入口:

// 首先,设置所有的颜色未用.
for(i=0; i<256; i++)
{
    torusColors[i] = 0;
}

// 锁定页面扫描下半部分(圆环区),
// 并保存所有找到的缩影的轨迹.
ddsd.dwSize = sizeof(ddsd);
while (lpDDSOne->Lock(NULL, &ddsd, 0, NULL) == DDERR_WASSTILLDRAWING)
    ;

// 搜索圆环的框架并标志用过的颜色.
for(y=480; y<480+384; y++)
{
    for(x=0; x<640; x++)
    {
        torusColors[((BYTE *)ddsd.lpSurface)[y*ddsd.lPitch+x]] = 1;
    }
}

lpDDSOne->Unlock(NULL);

torusColors 数组被作为调色板颜色索引值是否在 All.bmp 文件下半部分使用过的指示器.使用之前,其中所有的值被设为0.然后作为确定颜色索引值是否被使用的准备,离屏页面被锁定.

torusColors 数组从位图的480行0列开始.数组中的颜色索引值由内存中位图页面处的数据的字节数确定.位图在内存中的位置由 DDSURFACEDESC 结构的 lpSurface 成员确定,它指向内存中位图480行0列所对应的位置(y × lPitch + x).然后特定的颜色索引值的位置被设为1. y值(行)乘以 lPitch 值(DDSURFACEDESC 结构中)得到线性内存中像素的实际位置.

torusColors 中设置的颜色索引值将在后面被用来确定调色板中哪一种颜色被旋转.因为背景和红色圆环之间没有共有的颜色,只有那些和红色圆环相关的颜色被旋转.如果你要检查这是真是假,只需丛数组中去掉 "*ddsd.lPitch" 然后重新编译运行看发生了什么.(没有 y × lPitch,将不会涉及到红色圆环只会涉及到背景上的颜色索引值.)要得到更多关于宽度(width)和宽距(pitch)的信息,请参阅宽度和宽距.


Step 2: Rotating the Palettes

步骤 2:旋转调色板

DDEx5 中的 updateFrame 函数的工作方式和指南 4中的例程一样(DDEx4).首先把背景传送到后台缓存(back buffer),然后把三个圆环传送到前景.不同的是,在换页之前, updateFrame 通过 doInit 函数创建的 调色板索引(palette index)改变了主页面(primary surface)的调色板,如以下代码所示:

// 改变调色板.
if(lpDDPal->GetEntries(0, 0, 256, pe) != DD_OK)
{
    return;
}

for(i=1; i<256; i++)
{
    if(!torusColors[i])
    {
       continue;
    }
    pe[i].peRed = (pe[i].peRed+2) % 256;
    pe[i].peGreen = (pe[i].peGreen+1) % 256;
    pe[i].peBlue = (pe[i].peBlue+3) % 256;
}

if(lpDDPal->SetEntries(0, 0, 256, pe) != DD_OK)
{
    return;
}

第一行的 IDirectDrawPalette::GetEntries 函数从一个 DirectDrawPalette 对象查询了调色板值.因为 pe 所值的调色板入口值应该是有效的,函数将返回 DD_OK 然后继续.接着的循环检查 torusColors 来确定颜色索引是否在初始化时设为1.如果是, pe 所值的调色板入口的红绿蓝值被循环.

在所有标志过的调色板入口被旋转之后,调用 IDirectDrawPalette::SetEntries 函数来改变 DirectDrawPalette 对象的入口.如果你对主页面的调色板做此操作改动将立即发生.

完了以后,换页.


Tutorial 6: Using Overlay Surfaces

指南 6: 使用覆盖页面

这个指南将逐步的向你演示如何在程序中使用 DirectDraw 和硬件支持的覆盖页面.指南围绕着 SDK 所带的蚊子(Mosquito)的例程而写.蚊子是一个使用了覆盖页面的换页链在桌面上显示位图动画的简单程序,它不对主页面执行位块传送操作.例程调整了覆盖页面的特性以适应硬件的限制.

蚊子例程分以下几步执行(复杂任务又被分为更小的子步骤):

  • 步骤 1:创建一个主页面
  • 步骤 2:测试硬件覆盖支持
  • 步骤 3:创建一个覆盖页面
  • 步骤 4:显示覆盖页面
  • 步骤 5:更新覆盖页面的显示位置
  • 步骤 6:隐藏覆盖页面


Step 1: Creating a Primary Surface

步骤 1:创建一个主页面

要准备使用覆盖页面,你必须先初始化 DirectDraw 并创建一个将被用于覆盖页面显示其上的主页面.蚊子例程使用如下代码创建主页面:

    // 对结构清零和设置 dwSize 成员.
    ZeroMemory(&ddsd, sizeof(ddsd));
    ddsd.dwSize = sizeof(ddsd);

    // 设置标志并创建一个主页面.
    ddsd.dwFlags = DDSD_CAPS;
    ddsd.ddsCaps.dwCaps = DDSCAPS_PRIMARYSURFACE;
    ddrval = g_lpdd->CreateSurface(&ddsd, &g_lpddsPrimary, NULL );

上例一开始初始化后面将用到的 DDSURFACEDESC 结构.然后设置合适的标志来创建主页面并调用 IDirectDraw2::CreateSurface 函数创建之.对于这个调用,第一个参数是一个指向 DDSURFACEDESC 结构的指针,它描述了要创建的页面.第二个参数是一个指向调用成功后获得 IDirectDrawSurface 接口的变量的指针.最后一个参数设为 NULL 表示没有使用 COM 集合.


Step 2: Testing for Hardware Overlay Support

步骤 2:测试硬件覆盖支持

初始化 DirectDraw 之后,你需要校验设备是否支持覆盖页面.因为 DirectDraw 不仿真覆盖,如果硬件设备不支持你就不能继续.你可以通过调用 IDirectDraw2::GetCaps 函数获得硬件性能来测试是否支持覆盖.调用该函数之后,查看相关的 DDCAPS 结构的 dwFlags 成员是否有 DDCAPS_OVERLAY 标志.如果标志存在,表示显示硬件支持覆盖;反之,你不能在这个设备上使用覆盖页面.

以下从蚊子例程截取的例子演示了如何测试硬件覆盖支持:

BOOL AreOverlaysSupported()
{
    DDCAPS  capsDrv;
    HRESULT ddrval;

    // 获得驱动性能来确定是否支持覆盖.
    ZeroMemory(&capsDrv, sizeof(capsDrv));
    capsDrv.dwSize = sizeof(capsDrv);

    ddrval = g_lpdd->GetCaps(&capsDrv, NULL);
    if (FAILED(ddrval))
        return FALSE;

    // 当前模式是否支持覆盖?
    // (现在 DirectDraw 仿真层还不支持覆盖.
    // 如果硬件不支持与覆盖相关的 API 将失败).
    if (!(capsDrv.dwCaps & DDCAPS_OVERLAY))
        return FALSE;

    return TRUE;
}

上例调用 IDirectDraw2::GetCaps 函数来获得硬件性能.第一个参数是被用来填充描述设备驱动性能的信息的 DDCAPS 结构的地址.因为程序不需要仿真性能的信息,第二个参数设为 NULL.

获得驱动性能之后,例程使用逻辑 AND 操作来检查 dwCaps 成员是否有 DDCAPS_OVERLAY 标志.如果没有,例程返回 FALSE 以示失败.否则,返回 TRUE 表示驱动设备支持覆盖页面.

在你的代码里,这也是一个好的时机来检查 DDCAPS 结构的 dwMaxVisibleOverlays 和 dwCurrentVisibleOverlays 成员以确定没有其它程序使用覆盖页面.


Step 3: Creating an Overlay Surface

步骤 3:创建一个覆盖页面

在你知道驱动设备支持覆盖页面后就可以试着创建一个了.因为没有一个关于设备必须如何支持覆盖页面的标准的规范,你不能指望能够创建一个任意尺寸或像素格式的覆盖页面.另外，你也不要期望创建覆盖页面一次成功.因此,准备好多次尝试创建从最好的到最差的配置直到有一个可用.

注意 你可以调用 IDirectDraw2::GetFourCCCodes 函数来获得一个描述驱动设备对覆盖页面支持的非RGB像素格式的 FOURCC 代码列表.然而,如果你要使用 RGB 覆盖页面,推荐你尝试用多种普通的 RGB 格式创建覆盖页面,一种不行就试试差一点的一种.

蚊子例程就是在这种"最好的情况到最差的情况"的思想的指导下创建覆盖页面的.例程首先试着创建一个三缓冲换页复杂覆盖页面.如果不行,例程就试着用另一种普通的像素格式配置.如下的代码片断演示了是如何做的:

    ZeroMemory(&ddsdOverlay, sizeof(ddsdOverlay));
    ddsdOverlay.dwSize = sizeof(ddsdOverlay);

    ddsdOverlay.dwFlags= DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH |
                         DDSD_BACKBUFFERCOUNT| DDSD_PIXELFORMAT;
    ddsdOverlay.ddsCaps.dwCaps = DDSCAPS_OVERLAY | DDSCAPS_FLIP |
                                 DDSCAPS_COMPLEX | DDSCAPS_VIDEOMEMORY;
    ddsdOverlay.dwWidth  =320;
    ddsdOverlay.dwHeight =240;
    ddsdOverlay.dwBackBufferCount=2;

    //试着用我们的列表里的一种像素格式创建覆盖页面.
    i=0;
    do{
    ddsdOverlay.ddpfPixelFormat=g_ddpfOverlayFormats[i];
       // 尝试创建覆盖页面
       ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
    } while( FAILED(ddrval) && (++i < NUM_OVERLAY_FORMATS) );

上例通过在 DDSURFACEDESC 结构中设置相应的标志和值来反映要创建的是三缓冲换页复杂覆盖页面.然后例程执行了一个循环尝试在各种普通的像素格式之间创建页面,从最好得到最差的.如果尝试成功,跳出循环.如果所有的尝试都失败,可能是没有足够的内存来执行三缓冲任务或不支持换页覆盖页面.在这种情况下,例程尝试使用单个非换页覆盖页面的配置,如下所示:

    //如果创建三缓冲复杂覆盖页面失败,尝试单个非换页换存
    if(FAILED(ddrval))
    {
        ddsdOverlay.dwBackBufferCount=0;
        ddsdOverlay.ddsCaps.dwCaps=DDSCAPS_OVERLAY | DDSCAPS_VIDEOMEMORY;
        ddsdOverlay.dwFlags= DDSD_CAPS|DDSD_HEIGHT|DDSD_WIDTH|DDSD_PIXELFORMAT;

        // 尝试创建覆盖页面
        ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
        i=0;
        do{
            ddsdOverlay.ddpfPixelFormat=g_ddpfOverlayFormats[i];
            ddrval = g_lpdd->CreateSurface(&ddsdOverlay, &g_lpddsOverlay, NULL);
        } while( FAILED(ddrval) && (++i < NUM_OVERLAY_FORMATS) );

        // 不能创建覆盖页面.退出,返回失败.
        if (FAILED(ddrval))
            return FALSE;
    }

前面的代码重新设置了 DDSURFACEDESC 结构的标志和值以表明创建单个非换页覆盖页面.例程再次使用循环尝试各种像素格式来创建页面,如果尝试成功就停止循环.如果仍不行,例程返回 FALSE 以示失败.

在你成功地创建了覆盖页面之后,你可以把位图装载其上以备显示.


Step 4: Displaying the Overlay Surface

步骤 4:显示覆盖页面

在创建了覆盖页面之后,你就可以显示它了.通常,显示硬件要对覆盖页面的矩形的位置和像素进行对齐约束.另外,为了成功地显示覆盖页面你常常需要通过调整目标矩形的宽度来解决最少所需的拉伸因数.蚊子例程通过以下步骤准备显示覆盖页面:

  • 步骤 4.1:确定最少显示需求
  • 步骤 4.2:设置源和目标矩形
  • 步骤 4.3:显示覆盖页面


Step 4.1: Determining the Minimum Display Requirements

大部分的显示硬件在显示覆盖时都会有一些强制性的约束.为了成功的显示覆盖页面你必须小心的满足这些约束.你可以通过调用 IDirectDraw2::GetCaps 函数获得关于这些约束的信息.该函数填充的 DDCAPS 结构包含了关于覆盖性能和使用约束的信息.不同的硬件有不同的约束,因此一定要查看 dwFlags 成员的约束来决定用于你的是哪种约束.

蚊子例程开始先获得硬件的性能,然后采取基于最小拉伸因子的行动,如以下例程片断所示:

    // 获得驱动性能
    ddrval = g_lpdd->GetCaps(&capsDrv, NULL);
    if (FAILED(ddrval))
        return FALSE;

    // 确定最小拉伸因子并按此设置局部变量.
    if(capsDrv.dwCaps & DDCAPS_OVERLAYSTRETCH)
        uStretchFactor1000 = (capsDrv.dwMinOverlayStretch>1000) ? capsDrv.dwMinOverlayStretch : 1000;
    else
        uStretchFactor1000 = 1000;

上面的代码调用 GetCaps 仅获得硬件的性能.第一个参数是将被填充设备驱动信息的 DDCAPS 结构的指针, 第二个参数设为 NULL 表明不提取仿真的信息.

程序在一个临时变量中保留了最小拉伸因子以备后用(注意最小拉伸因子被报告为乘以 1000,因此 1300 实际上是 1.3). 如果驱动报告的值大于 1000,这表示所有的目标矩形必须沿 x 轴按此比例拉伸.例如,如果驱动报告的拉伸因子为 1.3 而源矩形为 320 像素宽,目标矩形至少 416 像素宽.如果驱动报告的拉伸因子小于 1000,这表示驱动可以显示覆盖比源矩形小,但也可以按需要拉伸.

接着,例程检查了描述驱动尺寸对齐约束的值,如下所示:

    // Grab any alignment restrictions and set the local variables acordingly.
    uSrcSizeAlign = (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)?capsDrv.dwAlignSizeSrc:0;
    uDestSizeAlign= (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC)?capsDrv.dwAlignSizeDest:0;

例程使用了更多的临时变量来保存 dwAlignSizeSrc 和 dwAlignSizeDest 成员报告的尺寸对齐约束.这些值提供了关于像素宽度对齐约束的信息将在后面设置源和目标矩形的尺寸时需要.源和目标矩形的像素宽度必须使这些成员值的倍数.

最后,例程检查了描述目标矩形边界对齐的值:

    // 设置全局的"目标位置对齐"我们就不需要每次移动覆盖页面时都调用 GetCaps().
    if (capsDrv.dwCaps & DDCAPS_ALIGNBOUNDARYDEST)
        g_dwOverlayXPositionAlignment = capsDrv.dwAlignBoundaryDest;
    else
        g_dwOverlayXPositionAlignment = 0;

前面的代码使用了一个全局变量来保存目标矩形的边界对齐的值,它从 dwAlignBoundaryDest 成员获得.这个值将在程序后面重新放置覆盖时用到(细节请参阅步骤 5:更新覆盖页面的显示位置).你必须设置目标矩形的左上角的X坐标像素值与之对齐.亦即,如果值为 4,你只能指定目标矩形的左上角的X坐标像素值为 0, 4, 8, 12, 等等.蚊子例程在 0,0 处初始化和显示覆盖,因此可以假定为对齐的同时例程也不需要获取约束信息直到第一次显示覆盖以后. 你可能要做的与之不同,因此你可能需要在显示覆盖以前检查这一信息并调整目标矩形.


Step 4.2: Setting Up the Source and Destination Rectangles

步骤 4.2:设置源和目标矩形

在获得了驱动的覆盖约束之后你应该按此设置源矩形和目标矩形的值,以确保能够正确显示覆盖。蚊子例程下面的代码设定了源矩形的特性:

    // 设置源 RECT 的初始值.
    rs.left=0; rs.top=0;
    rs.right = 320;
    rs.bottom = 240;

    // 如果必要,使用尺寸对齐约束.
    if (capsDrv.dwCaps & DDCAPS_ALIGNSIZESRC && uSrcSizeAlign)
        rs.right -= rs.right % uSrcSizeAlign;

上面的代码为页面设置了初始值包含整个页面的尺寸.如果设备驱动需要源矩形尺寸对齐,例程就调整源矩形来保证.例程调整了源矩形的宽度比原始值小是因为如果不完全重建页面就不能扩展宽度.然而,你的代码可以简单第以较小的矩形开始然后按照驱动约束拓宽.

在设定了源矩形的大小和适应了硬件约束后,需要设置和调整目标矩形的大小.这一过程需要稍多的工作因为目标矩形可能需要先拉伸再调整以符合尺寸对齐约束.下面的代码根据最小拉伸因子来完成这一任务:

    // 设置目标 RECT,以源 RECT 的值开始.
    // 我们使用源 RECT 的尺寸而不用页面的尺寸因为它们是不同的.
    rd.left=0; rd.top=0;
    rd.right  = (rs.right*uStretchFactor1000+999)/1000;
    // (Adding 999 avoids integer truncation problems.)

    // (这不是 DDraw 所必需的,但我们拉伸了高度也要维持屏幕高宽比).
    rd.bottom = rs.bottom*uStretchFactor1000/1000;

前面的代码先设置目标矩形的左上角为屏幕的左上角,再根据最小拉伸因子设置其宽度.根据拉伸因子调整时,注意例程在宽度和拉伸因子的乘积上又加了999.这是为了避免出现整数截断,那会导致矩形和最小拉伸因子要求的宽度不一致.要得到更多的信息,请参阅最小和最大拉伸因子.例程在拉伸宽度后也拉伸了高度.拉伸高度并不是必须的,这里只是为了保持位图的长宽比以免显示扭曲.

拉伸目标矩形后,例程继续对其进行调整以保证和尺寸对齐约束一致,如以下代码所示:

    // 调整目标 RECT 的宽度和对其约束一致.
    if (capsDrv.dwCaps & DDCAPS_ALIGNSIZEDEST && uDestSizeAlign)
        rd.right = (int)((rd.right+uDestSizeAlign-1)/uDestSizeAlign)*uDestSizeAlign;

例程检测性能标志来查看驱动是否强制目标尺寸对齐约束.如果是,就增加目标矩形的宽度到足够的像素来满足对齐约束.注意对矩形的调整是扩展其宽度而不能减少其宽度.因为减少宽度可能会导致目标矩形比最小拉伸因子要求的要小,从而引起显示覆盖表面失败.


Step 4.3: Displaying the Overlay Surface

步骤 4.3:显示覆盖页面

在设置了源矩形和目标矩形后，就可以第一次显示覆盖了。如果你正确地准备了，这会很简单。蚊子例程用如下的代码来显示覆盖：

    // 设置要传送给 UpdateOverlay 的标志
    dwUpdateFlags = DDOVER_SHOW | DDOVER_DDFX;

    // 硬件覆盖是否支持源关键色?
    // 如果支持，我们就可以隐藏图形的黑色背景.
    // 这可能不能在 YUV 格式下工作
    if (capsDrv.dwCKeyCaps & DDCKEYCAPS_SRCOVERLAY)
        dwUpdateFlags |= DDOVER_KEYSRCOVERRIDE;

    // 创建一个覆盖 FX 结构这样我们就可以指定一个源关键色.
    // 如果不设置 DDOVER_SRCKEYOVERRIDE 标志着一信息将被忽略.
    ZeroMemory(&ovfx, sizeof(ovfx));
    ovfx.dwSize = sizeof(ovfx);

    ovfx.dckSrcColorkey.dwColorSpaceLowValue=0; // 指定黑色为源关键色
    ovfx.dckSrcColorkey.dwColorSpaceHighValue=0;

    // 调用 UpdateOverlay() 显示覆盖到屏幕.
    ddrval = g_lpddsOverlay->UpdateOverlay(&rs, g_lpddsPrimary, &rd, dwUpdateFlags, &ovfx);
    if(FAILED(ddrval))
        return FALSE;

前面的例程开始在临时变量 dwUpdateFlags 中设定了 DDOVER_SHOW 和 DDOVER_DDFX 标志，指明该覆盖是第一次显示，以及硬件应该使用包含在相关的 DDOVERLAYFX 结构中的效果信息完成这一工作。然后，例程检查已存在的 DDCAPS 结构确定覆盖是否支持源 关键色(color keying) 。如果是， DDOVER_KEYSRCOVERRIDE 标志就包含在 dwUpdateFlags 变量中利用源关键色，例程也据此设置关键色。

准备完之后，例程调用 IDirectDrawSurface3::UpdateOverlay 函数来显示覆盖。对于该调用，第一个和第三个参数是已调整的源矩形和目标矩形的地址。第二个参数是覆盖将显示在其上的主表面的地址。第四个参数包括了放置于此前准备的 dwUpdateFlags 变量中的标志，第五个参数是 DDOVERLAYFX 结构的地址，其成员将被设为同那些标志相匹配。

如果硬件只支持一个覆盖页面而且该表面正在使用， UpdateOverlay 函数就会失败，并返回 DDERR_OUTOFCAPS。 另外，如果 UpdateOverlay 失败，你就需要尝试减少目标矩形的宽度来应付硬件错误报告出的最小拉伸因子过小的可能性。不过，这种情况很少发生，在蚊子例程中如果 UpdateOverlay 调用失败也只是简单地返回一个错误信息。


Step 5: Updating the Overlay Display Position

步骤 5:更新覆盖页面的显示位置

显示覆盖页面之后，有可能就不需要做其它操作了。然而，有些软件还需要重新放置覆盖页面。蚊子例程就使用IDirectDrawSurface3::SetOverlayPosition 函数重新放置覆盖，代码如下例程所示：

    // 设置 x轴 和 y轴 坐标
    .
    .
    .
    // 我们需要检查 x 轴的任何对齐约束，如果必要就对齐。
    if (g_dwOverlayXPositionAlignment)
        dwXAligned = g_nOverlayXPos - g_nOverlayXPos % g_dwOverlayXPositionAlignment;
    else
        dwXAligned = g_nOverlayXPos;

    // 设置覆盖到新的位置。
    ddrval = g_lpddsOverlay->SetOverlayPosition(dwXAligned, g_nOverlayYPos);
    if (ddrval == DDERR_SURFACELOST)
    {
        if (!RestoreAllSurfaces())
            return;
    }

以上例程开始对齐矩形以满足可能存在的任何目标矩形边界对齐约束。当程序此前调用 IDirectDraw2::GetCaps 函数时，以将全局变量 g_dwOverlayXPositionAlignment 已经设定为同 DDCAPS 结构中 dwAlignBoundaryDest 成员所报告出的值相等（详情请参阅步骤 4.1:确定最少显示需求）。如果存在目标对齐约束，程序就据此调整新的X坐标为像素对齐。若不满足要求，覆盖页面就不能显示。

在完成了对新的X坐标所需的调整之后，例程调用 IDirectDrawSurface3::SetOverlayPosition 函数重新放置覆盖。对于这一调用，第一个参数是对齐的X坐标，第二个参数是新的Y坐标。这些值表明了覆盖左上角新的位置。这里并不接受也不需要宽度和高度信息，因为 DirectDraw 在开始用 IDirectDrawSurface3::UpdateOverlay 函数初始化显示覆盖时就已经获得了页面的大小。如果因为一个或多个页面丢失而引起的重新放置覆盖表面的失败，例程就调用一个程序中定义的函数来恢复它们并重新装入它们的位图。

注意 小心不要使用太靠近目标页面的右、下边界的坐标。 IDirectDraw2::SetOverlayPosition 函数并不执行裁剪功能，所以使用那些可能导致覆盖超出目标页面边界的坐标会引起调用的失败，并返回 DDERR_INVALIDPOSITION。


Step 6: Hiding the Overlay Surface

步骤 6:隐藏覆盖页面

当你不再需要覆盖页面或只想不让覆盖可见，你可以设定适当的标志调用 IDirectDrawSurface3::UpdateOverlay 函数来隐藏该覆盖表面。蚊子例程在准备关闭应用程序时用以下代码隐藏覆盖表面：

void DestroyOverlay()
{
    if (g_lpddsOverlay){
        // 带 DDOVER_HIDE 标志使用 UpdateOverlay() 来从显示中移除覆盖。
        g_lpddsOverlay->UpdateOverlay(NULL, g_lpddsPrimary, NULL, DDOVER_HIDE, NULL);
        g_lpddsOverlay->Release();
        g_lpddsOverlay=NULL;
    }
}

以上例程在调用 IDirectDrawSurface3::UpdateOverlay 时，对源矩形和目标矩形指定了 NULL，因为在隐藏覆盖的过程中与它们无关。例程简单地使用第五个参数为 NULL 因为不使用覆盖效果。第二个参数是目标页面的指针。最后，例程在第四个参数使用 DDOVER_HIDE 标志表明该覆盖将从显示中移除。

例程在隐藏覆盖之后，释放了它的 IDirectDrawSurface3 接口，并将其全局变量设为 NULL 使之无效。对于蚊子例程的目的，覆盖就不再需要了。如果在应用程序中以后还需要使用该覆盖页面，就只需简单地隐藏覆盖而不释放它，然后在需要的时候再重新显示它。


DirectDraw Reference

DirectDraw 参考(DirectDraw Reference)

这部分包含了 DirectDraw 提供的 API 元素的参考信息.参考材料被分成以下几个目录:

  • 接口
  • 函数
  • 回调函数
  • 结构
  • 返回值
  • 像素格式掩码
  • 四字符代码(FOURCC)


Interfaces

接口(Interfaces)

这部分包含了 DirectDraw 部件所用到的接口的参考信息.包括以下接口:

  • IDDVideoPortContainer
  • IDirectDraw4
  • IDirectDrawClipper
  • IDirectDrawColorControl
  • IDirectDrawGammaControl
  • IDirectDrawPalette
  • IDirectDrawSurface4
  • IDirectDrawVideoPort


IDDVideoPortContainer

Applications use the methods of the IDDVideoPortContainer interface to create and manipulate DirectDrawVideoPort objects. You retrieve a pointer to this interface by calling the IUnknown::QueryInterface method of a DirectDraw object, specifying the IID_IDDVideoPortContainer reference identifier.

The methods of the IDDVideoPortContainer interface can be organized into the following groups:

Creating objects | CreateVideoPort
Video ports | EnumVideoPorts
 | QueryVideoPortStatus
Connections | GetVideoPortConnectInfo

The IDDVideoPortContainer interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

IUnknown | AddRef
 | QueryInterface
 | Release

You can use the LPDDVIDEOPORTCONTAINER data type to declare a variable that contains a pointer to an IDDVideoPortContainer interface. The Dvp.h header file declares the LPDDVIDEOPORTCONTAINER with the following code:

typedef struct IDDVideoPortContainer    FAR *LPDDVIDEOPORTCONTAINER;

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDDVideoPortContainer::CreateVideoPort

The IDDVideoPortContainer::CreateVideoPort method creates a DirectDrawVideoPort object.

HRESULT CreateVideoPort(
  DWORD dwFlags,
  LPDDVIDEOPORTDESC lpDDVideoPortDesc,
  LPDIRECTDRAWVIDEOPORT FAR *lplpDDVideoPort,
  IUnknown FAR *pUnkOuter
);

参数

dwFlags
Flags specifying video-port control options. This parameter can be one of the following flags, or NULL if control options are not needed:
DDVPCREATE_VBIONLY
The process only wants to control the VBI portion of the video stream.
DDVPCREATE_VIDEOONLY
The process only wants to control the non-VBI (video) portion of the video stream.
lpDDVideoPortDesc
Address of a DDVIDEOPORTDESC structure that describes the DirectDrawVideoPort object to be created.
lplpDDVideoPort
Address of a variable that will be filled with a pointer to the new DirectDrawVideoPort object's IDirectDrawVideoPort interface if the call succeeds.
pUnkOuter
Allows for future compatibility with COM aggregation features. Presently, however, this method will return an error if this parameter is anything but NULL.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_CURRENTLYNOTAVAIL
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFCAPS
DDERR_OUTOFMEMORY

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDDVideoPortContainer::EnumVideoPorts

The IDDVideoPortContainer::EnumVideoPorts method enumerates all of the video ports that the hardware exposes that are compatible with a provided video port description.

HRESULT EnumVideoPorts(
  DWORD dwFlags,
  LPDDVIDEOPORTCAPS lpDDVideoPortCaps,
  LPVOID lpContext,
  LPENUMVIDEOCALLBACK lpEnumVideoCallback
);

参数

dwFlags
Reserved for future use. This parameter must be zero.
lpDDVideoPortCaps
Pointer to a DDVIDEOPORTCAPS structure that will be checked against the available video ports. If this parameter is NULL, all video ports will be enumerated.
lpContext
Address of a caller-defined structure that will be passed to each enumeration member.
lpEnumVideoCallback
Address of the EnumVideoCallback function that will be called each time a match is found.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDDVideoPortContainer::GetVideoPortConnectInfo

The IDDVideoPortContainer::GetVideoPortConnectInfo method retrieves the connection information supported by all video ports.

HRESULT GetVideoPortConnectInfo(
  DWORD dwPortId,
  LPDWORD lpNumEntries,
  LPDDVIDEOPORTCONNECT lpConnectInfo
);

参数

dwPortId
Identifier of the video port for which the connection information will be retrieved.
lpNumEntries
Address of a variable containing the number of entries that the array at lpConnectInfo can hold. If this number is less than the total number of connections, the method fills the array with as many entries as will fit, sets the value at lpNumEntries to indicate the total number of connections, and returns DDERR_MOREDATA.
lpConnectInfo
Address of an array of DDVIDEOPORTCONNECT structures that will be filled with the connection options supported by the specified video port. If this parameter is NULL, the method sets lpNumEntries to indicate the total number of connections that the video port supports, then returns DD_OK.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDDVideoPortContainer::QueryVideoPortStatus

The IDDVideoPortContainer::QueryVideoPortStatus method retrieves the status of a DirectDrawVideoPort object.

HRESULT QueryVideoPortStatus(
  DWORD dwPortId,
  LPDDVIDEOPORTSTATUS lpVPStatus
);

参数

dwPortId
Identifier of the video port for which the status information will be retrieved.
lpVPStatus
Address of a DDVIDEOPORTSTATUS structure that will be filled with information about the status of the specified video port.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_CURRENTLYNOTAVAIL
DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDraw4

应用程序使用 IDirectDraw4 接口的方法来创建 DirectDraw 的各种对象，并且与系统层变量一起工作。这部分是关于该接口的函数参考。要得到概念性的总览，请参阅 DirectDraw 对象.

IDirectDraw4 接口的函数可以分为以下几组：

分配内存 | Compact
 | Initialize
控制级 | SetCooperativeLevel
 | TestCooperativeLevel
创建对象 | CreateClipper
 | CreatePalette
 | CreateSurface
设备特性 | GetCaps
显示模式 | EnumDisplayModes
 | GetDisplayMode
 | GetMonitorFrequency
 | RestoreDisplayMode
 | SetDisplayMode
 | WaitForVerticalBlank
显示状态 | GetScanLine
 | GetVerticalBlankStatus
杂项 | GetAvailableVidMem
 | GetDeviceIdentifier
 | GetFourCCCodes
页面管理 | DuplicateSurface
 | EnumSurfaces
 | FlipToGDISurface
 | GetGDISurface
 | GetSurfaceFromDC
 | RestoreAllSurfaces

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

IUnknown | AddRef
 | QueryInterface
 | Release

IDirectDraw4 接口通过提供使得页面管理比以前更为灵活的函数扩展了先前版本的特性。注意 IDirectDraw4 接口中所有跟页面相关的函数所接受的参数会跟 IDirectDraw2 接口中的对应项略有不同。在 IDirectDraw2 接口的函数接受 DDSURFACEDESC 结构和获得 IDirectDrawSurface3 接口的地方， IDirectDraw4 接口的函数接受 DDSURFACEDESC2 结构和获得 IDirectDrawSurface4 接口.

IDirectDraw4 引入了与 COM 规则所规定的子对象的生存周期的改善了的兼容。要得到更多信息，请参阅父对象和子对象的生存周期。

你可以使用 LPDIRECTDRAW， LPDIRECTDRAW2， 或 LPDIRECTDRAW4 数据类型来声明包含了一个指向 IDirectDraw， IDirectDraw2， 或 IDirectDraw4 接口的指针的变量。 Ddraw.h 头文件通过以下代码声明了这些数据类型：

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::Compact

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

HRESULT Compact();

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::CreateClipper

该函数创建一个 DirectDrawClipper 对象。

HRESULT CreateClipper(
  DWORD dwFlags,
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,
  IUnknown FAR *pUnkOuter
);

参数

dwFlags
这个参数目前没有被使用，必须置为0。
lplpDDClipper
如果函数调用成功，该参数将接收到指向 IDirectDrawClipper 接口的指针的地址。
pUnkOuter
该参数将允许与今后的 COM 集合特性相兼容。目前，只要这个参数不是 NULL，就返回一个错误。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY

备注

DirectDrawClipper 对象可以被隶属于一个 DirectDrawSurface 对象，并且在 IDirectDrawSurface4::Blt, IDirectDrawSurface4::BltBatch, 和 IDirectDrawSurface4::UpdateOverlay 过程中使用。

要创建一个不隶属于任何 DirectDraw 对象的 DirectDrawClipper 对象，使用 DirectDrawCreateClipper 函数。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetClipper, IDirectDrawSurface4::SetClipper


IDirectDraw4::CreatePalette

该函数为 DirectDraw 对象创建一个 DirectDrawPalette 对象。

HRESULT CreatePalette(
  DWORD dwFlags,
  LPPALETTEENTRY lpDDColorArray,
  LPDIRECTDRAWPALETTE FAR *lplpDDPalette,
  IUnknown FAR *pUnkOuter
);

参数

参数
下列标志的单个或组合：
DDPCAPS_1BIT
指定调色板索引为1比特。色彩表(color table)中只有两个入口。
DDPCAPS_2BIT
指定调色板索引为2比特。色彩表中有四个入口。
DDPCAPS_4BIT
指定调色板索引为4比特。色彩表中有16个入口。
DDPCAPS_8BIT
指定调色板索引为8比特。色彩表中有256个入口。
DDPCAPS_8BITENTRIES
表明调色板的索引值是另外一个8位调色板的索引。这个标志只有和 DDPCAPS_1BIT、 DDPCAPS_2BIT、 或 DDPCAPS_4BIT 标志一起使用才能生效，并且目标页面必须是8 bbp（8位色彩模式）。每一个色彩入口为1字节，并且指向目标页面的8 bbp 调色板。
DDPCAPS_ALPHA
Indicates that the peFlags member of the associated PALETTEENTRY structure is to be interpreted as a single 8-bit alpha value (in addition to the peRed, peGreen, and peBlue members). A palette created with this flag can only be attached to a texture梐 surface created with the DDSCAPS_TEXTURE capability flag.
DDPCAPS_ALLOW256
表明用户可以定义调色板的所有256个入口。
DDPCAPS_INITIALIZE
Initialize this palette with the colors in the color array passed at lpDDColorArray.
DDPCAPS_PRIMARYSURFACE
This palette is attached to the primary surface. Changing this palette's color table immediately affects the display unless DDPSETPAL_VSYNC is specified and supported.
DDPCAPS_PRIMARYSURFACELEFT
This palette is the one attached to the left eye primary surface. Changing this palette's color table immediately affects the left eye display unless DDPSETPAL_VSYNC is specified and supported.
DDPCAPS_VSYNC
This palette can have modifications to it synced with the monitors refresh rate.
lpDDColorArray
2、4、16或256个 PALETTEENTRY 结构序列的地址，用来初始化这个 DirectDrawPalette 对象。
lplpDDPalette
如果函数调用成功，这个参数将接收到指向 IDirectDrawPalette 接口的指针的地址。
pUnkOuter
该参数将允许与今后的 COM 集合特性相兼容。目前，只要这个参数不是 NULL， 就返回一个错误。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOOPERATIVELEVELSET
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::CreateSurface

该函数为该 DirectDraw 对象创建一个 DirectDrawSurface 对象。

HRESULT CreateSurface(
  LPDDSURFACEDESC2 lpDDSurfaceDesc2,
  LPDIRECTDRAWSURFACE4 FAR *lplpDDSurface,
  IUnknown FAR *pUnkOuter
);

参数

lpDDSurfaceDesc2
一个 DDSURFACEDESC2 结构的地址，用来描述所请求创建的页面的页面信息。在调用这个函数之前，你应该设置 DDSURFACEDESC2 结构所有成员的值为0。 DDSCAPS2 结构是 DDSURFACEDESC2的一个成员。
lplpDDSurface
如果函数调用成功，该参数将接收到指向的 IDirectDrawSurface4 接口的指针的地址。
pUnkOuter
该参数将允许与今后的 COM 集合特性相兼容。目前，只要这个参数不是 NULL， 就返回一个错误。

返回值

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

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::DuplicateSurface

该函数复制一个 DirectDrawSurface 对象。

HRESULT DuplicateSurface(
  LPDIRECTDRAWSURFACE4 lpDDSurface,
  LPLPDIRECTDRAWSURFACE4 FAR *lplpDupDDSurface
);

参数

lpDDSurface
将要被复制的 IDirectDrawSurface4 接口的地址。
lplpDupDDSurface
如果该函数调用成功，该参数将接收到指向新复制的 IDirectDrawSurface4 接口的指针的地址。

返回值

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

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

DDERR_CANTDUPLICATE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_SURFACELOST

备注

这个函数创建一个新的 DirectDrawSurface 对象，与一个已存在的 DirectDrawSurface 对象指向同一个页面内存区。这个复制品可以象原始对象一样使用。该页面内存在最后一个引用它的对象被释放之后被释放。主页面(primary surface)，3-D页面，或隐性页面不能被复制。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::EnumDisplayModes

该函数列举出暴露于 DirectDraw 对象的与所提供的页面描述相兼容的所有显示模式。

HRESULT EnumDisplayModes(
  DWORD dwFlags,
  LPDDSURFACEDESC2 lpDDSurfaceDesc2,
  LPVOID lpContext,
  LPDDENUMMODESCALLBACK2 lpEnumModesCallback
);

参数

dwFlags
DDEDM_REFRESHRATES
列举不同刷新率的显示模式。因为 IDirectDraw4::EnumDisplayModes 保证每一种模式只被列举一次，这个标志指定是否将刷新率也考虑在内。
DDEDM_STANDARDVGAMODES
除了 320x200x8 Mode X 模式之外，还列举出 Mode 13 模式。
lpDDSurfaceDesc2
指向一个 DDSURFACEDESC2 结构的地址，被用来判断其是否存在于系统所支持的显示模式中。如果该参数为 NULL， 则所有的模式将被列举。
lpContext
一个应用程序定义的结构的地址，用来传递给每一个列举的成员。
lpEnumModesCallback
EnumModesCallback2 函数的地址，每列举出一个显示模式的时候，该函数将被执行一次。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

这个方法可以列举出 DDSURFACEDESC2 结构的 dwRefreshRate 成员；而 IDirectDraw::EnumDisplayModes 却无法提供这个功能。如果你用 IDirectDraw4::SetDisplayMode 来设置某个显示模式的刷新率，你必须先用 IDirectDraw4::EnumDisplayModes 来列举出 dwRefreshRate 成员。

这个方法不同于以前版本接口中对应的方法，以前的版本接受 EnumModesCallback 函数的地址，而现在的版本接受 EnumModesCallback2 函数。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::GetDisplayMode, IDirectDraw4::SetDisplayMode, IDirectDraw4::RestoreDisplayMode


IDirectDraw4::EnumSurfaces

该函数列举出所有满足指定的搜索条件的已经存在或可能存在的页面。

HRESULT EnumSurfaces(
  DWORD dwFlags,
  LPDDSURFACEDESC2 lpDDSD2,
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpEnumSurfacesCallback
);

参数

dwFlags
A combination of one search type flag and one matching flag. The search type flag determines how the method searches for matching surfaces; you can search for surfaces that can be created using the description in the lpDDSD2 parameter or you can search for existing surfaces that already match that description. The matching flag determines whether the method enumerates all surfaces, only those that match, or only those that don't match the description in the lpDDSD2 parameter.
Search type flags
DDENUMSURFACES_CANBECREATED
列举出可以被创建并且满足搜索条件的第一个页面。只可以和 DDENUMSURFACES_MATCH 一起使用。
DDENUMSURFACES_DOESEXIST
列举出满足搜索条件的已经存在的页面。
Matching flags
DDENUMSURFACES_ALL
列举出满足搜索条件的所有页面。只可以和 DDENUMSURFACES_DOESEXIST 一起使用。
DDENUMSURFACES_MATCH
搜索任何一个符合页面描述的页面。
DDENUMSURFACES_NOMATCH
搜索任何一个不符合页面描述的页面。
lpDDSD2
一个 DDSURFACEDESC2 结构的地址，用来定义列举页面的依据。如果 dwFlags 包含了 DDENUMSURFACES_ALL， 这个参数可以为 NULL。
lpContext
一个应用程序定义的结构，用来传递给列举的回调函数。
lpEnumSurfacesCallback
EnumSurfacesCallback2 函数的地址，每列举出一个页面的时候，将执行该函数。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

如果 DDENUMSURFACES_CANBECREATED 标志被设置，该函数将尝试临时的创建一个满足条件的页面。

当使用 DDENUMSURFACES_DOESEXIST 标志时，注意一个页面被列举的时候，它的引用记录（Reference count）递增1，如果你不打算使用该页面，就应该在每次列举之后调用 IDirectDrawSurface4::Release 来释放该页面。

这个方法不同于以前版本接口中对应的方法，以前的版本接受 EnumModesCallback 函数的地址，而现在的版本接受 EnumModesCallback2 函数。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

Enumerating Surfaces


IDirectDraw4::FlipToGDISurface

该函数使 GDI 所写向的页面成为主页面(primary surface)。

HRESULT FlipToGDISurface();

参数

无。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

备注

这个函数可以在一个换页的应用程序结束之前调用，以确保 GDI 所写向的显存对用户来说是可见的。

The method can also be used to make the GDI surface the primary surface, so that normal windows such as dialog boxes can be displayed in full-screen mode. The hardware must have the DDCAPS2_CANRENDERWINDOWED capability. For more information, see Displaying a Window in Full-Screen Mode

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::GetGDISurface


IDirectDraw4::GetAvailableVidMem

该函数可以获得所有可用的显存容量值，和当前可以为某种指定类型的页面所用的空余显存容量值。

HRESULT GetAvailableVidMem(
  LPDDSCAPS2 lpDDSCaps2,
  LPDWORD    lpdwTotal,
  LPDWORD    lpdwFree
);

参数

lpDDSCaps2
一个 DDSCAPS2 结构的地址，用来指定被提供的页面的硬件性能。
lpdwTotal
一个变量的地址，将返回所有可用的显存容量值。The value retrieved reflects the total video memory, less the video memory required for the primary surface and any private caches the display driver reserves.
lpdwFree
一个变量的地址，将返回当前可以分配给某指定类型的页面的空余显存容量值，该页面的类型符合 lpDDSCaps2 结构。

返回值

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

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

DDERR_INVALIDCAPS
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW

如果给 lpdwTotal 或 lpdwFree 的值为 NULL， 则不返回该参数的值。

备注

以下的C++例程演示了使用 IDirectDraw4::GetAvailableVidMem 来确定显存总量以及纹理贴图可用的空闲显存：

// For this example, the lpDD variable is a valid
// pointer to an IDirectDraw interface.
LPDIRECTDRAW4 lpDD4;
DDSCAPS2      ddsCaps2;
DWORD         dwTotal;
DWORD         dwFree;
HRESULT       hr;

hr = lpDD->QueryInterface(IID_IDirectDraw4, &lpDD4);
if (FAILED(hr))
    return hr;

// Initialize the structure.
ZeroMemory(&ddsCaps2, sizeof(ddsCaps2));

ddsCaps2.dwCaps = DDSCAPS_TEXTURE;
hr = lpDD4->GetAvailableVidMem(&ddsCaps2, &dwTotal, &dwFree);
if (FAILED(hr))
    return hr;

这个函数只是为当前的显存状态做了一个快照。空余显存容量将随着页面的创建和销毁而不断的改变。因此，你应该把这个空余容量当作一个近似值来使用。此外，某些种类的显示卡不会将某两种不同的显存类型视为不同。例如：某显卡可能会使用显存上的同一区域既储存z-缓冲区值，又储存材质。于是，给其中的某一个页面类型（如z-缓冲区）分配内存将影响到另一个页面类型（如材质）所能使用的内存容量。因此，最好的做法是：首先就给应用程序划分好固定的资源（比如前台和后台缓冲区(back buffers)，z-缓冲区），而不是动态的分配内存（如材质贴图(texture mapping)）。

这个函数 IDirectDraw 接口不支持.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::GetCaps

该函数获得硬件和硬件仿真层（HEL）的设备驱动性能。

HRESULT GetCaps(
  LPDDCAPS lpDDDriverCaps,
  LPDDCAPS lpDDHELCaps
);

参数

lpDDDriverCaps
将被填充设备驱动所报告的描述了硬件性能的 DDCAPS 结构的地址。如果不想获得该描述，设置该参数为 NULL。
lpDDHELCaps
将被填充描述硬件仿真层（HEL）性能的 DDCAPS 结构的地址。如果不想获得该描述，设置该参数为 NULL。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

你只能将两个参数之中的一个设为 NULL 以排除该参数。如果两个参数均被设为 NULL，该函数返回DDERR_INVALIDPARAMS 。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::GetDeviceIdentifier

The IDirectDraw4::GetDeviceIdentifier method obtains information about the driver. This method can be used, with caution, to recognize specific hardware installations in order to implement workarounds for poor driver/chipset behavior.

HRESULT GetDeviceIdentifier(
  LPDDDEVICEIDENTIFIER lpdddi,
  DWORD dwFlags
);

参数

lpdddi
Address of a DDDEVICEIDENTIFIER structure to receive information about the driver.
dwFlags
Flags specifying options. The following flag is defined:
DDGDI_GETHOSTIDENTIFIER
Causes the method to return information about the host (typically 2-D) adapter in a system equipped with a stacked secondary 3-D adapter. Such an adapter appears to the application as if it were part of the host adapter, but is typically located on a separate card. When the dwFlags parameter is zero, the stacked secondary's information is returned, because this most accurately reflects the qualities of the DirectDraw object involved.

返回值

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

If the method fails, the return value may be DDERR_INVALIDPARAMS.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::GetDisplayMode

该函数获得当前的显示模式。

HRESULT GetDisplayMode(
  LPDDSURFACEDESC2 lpDDSurfaceDesc2
);

参数

lpDDSurfaceDesc2
一个 DDSURFACEDESC2 结构的地址，将被填充页面描述。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTEDMODE

备注

应用程序不应该保存这个函数所返回的信息，以在程序收尾时恢复显示模式。而应该在程序收尾时调用 IDirectDraw4::RestoreDisplayMode 函数来恢复显示模式，从而避免在多进程的环境中导致模式设置的冲突。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::SetDisplayMode, IDirectDraw4::RestoreDisplayMode, IDirectDraw4::EnumDisplayModes


IDirectDraw4::GetFourCCCodes

该函数获得 DirectDraw 对象所支持的 FOURCC 代码，也可获得所支持的代码个数。

HRESULT GetFourCCCodes(
  LPDWORD lpNumCodes,
  LPDWORD lpCodes
);

参数

lpNumCodes
一个变量数的地址，包含了 lpCodes 参数可以容纳的 FOURCC 代码入口的个数。如果入口的个数太小以致于不能容纳所有的 FOURCC 代码， lpNumCodes 将被设为所请求的个数，并且 lpCodes 所指向的序列将填入适当的代码。
lpCodes
一个变量序列的地址，将被填充该 DirectDraw 对象所支持的 FOURCC 代码。如果给该参数指定了 NULL，lpNumCodes 参数将返回该 DirectDraw 对象所支持的 FOURCC 代码的种类个数。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::GetGDISurface

该函数获得当前 GDI 视为主页面(primary surface)的 DirectDrawSurface 对象。

HRESULT GetGDISurface(
  LPDIRECTDRAWSURFACE4 FAR *lplpGDIDDSSurface4
);

参数

lplpGDIDDSSurface4
一个指向 IDirectDrawSurface4 接口的指针的地址，该 DirectDrawSurface 对是当前 GDI 所控制的主页面(primary surface)内存。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::FlipToGDISurface


IDirectDraw4::GetMonitorFrequency

该函数获得 DirectDraw 对象驱动的显示器的刷新频率。

HRESULT GetMonitorFrequency(
  LPDWORD lpdwFrequency
);

参数

lpdwFrequency
一个变量的地址，将获得显示器的刷新频率，单位为：Hz。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::GetScanLine

该函数提取显示器当前所画的扫描线(scan line)。

HRESULT GetScanLine(
  LPDWORD lpdwScanLine
);

参数

lpdwScanLine
一个变量的地址，将获得当前显示扫描线的位置。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS

备注

Scan lines are reported as zero-based integers. The returned scan line value is between 0 and n, where scan line 0 is the first visible scan line on the screen and n is the last visible scan line, plus any scan lines that occur during the vertical blank period. So, in a case where an application is running at 640×480, and there are 12 scan lines during vblank, the values returned by this method will range from 0 to 491.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::GetVerticalBlankStatus, IDirectDraw4::WaitForVerticalBlank


IDirectDraw4::GetSurfaceFromDC

The IDirectDraw4::GetSurfaceFromDC method retrieves the IDirectDrawSurface4 interface for a surface based on its GDI device context handle.

HRESULT GetSurfaceFromDC(
  HDC hdc,
  LPDIRECTDRAWSURFACE4 * lpDDS4
);

参数

hdc
Handle to a display device context.
lpDDS4
Address of a variable that will be filled with a valid IDirectDrawSurface4 interface pointer if the call succeeds.

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY
DDERR_NOTFOUND

备注

This method will succeed only for device context handles that identify surfaces already associated with the DirectDraw object.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

Surfaces and Device Contexts


IDirectDraw4::GetVerticalBlankStatus

The IDirectDraw4::GetVerticalBlankStatus method retrieves the status of the vertical blank.

HRESULT GetVerticalBlankStatus(
  LPBOOL lpbIsInVB
);

参数

lpbIsInVB
Address of the variable that will be filled with the status of the vertical blank. This parameter is TRUE if a vertical blank is occurring, and FALSE otherwise.

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

To synchronize with the vertical blank, use the IDirectDraw4::WaitForVerticalBlank method.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::GetScanLine, IDirectDraw4::WaitForVerticalBlank


IDirectDraw4::Initialize

该函数初始化一个用 CoCreateInstance COM函数创建的 DirectDraw 对象。

HRESULT Initialize(
  GUID FAR *lpGUID
);

参数

lpGUID
全局唯一标志符（GUID）的地址，用做接口标志符。

返回值

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

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

DDERR_ALREADYINITIALIZED
DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_NODIRECTDRAWSUPPORT
DDERR_OUTOFMEMORY

这个函数是为了符合部件对象模型（COM）的协议而提供。如果该 DirectDraw 对象是由调用 DirectDrawCreate 函数创建的，该函数返回 DDERR_ALREADYINITIALIZED。如果在使用 CoCreateInstance 创建一DirectDraw对象后，没有调用 IDirectDraw4::Initialize， 对该 DirectDraw 对象的任何使用都将导致一个 DDERR_NOTINITIALIZED 的错误。

备注

要得到更多的关于如何使用 IDirectDraw4::Initialize 和 CoCreateInstance的资料，请参阅：用 CoCreateInstance 创建 DirectDraw 对象。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::RestoreAllSurfaces

该函数按照页面生成的次序恢复所有的页面。

HRESULT RestoreAllSurfaces();

参数

无。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

This method is provided for convenience. Effectively, this method calls the IDirectDrawSurface4::Restore method for each surface created by this DirectDraw object.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::Restore, Losing and Restoring Surfaces


IDirectDraw4::RestoreDisplayMode

The IDirectDraw4::RestoreDisplayMode method resets the mode of the display device hardware for the primary surface to what it was before the IDirectDraw4::SetDisplayMode method was called. Exclusive-level access is required to use this method.

HRESULT RestoreDisplayMode();

参数

None.

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::SetDisplayMode, IDirectDraw4::EnumDisplayModes, IDirectDraw4::SetCooperativeLevel


IDirectDraw4::SetCooperativeLevel

该函数决定了应用程序最高层次的行为模式。

HRESULT SetCooperativeLevel(
  HWND hWnd,
  DWORD dwFlags
);

参数

hWnd
应用程序所使用的窗口的句柄。只能是顶级窗口句柄,不能是子窗口句柄。当设置 dwFlags 为 DDSCL_NORMAL 时，这个参数可以是 NULL。
dwFlags
可以是以下标志的单个或组合：
DDSCL_ALLOWMODEX
允许使用 Mode X 显示模式。这个标志必须与 DDSCL_EXCLUSIVE 和 DDSCL_FULLSCREEN 一起使用。
DDSCL_ALLOWREBOOT
当处于独占（全屏）模式时，允许使用 CTRL+ALT+DEL 组合键。
DDSCL_CREATEDEVICEWINDOW
这个标志只在 Windows 98 和 Windows 2000 中被支持。表明 DirectDraw 接口将为该 DirectDraw 对象创建和管理一个缺省的设备窗口(device window)。要得到更多信息，请参阅焦点窗口和设备窗口。
DDSCL_EXCLUSIVE
请求独占模式。这个标志必须与 DDSCL_FULLSCREEN 同时使用。
DDSCL_FPUSETUP
Indicates that the calling application is likely to keep the FPU set up for optimal Direct3D performance (single precision and exceptions disabled) so Direct3D does not need to explicitly set the FPU each time. For more information, see DirectDraw Cooperative Levels and FPU Precision.
DDSCL_FULLSCREEN
指定独占模式的所有者将管理整个主页面(primary surface)。GDI 可以被忽略。这个标志必须与 DDSCL_EXCLUSIVE 同时使用。
DDSCL_MULTITHREADED
Requests multithread-safe DirectDraw behavior. This causes Direct3D to take the global critical section more frequently.
DDSCL_NORMAL
指定应用程序将以普通窗口的形式出现。这个标志不能与 DDSCL_ALLOWMODEX、DDSCL_EXCLUSIVE 或 DDSCL_FULLSCREEN 同时使用。
DDSCL_NOWINDOWCHANGES
表明 DirectDraw 不允许最小化或还原应用程序窗口。
DDSCL_SETDEVICEWINDOW
这个标志只在 Windows 98 和 Windows 2000 中被支持。表明 hWnd 参数是该 DirectDraw 对象的设备窗口(device window)句柄。这个标志不能与 DDSCL_SETFOCUSWINDOW 同时使用。
DDSCL_SETFOCUSWINDOW
这个标志只在 Windows 98 和 Windows 2000 中被支持。表明 hWnd 参数是该 DirectDraw 对象的焦点窗口(focus window)句柄。这个标志不能与 DDSCL_SETDEVICEWINDOW 同时使用。

返回值

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

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

DDERR_EXCLUSIVEMODEALREADYSET
DDERR_HWNDALREADYSET
DDERR_HWNDSUBCLASSED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

备注

该函数必须在于创建应用程序窗口的同一个线程中调用。

一个应用程序必须设置DDSCL_EXCLUSIVE和DDSCL_NORMAL标志中的一个。

DDSCL_EXCLUSIVE 标志必须为那些具有激烈的动态效果的程序所设置。要得到更多的信息，请参阅控制级。

这个函数与 IDirectDraw4::SetDisplayMode 函数之间的相互影响因为 IDirectDraw 版本的不同而不同。要得到更多的信息，请参阅恢复显示模式。

Developers using Microsoft Foundation Classes (MFC) should keep in mind that the window handle passed to this method should identify the application's top-level window, not a derived child window. To retrieve your MFC application's top level window handle, you could use the following code:

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::SetDisplayMode, IDirectDraw4::Compact, IDirectDraw4::EnumDisplayModes, Mode X and Mode 13 Display Modes, Focus and Device Windows


IDirectDraw4::SetDisplayMode

该函数设置显示设备的模式。

HRESULT SetDisplayMode(
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwBPP,
  DWORD dwRefreshRate,
  DWORD dwFlags
);

参数

dwWidth and dwHeight
显示模式的宽度和高度。
dwBPP
显示模式的位深度(bpp)。
dwRefreshRate
显示模式的刷新率。如果这个参数为0，将使用IDirectDraw 接口的该函数的版本。
dwFlags
额外的选项。目前，唯一可用的标志是 DDSDM_STANDARDVGAMODE， 它将使显示模式被设为 Mode 13， 而不是 Mode X 320x200x8。如果你要设置另一种分辨率，位深度或 Mode X 模式，不要使用这个参数，并且将其设为0。

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDMODE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_LOCKEDSURFACES
DDERR_NOEXCLUSIVEMODE
DDERR_SURFACEBUSY
DDERR_UNSUPPORTED
DDERR_UNSUPPORTEDMODE
DDERR_WASSTILLDRAWING

备注

这个函数必须在与创建应用程序的同一个线程中调用.

如果另一个应用程序改变了显示模式，主页面(primary surface)将丢失，并且返回一个 DDERR_SURFACELOST 错误，直到它被重建以适合新的显示模式。

IDirectDraw 接口的这个函数，没有包含 dwRefreshRate 和 dwFlags 参数。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::RestoreDisplayMode, IDirectDraw4::GetDisplayMode, IDirectDraw4::EnumDisplayModes, IDirectDraw4::SetCooperativeLevel, Setting Display Modes, Restoring Display Modes


IDirectDraw4::TestCooperativeLevel

The IDirectDraw4::TestCooperativeLevel method reports the current cooperative-level status of the DirectDraw device for a windowed or full-screen application.

HRESULT TestCooperativeLevel(void);

参数

None.

返回值

If the method succeeds, the return value is DD_OK, indicating that the calling application can continue executing.

If the method fails, the return value may be one of the following error values (see remarks):

DDERR_INVALIDOBJECT
DDERR_EXCLUSIVEMODEALREADYSET
DDERR_NOEXCLUSIVEMODE
DDERR_WRONGMODE

备注

This method is particularly useful to applications that use the WM_ACTIVATEAPP and WM_DISPLAYCHANGE system messages as a notification to restore surfaces or re-create DirectDraw objects. The DD_OK return value always indicates that the application can continue execution, but the failure codes are interpreted differently depending on the cooperative-level that the application uses. For more information, see Testing Cooperative Levels.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDraw4::WaitForVerticalBlank

The IDirectDraw4::WaitForVerticalBlank method helps the application synchronize itself with the vertical-blank interval.

HRESULT WaitForVerticalBlank(
  DWORD dwFlags,
  HANDLE hEvent
);

参数

dwFlags
Determines how long to wait for the vertical blank.
DDWAITVB_BLOCKBEGIN
Returns when the vertical-blank interval begins.
DDWAITVB_BLOCKBEGINEVENT
Triggers an event when the vertical blank begins. This value is not currently supported.
DDWAITVB_BLOCKEND
Returns when the vertical-blank interval ends and the display begins.
hEvent
Handle of the event to be triggered when the vertical blank begins. This parameter is not currently used.

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::GetVerticalBlankStatus, IDirectDraw4::GetScanLine


IDirectDrawClipper

应用程序使用 IDirectDrawClipper 接口的函数来管理裁剪表(clip lists)。这部分是关于该接口函数的参考。要得到概念性的总览,请参阅裁剪器。

IDirectDrawClipper 接口的函数可以分为以下几组：

分配内存 | Initialize
裁剪表 | GetClipList
 | IsClipListChanged
 | SetClipList
 | SetHWnd
窗口句柄 | GetHWnd

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

IUnknown | AddRef
 | QueryInterface
 | Release

你可以使用 LPDIRECTDRAWCLIPPER 数据类型来声明一个指向 IDirectDrawClipper 接口的指针变量。在 Ddraw.h 头文件中，用如下代码声明了这种数据类型：

typedef struct IDirectDrawClipper    FAR *LPDIRECTDRAWCLIPPER;

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawClipper::GetClipList

该函数获得与一个 DirectDrawClipper 对象相关联的裁剪表(clip list)的复件。也可以提供一个矩形来裁剪裁剪表，以获得裁剪表的一个子集。

HRESULT GetClipList(
  LPRECT lpRect,
  LPRGNDATA lpClipList,
  LPDWORD lpdwSize
);

参数

lpRect
一个矩形的地址，被用来裁剪裁剪表(clip list)。该参数可以是NULL，以获得整个裁剪表。
lpClipList
一个 RGNDATA 结构的地址，将获得裁剪表的复件。如果该参数为NULL，则该函数把要容纳整个裁剪表所需要的缓冲区容量值（按字节数）返回给 lpdwSize。
lpdwSize
裁剪表缓冲区容量的长度值（按字节数）。当 lpClipList 参数不为NULL，则应赋予该参数 lpClipList 的缓冲区容量（即lpClipList的长度，按字节数）。当 lpClipList 为NULL，则该参数将获得要容纳整个裁剪表所需要的缓冲区容量值。

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPLIST
DDERR_REGIONTOOSMALL

备注

该函数使用的 RGNDATA 结构的定义如下。

typedef struct _RGNDATA {
    RGNDATAHEADER rdh;
    char          Buffer[1];
} RGNDATA;

RGNDATA 结构的 rdh 成员是一个 RGNDATAHEADER 结构，它的定义如下：

typedef struct _RGNDATAHEADER {
    DWORD dwSize;
    DWORD iType;
    DWORD nCount;
    DWORD nRgnSize;
    RECT  rcBound;
} RGNDATAHEADER;

要得到关于这些结构的更多的信息，请参阅平台 SDK 中的文档。

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawClipper::SetClipList


IDirectDrawClipper::GetHWnd

该函数获得由先前调用 IDirectDrawClipper::SetHWnd 函数与该 DirectDrawClipper 对象关联上的窗口的句柄。

HRESULT GetHWnd(
  HWND FAR *lphWnd
);

参数

lphWnd
窗口句柄的地址，该窗口是由先前调用 IDirectDrawClipper::SetHWnd 函数与该 DirectDrawClipper 对象关联上的。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawClipper::SetHWnd


IDirectDrawClipper::Initialize

该函数初始化一个 DirectDrawClipper 对象，该对象是由调用 CoCreateInstance COM函数创建的。

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  DWORD dwFlags
);

参数

lpDD
一个 DirectDraw 结构的地址，代表 DirectDraw 对象。如果该参数设为 NULL， 将创建一个独立的 DirectDrawClipper 对象（与使用 DirectDrawCreateClipper 函数相同）。
dwFlags
该参数尚未使用，只能设为0。

返回值

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

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

DDERR_ALREADYINITIALIZED
DDERR_INVALIDPARAMS

提供这个函数是为了与部件对象模型（COM）的协议保持一致性。如果已经调用 DirectDrawCreateClipper 或 IDirectDraw4::CreateClipper 创建了该DirectDrawClipper对象，该函数将返回 DDERR_ALREADYINITIALIZED。

备注

要得到更多关于如何与 CoCreateInstance 一起使用 IDirectDrawClipper::Initialize 的信息，请参阅用 CoCreateInstance 创建 DirectDrawClipper 对象。

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IUnknown::AddRef, IUnknown::QueryInterface, IUnknown::Release, IDirectDraw4::CreateClipper


IDirectDrawClipper::IsClipListChanged

如果一个窗口句柄与 DirectDrawClipper 对象关联上，该函数用来监控裁剪表(clip list)的状态。

HRESULT IsClipListChanged(
  BOOL FAR *lpbChanged
);

参数

lpbChanged
一个变量的地址，如果裁剪表(clip list)已经改变，则设为 TRUE。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawClipper::SetClipList

该函数设置或删除与 DirectDrawClipper 对象相关联的裁剪表(clip list)，该裁剪表被用于页面的 IDirectDrawSurface4::Blt， IDirectDrawSurface4::BltBatch, 和 IDirectDrawSurface4::UpdateOverlay操作。

HRESULT SetClipList(
  LPRGNDATA lpClipList,
  DWORD dwFlags
);

参数

lpClipList
一个合法的 RGNDATA 结构的地址或 NULL。如果已经存在一个裁剪表(clip list)与 DirectDrawClipper 对象相关联并且该参数被设为 NULL，则裁剪表被删除。
dwFlags
该参数尚未使用，必须设为0。

返回值

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

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

DDERR_CLIPPERISUSINGHWND
DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

备注

如果已经有一个窗口句柄与 DirectDrawClipper 对象相关联，裁剪表将不能被设置。应注意的是： BltFast 函数不支持裁剪。

该函数使用的 RGNDATA 结构的定义如下：

typedef struct _RGNDATA {
    RGNDATAHEADER rdh;
    char          Buffer[1];
} RGNDATA;

RGNDATA 结构的 rdh 成员是一个 RGNDATAHEADER 结构，它的定义如下：

typedef struct _RGNDATAHEADER {
    DWORD dwSize;
    DWORD iType;
    DWORD nCount;
    DWORD nRgnSize;
    RECT  rcBound;
} RGNDATAHEADER;

要得到更多的关于这些结构的信息，请参阅平台 SDK 中的文档。

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawClipper::GetClipList, IDirectDrawSurface4::Blt, IDirectDrawSurface4::BltFast, IDirectDrawSurface4::BltBatch, IDirectDrawSurface4::UpdateOverlay


IDirectDrawClipper::SetHWnd

该函数将一个窗口的客户区与裁剪表关联上。

HRESULT SetHWnd(
  DWORD dwFlags,
  HWND hWnd
);

参数

dwFlags
该参数尚未使用，只能设为0。
hWnd
包含了裁剪信息的窗口句柄。

返回值

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

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

DDERR_INVALIDCLIPLIST
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawClipper::GetHWnd


IDirectDrawColorControl

The IDirectDrawColorControl interface allows you to get and set color controls:

Color controls | GetColorControls
 | SetColorControls

The IDirectDrawColorControl interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

IUnknown | AddRef
 | QueryInterface
 | Release

You can use the LPDIRECTDRAWCOLORCONTROL data type to declare a variable that contains a pointer to an IDirectDrawColorControl interface. The Ddraw.h header file declares these data types with the following code:

typedef struct IDirectDrawColorControl    FAR *LPDIRECTDRAWCOLORCONTROL;

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawColorControl::GetColorControls

The IDirectDrawColorControl::GetColorControls method returns the current color control settings associated with the specified overlay or primary surface. The dwFlags member of the DDCOLORCONTROL structure indicates which of the color control options are supported.

HRESULT GetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

参数

lpColorControl
Address of the DDCOLORCONTROL structure that will receive the current control settings of the specified surface.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawColorControl::SetColorControls, Using Color Controls, Gamma and Color Controls


IDirectDrawColorControl::SetColorControls

The IDirectDrawColorControl::SetColorControls method sets the color control settings associated with the specified overlay or primary surface.

HRESULT SetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

参数

lpColorControl
Address of the DDCOLORCONTROL structure containing the new values to be applied to the specified surface.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawColorControl::GetColorControls, Using Color Controls, Gamma and Color Controls


IDirectDrawGammaControl

Applications use the methods of the IDirectDrawGammaControl interface to adjust the red, green, and blue gamma ramp levels of the primary surface. This section is a reference to the methods of this interface. This interface is supported by DirectDrawSurface objects; you can retrieve a pointer to this interface by calling the IUnknown::QueryInterface method of a DirectDrawSurface object, specifying the IID_IDirectDrawGammaControl reference identifier.

For a conceptual overview, see Gamma and Color Controls.

Gamma ramps | GetGammaRamp
 | SetGammaRamp

The IDirectDrawGammaControl interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

IUnknown | AddRef
 | QueryInterface
 | Release

You can use the LPDIRECTDRAWGAMMACONTROL data type to declare a variable that contains a pointer to an IDirectDrawGammaControl interface. The Ddraw.h header file declares the data type with the following code:

typedef struct IDirectDrawGammaControl    FAR *LPDIRECTDRAWGAMMACONTROL;

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawGammaControl::GetGammaRamp

The IDirectDrawGammaControl::GetGammaRamp method retrieves the red, green, and blue gamma ramps for the primary surface.

HRESULT GetGammaRamp(
  DWORD  dwFlags,
  LPGAMMARAMP lpRampData
);

参数

dwFlags
Not currently used; set to 0.
lpRampData
Address of a DDGAMMARAMP structure that will be filled with the current red, green, and blue gamma ramps. Each array maps color values in the frame buffer to the color values that will be passed to the DAC (Digital-to-Analog Converter).

返回值

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

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

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawGammaControl::SetGammaRamp, Gamma and Color Controls


IDirectDrawGammaControl::SetGammaRamp

The IDirectDrawGammaControl::SetGammaRamp method retrieves the red, green, and blue gamma ramps for the primary surface.

HRESULT SetGammaRamp(
  DWORD  dwFlags,
  LPGAMMARAMP lpRampData
);

参数

dwFlags
Flag indicating if gamma calibration is desired. Set this parameter DDSGR_CALIBRATE to request that the calibrator adjust the gamma ramp according to the physical properties of the display, making the result identical on all systems. If calibration is not needed, set this parameter to 0.
lpRampData
Address of a DDGAMMARAMP structure that contains the new red, green, and blue gamma ramp entries. Each array maps color values in the frame buffer to the color values that will be passed to the DAC (Digital-to-Analog Converter).

返回值

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

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

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

备注

Not all systems support gamma calibration. To determine if gamma calibration is supported, call IDirectDraw4::GetCaps, and examine the dwCaps2 member of the associated DDCAPS structure after the method returns. If the DDCAPS2_CANCALIBRATEGAMMA capability flag is present, then gamma calibration is supported.

Calibrating gamma ramps incurs some processing overhead, and should not be used frequently.

Including the DDSGR_CALIBRATE flag in the dwFlags parameter when running on systems that do not support gamma calibration will not cause this method to fail. The method succeeds, setting new gamma ramp values without calibration.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawGammaControl::GetGammaRamp, Gamma and Color Controls


IDirectDrawPalette

应用程序使用 IDirectDrawPalette 接口的方法来创建 DirectDrawPalette 对象，并使其与系统层变量协同工作。这部分是该接口的函数的参考。要得到一个概念性的总览，请参阅调色板。

IDirectDrawPalette 接口的函数可以分为以下几组：

分配内存 | Initialize
调色板特性 | GetCaps
调色板入口 | GetEntries
 | SetEntries

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

IUnknown | AddRef
 | QueryInterface
 | Release

你可以使用 LPDIRECTDRAWPALETTE 数据类型来声明一个指向 IDirectDrawPalette 接口的指针变量。在 Ddraw.h 头文件中，用如下代码声明了这种数据类型：

typedef struct IDirectDrawPalette    FAR *LPDIRECTDRAWPALETTE;

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawPalette::GetCaps

该函数获得该调色板对象的特性。

HRESULT GetCaps(
  LPDWORD lpdwCaps
);

参数

lpdwCaps
返回调色板的特性。将为 DDCAPS 结构 dwPalCaps 成员的下列标志之一：
DDPCAPS_1BIT
DDPCAPS_2BIT
DDPCAPS_4BIT
DDPCAPS_8BIT
DDPCAPS_8BITENTRIES
DDPCAPS_ALPHA
DDPCAPS_ALLOW256
DDPCAPS_PRIMARYSURFACE
DDPCAPS_PRIMARYSURFACELEFT
DDPCAPS_VSYNC

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawPalette::GetEntries

该函数获得调色板指定入口的地址。

HRESULT GetEntries(
  DWORD dwFlags,
  DWORD dwBase,
  DWORD dwNumEntries,
  LPPALETTEENTRY lpEntries
);

参数

dwFlags
该参数目前未用，必须设为0。
dwBase
要获得的调色板入口的开始位置。
dwNumEntries
Number of palette entries that can fit in the address specified in lpEntries. The colors of each palette entry are returned in sequence, from the value of the dwStartingEntry parameter through the value of the dwCount parameter minus 1. (These parameters are set by IDirectDrawPalette::SetEntries.)
lpEntries
调色板入口的地址。如果给调色板设置了 DDPCAPS_8BITENTRIES 标志（为索引调色板），则每个入口为1字节，其余类型调色板的每个入口为4字节。其内容为颜色值的描述。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPALETTIZED

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawPalette::SetEntries


IDirectDrawPalette::Initialize

该函数初始化一个 DirectDrawPalette 对象。

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  DWORD dwFlags,
  LPPALETTEENTRY lpDDColorTable
);

参数

lpDD
DirectDraw 结构的地址，代表 DirectDraw 对象。
dwFlags and lpDDColorTable
这两个参数未用，必须设为0。

返回值

This method returns DDERR_ALREADYINITIALIZED.

This method is provided for compliance with the Component Object Model (COM) protocol. Because the DirectDrawPalette object is initialized when it is created, this method always returns DDERR_ALREADYINITIALIZED.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IUnknown::AddRef, IUnknown::QueryInterface, IUnknown::Release


IDirectDrawPalette::SetEntries

该函数立即改变一个 DirectDrawPalette 对象的调色板入口。

HRESULT SetEntries(
  DWORD dwFlags,
  DWORD dwStartingEntry,
  DWORD dwCount,
  LPPALETTEENTRY lpEntries
);

参数

dwFlags
该参数目前未用，必须设为0。
dwStartingEntry
要改变的第一个调色板入口。
dwCount
要改变的调色板入口个数。
lpEntries
调色板入口的地址。如果给调色板设置了 DDPCAPS_8BITENTRIES 标志（为索引调色板），则每个入口为1字节，其余类型调色板的每个入口为4字节。其内容为颜色值的描述。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOPALETTEATTACHED
DDERR_NOTPALETTIZED
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawPalette::GetEntries, IDirectDrawSurface4::SetPalette


IDirectDrawSurface4

应用程序使用 IDirectDrawSurface4 接口的方法来创建 DirectDrawSurface 对象，并且与系统层变量一起工作。这部分是关于该接口方法的参考。要得到一个概念性的总览，请参阅页面。

IDirectDrawSurface4 接口的函数可以分为以下几组：

分配内存 | 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
Private surface data | FreePrivateData
 | GetPrivateData
 | SetPrivateData
页面性能 | GetCaps
页面裁剪 | GetClipper
 | SetClipper
页面描述 | ChangeUniquenessValue
 | GetPixelFormat
 | GetSurfaceDesc
 | GetUniquenessValue
 | SetSurfaceDesc
页面调色板 | GetPalette
 | SetPalette

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

IUnknown | AddRef
 | QueryInterface
 | Release

The IDirectDrawSurface4 interface extends the features of previous versions of the interface by offering methods that offer better surface management and ease of use. Note that many methods in this interface accept slightly different parameters than their counterparts in former versions of the interface. Wherever an IDirectDrawSurface3 interface method might accept a DDSURFACEDESC structure or an IDirectDrawSurface3 interface, the methods in IDirectDrawSurface4 accept a DDSURFACEDESC2 structure or an IDirectDrawSurface4 interface instead.

你可以使用 LPDIRECTDRAWSURFACE, LPDIRECTDRAWSURFACE2, LPDIRECTDRAWSURFACE3, 或 LPDIRECTDRAWSURFACE4 数据类型来声明一个指向 DirectDrawSurface 对象接口的变量。在 Ddraw.h 头文件中，用如下代码声明了这三种数据类型：

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::AddAttachedSurface

该函数将一个页面隶属于另一个页面。

HRESULT AddAttachedSurface(
  LPDIRECTDRAWSURFACE4 lpDDSAttachedSurface
);

参数

lpDDSAttachedSurface
将要被隶属的页面的 IDirectDrawSurface4 接口的地址。

返回值

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

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

DDERR_CANNOTATTACHSURFACE
DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACEALREADYATTACHED
DDERR_SURFACELOST
DDERR_WASSTILLDRAWING

备注

This method increments the reference count of the surface being attached. You can explicitly unattach the surface and decrement its reference count by using the IDirectDrawSurface4::DeleteAttachedSurface method. Unlike complex surfaces that you create with a single call to IDirectDraw4::CreateSurface, surfaces attached with this method are not automatically released. It is the application's responsibility to release such surfaces.

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::DeleteAttachedSurface, IDirectDrawSurface4::EnumAttachedSurfaces


IDirectDrawSurface4::AddOverlayDirtyRect

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

HRESULT AddOverlayDirtyRect(
  LPRECT lpRect
);

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::UpdateOverlayDisplay


IDirectDrawSurface4::Blt

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

HRESULT Blt(
  LPRECT lpDestRect,
  LPDIRECTDRAWSURFACE4 lpDDSrcSurface,
  LPRECT lpSrcRect,
  DWORD dwFlags,
  LPDDBLTFX lpDDBltFx
);

参数

lpDestRect
一个 RECT 结构的地址，定义了一个矩形区域的左上和右下点，作为目标页面上将被位块传送的区域。如果该参数是 NULL， 整个目标页面将被使用。
lpDDSrcSurface
一个 DirectDrawSurface 对象的 IDirectDrawSurface4 接口的地址，作为位块操作的源页面。
lpSrcRect
一个 RECT 结构的地址，定义了一个矩形区域的左上和右下点，作为源页面上将被位块传送的区域。如果该参数是 NULL，整个源页面将被使用。
dwFlags
A combination of flags that determine the valid members of the associated DDBLTFX structure, specify color key information, or that request special behavior from the method. The following flags are defined.
Validation flags
DDBLT_COLORFILL
使用 DDBLTFX 结构的 dwFillColor 成员作为填充目标页面上的目标矩形区域的颜色。
DDBLT_DDFX
使用 DDBLTFX 结构的 dwDDFX 成员来指定该位块传送操作的所使用的效果。
DDBLT_DDROPS
使用 DDBLTFX 结构的 dwDDROP 成员来指定光栅操作模式（ROPS），这些 ROP 不属于Win32 API。
DDBLT_DEPTHFILL
使用 DDBLTFX 结构的 dwFillDepth 成员作为填充目标 z-缓冲区页面上的目标矩形区域的深度值。
DDBLT_KEYDESTOVERRIDE
使用 DDBLTFX 结构的 ddckDestColorkey 成员作为目标页面的关键色(color key)。
DDBLT_KEYSRCOVERRIDE
使用 DDBLTFX 结构的 ddckSrcColorkey 成员作为源页面的关键色(color key)。
DDBLT_ROP
使用 DDBLTFX 结构的 dwROP 成员作为该位块传送操作的 ROP 模式。这些 ROP 与 Win32 API 中的定义是一样的。
DDBLT_ROTATIONANGLE
使用 DDBLTFX 结构的 dwRotationAngle 成员作为页面的旋转角度(specified in 1/100th of a degree)。
Color key flags
DDBLT_KEYDEST
使用目标页面的关键色(color key)。
DDBLT_KEYSRC
使用源页面的关键色(color key)。
Behavior flags
DDBLT_ASYNC
以异步的方式执行该位块传送操作，按照接收命令的先进先出的原则。如果没有可用的空间用于先进先出操作，该调用失败。
DDBLT_WAIT
如果位块传送器正忙，延迟 DDERR_WASSTILLDRAWING 消息的发送，直到位块传送器准备好或发生其它错误时返回。
Obsolete and unsupported flags
All "DDBLT_ALPHA" flag values.
Not currently implemented.
All "DDBLT_ZBUFFER" flag values
This method does not currently support z-aware blit operations. None of the flags beginning with "DDBLT_ZBUFFER" are supported in this release of DirectX 6.0.
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

备注

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

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::BltBatch

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

HRESULT BltBatch(
  LPDDBLTBATCH lpDDBltBatch,
  DWORD dwCount,
  DWORD dwFlags
);

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::BltFast

该函数通过使用源关键色(source color key) 或 目标关键色(destination color key)，完成一次源图复制或带透明的位块传送。

HRESULT BltFast(
  DWORD dwX,
  DWORD dwY,
  LPDIRECTDRAWSURFACE4 lpDDSrcSurface,
  LPRECT lpSrcRect,
  DWORD dwTrans
);

参数

dwX and dwY
目标页面上将被位块传送的x和y坐标。
lpDDSrcSurface
一个 DirectDraw 页面的 IDirectDrawSurface4 接口的地址，作为位块传送操作的源页面。
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。

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::ChangeUniquenessValue

The IDirectDrawSurface4::ChangeUniquenessValue method manually updates the uniqueness value for this surface.

HRESULT ChangeUniquenessValue();

参数

None.

返回值

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

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

DDERR_EXCEPTION
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

DirectDraw automatically updates uniqueness values whenever the contents of a surface change.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetUniquenessValue, Surface Uniqueness Values


IDirectDrawSurface4::DeleteAttachedSurface

该函数解除两个页面之间的隶属关系。

HRESULT DeleteAttachedSurface(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE4 lpDDSAttachedSurface
);

参数

dwFlags
该参数目前没有使用，只能设为0。
lpDDSAttachedSurface
将被解除隶属关系的 DirectDrawSurface 对象的 IDirectDrawSurface4 接口的地址。如果为NULL，所有相隶属的页面将相互脱离。

返回值

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

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

DDERR_CANNOTDETACHSURFACE
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_SURFACENOTATTACHED

备注

This method decrements the reference count of the surface being detached. If the reference count of the surface being detached reaches zero, it is lost and removed from memory.

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::Flip


IDirectDrawSurface4::EnumAttachedSurfaces

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

HRESULT EnumAttachedSurfaces(
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpEnumSurfacesCallback
);

参数

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

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

备注

This method enumerates only those surfaces that are directly attached to this surface. For example, in a flipping chain of three or more surfaces, only one surface will be enumerated, because each surface is attached only to the next surface in the flipping chain. In such a configuration, you can call EnumAttachedSurfaces on each successive surface to walk the entire flipping chain.

This method differs from its counterparts in previous interface versions in that it accepts a pointer to an EnumSurfacesCallback2 function, rather than an EnumSurfacesCallback function.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::EnumOverlayZOrders

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

HRESULT EnumOverlayZOrders(
  DWORD dwFlags,
  LPVOID lpContext,
  LPDDENUMSURFACESCALLBACK2 lpfnCallback
);

参数

dwFlags
下列标志之一：
DDENUMOVERLAYZ_BACKTOFRONT
从后往前列举覆盖页面。
DDENUMOVERLAYZ_FRONTTOBACK
从前往后列举覆盖页面。
lpContext
一个用户定义的结构的地址，每列举出一个覆盖页面的时候，它将被传递给列举的回调函数。
lpfnCallback
EnumSurfacesCallback2 回调函数的地址，每列举出一个页面的时候，这个函数将被调用。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

This method differs from its counterparts in previous interface versions in that it accepts a pointer to an EnumSurfacesCallback2 function, rather than an EnumSurfacesCallback function.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::Flip

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

HRESULT Flip(
  LPDIRECTDRAWSURFACE4 lpDDSurfaceTargetOverride,
  DWORD dwFlags
);

参数

lpDDSurfaceTargetOverride
换页链中另一个页面的 IDirectDrawSurface4 接口的地址，代表换页操作的目标页面。这个页面必须是换页链中的一员。该参数缺省值是 NULL， 在这种情况下， DirectDraw 从换页链中按照前后隶属关系依次换页。
dwFlags
换页的标志选项：
DDFLIP_EVEN
仅当在覆盖页面上显示视频图象时才能使用。新的页面上包含从视频信号的奇数行(even field)上传来的数据。该参数不能与 DDFLIP_ODD 标志同时使用。
DDFLIP_INTERVAL2
DDFLIP_INTERVAL3
DDFLIP_INTERVAL4
These flags indicate how many vertical retraces to wait between each flip. The default is 1. DirectDraw will return DERR_WASSTILLDRAWING for each surface involved in the flip until the specified number of vertical retraces has occurred. If DDFLIP_INTERVAL2 is set, DirectDraw will flip on every second vertical sync; if DDFLIP_INTERVAL3, on every third sync; and if DDFLIP_INTERVAL4, on every fourth sync.

These flags are effective only if DDCAPS2_FLIPINTERVAL is set in the DDCAPS structure returned for the device.

DDFLIP_NOVSYNC
Causes DirectDraw to perform the physical flip as close as possible to the next scan line. Subsequent operations involving the two flipped surfaces will not check to see if the physical flip has finished梩hat is, they will not return DDERR_WASSTILLDRAWING for that reason (but may for other reasons). This allows an application to perform flips at a higher frequency than the monitor refresh rate, but may introduce visible artifacts.

If DDCAPS2_FLIPNOVSYNC is not set in the DDCAPS structure returned for the device, DDFLIP_NOVSYNC has no effect.

DDFLIP_ODD
仅当在覆盖页面上显示视频图象时才能使用。新的页面上包含从视频信号的偶数行(odd field)上传来的数据。该参数不能与DDFLIP_EVEN标志同时使用。
DDFLIP_WAIT
典型的，如果不使用该标志，因为显示硬件不在状态（因为上一次的换页尚未完成或其它原因）而导致换页操作没能准备好，函数将立即返回 DDERR_WASSTILLDRAWING，并且不能完成换页操作。如果设置了该 DDFLIP_WAIT 标志，可以使该函数在收到从 HAL 传来的 DDERR_WASSTILLDRAWING 的消息后继续重试换页操作，除非换页已经成功的完成，或是发生了另一个错误例如 DDERR_SURFACEBUSY，否则该函数将不会返回。

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOFLIPHW
DDERR_NOTFLIPPABLE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

备注

这个函数只能被具有 DDSCAPS_FLIP 和 DDSCAPS_FRONTBUFFER 标志的页面调用。先前与前台缓冲区(front buffer)相关联的页面内存在换页后与后台缓冲区(back buffer)相关联。

lpDDSurfaceTargetOverride 参数在很少情况下(当不应该是后台缓存成为前台缓存时)才被使用，通常，该参数为NULL。

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

要得到更多的信息，请参阅换页页面。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetFlipStatus


IDirectDrawSurface4::FreePrivateData

The IDirectDrawSurface4::FreePrivateData method frees the specified private data associated with this surface.

HRESULT FreePrivateData(
  REFGUID guidTag,
);

参数

guidTag
Reference to (C++) or address of (C) the globally unique identifier that identifies the private data to be freed.

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND

备注

DirectDraw calls this method automatically when a surface is released.

If the private data was set by using the DDSPD_IUNKNOWNPOINTER flag, this method calls the IUnknown::Release method on the associated interface.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetPrivateData, IDirectDrawSurface4::SetPrivateData


IDirectDrawSurface4::GetAttachedSurface

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

HRESULT GetAttachedSurface(
  LPDDSCAPS2 lpDDSCaps,
  LPDIRECTDRAWSURFACE4 FAR *lplpDDAttachedSurface
);

参数

lpDDSCaps
DDSCAPS2 结构的地址，包含了页面的硬件特性描述。
lplpDDAttachedSurface
返回一个指向 IDirectDrawSurface4 接口的指针地址。该页面符合 lpDDSCaps 参数所提供的页面特性描述，并且隶属于该页面。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTFOUND
DDERR_SURFACELOST

备注

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::GetBltStatus

该函数获得位块传送器的状态。

HRESULT GetBltStatus(
  DWORD dwFlags
);

参数

dwFlags
下列标志之一：
DDGBS_CANBLT
询问对该页面的位块传送操作是否能立即开始，如果返回 DD_OK，表示位块传送器准备就绪。
DDGBS_ISBLTDONE
询问位块操作是否已经完成，如果返回 DD_OK，表明对该页面的位块操作已经完成。

返回值

If the method succeeds, that means a blitter is present, the return value is DD_OK.

If the method fails, the return value is DDERR_WASSTILLDRAWING if the blitter is busy, DDERR_NOBLTHW if there is no blitter, or one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOBLTHW
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::GetCaps

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

HRESULT GetCaps(
  LPDDSCAPS2 lpDDSCaps
);

参数

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

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

This method differs from its counterpart in the IDirectDrawSurface3 interface in that it accepts a pointer to a DDSCAPS2 structure rather than the legacy DDSCAPS structure.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::GetClipper

The IDirectDrawSurface4::GetClipper method retrieves the DirectDrawClipper object associated with this surface and increments the reference count of the returned clipper.

HRESULT GetClipper(
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper
);

参数

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

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCLIPPERATTACHED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::SetClipper


IDirectDrawSurface4::GetColorKey

该函数获得 DirectDrawSurface 对象的关键色(color key)的值。

HRESULT GetColorKey(
  DWORD dwFlags,
  LPDDCOLORKEY lpDDColorKey
);

参数

dwFlags
指定要获得哪种关键色。
DDCKEY_DESTBLT
Set if the structure specifies a color key or color space to be used as a destination color key for blit operations.
DDCKEY_DESTOVERLAY
Set if the structure specifies a color key or color space to be used as a destination color key for overlay operations.
DDCKEY_SRCBLT
Set if the structure specifies a color key or color space to be used as a source color key for blit operations.
DDCKEY_SRCOVERLAY
Set if the structure specifies a color key or color space to be used as a source color key for overlay operations.
lpDDColorKey
一个 DDCOLORKEY 结构的地址，将被填充 DirectDrawSurface 对象的关键色的当前值。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOCOLORKEY
DDERR_NOCOLORKEYHW
DDERR_SURFACELOST
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::SetColorKey


IDirectDrawSurface4::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

备注

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::Lock


IDirectDrawSurface4::GetDDInterface

该函数获得创建该页面的 DirectDraw 对象的接口。

HRESULT GetDDInterface(
  LPVOID FAR *lplpDD
);

参数

lplpDD
如果调用成功，将返回一个指向合法的 DirectDraw 对象的指针的地址。 Cast this pointer to an IUnknown interface pointer, then query for the desired DirectDraw interface.

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

This method was not implemented in the IDirectDraw interface.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::GetFlipStatus

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

HRESULT GetFlipStatus(
  DWORD dwFlags
);

参数

dwFlags
下列值之一：
DDGFS_CANFLIP
询问该页面是否能立即进行换页操作，如果可以的话，函数将返回 DD_OK。
DDGFS_ISFLIPDONE
询问换页操作是否已经结束，如果是的话，函数将返回 DD_OK。

返回值

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

If the method fails, the return value is DDERR_WASSTILLDRAWING if the surface has not finished its flipping process, or one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_SURFACEBUSY
DDERR_SURFACELOST
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::Flip


IDirectDrawSurface4::GetOverlayPosition

假设存在一个可见的，活跃的覆盖页面(overlay surface)（设置了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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::SetOverlayPosition, IDirectDrawSurface4::UpdateOverlay


IDirectDrawSurface4::GetPalette

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

HRESULT GetPalette(
  LPDIRECTDRAWPALETTE FAR *lplpDDPalette
);

参数

lplpDDPalette
获得一个与该页面相关联的DirectDrawPalette对象的 IDirectDrawPalette 接口的指针的地址。

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_NOPALETTEATTACHED
DDERR_SURFACELOST
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::SetPalette


IDirectDrawSurface4::GetPixelFormat

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

HRESULT GetPixelFormat(
  LPDDPIXELFORMAT lpDDPixelFormat
);

参数

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

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::GetPrivateData

The IDirectDrawSurface4::GetPrivateData method copies the private data associated with the surface to a provided buffer.

HRESULT GetPrivateData(
  REFGUID guidTag,
  LPVOID  lpBuffer,
  LPDWORD lpcbBufferSize
);

参数

guidTag
Reference to (C++) or address of (C) the globally unique identifier that identifies the private data to be retrieved.
lpBuffer
Address of a previously allocated buffer that will be filled with the requested private data if the call succeeds. The application calling this method is responsible for allocating and releasing this buffer.
lpcbBufferSize
Size of the buffer at lpBuffer, in bytes. If this value is less than the actual size of the private data (such as zero), the method sets this parameter to the required buffer size, and the method returns DDERR_MOREDATA.

返回值

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

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

DDERR_EXPIRED
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA
DDERR_NOTFOUND
DDERR_OUTOFMEMORY

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::SetPrivateData, IDirectDrawSurface4::FreePrivateData


IDirectDrawSurface4::GetSurfaceDesc

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

HRESULT GetSurfaceDesc(
  LPDDSURFACEDESC2 lpDDSurfaceDesc
);

参数

lpDDSurfaceDesc
DDSURFACEDESC2 结构的地址，将被填充页面当前的描述信息。 You need only initialize this structure's dwSize member to the size, in bytes, of the structure prior to the call; no other preparation is required.

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

DDSURFACEDESC, DDSURFACEDESC2


IDirectDrawSurface4::GetUniquenessValue

The IDirectDrawSurface4::GetUniquenessValue method retrieves the current uniqueness value for this surface.

HRESULT GetUniquenessValue(
  LPDWORD lpValue,
);

参数

lpValue
Address of a variable that will be filled with the surface's current uniqueness value, if the call succeeds.

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

The only defined uniqueness value is 0, to indicate that the surface is likely to be changing beyond DirectDraw's control. Other uniqueness values are only significant if they differ from a previously cached uniqueness value. If the current value is different than a cached value, then the contents of the surface have changed.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::ChangeUniquenessValue, Surface Uniqueness Values


IDirectDrawSurface4::Initialize

该函数初始化一个 DirectDrawSurface 对象。

HRESULT Initialize(
  LPDIRECTDRAW lpDD,
  LPDDSURFACEDESC2 lpDDSurfaceDesc
);

参数

lpDD
一个 DirectDraw 结构的地址，代表 DirectDraw 对象。
lpDDSurfaceDesc
DDSURFACEDESC2 结构的地址，将被填充关于页面的相关细节的信息。

返回值

该函数返回 DDERR_ALREADYINITIALIZED。

备注

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IUnknown::AddRef, IUnknown::QueryInterface, IUnknown::Release


IDirectDrawSurface4::IsLost

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

HRESULT IsLost();

参数

无。

返回值

If the method succeeds, the return value is DD_OK because the memory has not been freed.

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

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

备注

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::Restore, Losing and Restoring Surfaces


IDirectDrawSurface4::Lock

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

HRESULT Lock(
  LPRECT lpDestRect,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  DWORD dwFlags,
  HANDLE hEvent
);

参数

lpDestRect
一个 RECT 结构的地址，指定将被锁定的页面区域。如果该参数为 NULL，整个页面将被锁定。
lpDDSurfaceDesc
一个 DDSURFACEDESC2 结构的地址，将被填充页面的相关信息。
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

备注

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

在获得了页面内存指针之后，你就可以访问页面内存，直到调用了相应的 IDirectDrawSurface4::Unlock 函数。当页面被解锁，指向页面内存的指针将成为非法。

绝对不要调用 DirectDraw 的 blit 函数从一个页面锁定的区域进行位块传送操作，否则，将返回 DDERR_SURFACEBUSY 或 DDERR_LOCKEDSURFACES 错误。除此之外，当使用一个锁定的显存中的页面时，GDI 的 blit 函数也将失败。

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::Unlock, IDirectDrawSurface4::GetDC, IDirectDrawSurface4::ReleaseDC


IDirectDrawSurface4::PageLock

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

HRESULT PageLock(
  DWORD dwFlags
);

参数

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

返回值

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

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

DDERR_CANTPAGELOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

备注

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

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

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

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::PageUnlock


IDirectDrawSurface4::PageUnlock

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

HRESULT PageUnlock(
  DWORD dwFlags
);

参数

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

返回值

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

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

DDERR_CANTPAGEUNLOCK
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTPAGELOCKED
DDERR_SURFACELOST

备注

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

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::PageLock


IDirectDrawSurface4::ReleaseDC

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

HRESULT ReleaseDC(
  HDC hDC
);

参数

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

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST
DDERR_UNSUPPORTED

备注

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetDC


IDirectDrawSurface4::Restore

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

HRESULT Restore();

参数

None.

返回值

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

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

DDERR_GENERIC
DDERR_IMPLICITLYCREATED
DDERR_INCOMPATIBLEPRIMARY
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOEXCLUSIVEMODE
DDERR_OUTOFMEMORY
DDERR_UNSUPPORTED
DDERR_WRONGMODE

备注

该函数恢复曾分配给一个页面的内存，但不能恢复内存的内容。重建丢失的图象以恢复内存内容应该由应用程序来负责。 要得到更多的信息，请参阅丢失和恢复页面。

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::IsLost


IDirectDrawSurface4::SetClipper

该函数将一个裁剪器对象隶属到页面对象上，或使之分离。

HRESULT SetClipper(
  LPDIRECTDRAWCLIPPER lpDDClipper
);

参数

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

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOCLIPPERATTACHED

备注

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetClipper


IDirectDrawSurface4::SetColorKey

该函数设置 DirectDrawSurface 对象的关键色(color key)的值，如果硬件支持关键色的话。

HRESULT SetColorKey(
  DWORD dwFlags,
  LPDDCOLORKEY lpDDColorKey
);

参数

dwFlags
指定要设置哪种关键色。
DDCKEY_COLORSPACE
如果关键色结构中包含了一个色彩空间(color space)，设置此标志。如果关键色结构中只包含了单个关键色，则不要设置此标志。
DDCKEY_DESTBLT
指定该关键色为位块传送操作中的目标关键色(destination color key)。
DDCKEY_DESTOVERLAY
指定该关键色为覆盖操作中的目标关键色。
DDCKEY_SRCBLT
指定该关键色为位块传送操作中的源关键色(source color key)。
DDCKEY_SRCOVERLAY
指定该关键色为覆盖操作中的源关键色。
lpDDColorKey
一个 DDCOLORKEY 结构的地址，包含了 DirectDrawSurface 对象的新的关键色的值。这个值可以为 NULL 来去除先前设置的关键色。

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDSURFACETYPE
DDERR_NOOVERLAYHW
DDERR_NOTAOVERLAYSURFACE
DDERR_SURFACELOST
DDERR_UNSUPPORTED
DDERR_WASSTILLDRAWING

备注

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetColorKey


IDirectDrawSurface4::SetOverlayPosition

该函数改变一个覆盖页面(overlay surface)的显示坐标。

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetOverlayPosition, IDirectDrawSurface4::UpdateOverlay


IDirectDrawSurface4::SetPalette

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

HRESULT SetPalette(
  LPDIRECTDRAWPALETTE lpDDPalette
);

参数

lpDDPalette
将隶属到页面上的 DirectDrawPalette 对象的 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

备注

如果对同一页面和同一调色板多次调用该函数，调色板的引用记录只会递增一次，以后的调用不会影响到调色板的引用记录。 If you pass NULL as the lpDDPalette parameter, the palette is removed from the surface, and the palette's reference count is decremented. If you do not delete the palette, the surface will automatically release its reference to the palette when the surface itself is released. According to COM rules, your application is responsible for releasing any references it holds to the palette when the object is no longer needed.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetPalette, IDirectDraw4::CreatePalette


IDirectDrawSurface4::SetPrivateData

The IDirectDrawSurface4::SetPrivateData method associates data with the surface that is intended for use by the application, not by DirectDraw. Data is passed by value, and multiple sets of data can be associated with a single surface.

HRESULT SetPrivateData(
  REFGUID guidTag,
  LPVOID  lpData,
  DWORD   cbSize,
  DWORD   dwFlags
);

参数

guidTag
Reference to (C++) or address of (C) the globally unique identifier that identifies the private data to be set.
lpData
Address of a buffer that contains the data to be associated with the surface.
cbSize
Size of the buffer at lpData, in bytes.
dwFlags
Flags describing the type of data being passed, or requesting that the data be invalidated when the surface changes. The following flags are defined:
(none)
If no flags are specified, DirectDraw allocates memory to hold the data within the buffer, and copies the data into the new buffer. The buffer allocated by DirectDraw will automatically be freed as appropriate.
DDSPD_IUNKNOWNPOINTER
The data at lpData is a pointer to an IUnknown interface. DirectDraw automatically calls the IUnknown::AddRef method of this interface. When this data is no longer needed, DirectDraw automatically calls the IUnknown::Release method of this interface.
DDSPD_VOLATILE
The buffer at lpData is only valid while the surface remains unchanged from its current state. If the surface's contents change, subsequent calls to the IDirectDrawSurface4::GetPrivateData method will return DDERR_EXPIRED.

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

备注

DirectDraw does not manage the memory at lpData. If this buffer was dynamically allocated, it is the caller's responsibility to free the memory.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::GetPrivateData, IDirectDrawSurface4::FreePrivateData


IDirectDrawSurface4::SetSurfaceDesc

该函数设置页面的特性描述。

HRESULT SetSurfaceDesc(
  LPDDSURFACEDESC2 lpddsd2,
  DWORD dwFlags
);

参数

lpddsd2
一个 DDSURFACEDESC2 结构的地址，包含了页面新的特性描述。
dwFlags
该参数尚未使用，只能设为0。

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDPARAMS
DDERR_INVALIDOBJECT
DDERR_SURFACELOST
DDERR_SURFACEBUSY
DDERR_INVALIDSURFACETYPE
DDERR_INVALIDPIXELFORMAT
DDERR_INVALIDCAPS
DDERR_UNSUPPORTED
DDERR_GENERIC

备注

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

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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::Unlock

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

HRESULT Unlock(
  LPRECT lpRect
);

参数

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

返回值

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

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

DDERR_GENERIC
DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_INVALIDRECT
DDERR_NOTLOCKED
DDERR_SURFACELOST

备注

因为对同一个页面多次调用 IDirectDrawSurface4::Lock 函数以锁定不同的区域是可能的， lpRect 中的指针使得 IDirectDrawSurface4::Unlock 函数与相应的 IDirectDrawSurface4::Lock 函数对应上。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::Lock


IDirectDrawSurface4::UpdateOverlay

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

HRESULT UpdateOverlay(
  LPRECT lpSrcRect,
  LPDIRECTDRAWSURFACE4 lpDDDestSurface,
  LPRECT lpDestRect,
  DWORD dwFlags,
  LPDDOVERLAYFX lpDDOverlayFx
);

参数

lpSrcRect
一个 RECT 结构的地址，定义了源页面上作为覆盖区域的x、y、宽度和高度。当隐藏一个覆盖层，或指定整个覆盖页面将被使用（该覆盖页面遵循设备驱动所规定的所有边界和大小的限制），该参数可以是 NULL。
lpDDDestSurface
指向被覆盖页面的 IDirectDrawSurface4 接口的指针的地址。
lpDestRect
一个 RECT 结构的地址，定义了目标页面上作为被覆盖区域的x、y、宽度和高度。当要隐藏覆盖层的时候，该参数可以是 NULL。
dwFlags
DDOVER_ADDDIRTYRECT
Adds a dirty rectangle to an emulated overlay surface.
DDOVER_ALPHADEST
使用像素格式的 alpha 信息，或隶属于目标页面的 alpha 通道(alpha channel)页面，作为该覆盖层的 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
Uses the dwAlphaSrcConst member of the DDOVERLAYFX structure as the source alpha channel for this overlay.
使用DDOVERLAYFX结构的dwAlphaSrcConst成员作为该覆盖层的源alpha通道。
DDOVER_ALPHASRCNEG
指定源页面的透明度随着alpha值的增大而增大（0为不透明）。
DDOVER_ALPHASRCSURFACEOVERRIDE
使用 DDOVERLAYFX 结构的 lpDDSAlphaSrc 成员作为该覆盖层的alpha通道源。
DDOVER_AUTOFLIP
每当一个视频端口发出 VSYNC 消息时，自动换页到换页链中的下一个页面。
DDOVER_BOB
Display each field individually of the interlaced video stream without causing any artifacts.
DDOVER_BOBHARDWARE
Indicates that bob operations will be performed using hardware rather than software or emulated. This flag must be used with the DDOVER_BOB flag.
DDOVER_DDFX
使用 lpDDOverlayFx 参数的 覆盖 FX 标志来指定特殊的覆盖效果。
DDOVER_HIDE
关闭此覆盖层。
DDOVER_KEYDEST
使用与目标页面相关联的关键色(color key)。
DDOVER_KEYDESTOVERRIDE
使用 DDOVERLAYFX 结构的 dckDestColorkey 成员作为目标页面关键色。
DDOVER_KEYSRC
使用与源页面相关联的关键色。
DDOVER_KEYSRCOVERRIDE
使用 DDOVERLAYFX 结构的 dckSrcColorkey 成员作为源页面的关键色。
DDOVER_OVERRIDEBOBWEAVE
Indicates that bob/weave decisions should not be overridden by other interfaces.
DDOVER_INTERLEAVED
Indicates that the surface memory is composed of interleaved fields.
DDOVER_SHOW
启用该覆盖层。
lpDDOverlayFx
一个 DDOVERLAYFX 结构的地址，表示要使用的效果。如果没有设置 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

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


IDirectDrawSurface4::UpdateOverlayDisplay

该函数目前尚不能执行。

HRESULT UpdateOverlayDisplay(
  DWORD dwFlags
);

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::AddOverlayDirtyRect


IDirectDrawSurface4::UpdateOverlayZOrder

该函数设置一个覆盖层的Z序。

HRESULT UpdateOverlayZOrder(
  DWORD dwFlags,
  LPDIRECTDRAWSURFACE4 lpDDSReference
);

参数

dwFlags
下列标志之一：
DDOVERZ_INSERTINBACKOF
在覆盖链中，将该覆盖层置于指定的覆盖层之后。
DDOVERZ_INSERTINFRONTOF
将给覆盖层置于指定的覆盖层之前。
DDOVERZ_MOVEBACKWARD
将该覆盖层置后一位。
DDOVERZ_MOVEFORWARD
将该覆盖层置前一位。
DDOVERZ_SENDTOBACK
将该覆盖层置于最底层。
DDOVERZ_SENDTOFRONT
将该覆盖层置于最高层。
lpDDSReference
一个覆盖页面的 IDirectDrawSurface4 接口的地址，作为覆盖链中的参照页面。只有在使用了 DDOVERZ_INSERTINBACKOF 或 DDOVERZ_INSERTINFRONTOF 标志后才需要指定该参数。

返回值

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

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

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_NOTAOVERLAYSURFACE

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawSurface4::EnumOverlayZOrders


IDirectDrawVideoPort

Applications use the methods of the IDirectDrawVideoPort interface to channel live video data from a hardware video port to a DirectDraw surface. This section is a reference to the methods of this interface. For a conceptual overview, see Video Ports.

The methods of the IDirectDrawVideoPort interface can be organized into the following groups:

Color controls | GetColorControls
 | SetColorControls
Fields and Signals | GetFieldPolarity
 | GetVideoSignalStatus
Flipping | Flip
 | SetTargetSurface
Formats | GetInputFormats
 | GetOutputFormats
Timing and Synchronization | GetVideoLine
 | WaitForSync
Video control | StartVideo
 | StopVideo
 | UpdateVideo
Zoom factors | GetBandwidthInfo

The IDirectDrawVideoPort interface, like all COM interfaces, inherits the IUnknown interface methods. The IUnknown interface supports the following three methods:

IUnknown | AddRef
 | QueryInterface
 | Release

You can use the LPDIRECTDRAWVIDEOPORT data type to declare a variable that contains a pointer to an IDirectDrawVideoPort interface. The Dvp.h header file declares the LPDIRECTDRAWVIDEOPORT with the following code:

typedef struct IDirectDrawVideoPort    FAR *LPDIRECTDRAWVIDEOPORT;

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::Flip

The IDirectDrawVideoPort::Flip method instructs the DirectDrawVideoPort object to write the next frame of video to a new surface.

HRESULT Flip(
  LPDIRECTDRAWSURFACE lpDDSurface,
  DWORD dwFlags
);

参数

lpDDSurface
Address of the IDirectDrawSurface interface for the surface that will receive the next frame of video. Setting this parameter to NULL causes DirectDraw to cycle through surfaces in the flipping chain in the order they were attached.
dwFlags
Flip options flags. This parameter can be one of the following values:
DDVPFLIP_VIDEO
The specified surface is to receive the normal video data.
DDVPFLIP_VBI
The specified surface is to receive only the data within the vertical blanking interval.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

This method can be used to prevent tearing. Calls to IDirectDrawVideoPort::Flip are asynchronous梩he actual flip operation will always be synchronized with the vertical blank of the video signal.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::GetBandwidthInfo

The IDirectDrawVideoPort::GetBandwidthInfo method retrieves the minimum required overlay zoom factors and device limitations of a video port that uses the provided output pixel format.

HRESULT GetBandwidthInfo(
  LPDDPIXELFORMAT lpddpfFormat,
  DWORD dwWidth,
  DWORD dwHeight,
  DWORD dwFlags,
  LPDDVIDEOPORTBANDWIDTH lpBandwidth
);

参数

lpddpfFormat
Address of a DDPIXELFORMAT structure that describes the output pixel format for which bandwidth information will be retrieved.
dwWidth and dwHeight
Dimensions of an overlay or video data. These interpretation of these parameters depends on the value specified in the dwFlags parameter.
dwFlags
Flags indicating how the method is to interpret the dwWidth and dwHeight parameters. This parameter can be one of the following values:
DDVPB_OVERLAY
The dwWidth and dwHeight parameters indicate the size of the source overlay surface. Use this flag when the video port is dependent on the overlay source size.
DDVPB_TYPE
The dwWidth and dwHeight parameters are not set. The method will retrieve the device's dependency type in the dwCaps member of the associated DDVIDEOPORTBANDWIDTH structure. Use this flag when you call this method the first time.
DDVPB_VIDEOPORT
The dwWidth and dwHeight parameters indicate the prescale size of the video data that the video port writes to the frame buffer. Use this flag when the video port is dependent on the overlay zoom factor.
lpBandwidth
Address of a DDVIDEOPORTBANDWIDTH structure that will be filled with the retrieved bandwidth and device dependency information.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

备注

This method will usually be called twice. When you make the first call, specify the DDVPB_TYPE flag in the dwFlags parameter to retrieve information about the device's overlay dependency type. Subsequent calls using the DDVPB_VIDEOPORT or DDVPB_OVERLAY flags must be interpreted considering the device's dependency type.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::GetColorControls

The IDirectDrawVideoPort::GetColorControls method returns the current color control settings associated with the video port.

HRESULT GetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

参数

lpColorControl
Address of a DDCOLORCONTROL structure that will be filled with the current settings of the video port's color control.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

备注

The dwFlags member of the DDCOLORCONTROL structure indicate which of the color control options are supported.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::GetFieldPolarity

The IDirectDrawVideoPort::GetFieldPolarity method retrieves the polarity of a video field.

HRESULT GetFieldPolarity(
  LPBOOL lpbFieldPolarity
);

参数

lpbFieldPolarity
Address of a variable that will be set to indicate the current field polarity. This value is set to TRUE if the current video field is the even field of an interlaced video signal and FALSE otherwise.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VIDEONOTACTIVE

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::GetInputFormats

The IDirectDrawVideoPort::GetInputFormats method retrieves the input formats supported by the DirectDrawVideoPort object.

HRESULT GetInputFormats(
  LPDWORD lpNumFormats,
  LPDDPIXELFORMAT lpFormats,
  DWORD dwFlags
);

参数

lpNumFormats
Address of a variable containing the number of entries that the array at lpFormats can hold. If this number is less than the total number of codes, the method fills the array with as many codes as will fit, sets the value at lpNumFormats to indicate the total number of codes, and returns DDERR_MOREDATA.
lpFormats
Address of an array of DDPIXELFORMAT structures that will be filled in with the input formats supported by this DirectDrawVideoPort object. If this parameter is NULL, the method sets lpNumFormats to the number of supported formats and then returns DD_OK.
dwFlags
Flags specifying the part of the video signal for which formats will be enumerated. This parameter can be one of the following values:
DDVPFORMAT_VIDEO
Returns formats for the video data.
DDVPFORMAT_VBI
Returns formats for the VBI data.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

备注

This method can also be used to return the number of formats supported. To do this, set the lpFormats parameter to NULL. When the method returns, the variable at lpNumFormats contains the total number of supported input formats.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::GetOutputFormats

The IDirectDrawVideoPort::GetOutputFormats method retrieves a list of output formats that the DirectDrawVideoPort object supports for a specified input format.

HRESULT GetOutputFormats(
  LPDDPIXELFORMAT lpInputFormat,
  LPDWORD lpNumFormats,
  LPDDPIXELFORMAT lpFormats,
  DWORD dwFlags
);

参数

lpInputFormat
Address of a DDPIXELFORMAT structure that describes the input format for which conversion information is requested.
lpNumFormats
Address of a variable containing the number of entries that the array at lpFromats can hold. If this number is less than the total number of codes, the method fills the array with as many codes as will fit, sets the value at lpNumFormats to indicate the total number of codes, and returns DDERR_MOREDATA.
lpFormats
Address of an array of DDPIXELFORMAT structures that will be filled in with the output formats supported by this DirectDrawVideoPort object. If this parameter is NULL, the method sets lpNumFormats to the number of supported formats and then returns DD_OK.
dwFlags
Flags specifying the part of the video signal for which formats will be enumerated. This parameter can be one of the following values:
DDVPFORMAT_VIDEO
Returns formats for the video data.
DDVPFORMAT_VBI
Returns formats for the VBI data.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_MOREDATA

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::GetVideoLine

The IDirectDrawVideoPort::GetVideoLine method retrieves the current line of video being written to the frame buffer.

HRESULT GetVideoLine(
  LPDWORD lpdwLine
);

参数

lpdwLine
Address of a variable that will be filled with a value indicating the video line currently being written to the frame buffer.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VERTICALBLANKINPROGRESS
DDERR_VIDEONOTACTIVE

备注

The value this method retrieves reflects the true video line being written, relative to the field height, before any prescaling occurs.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::GetVideoSignalStatus

The IDirectDrawVideoPort::GetVideoSignalStatus method retrieves the status of the video signal currently being presented to the video port.

HRESULT GetVideoSignalStatus(
  LPDWORD lpdwStatus
);

参数

lpdwStatus
Address of a variable that will contain a return code indicating the quality of the video signal at the video port. The value will be set to one of the following codes:
DDVPSQ_NOSIGNAL
No video signal is present at the video port.
DDVPSQ_SIGNALOK
A valid video signal is present at the video port.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::SetColorControls

The IDirectDrawVideoPort::SetColorControls method sets the color control settings associated with the video port.

HRESULT SetColorControls(
  LPDDCOLORCONTROL lpColorControl
);

参数

lpColorControl
Address of a DDCOLORCONTROL structure containing the new color control settings that will be applied to the video port.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


IDirectDrawVideoPort::SetTargetSurface

The IDirectDrawVideoPort::SetTargetSurface method sets the DirectDraw surface object that will receive the stream of live video data and/or the vertical blank interval data.

HRESULT SetTargetSurface(
  LPDIRECTDRAWSURFACE lpDDSurface,
  DWORD dwFlags
);

参数

lpDDSurface
Address of the DirectDrawSurface object that will receive the video data.
dwFlags
Value specifying the type of target surface.
DDVPTARGET_VIDEO
The specified surface should receive the normal video data and vertical interval data unless a separate surface was attached for this purpose.
DDVPTARGET_VBI
The specified surface should receive the data within the vertical blanking interval.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawVideoPort::StartVideo, IDirectDrawVideoPort::StopVideo, IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::StartVideo

The IDirectDrawVideoPort::StartVideo method enables the hardware video port and starts the flow of video data into the currently specified surface.

HRESULT StartVideo(
  LPDDVIDEOPORTINFO lpVideoInfo
);

参数

lpVideoInfo
Address of a pointer to a DDVIDEOPORTINFO structure.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_SURFACELOST

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawVideoPort::SetTargetSurface, IDirectDrawVideoPort::StopVideo, IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::StopVideo

The IDirectDrawVideoPort::StopVideo method stops the flow of video port data into the frame buffer.

HRESULT StopVideo();

参数

None.

返回值

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

If the method fails, the return value is DDERR_INVALIDOBJECT.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawVideoPort::SetTargetSurface, IIDirectDrawVideoPort::StartVideo, IDirectDrawVideoPort::UpdateVideo


IDirectDrawVideoPort::UpdateVideo

The IDirectDrawVideoPort::UpdateVideo method updates parameters that govern the flow of video data from the video port to the DirectDrawSurface object.

HRESULT UpdateVideo(
  LPDDVIDEOPORTINFO lpVideoInfo
);

参数

lpVideoInfo
Address of a DDVIDEOPORTINFO structure that describes the video transfer parameters.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.

参阅

IDirectDrawVideoPort::SetTargetSurface, IDirectDrawVideoPort::StartVideo, IDirectDrawVideoPort::StopVideo


IDirectDrawVideoPort::WaitForSync

The IDirectDrawVideoPort::WaitForSync method waits for VSYNC or until a given scan line is being drawn.

HRESULT WaitForSync(
  DWORD dwFlags,
  DWORD dwLine,
  DWORD dwTimeout
);

参数

dwFlags
Flag specifying how the method will wait for the video VSYNC or the specified line number.
DDVPWAIT_BEGIN
Return at the start of the vertical blanking interval.
DDVPWAIT_END
Return at the end of the vertical blanking interval.
DDVPWAIT_LINE
Return when the video counter either reaches or passes the line specified by the dwLine parameter.
dwLine
The video line determining when the method should return, relative to the field height, before prescaling. This parameter is ignored if the dwFlags parameter is set to DDVPWAIT_BEGIN or DDVPWAIT_END.
dwTimeout
Amount of time, in milliseconds, that the method will wait for the next video vertical blank before timing out. If this parameter is 0, the method waits 3 times the value specified in the dwMicrosecondsPerField member of the DDVIDEOPORTDESC.

返回值

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

If the method fails, the return value may be one of the following error values:

DDERR_INVALIDOBJECT
DDERR_INVALIDPARAMS
DDERR_UNSUPPORTED
DDERR_VIDEONOTACTIVE
DDERR_WASSTILLDRAWING

备注

This method helps the caller synchronize with the video vertical blank interval or with an arbitrary line of video data. The method blocks the calling thread until either the video VSYNC occurs or when the video line counter matches the specified line number.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.
Import Library: Use ddraw.lib.


Functions

函数(Functions)

这部分包含了以下 DirectDraw 全局函数的信息：

  • DirectDrawCreate
  • DirectDrawCreateClipper
  • DirectDrawEnumerate
  • DirectDrawEnumerateEx


DirectDrawCreate

该函数创建一个 DirectDraw 对象的实例。

HRESULT WINAPI DirectDrawCreate(
  GUID FAR *lpGUID,
  LPDIRECTDRAW FAR *lplpDD,
  IUnknown FAR *pUnkOuter
);

参数

lpGUID
全局唯一标志符（GUID）的地址，代表了要创建的驱动类型。该参数可以是NULL，代表当前所使用的显示驱动；你也可以指定其为下列值之一，以限制当前显示驱动的行为能力，为调试所用：
DDCREATE_EMULATIONONLY
该 DirectDraw 对象只使用软件仿真的方式实现所有的特性；它将不会从硬件加速中获得任何好处。
DDCREATE_HARDWAREONLY
该 DirectDraw 对象只使用硬件支持的加速特性；对于那些硬件不支持的特性，也绝不会使用软件仿真的方式来完成，而且将返回 DDERR_UNSUPPORTED 的错误值。
lplpDD
如果函数调用成功，该参数将为指向一合法的 DirectDraw 对象的 IDirectDraw 接口的指针的地址。
pUnkOuter
该参数将允许与今后的COM集合特性相兼容。目前，只要这个参数不是NULL，该函数将返回一个错误。

返回值

If the function succeeds, the return value is DD_OK.

If the function fails, the return value may be one of the following error values:

DDERR_DIRECTDRAWALREADYCREATED
DDERR_GENERIC
DDERR_INVALIDDIRECTDRAWGUID
DDERR_INVALIDPARAMS
DDERR_NODIRECTDRAWHW
DDERR_OUTOFMEMORY

备注

该函数试图初始化一个 DirectDraw 对象，如果成功则返回一个指向该对象的指针。

在多显示器的系统上，当设置协作模式为普通，并给 lpGUID 指定了 NULL 将导致 DirectDraw 对象运行于仿真的模式。要在这些系统上获得硬件加速特性，你必须指定设备的 GUID。 要得到更多的信息，请参阅多显示器系统上的设备和加速。

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.


DirectDrawCreateClipper

该函数创建一个与任何 DirectDraw 对象都无关的 DirectDrawClipper 对象的实例。

HRESULT WINAPI DirectDrawCreateClipper(
  DWORD dwFlags,
  LPDIRECTDRAWCLIPPER FAR *lplpDDClipper,
  IUnknown FAR *pUnkOuter
);

参数

dwFlags
该参数尚未使用，只能设为0。
lplpDDClipper
一个指向新的 DirectDrawClipper 对象的指针的地址。
pUnkOuter
该参数将允许与今后的 COM 集合特性相兼容。目前，只要这个参数不是 NULL， 该函数将返回一个错误。

返回值

If the function succeeds, the return value is DD_OK.

If the function fails, the return value may be one of the following error values:

DDERR_INVALIDPARAMS
DDERR_OUTOFMEMORY

备注

该函数可以在所有 DirectDraw 对象被创建之前调用。因为这些 DirectDrawClipper 对象不被任何 DirectDraw 对象所拥有，所以在应用程序对象被释放的时候，它们不会自动的被释放。应用程序应该在结束前明确的释放这些 DirectDrawClipper 对象。

要创建一个被某特定的 DirectDraw 对象所拥有的 DirectDrawClipper 对象，应使用 IDirectDraw4::CreateClipper 函数。

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

IDirectDraw4::CreateClipper


DirectDrawEnumerate

This function is superseded by the DirectDrawEnumerateEx function.

该函数列举出主要的 DirectDraw 显示设备或一个非显示设备（比如一个不带2-D特性的3-D加速卡）。 NULL 入口通常指定了与 GDI 共享的主显示设备。

HRESULT WINAPI DirectDrawEnumerate(
  LPDDENUMCALLBACK lpCallback,
  LPVOID lpContext
);

参数

lpCallback
DDEnumCallback 函数的地址，每列举出一个模式的时候，将执行该函数，并且传递一个DirectDraw HAL的描述。
lpContext
一个应用程序定义的结构的地址，用来传递给列举的回调函数。.

返回值

If the function succeeds, the return value is DD_OK.

If the function fails, the return value is DDERR_INVALIDPARAMS.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.

参阅

DirectDrawEnumerateEx


DirectDrawEnumerateEx

该函数列举已安装的所有 DirectDraw 设备。 NULL 入口通常指定与 GDI 共享的主显示设备。

HRESULT WINAPI DirectDrawEnumerateEx(
  LPDDENUMCALLBACKEX lpCallback,
  LPVOID lpContext,
  DWORD  dwFlags
);

参数

lpCallback
DDEnumCallbackEx 函数的地址，每列举出一个模式的时候，将执行该函数，并且传递一个DirectDraw HAL的描述。
lpContext
一个应用程序定义的结构的地址，用来传递给列举的回调函数。
dwFlags
指定列举的范围。该参数可以是0或下列标志的组合。如果值为0，该函数将只列举出主显示设备和一个已安装的非显示设备。
DDENUM_ATTACHEDSECONDARYDEVICES
该函数将列举出主设备，和任何隶属于桌面的显示设备。
DDENUM_DETACHEDSECONDARYDEVICES
该函数将列举出主设备，和任何不隶属于桌面的显示设备。
DDENUM_NONDISPLAYDEVICES
该函数将列举出非显示设备，比如不带2-D特性的3-D加速卡。

返回值

If the function succeeds, the return value is DD_OK.

If the function fails, the return value is DDERR_INVALIDPARAMS.

备注

在多显示器系统上，该函数列举出多显示设备。要得到更多的信息，请参阅多显示器系统。

对于 Windows 98 该函数只被 DirectX 5.0 或更晚的版本支持，而对于其他操作系统， DirectX 6.0 是必须的。调用GetProcAddress Win32函数（指定"DirectDrawEnumerateExA" (ANSI)或"DirectDrawEnumerateExW" (Unicode) 过程名称字符串）可以从 Ddraw.dll 动态连接库获得 DirectDrawEnumerateEx 函数的地址。如果失败，则表明安装的操作系统的版本不支持多显示器。要得到更多的信息，请参阅在多显示器系统上列举设备。

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 98.
Header: Declared in ddraw.h.
Import Library: Use ddraw.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT.


Callback Functions

This section contains information about the following callback functions used with DirectDraw:

  • DDEnumCallback
  • DDEnumCallbackEx
  • EnumModesCallback
  • EnumModesCallback2
  • EnumSurfacesCallback
  • EnumSurfacesCallback2
  • EnumVideoCallback


DDEnumCallback

The DDEnumCallback function is an application-defined callback function for the DirectDrawEnumerate function.

BOOL WINAPI DDEnumCallback(
  GUID FAR *lpGUID,
  LPSTR  lpDriverDescription,
  LPSTR  lpDriverName,
  LPVOID lpContext
);

参数

lpGUID
Address of the unique identifier of the DirectDraw object.
lpDriverDescription
Address of a string containing the driver description.
lpDriverName
Address of a string containing the driver name.
lpContext
Address of an application-defined structure that will be passed to the callback function each time the function is called.

返回值

The callback function returns non-zero to continue the enumeration.

The callback function returns zero to stop it.

备注

You can use the LPDDENUMCALLBACK data type to declare a variable that can contain a pointer to this callback function.

If UNICODE is defined, the string values will be returned as type LPWSTR rather than LPSTR.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: User-defined.


DDEnumCallbackEx

The DDEnumCallbackEx function is an application-defined callback function for the DirectDrawEnumerateEx function.

BOOL WINAPI DDEnumCallbackEx(
  GUID FAR *lpGUID,
  LPSTR     lpDriverDescription,
  LPSTR     lpDriverName,
  LPVOID    lpContext,
  HMONITOR  hm
);

参数

lpGUID
Address of the unique identifier of the DirectDraw object.
lpDriverDescription
Address of a string containing the driver description.
lpDriverName
Address of a string containing the driver name.
lpContext
Address of an application-defined structure that will be passed to the callback function each time the function is called.
hm
Handle to the monitor associated with the enumerated DirectDraw object. This parameter will be NULL when the enumerated DirectDraw object is for the primary device, a non-display device (such as a 3-D accelerator with no 2-D capabilities), and devices not attached to the desktop.

返回值

The callback function returns non-zero to continue the enumeration.

The callback function returns zero to stop it.

备注

You can use the LPDDENUMCALLBACKEX data type to declare a variable that can contain a pointer to this callback function.

If UNICODE is defined, the string values will be returned as type LPWSTR rather than LPSTR.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 98.
Header: Declared in ddraw.h.
Import Library: User-defined.

参阅

Enumerating Devices on MultiMon Systems, Multiple Monitor Systems


EnumModesCallback

The EnumModesCallback function is an application-defined callback function for the IDirectDraw3::EnumDisplayModes method, and its counterparts in earlier interfaces.

This callback function is superseded by the EnumModesCallback2 function that is used with the IDirectDraw4::EnumDisplayModes method.

HRESULT WINAPI EnumModesCallback(
  LPDDSURFACEDESC lpDDSurfaceDesc,
  LPVOID lpContext
);

参数

lpDDSurfaceDesc
Address of a read-only DDSURFACEDESC structure that provides the monitor frequency and the mode that can be created.
lpContext
Address of an application-defined structure that will be passed to the callback function each time the function is called.

返回值

The callback function returns DDENUMRET_OK to continue the enumeration.

The callback function returns DDENUMRET_CANCEL to stop it.

备注

You can use the LPDDENUMMODESCALLBACK data type to declare a variable that can contain a pointer to this callback function.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: User-defined.


EnumModesCallback2

The EnumModesCallback2 function is an application-defined callback function for the IDirectDraw4::EnumDisplayModes method.

HRESULT WINAPI EnumModesCallback(
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

参数

lpDDSurfaceDesc
Address of a read-only DDSURFACEDESC2 structure that provides the monitor frequency and the mode that can be created.
lpContext
Address of an application-defined structure that will be passed to the callback function each time the function is called.

返回值

The callback function returns DDENUMRET_OK to continue the enumeration.

The callback function returns DDENUMRET_CANCEL to stop it.

备注

You can use the LPDDENUMMODESCALLBACK2 data type to declare a variable that can contain a pointer to this callback function.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: User-defined.


EnumSurfacesCallback

The EnumSurfacesCallback function is an application-defined callback function for the IDirectDraw2::EnumSurfaces, IDirectDrawSurface3::EnumAttachedSurfaces, and IDirectDrawSurface3::EnumOverlayZOrders methods (and the versions from earlier interfaces).

HRESULT WINAPI EnumSurfacesCallback(
  LPDIRECTDRAWSURFACE lpDDSurface,
  LPDDSURFACEDESC lpDDSurfaceDesc,
  LPVOID lpContext
);

参数

lpDDSurface
Address of the IDirectDrawSurface interface for the attached surface.
lpDDSurfaceDesc
Address of a DDSURFACEDESC structure that describes the attached surface.
lpContext
Address of an application-defined structure that will be passed to the callback function each time the function is called.

返回值

The callback function returns DDENUMRET_OK to continue the enumeration.

The callback function returns DDENUMRET_CANCEL to stop it.

备注

You can use the LPDDENUMSURFACESCALLBACK data type to declare a variable that can contain a pointer to this callback function.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: User-defined.


EnumSurfacesCallback2

The EnumSurfacesCallback2 function is an application-defined callback function for the IDirectDrawSurface4::EnumAttachedSurfaces and IDirectDrawSurface4::EnumOverlayZOrders methods.

HRESULT WINAPI EnumSurfacesCallback2(
  LPDIRECTDRAWSURFACE4 lpDDSurface,
  LPDDSURFACEDESC2 lpDDSurfaceDesc,
  LPVOID lpContext
);

参数

lpDDSurface
Address of the IDirectDrawSurface4 interface of the attached surface.
lpDDSurfaceDesc
Address of a DDSURFACEDESC2 structure that describes the attached surface.
lpContext
Address of an application-defined structure that will be passed to the callback function each time the function is called.

返回值

The callback function returns DDENUMRET_OK to continue the enumeration.

The callback function returns DDENUMRET_CANCEL to stop it.

备注

You can use the LPDDENUMSURFACESCALLBACK2 data type to declare a variable that can contain a pointer to this callback function.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: User-defined.


EnumVideoCallback

The EnumVideoCallback function is an application-defined callback procedure for the IDDVideoPortContainer::EnumVideoPorts method.

HRESULT WINAPI EnumVideoCallback(
  LPDDVIDEOPORTCAPS lpDDVideoPortCaps,
  LPVOID lpContext
);

参数

lpDDVideoPortCaps
Pointer to the DDVIDEOPORTCAPS structure that contains the video port information, including the ID and capabilities. This data is read-only.
lpContext
Pointer to a caller-defined structure that is passed to the member every time it is called.

返回值

The callback function returns DDENUMRET_OK to continue the enumeration.

The callback function returns DDENUMRET_CANCEL to stop it.

备注

Video-port related functions cannot be called from inside the EnumVideoCallback function. Attempts to do so will fail, returning DDERR_CURRENTLYNOTAVAIL.

You can use the LPDDENUMVIDEOCALLBACK data type to declare a variable that can contain a pointer to this callback function.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.
Import Library: User-defined.


Structures

This section contains information about the following structures used with DirectDraw:

  • DDBLTBATCH
  • DDBLTFX
  • DDCAPS
  • DDCOLORCONTROL
  • DDCOLORKEY
  • DDDEVICEIDENTIFIER
  • DDGAMMARAMP
  • DDOVERLAYFX
  • DDPIXELFORMAT
  • DDSCAPS
  • DDSCAPS2
  • DDSURFACEDESC
  • DDSURFACEDESC2
  • DDVIDEOPORTBANDWIDTH
  • DDVIDEOPORTCAPS
  • DDVIDEOPORTCONNECT
  • DDVIDEOPORTDESC
  • DDVIDEOPORTINFO
  • DDVIDEOPORTSTATUS

Note The memory for all DirectX structures should be initialized to zero before use. In addition, all structures that contain a dwSize member should set the member to the size of the structure, in bytes, before use. The following example performs these tasks on a common structure, DDCAPS:

DDCAPS ddcaps; // Can't use this yet.

ZeroMemory(&ddcaps, sizeof(DDCAPS));
ddcaps.dwSize = sizeof(DDCAPS);

// Now the structure can be used.
.
.


DDBLTBATCH

The DDBLTBATCH structure passes blit operations to the IDirectDrawSurface4::BltBatch method.

typedef struct _DDBLTBATCH{
    LPRECT              lprDest;
    LPDIRECTDRAWSURFACE lpDDSSrc;
    LPRECT              lprSrc;
    DWORD               dwFlags;
    LPDDBLTFX           lpDDBltFx;
} DDBLTBATCH,FAR *LPDDBLTBATCH;

Members

lprDest
Address of a RECT structure that defines the destination for the blit.
lpDDSSrc
Address of a DirectDrawSurface object that will be the source of the blit.
lprSrc
Address of a RECT structure that defines the source rectangle of the blit.
dwFlags
Optional control flags.
DDBLT_ALPHADEST
Uses either the alpha information in pixel format or the alpha channel surface attached to the destination surface as the alpha channel for this blit.
DDBLT_ALPHADESTCONSTOVERRIDE
Uses the dwAlphaDestConst member of the DDBLTFX structure as the alpha channel for the destination surface for this blit.
DDBLT_ALPHADESTNEG
Indicates that the destination surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHADESTSURFACEOVERRIDE
Uses the lpDDSAlphaDest member of the DDBLTFX structure as the alpha channel for the destination surface for this blit.
DDBLT_ALPHAEDGEBLEND
Uses the dwAlphaEdgeBlend member of the DDBLTFX structure as the alpha channel for the edges of the image that border the color key colors.
DDBLT_ALPHASRC
Uses either the alpha information in pixel format or the alpha channel surface attached to the source surface as the alpha channel for this blit.
DDBLT_ALPHASRCCONSTOVERRIDE
Uses the dwAlphaSrcConst member of the DDBLTFX structure as the source alpha channel for this blit.
DDBLT_ALPHASRCNEG
Indicates that the source surface becomes more transparent as the alpha value increases (0 is opaque).
DDBLT_ALPHASRCSURFACEOVERRIDE
Uses the lpDDSAlphaSrc member of the DDBLTFX structure as the alpha channel source for this blit.
DDBLT_ASYNC
Processes this blit asynchronously through the FIFO hardware in the order received. If there is no room in the FIFO hardware, the call fails.
DDBLT_COLORFILL
Uses the dwFillColor member of the DDBLTFX structure as the RGB color that fills the destination rectangle on the destination surface.
DDBLT_DDFX
Uses the dwDDFX member of the DDBLTFX structure to specify the effects to be used for this blit.
DDBLT_DDROPS
Uses the dwDDROP member of the DDBLTFX structure to specify the raster operations (ROPs) that are not part of the Win32 API.
DDBLT_KEYDEST
Uses the color key associated with the destination surface.
DDBLT_KEYDESTOVERRIDE
Uses the ddckDestColorkey member of the DDBLTFX structure as the color key for the destination surface.
DDBLT_KEYSRC
Uses the color key associated with the source surface.
DDBLT_KEYSRCOVERRIDE
Uses the ddckSrcColorkey member of the DDBLTFX structure as the color key for the source surface.
DDBLT_ROP
Uses the dwROP member of the DDBLTFX structure for the ROP for this blit. The ROPs are the same as those defined in the Win32 API.
DDBLT_ROTATIONANGLE
Uses the dwRotationAngle member of the DDBLTFX structure as the rotation angle (specified in 1/100th of a degree) for the surface.
DDBLT_ZBUFFER
Performs a z-buffered blit using the z-buffers attached to the source and destination surfaces and the dwZBufferOpCode member of the DDBLTFX structure as the z-buffer opcode.
DDBLT_ZBUFFERDESTCONSTOVERRIDE
Performs a z-buffered blit using the dwZDestConst and dwZBufferOpCode members of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the destination.
DDBLT_ZBUFFERDESTOVERRIDE
Performs a z-buffered blit using the lpDDSZBufferDest and dwZBufferOpCode members of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the destination.
DDBLT_ZBUFFERSRCCONSTOVERRIDE
Performs a z-buffered blit using the dwZSrcConst and dwZBufferOpCode members of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the source.
DDBLT_ZBUFFERSRCOVERRIDE
A z-buffered blit using the lpDDSZBufferSrc and dwZBufferOpCode members of the DDBLTFX structure as the z-buffer and z-buffer opcode, respectively, for the source.
lpDDBltFx
Address of a DDBLTFX structure specifying additional blit effects.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDBLTFX

The DDBLTFX structure passes raster operations, effects, and override information to the IDirectDrawSurface4::Blt method. This structure is also part of the DDBLTBATCH structure used with the IDirectDrawSurface4::BltBatch method.

typedef struct _DDBLTFX{
    DWORD dwSize;
    DWORD dwDDFX;
    DWORD dwROP;
    DWORD dwDDROP;
    DWORD dwRotationAngle;
    DWORD dwZBufferOpCode;
    DWORD dwZBufferLow;
    DWORD dwZBufferHigh;
    DWORD dwZBufferBaseDest;
    DWORD dwZDestConstBitDepth;
    union
    {
        DWORD               dwZDestConst;
        LPDIRECTDRAWSURFACE lpDDSZBufferDest;
    } DUMMYUNIONNAMEN(1);
    DWORD dwZSrcConstBitDepth;
    union
    {
        DWORD               dwZSrcConst;
        LPDIRECTDRAWSURFACE lpDDSZBufferSrc;
    } DUMMYUNIONNAMEN(2);
    DWORD dwAlphaEdgeBlendBitDepth;
    DWORD dwAlphaEdgeBlend;
    DWORD dwReserved;
    DWORD dwAlphaDestConstBitDepth;
    union
    {
        DWORD               dwAlphaDestConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaDest;
    } DUMMYUNIONNAMEN(3);
    DWORD dwAlphaSrcConstBitDepth;
    union
    {
        DWORD               dwAlphaSrcConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
    } DUMMYUNIONNAMEN(4);
    union
    {
        DWORD               dwFillColor;
        DWORD               dwFillDepth;
        DWORD               dwFillPixel;
        LPDIRECTDRAWSURFACE lpDDSPattern;
    } DUMMYUNIONNAMEN(5);
    DDCOLORKEY ddckDestColorkey;
    DDCOLORKEY ddckSrcColorkey;
} DDBLTFX,FAR* LPDDBLTFX;

Members

dwSize
Size of the structure, in bytes. This member must be initialized before the structure is used.
dwDDFX
Type of FX operations.
DDBLTFX_ARITHSTRETCHY
Uses arithmetic stretching along the y-axis for this blit.
DDBLTFX_MIRRORLEFTRIGHT
Turns the surface on its y-axis. This blit mirrors the surface from left to right.
DDBLTFX_MIRRORUPDOWN
Turns the surface on its x-axis. This blit mirrors the surface from top to bottom.
DDBLTFX_NOTEARING
Schedules this blit to avoid tearing.
DDBLTFX_ROTATE180
Rotates the surface 180 degrees clockwise during this blit.
DDBLTFX_ROTATE270
Rotates the surface 270 degrees clockwise during this blit.
DDBLTFX_ROTATE90
Rotates the surface 90 degrees clockwise during this blit.
DDBLTFX_ZBUFFERBASEDEST
Adds the dwZBufferBaseDest member to each of the source z-values before comparing them with the destination z-values during this z-blit.
DDBLTFX_ZBUFFERRANGE
Uses the dwZBufferLow and dwZBufferHigh members as range values to specify limits to the bits copied from a source surface during this z-blit.
dwROP
Win32 raster operations. You can retrieve a list of supported raster operations by calling the IDirectDraw4::GetCaps method.
dwDDROP
DirectDraw raster operations.
dwRotationAngle
Rotation angle for the blit.
dwZBufferOpCode
Z-buffer compares.
dwZBufferLow
Low limit of a z-buffer.
dwZBufferHigh
High limit of a z-buffer.
dwZBufferBaseDest
Destination base value of a z-buffer.
dwZDestConstBitDepth
Bit depth of the destination z-constant.
dwZDestConst
Constant used as the z-buffer destination.
lpDDSZBufferDest
Surface used as the z-buffer destination.
dwZSrcConstBitDepth
Bit depth of the source z-constant.
dwZSrcConst
Constant used as the z-buffer source.
lpDDSZBufferSrc
Surface used as the z-buffer source.
dwAlphaEdgeBlendBitDepth
Bit depth of the constant for an alpha edge blend.
dwAlphaEdgeBlend
Alpha constant used for edge blending.
dwReserved
Reserved for future use.
dwAlphaDestConstBitDepth
Bit depth of the destination alpha constant.
dwAlphaDestConst
Constant used as the alpha channel destination.
lpDDSAlphaDest
Surface used as the alpha channel destination.
dwAlphaSrcConstBitDepth
Bit depth of the source alpha constant.
dwAlphaSrcConst
Constant used as the alpha channel source.
lpDDSAlphaSrc
Surface used as the alpha channel source.
dwFillColor
Color used to fill a surface when DDBLT_COLORFILL is specified. This value must be a pixel appropriate to the pixel format of the destination surface. For a palettized surface it would be a palette index, and for a 16-bit RGB surface it would be a 16-bit pixel value.
dwFillDepth
Depth value for the z-buffer.
dwFillPixel
Pixel value for RGBA or RGBZ fills. Applications that use RGBZ fills should use this member, not dwFillColor or dwFillDepth.
lpDDSPattern
Surface to use as a pattern. The pattern can be used in certain blit operations that combine a source and a destination.
ddckDestColorkey
Destination color key override.
ddckSrcColorkey
Source color key override.

备注

The unions in this structure have been updated to work with compilers that don't support nameless unions. If your compiler doesn't support nameless unions, define the NONAMELESSUNION token before including the Ddraw.h header file.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDCAPS

The DDCAPS structure represents the capabilities of the hardware exposed through the DirectDraw object. This structure contains a DDSCAPS structure used in this context to describe what kinds of DirectDrawSurface objects can be created. It may not be possible to simultaneously create all of the surfaces described by these capabilities. This structure is used with the IDirectDraw4::GetCaps method.

The ddraw.h header file contains multiple versions of this structure. See 备注 for more information.

typedef struct _DDCAPS {
    DWORD    dwSize;
    DWORD    dwCaps;                  // driver-specific caps
    DWORD    dwCaps2;                 // more driver-specific caps
    DWORD    dwCKeyCaps;              // color key caps
    DWORD    dwFXCaps;                // stretching and effects caps
    DWORD    dwFXAlphaCaps;           // alpha caps
    DWORD    dwPalCaps;               // palette caps
    DWORD    dwSVCaps;                // stereo vision caps
    DWORD    dwAlphaBltConstBitDepths;       // alpha bit-depth members
    DWORD    dwAlphaBltPixelBitDepths;       //  .
    DWORD    dwAlphaBltSurfaceBitDepths;     //  .
    DWORD    dwAlphaOverlayConstBitDepths;   //  .
    DWORD    dwAlphaOverlayPixelBitDepths;   //  .
    DWORD    dwAlphaOverlaySurfaceBitDepths; //  .
    DWORD    dwZBufferBitDepths;      // Z-buffer bit depth
    DWORD    dwVidMemTotal;           // total video memory
    DWORD    dwVidMemFree;            // total free video memory
    DWORD    dwMaxVisibleOverlays;    // maximum visible overlays
    DWORD    dwCurrVisibleOverlays;   // overlays currently visible
    DWORD    dwNumFourCCCodes;        // number of supported FOURCC codes
    DWORD    dwAlignBoundarySrc;      // overlay alignment restrictions
    DWORD    dwAlignSizeSrc;          //  .
    DWORD    dwAlignBoundaryDest;     //  .
    DWORD    dwAlignSizeDest;         //  .
    DWORD    dwAlignStrideAlign;      // stride alignment
    DWORD    dwRops[DD_ROP_SPACE];    // supported raster ops
    DWORD    dwReservedCaps;          // reserved
    DWORD    dwMinOverlayStretch;     // overlay stretch factors
    DWORD    dwMaxOverlayStretch;     //  .
    DWORD    dwMinLiveVideoStretch;   // obsolete
    DWORD    dwMaxLiveVideoStretch;   //  .
    DWORD    dwMinHwCodecStretch;     //  .
    DWORD    dwMaxHwCodecStretch;     //  .
    DWORD    dwReserved1;             // reserved
    DWORD    dwReserved2;             //  .
    DWORD    dwReserved3;             //  .
    DWORD    dwSVBCaps;               // system-to-video blit related caps
    DWORD    dwSVBCKeyCaps;           //  .
    DWORD    dwSVBFXCaps;             //  .
    DWORD    dwSVBRops[DD_ROP_SPACE]; //  .
    DWORD    dwVSBCaps;               // video-to-system blit related caps
    DWORD    dwVSBCKeyCaps;           //  .
    DWORD    dwVSBFXCaps;             //  .
    DWORD    dwVSBRops[DD_ROP_SPACE]; //  .
    DWORD    dwSSBCaps;               // system-to-system blit related caps
    DWORD    dwSSBCKeyCaps;           //  .
    DWORD    dwSSBCFXCaps;            //  .
    DWORD    dwSSBRops[DD_ROP_SPACE]; //  .
    DWORD    dwMaxVideoPorts;         // maximum number of live video ports
    DWORD    dwCurrVideoPorts;        // current number of live video ports
    DWORD    dwSVBCaps2;              // additional system-to-video blit caps
    DWORD    dwNLVBCaps;              // nonlocal-to-local video memory blit caps
    DWORD    dwNLVBCaps2;             //  .
    DWORD    dwNLVBCKeyCaps;          //  .
    DWORD    dwNLVBFXCaps;            //  .
    DWORD    dwNLVBRops[DD_ROP_SPACE];//  .
    DDSCAPS2 ddsCaps;                 // general surface caps
} DDCAPS,FAR* LPDDCAPS;

Members

dwSize
Size of the structure, in bytes. This member must be initialized before the structure is used.
dwCaps
Driver-specific capabilities.
DDCAPS_3D
Indicates that the display hardware has 3-D acceleration.
DDCAPS_ALIGNBOUNDARYDEST
Indicates that DirectDraw will support only those overlay destination rectangles with the x-axis aligned to the dwAlignBoundaryDest boundaries of the surface.
DDCAPS_ALIGNBOUNDARYSRC
Indicates that DirectDraw will support only those overlay source rectangles with the x-axis aligned to the dwAlignBoundarySrc boundaries of the surface.
DDCAPS_ALIGNSIZEDEST
Indicates that DirectDraw will support only those overlay destination rectangles whose x-axis sizes, in pixels, are dwAlignSizeDest multiples.
DDCAPS_ALIGNSIZESRC
Indicates that DirectDraw will support only those overlay source rectangles whose x-axis sizes, in pixels, are dwAlignSizeSrc multiples.
DDCAPS_ALIGNSTRIDE
Indicates that DirectDraw will create display memory surfaces that have a stride alignment equal to the dwAlignStrideAlign value.
DDCAPS_ALPHA
Indicates that the display hardware supports alpha-only surfaces. (See alpha channel)
DDCAPS_BANKSWITCHED
Indicates that the display hardware is bank-switched and is potentially very slow at random access to display memory.
DDCAPS_BLT
Indicates that display hardware is capable of blit operations.
DDCAPS_BLTCOLORFILL
Indicates that display hardware is capable of color filling with a blitter.
DDCAPS_BLTDEPTHFILL
Indicates that display hardware is capable of depth filling z-buffers with a blitter.
DDCAPS_BLTFOURCC
Indicates that display hardware is capable of color-space conversions during blit operations.
DDCAPS_BLTQUEUE
Indicates that display hardware is capable of asynchronous blit operations.
DDCAPS_BLTSTRETCH
Indicates that display hardware is capable of stretching during blit operations.
DDCAPS_CANBLTSYSMEM
Indicates that display hardware is capable of blitting to or from system memory.
DDCAPS_CANCLIP
Indicates that display hardware is capable of clipping with blitting.
DDCAPS_CANCLIPSTRETCHED
Indicates that display hardware is capable of clipping while stretch blitting.
DDCAPS_COLORKEY
Supports some form of color key in either overlay or blit operations. More specific color key capability information can be found in the dwCKeyCaps member.
DDCAPS_COLORKEYHWASSIST
Indicates that the color key is partially hardware assisted. This means that other resources (CPU or video memory) might be used. If this bit is not set, full hardware support is in place.
DDCAPS_GDI
Indicates that display hardware is shared with GDI.
DDCAPS_NOHARDWARE
Indicates that there is no hardware support.
DDCAPS_OVERLAY
Indicates that display hardware supports overlays.
DDCAPS_OVERLAYCANTCLIP
Indicates that display hardware supports overlays but cannot clip them.
DDCAPS_OVERLAYFOURCC
Indicates that overlay hardware is capable of color-space conversions during overlay operations.
DDCAPS_OVERLAYSTRETCH
Indicates that overlay hardware is capable of stretching. The dwMinOverlayStretch and dwMaxOverlayStretch members contain valid data.
DDCAPS_PALETTE
Indicates that DirectDraw is capable of creating and supporting DirectDrawPalette objects for more surfaces than only the primary surface.
DDCAPS_PALETTEVSYNC
Indicates that DirectDraw is capable of updating a palette synchronized with the vertical refresh.
DDCAPS_READSCANLINE
Indicates that display hardware is capable of returning the current scan line.
DDCAPS_STEREOVIEW
Indicates that display hardware has stereo vision capabilities.
DDCAPS_VBI
Indicates that display hardware is capable of generating a vertical-blank interrupt.
DDCAPS_ZBLTS
Supports the use of z-buffers with blit operations.
DDCAPS_ZOVERLAYS
Supports the use of the IDirectDrawSurface4::UpdateOverlayZOrder method as a z-value for overlays to control their layering.
dwCaps2
More driver-specific capabilities.
DDCAPS2_AUTOFLIPOVERLAY
The overlay can be automatically flipped to the next surface in the flip chain each time a video port VSYNC occurs, allowing the video port and the overlay to double buffer the video without CPU overhead. This option is only valid when the surface is receiving data from a video port. If the video port data is non-interlaced or non-interleaved, it will flip on every VSYNC. If the data is being interleaved in memory, it will flip on every other VSYNC.
DDCAPS2_CANBOBHARDWARE
The overlay hardware can display each field of an interlaced video stream individually.
DDCAPS2_CANBOBINTERLEAVED
The overlay hardware can display each field individually of an interlaced video stream while it is interleaved in memory without causing any artifacts that might normally occur without special hardware support. This option is only valid when the surface is receiving data from a video port and is only valid when the video is zoomed at least two times in the vertical direction.
DDCAPS2_CANBOBNONINTERLEAVED
The overlay hardware can display each field individually of an interlaced video stream while it is not interleaved in memory without causing any artifacts that might normally occur without special hardware support. This option is only valid when the surface is receiving data from a video port and is only valid when the video is zoomed at least two times in the vertical direction.
DDCAPS2_CANCALIBRATEGAMMA
The system has a calibrator installed that can automatically adjust the gamma ramp so that the result will be identical on all systems that have a calibrator. To invoke the calibrator when setting new gamma levels, use the DDSGR_CALIBRATE flag when calling the IDirectDrawGammaControl::SetGammaRamp method. Calibrating gamma ramps incurs some processing overhead, and should not be used frequently.
DDCAPS2_CANDROPZ16BIT
16-bit RGBZ values can be converted into sixteen-bit RGB values. (The system does not support eight-bit conversions.)
DDCAPS2_CANFLIPODDEVEN
The driver is capable of performing odd and even flip operations, as specified by the DDFLIP_ODD and DDFLIP_EVEN flags used with the IDirectDrawSurface4::Flip method.
DDCAPS2_CANRENDERWINDOWED
The driver is capable of rendering in windowed mode.
DDCAPS2_CERTIFIED
Indicates that display hardware is certified.
DDCAPS2_COLORCONTROLPRIMARY
The primary surface contains color controls (for instance, gamma)
DDCAPS2_COLORCONTROLOVERLAY
The overlay surface contains color controls (such as brightness, sharpness)
DDCAPS2_COPYFOURCC
Indicates that the driver supports blitting any FOURCC surface to another surface of the same FOURCC.
DDCAPS2_FLIPINTERVAL
Indicates that the driver will respond to the DDFLIP_INTERVAL* flags. (see IDirectDrawSurface4::Flip).
DDCAPS2_FLIPNOVSYNC
Indicates that the driver will respond to the DDFLIP_NOVSYNC flag (see IDirectDrawSurface4::Flip).
DDCAPS2_NO2DDURING3DSCENE
Indicates that 2-D operations such as IDirectDrawSurface4::Blt and IDirectDrawSurface4::Lock cannot be performed on any surfaces that Direct3D� is using between calls to the IDirect3DDevice3::BeginScene and IDirect3DDevice3::EndScene methods.
DDCAPS2_NONLOCALVIDMEM
Indicates that the display driver supports surfaces in non-local video memory.
DDCAPS2_NONLOCALVIDMEMCAPS
Indicates that blit capabilities for non-local video memory surfaces differ from local video memory surfaces. If this flag is present, the DDCAPS2_NONLOCALVIDMEM flag will also be present.
DDCAPS2_NOPAGELOCKREQUIRED
DMA blit operations are supported on system memory surfaces that are not page locked.
DDCAPS2_PRIMARYGAMMA
Supports dynamic gamma ramps for the primary surface. For more information, see Gamma and Color Controls.
DDCAPS2_VIDEOPORT
Indicates that display hardware supports live video.
DDCAPS2_WIDESURFACES
Indicates that the display surfaces supports surfaces wider than the primary surface.
dwCKeyCaps
Color-key capabilities.
DDCKEYCAPS_DESTBLT
Supports transparent blitting with a color key that identifies the replaceable bits of the destination surface for RGB colors.
DDCKEYCAPS_DESTBLTCLRSPACE
Supports transparent blitting with a color space that identifies the replaceable bits of the destination surface for RGB colors.
DDCKEYCAPS_DESTBLTCLRSPACEYUV
Supports transparent blitting with a color space that identifies the replaceable bits of the destination surface for YUV colors.
DDCKEYCAPS_DESTBLTYUV
Supports transparent blitting with a color key that identifies the replaceable bits of the destination surface for YUV colors.
DDCKEYCAPS_DESTOVERLAY
Supports overlaying with color keying of the replaceable bits of the destination surface being overlaid for RGB colors.
DDCKEYCAPS_DESTOVERLAYCLRSPACE
Supports a color space as the color key for the destination of RGB colors.
DDCKEYCAPS_DESTOVERLAYCLRSPACEYUV
Supports a color space as the color key for the destination of YUV colors.
DDCKEYCAPS_DESTOVERLAYONEACTIVE
Supports only one active destination color key value for visible overlay surfaces .
DDCKEYCAPS_DESTOVERLAYYUV
Supports overlaying using color keying of the replaceable bits of the destination surface being overlaid for YUV colors.
DDCKEYCAPS_NOCOSTOVERLAY
Indicates there are no bandwidth trade-offs for using the color key with an overlay.
DDCKEYCAPS_SRCBLT
Supports transparent blitting using the color key for the source with this surface for RGB colors.
DDCKEYCAPS_SRCBLTCLRSPACE
Supports transparent blitting using a color space for the source with this surface for RGB colors.
DDCKEYCAPS_SRCBLTCLRSPACEYUV
Supports transparent blitting using a color space for the source with this surface for YUV colors.
DDCKEYCAPS_SRCBLTYUV
Supports transparent blitting using the color key for the source with this surface for YUV colors.
DDCKEYCAPS_SRCOVERLAY
Supports overlaying using the color key for the source with this overlay surface for RGB colors.
DDCKEYCAPS_SRCOVERLAYCLRSPACE
Supports overlaying using a color space as the source color key for the overlay surface for RGB colors.
DDCKEYCAPS_SRCOVERLAYCLRSPACEYUV
Supports overlaying using a color space as the source color key for the overlay surface for YUV colors.
DDCKEYCAPS_SRCOVERLAYONEACTIVE
Supports only one active source color key value for visible overlay surfaces.
DDCKEYCAPS_SRCOVERLAYYUV
Supports overlaying using the color key for the source with this overlay surface for YUV colors.
dwFXCaps
Driver-specific stretching and effects capabilities.
DDFXCAPS_BLTALPHA
Supports alpha-blended blit operations.
DDFXCAPS_BLTARITHSTRETCHY
Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during a blit operation. Occurs along the y-axis (vertically).
DDFXCAPS_BLTARITHSTRETCHYN
Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink surfaces during a blit operation. Occurs along the y-axis (vertically), and works only for integer stretching (×1, ×2, and so on).
DDFXCAPS_BLTFILTER
Driver can do surface-reconstruction filtering for warped blits.
DDFXCAPS_BLTMIRRORLEFTRIGHT
Supports mirroring left to right in a blit operation.
DDFXCAPS_BLTMIRRORUPDOWN
Supports mirroring top to bottom in a blit operation.
DDFXCAPS_BLTROTATION
Supports arbitrary rotation in a blit operation.
DDFXCAPS_BLTROTATION90
Supports 90-degree rotations in a blit operation.
DDFXCAPS_BLTSHRINKX
Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSHRINKXN
Supports integer shrinking (×1, ×2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSHRINKY
Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_BLTSHRINKYN
Supports integer shrinking (×1, ×2, and so on) of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHX
Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHXN
Supports integer stretching (×1, ×2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHY
Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_BLTSTRETCHYN
Supports integer stretching (×1, ×2, and so on) of a surface along the y-axis (vertically). This flag is valid only for blit operations.
DDFXCAPS_BLTTRANSFORM
Supports geometric transformations (or warps) for blitted sprites. Transformations are not currently supported for explicit blit operations.
DDFXCAPS_OVERLAYALPHA
Supports alpha blending for overlay surfaces.
DDFXCAPS_OVERLAYARITHSTRETCHY
Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink overlay surfaces. Occurs along the y-axis (vertically).
DDFXCAPS_OVERLAYARITHSTRETCHYN
Uses arithmetic operations, rather than pixel-doubling techniques, to stretch and shrink overlay surfaces. Occurs along the y-axis (vertically), and works only for integer stretching (×1, ×2, and so on).
DDFXCAPS_OVERLAYFILTER
Supports surface-reconstruction filtering for warped overlay sprites. Filtering is not currently supported for explicitly displayed overlay surfaces (those displayed with calls to IDirectDrawSurface4::UpdateOverlay).
DDFXCAPS_OVERLAYMIRRORLEFTRIGHT
Supports mirroring of overlays across the vertical axis.
DDFXCAPS_OVERLAYMIRRORUPDOWN
Supports mirroring of overlays across the horizontal axis.
DDFXCAPS_OVERLAYSHRINKX
Supports arbitrary shrinking of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKXN
Supports integer shrinking (×1, ×2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKY
Supports arbitrary shrinking of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSHRINKYN
Supports integer shrinking (×1, ×2, and so on) of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that shrinking is available.
DDFXCAPS_OVERLAYSTRETCHX
Supports arbitrary stretching of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHXN
Supports integer stretching (×1, ×2, and so on) of a surface along the x-axis (horizontally). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHY
Supports arbitrary stretching of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYSTRETCHYN
Supports integer stretching (×1, ×2, and so on) of a surface along the y-axis (vertically). This flag is valid only for DDSCAPS_OVERLAY surfaces. This flag indicates only the capabilities of a surface; it does not indicate that stretching is available.
DDFXCAPS_OVERLAYTRANSFORM
Supports geometric transformations (or warps) for overlay sprites. Transformations are not currently supported for explicitly displayed overlay surfaces (those displayed with calls to IDirectDrawSurface4::UpdateOverlay).
dwFXAlphaCaps
Driver-specific alpha capabilities.
DDFXALPHACAPS_BLTALPHAEDGEBLEND
Supports alpha blending around the edge of a source color-keyed surface. Used for blit operations.
DDFXALPHACAPS_BLTALPHAPIXELS
Supports alpha information in pixel format. The bit depth of alpha information in the pixel format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for blit operations.
DDFXALPHACAPS_BLTALPHAPIXELSNEG
Supports alpha information in pixel format. The bit depth of alpha information in the pixel format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be used only if DDCAPS_ALPHA is set. Used for blit operations.
DDFXALPHACAPS_BLTALPHASURFACES
Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for blit operations.
DDFXALPHACAPS_BLTALPHASURFACESNEG
Indicates that the alpha channel becomes more transparent as the alpha value increases. The depth of the alpha channel data can be 1, 2, 4, or 8. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be set only if DDCAPS_ALPHA has been set. Used for blit operations.
DDFXALPHACAPS_OVERLAYALPHAEDGEBLEND
Supports alpha blending around the edge of a source color-keyed surface. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHAPIXELS
Supports alpha information in pixel format. The bit depth of alpha information in pixel format can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHAPIXELSNEG
Supports alpha information in pixel format. The bit depth of alpha information in pixel format can be 1, 2, 4, or 8. The alpha value becomes more transparent as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be used only if DDCAPS_ALPHA has been set. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHASURFACES
Supports alpha-only surfaces. The bit depth of an alpha-only surface can be 1, 2, 4, or 8. The alpha value becomes more opaque as the alpha value increases. Regardless of the depth of the alpha information, 0 is always the fully transparent value. Used for overlays.
DDFXALPHACAPS_OVERLAYALPHASURFACESNEG
Indicates that the alpha channel becomes more transparent as the alpha value increases. The depth of the alpha channel data can be 1, 2, 4, or 8. Regardless of the depth of the alpha information, 0 is always the fully opaque value. This flag can be used only if DDCAPS_ALPHA has been set. Used for overlays.
dwPalCaps
Palette capabilities.
DDPCAPS_1BIT
Supports palettes that contain 1 bit color entries (two colors).
DDPCAPS_2BIT
Supports palettes that contain 2 bit color entries (four colors).
DDPCAPS_4BIT
Supports palettes that contain 4 bit color entries (16 colors).
DDPCAPS_8BIT
Supports palettes that contain 8 bit color entries (256 colors).
DDPCAPS_8BITENTRIES
Specifies an index to an 8-bit color index. This field is valid only when used with the DDPCAPS_1BIT, DDPCAPS_2BIT, or DDPCAPS_4BIT capability and when the target surface is in 8 bits per pixel (bpp). Each color entry is 1 byte long and is an index to an 8-bpp palette on the destination surface.
DDPCAPS_ALPHA
Supports palettes that include an alpha component. For alpha-capable palettes, the peFlags member of for each PALETTEENTRY structure the palette contains is to be interpreted as a single 8-bit alpha value (in addition to the color data in the peRed, peGreen, and peBlue members). A palette created with this flag can only be attached to a texture surface.
DDPCAPS_ALLOW256
Supports palettes that can have all 256 entries defined.
DDPCAPS_PRIMARYSURFACE
Indicates that the palette is attached to the primary surface. Changing the palette has an immediate effect on the display unless the DDPCAPS_VSYNC capability is specified and supported.
DDPCAPS_PRIMARYSURFACELEFT
Indicates that the palette is attached to the primary surface on the left. Changing the palette has an immediate effect on the display unless the DDPCAPS_VSYNC capability is specified and supported.
DDPCAPS_VSYNC
Indicates that the palette can be modified synchronously with the monitor's refresh rate.
dwSVCaps
Stereo vision capabilities.
DDSVCAPS_ENIGMA
Indicates that the stereo view is accomplished using Enigma encoding.
DDSVCAPS_FLICKER
Indicates that the stereo view is accomplished using high-frequency flickering.
DDSVCAPS_REDBLUE
Indicates that the stereo view is accomplished when the viewer looks at the image through red and blue filters placed over the left and right eyes. All images must adapt their color spaces for this process.
DDSVCAPS_SPLIT
Indicates that the stereo view is accomplished with split-screen technology.
dwAlphaBltConstBitDepths
DDBD_2, DDBD_4, or DDBD_8. (Indicates 2-, 4-, or 8-bits per pixel.)
dwAlphaBltPixelBitDepths
DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
dwAlphaBltSurfaceBitDepths
DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
dwAlphaOverlayConstBitDepths
DDBD_2, DDBD_4, or DDBD_8. (Indicates 2-, 4-, or 8-bits per pixel.)
dwAlphaOverlayPixelBitDepths
DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
dwAlphaOverlaySurfaceBitDepths
DDBD_1, DDBD_2, DDBD_4, or DDBD_8. (Indicates 1-, 2-, 4-, or 8-bits per pixel.)
dwZBufferBitDepths
DDBD_8, DDBD_16, DDBD_24, or DDBD_32. (Indicates 8-, 16-, 24-, 32-bits per pixel.) This member is obsolete for DirectX 6.0 and later. Use the IDirect3D3::EnumZBufferFormats to retrieve information about supported depth buffer formats.
dwVidMemTotal
Total amount of display memory on the device, in bytes, less memory reserved for the primary surface and any private data structures reserved by the driver. (This value is the same as the total video memory reported by the IDirectDraw4::GetAvailableVidMem method.)
dwVidMemFree
Free display memory. This value equals the value in dwVidMemTotal, less any memory currently allocated by the application for surfaces. Unlike the GetAvailableVidMem method, which reports the memory available for a particular type of surface (like a texture), this value reflects the memory available for any type of surface.
dwMaxVisibleOverlays
Maximum number of visible overlays or overlay sprites.
dwCurrVisibleOverlays
Current number of visible overlays or overlay sprites.
dwNumFourCCCodes
Number of FourCC codes.
dwAlignBoundarySrc
Source rectangle alignment for an overlay surface, in pixels.
dwAlignSizeSrc
Source rectangle size alignment for an overlay surface, in pixels. Overlay source rectangles must have a pixel width that is a multiple of this value.
dwAlignBoundaryDest
Destination rectangle alignment for an overlay surface, in pixels.
dwAlignSizeDest
Destination rectangle size alignment for an overlay surface, in pixels. Overlay destination rectangles must have a pixel width that is a multiple of this value.
dwAlignStrideAlign
Stride alignment.
dwRops[DD_ROP_SPACE]
Raster operations supported.
dwReservedCaps
Reserved. Prior to DirectX 6.0, this member contained general surface capabilities, which are now contained in the ddsCaps member (a DDSCAPS2 structure).
dwMinOverlayStretch and dwMaxOverlayStretch
Minimum and maximum overlay stretch factors multiplied by 1000. For example, 1.3 = 1300.
dwMinLiveVideoStretch and dwMaxLiveVideoStretch
These members are obsolete; do not use.
dwMinHwCodecStretch and dwMaxHwCodecStretch
These members are obsolete; do not use.
dwReserved1, dwReserved2, and dwReserved3
Reserved for future use.
dwSVBCaps
Driver-specific capabilities for system-memory-to-display-memory blits. Valid flags are identical to the blit-related flags used with the dwCaps member.
dwSVBCKeyCaps
Driver color-key capabilities for system-memory-to-display-memory blits. Valid flags are identical to the blit-related flags used with for the dwCKeyCaps member.
dwSVBFXCaps
Driver FX capabilities for system-memory-to-display-memory blits. Valid flags are identical to the blit-related flags used with the dwFXCaps member.
dwSVBRops[DD_ROP_SPACE]
Raster operations supported for system-memory-to-display-memory blits.
dwVSBCaps
Driver-specific capabilities for display-memory-to-system-memory blits. Valid flags are identical to the blit-related flags used with the dwCaps member.
dwVSBCKeyCaps
Driver color-key capabilities for display-memory-to-system-memory blits. Valid flags are identical to the blit-related flags used with for the dwCKeyCaps member.
dwVSBFXCaps
Driver FX capabilities for display-memory-to-system-memory blits. Valid flags are identical to the blit-related flags used with the dwFXCaps member.
dwVSBRops[DD_ROP_SPACE]
Raster operations supported for display-memory-to-system-memory blits.
dwSSBCaps
Driver-specific capabilities for system-memory-to-system-memory blits. Valid flags are identical to the blit-related flags used with the dwCaps member.
dwSSBCKeyCaps
Driver color-key capabilities for system-memory-to-system-memory blits. Valid flags are identical to the blit-related flags used with for the dwCKeyCaps member.
dwSSBCFXCaps
Driver FX capabilities for system-memory-to-system-memory blits. Valid flags are identical to the blit-related flags used with the dwFXCaps member.
dwSSBRops[DD_ROP_SPACE]
Raster operations supported for system-memory-to-system-memory blits.
dwMaxVideoPorts
Maximum number of live video ports.
dwCurrVideoPorts
Current number of live video ports.
dwSVBCaps2
More driver-specific capabilities for system-memory-to-video-memory blits. Valid flags are identical to the blit-related flags used with the dwCaps2 member.
dwNLVBCaps
Driver-specific capabilities for nonlocal-to-local video memory blits. Valid flags are identical to the blit-related flags used with the dwCaps member.
dwNLVBCaps2
More driver-specific capabilities for nonlocal-to-local video memory blits. Valid flags are identical to the blit-related flags used with the dwCaps2 member.
dwNLVBCKeyCaps
Driver color-key capabilities for nonlocal-to-local video memory blits. Valid flags are identical to the blit-related flags used with for the dwCKeyCaps member.
dwNLVBFXCaps
Driver FX capabilities for nonlocal-to-local video memory blits. Valid flags are identical to the blit-related flags used with the dwFXCaps member.
dwNLVBRops[DD_ROP_SPACE]
Raster operations supported for nonlocal-to-local video memory blits.
ddsCaps
DDSCAPS2 structure with general surface capabilities.

备注

For backward compatibility with previous versions of DirectX, the ddraw.h header file contains multiple definitions for the DDCAPS structure. The version that passes the preprocessor is determined by the value of the DIRECTDRAW_VERSION constant. For details, see Component Version Constants.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDCOLORCONTROL

The DDCOLORCONTROL structure defines the color controls associated with a DirectDrawVideoPortObject, an overlay surface, or a primary surface.

typedef struct _DDCOLORCONTROL {
    DWORD   dwSize;
    DWORD   dwFlags;
    LONG    lBrightness;
    LONG    lContrast;
    LONG    lHue;
    LONG    lSaturation;
    LONG    lSharpness;
    LONG    lGamma;
    LONG    lColorEnable;
    DWORD   dwReserved1;
} DDCOLORCONTROL, FAR *LPDDCOLORCONTROL;

Members

dwSize
The the size of the structure, in bytes. This member must be initialized before use.
dwFlags
Flags specifying which structure members contain valid data . When the structure is returned by the IDirectDrawColorControl::GetColorControls method, it also indicates which options are supported by the device.
DDCOLOR_BRIGHTNESS
The lBrightness member contains valid data.
DDCOLOR_COLORENABLE
The lColorEnable member contains valid data.
DDCOLOR_CONTRAST
The lContrast member contains valid data.
DDCOLOR_GAMMA
The lGamma member contains valid data.
DDCOLOR_HUE
The lHue member contains valid data.
DDCOLOR_SATURATION
The lSaturation member contains valid data.
DDCOLOR_SHARPNESS
The lSharpness member contains valid data.
lBrightness
Luminance intensity, in IRE units times 100. The valid range is 0 to 10,000. The default is 750, which translates to 7.5 IRE.
lContrast
Relative difference between higher and lower intensity luminance values in IRE units times 100. The valid range is 0 to 20,000. The default value is 10,000 (100 IRE). Higher values of contrast cause darker luminance values to tend towards black, and cause lighter luminance values to tend towards white. Lower values of contrast cause all luminance values to move towards the middle luminance values.
lHue
Phase relationship of the chrominance components. Hue is specified in degrees and the valid range is -180 to 180. The default is 0.
lSaturation
Color intensity, in IRE units times 100. The valid range is 0 to 20,000. The default value is 10,000, which translates to 100 IRE.
lSharpness
Sharpness in arbitrary units. The valid range is 0 to 10. The default value is 5.
lGamma
Controls the amount of gamma correction applied to the luminance values. The valid range is 1 to 500 gamma units, with a default of 1.
lColorEnable
Flag indicating whether color is used. If this member is zero, color is not used; if it is 1, then color is used. The default value is 1.
dwReserved1
This member is reserved.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDDEVICEIDENTIFIER

The DDDEVICEIDENTIFIER structure is passed to the IDirectDraw4::GetDeviceIdentifier method to obtain information about a device.

typedef struct tagDDDEVICEIDENTIFIER {
    char    szDriver[MAX_DDDEVICEID_STRING];
    char    szDescription[MAX_DDDEVICEID_STRING];
    LARGE_INTEGER  liDriverVersion;
    DWORD   dwVendorId;
    DWORD   dwDeviceId;
    DWORD   dwSubSysId;
    DWORD   dwRevision;
    GUID    guidDeviceIdentifier;
} DDDEVICEIDENTIFIER, * LPDDDEVICEIDENTIFIER;

Members

szDriver
Name of the driver.
szDescription
Description of the driver.
liDriverVersion
Version of the driver. It is legal to do less than and greater than comparisons on the whole 64 bits. Caution should be exercised if you use this element to identify problematic drivers. It is recommended that guidDeviceIdentifier be used for this purpose.

The data takes the following form:

wProduct = HIWORD(liDriverVersion.HighPart)
wVersion = LOWORD(liDriverVersion.HighPart)
wSubVersion = HIWORD(liDriverVersion.LowPart)
wBuild = LOWORD(liDriverVersion.LowPart)
dwVendorId
Identifier of the manufacturer. Can be 0 if unknown.
dwDeviceId
Identifier of the type of chipset. Can be 0 if unknown.
dwSubSysId
Identifier of the subsystem. Typically this means the particular board. Can be 0 if unknown.
dwRevision
Identifier of the revision level of the chipset. Can be 0 if unknown.
guidDeviceIdentifier
Unique identifier for the driver/chipset pair. Use this value if you wish to track changes to the driver/chipset in order to reprofile the graphics subsystem. It can also be used to identify particular problematic drivers.

备注

The values in szDriver and szDescription are for presentation to the user only. They should not be used to identify particular drivers, because different strings might be associated with the same device, or the same driver from different vendors might be described differently.

The dwVendorId, dwDeviceId, dwSubSysId, and dwRevision members can be used to identify particular chipsets, but use extreme caution.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDGAMMARAMP

The DDGAMMARAMP structure contains red, green, and blue ramp data for the IDirectDrawGammaControl::GetGammaRamp and IDirectDrawGammaControl::SetGammaRamp methods.

typedef struct _DDGAMMARAMP {
    WORD red[256];
    WORD green[256];
    WORD blue[256];
} DDGAMMARAMP, FAR * LPDDGAMMARAMP;

Members

red, green, and blue
Array of 256 WORD elements that describe the red, green, and blue gamma ramps.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.

参阅

Gamma and Color Controls


DDCOLORKEY

The DDCOLORKEY structure describes a source color key, destination color key, or color space. A color key is specified if the low and high range values are the same. This structure is used with the IDirectDrawSurface4::GetColorKey and IDirectDrawSurface4::SetColorKey methods.

typedef struct _DDCOLORKEY{
    DWORD dwColorSpaceLowValue;
    DWORD dwColorSpaceHighValue;
} DDCOLORKEY,FAR* LPDDCOLORKEY;

Members

dwColorSpaceLowValue
Low value, inclusive, of the color range that is to be used as the color key.
dwColorSpaceHighValue
High value, inclusive, of the color range that is to be used as the color key.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDOVERLAYFX

The DDOVERLAYFX structure passes override information to the IDirectDrawSurface4::UpdateOverlay method.

typedef struct _DDOVERLAYFX{
    DWORD dwSize;
    DWORD dwAlphaEdgeBlendBitDepth;
    DWORD dwAlphaEdgeBlend;
    DWORD dwReserved;
    DWORD dwAlphaDestConstBitDepth;
    union
    {
        DWORD               dwAlphaDestConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaDest;
    } DUMMYUNIONNAMEN(1);
    DWORD dwAlphaSrcConstBitDepth;
    union
    {
        DWORD               dwAlphaSrcConst;
        LPDIRECTDRAWSURFACE lpDDSAlphaSrc;
    } DUMMYUNIONNAMEN(2);
    DDCOLORKEY dckDestColorkey;
    DDCOLORKEY dckSrcColorkey;

    DWORD dwDDFX;
    DWORD dwFlags;
} DDOVERLAYFX,FAR *LPDDOVERLAYFX;

Members

dwSize
Size of the structure, in bytes. This members must be initialized before the structure is used.
dwAlphaEdgeBlendBitDepth
Bit depth used to specify the constant for an alpha edge blend.
dwAlphaEdgeBlend
Constant to use as the alpha for an edge blend.
dwReserved
Reserved for future use.
dwAlphaDestConstBitDepth
Bit depth used to specify the alpha constant for a destination.
dwAlphaDestConst
Constant to use as the alpha channel for a destination.
lpDDSAlphaDest
Address of a surface to use as the alpha channel for a destination.
dwAlphaSrcConstBitDepth
Bit depth used to specify the alpha constant for a source.
dwAlphaSrcConst
Constant to use as the alpha channel for a source.
lpDDSAlphaSrc
Address of a surface to use as the alpha channel for a source.
dckDestColorkey
Destination color key override.
dckSrcColorkey
Source color key override.
dwDDFX
Overlay FX flags.
DDOVERFX_ARITHSTRETCHY
If stretching, use arithmetic stretching along the y-axis for this overlay.
DDOVERFX_MIRRORLEFTRIGHT
Mirror the overlay around the vertical axis.
DDOVERFX_MIRRORUPDOWN
Mirror the overlay around the horizontal axis.
dwFlags
This member is currently not used and must be set to 0.

备注

The unions in this structure have been updated to work with compilers that don't support nameless unions. If your compiler doesn't support nameless unions, define the NONAMELESSUNION token before including the Ddraw.h header file.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDPIXELFORMAT

The DDPIXELFORMAT structure describes the pixel format of a DirectDrawSurface object for the IDirectDrawSurface4::GetPixelFormat method.

typedef struct _DDPIXELFORMAT{
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwFourCC;
    union
    {
        DWORD dwRGBBitCount;
        DWORD dwYUVBitCount;
        DWORD dwZBufferBitDepth;
        DWORD dwAlphaBitDepth;
        DWORD dwLuminanceBitCount; // new for DirectX 6.0
        DWORD dwBumpBitCount;      // new for DirectX 6.0
    } DUMMYUNIONNAMEN(1);
    union
    {
        DWORD dwRBitMask;
        DWORD dwYBitMask;
        DWORD dwStencilBitDepth;   // new for DirectX 6.0
        DWORD dwLuminanceBitMask;  // new for DirectX 6.0
        DWORD dwBumpDuBitMask;     // new for DirectX 6.0
    } DUMMYUNIONNAMEN(2);
    union
    {
        DWORD dwGBitMask;
        DWORD dwUBitMask;
        DWORD dwZBitMask;          // new for DirectX 6.0
        DWORD dwBumpDvBitMask;     // new for DirectX 6.0
    } DUMMYUNIONNAMEN(3);
    union
    {
        DWORD dwBBitMask;
        DWORD dwVBitMask;
        DWORD dwStencilBitMask;    // new for DirectX 6.0
        DWORD dwBumpLuminanceBitMask;  // new for DirectX 6.0
    } DUMMYUNIONNAMEN(4);
    union
    {
        DWORD dwRGBAlphaBitMask;
        DWORD dwYUVAlphaBitMask;
        DWORD dwLuminanceAlphaBitMask; // new for DirectX 6.0
        DWORD dwRGBZBitMask;
        DWORD dwYUVZBitMask;
    } DUMMYUNIONNAMEN(5);
} DDPIXELFORMAT, FAR* LPDDPIXELFORMAT;

Members

dwSize
Size of the structure, in bytes. This member must be initialized before the structure is used.
dwFlags
Optional control flags.
DDPF_ALPHA
The pixel format describes an alpha-only surface.
DDPF_ALPHAPIXELS
The surface has alpha channel information in the pixel format.
DDPF_ALPHAPREMULT
The surface uses the premultiplied alpha format. That is, the color components in each pixel are premultiplied by the alpha component.
DDPF_BUMPLUMINANCE
The luminance data in the pixel format is valid, and the dwLuminanceBitMask member describes valid luminance bits for a luminance-only or luminance-alpha surface.
DDPF_BUMPDUDV
Bump-map data in the pixel format is valid. Bump-map information is in the dwBumpBitCount, dwBumpDuBitMask, dwBumpDvBitMask, and dwBumpLuminanceBitMask members.
DDPF_COMPRESSED
The surface will accept pixel data in the specified format and compress it during the write operation.
DDPF_FOURCC
The dwFourCC member is valid and contains a FOURCC code describing a non-RGB pixel format.
DDPF_LUMINANCE
The pixel format describes a luminance-only or luminance-alpha surface.
DDPF_PALETTEINDEXED1
DDPF_PALETTEINDEXED2
DDPF_PALETTEINDEXED4
DDPF_PALETTEINDEXED8
The surface is 1-, 2-, 4-, or 8-bit color indexed.
DDPF_PALETTEINDEXEDTO8
The surface is 1-, 2-, or 4-bit color indexed to an 8-bit palette.
DDPF_RGB
The RGB data in the pixel format structure is valid.
DDPF_RGBTOYUV
The surface will accept RGB data and translate it during the write operation to YUV data. The format of the data to be written will be contained in the pixel format structure. The DDPF_RGB flag will be set.
DDPF_STENCILBUFFER
The surface encodes stencil and depth information in each pixel of the z-buffer. This flag can only be used if the DDPF_ZBUFFER flag is also specified.
DDPF_YUV
The YUV data in the pixel format structure is valid.
DDPF_ZBUFFER
The pixel format describes a z-buffer surface.
DDPF_ZPIXELS
The surface contains z information in the pixels.
dwFourCC
FourCC code. For more information see, Four Character Codes (FOURCC).
dwRGBBitCount
RGB bits per pixel (4, 8, 16, 24, or 32).
dwYUVBitCount
YUV bits per pixel (4, 8, 16, 24, or 32).
dwZBufferBitDepth
Z-buffer bit depth (8, 16, 24, or 32).
dwAlphaBitDepth
Alpha channel bit depth (1, 2, 4, or 8) for an alpha-only surface (DDPF_ALPHA). For pixel formats that contain alpha information interleaved with color data (DDPF_ALPHAPIXELS), you must count the bits in the dwRGBAlphaBitMask member to obtain the bit-depth of the alpha component. For more information, see 备注.
dwLuminanceBitCount
Total luminance bits per pixel. This member applies only to luminance-only and luminance-alpha surfaces.
dwBumpBitCount
Total bump-map bits per pixel in a bump-map surface.
dwRBitMask
Mask for red bits.
dwYBitMask
Mask for Y bits.
dwStencilBitDepth
Bit depth of the stencil buffer. This member specifies how many bits are reserved within each pixel of the z-buffer for stencil information (the total number of z-bits is equal to dwZBufferBitDepth minus dwStencilBitDepth).
dwLuminanceBitMask
Mask for luminance bits.
dwBumpDuBitMask
Mask for bump-map UΔ bits.
dwGBitMask
Mask for green bits.
dwUBitMask
Mask for U bits.
dwZBitMask
Mask for z bits.
dwBumpDvBitMask
Mask for bump-map VΔ bits.
dwBBitMask
Mask for blue bits.
dwVBitMask
Mask for V bits.
dwStencilBitMask
Mask for stencil bits within each z-buffer pixel.
dwBumpLuminanceBitMask
Mask for luminance in a bump-map pixel.
dwRGBAlphaBitMask and dwYUVAlphaBitMask and dwLuminanceAlphaBitMask
Masks for alpha channel.
dwRGBZBitMask and dwYUVZBitMask
Masks for z channel.

备注

The dwAlphaBitDepth member reflects the bit depth of an alpha-only pixel format (DDPF_ALPHA). For pixel formats that include the alpha component with color components (DDPF_ALPHAPIXELS), the alpha bit depth is obtained by counting the bits in the various mask members. The following example function returns the number of bits set in a given bitmask:

WORD GetNumberOfBits( DWORD dwMask )
{
    WORD wBits = 0;
    while( dwMask )
    {
        dwMask = dwMask & ( dwMask - 1 );
        wBits++;
    }
    return wBits;
}

The unions in this structure have been updated to work with compilers that don't support nameless unions. If your compiler doesn't support nameless unions, define the NONAMELESSUNION token before including the Ddraw.h header file.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.

参阅

Off-Screen Surface Formats


DDSCAPS

The DDSCAPS structure defines the capabilities of a DirectDrawSurface object. This structure is part of the DDCAPS and DDSURFACEDESC structures.

typedef struct _DDSCAPS{
    DWORD dwCaps;
} DDSCAPS, FAR* LPDDSCAPS;

Members

dwCaps
Capabilities of the surface. One or more of the following flags:
DDSCAPS_3D
Unsupported. Use the DDSCAPS_3DDEVICE instead.
DDSCAPS_3DDEVICE
Indicates that this surface can be used for 3-D rendering. Applications can use this flag to ensure that a device that can only render to a certain heap has off-screen surfaces allocated from the correct heap. If this flag is set for a heap, the surface is not allocated from that heap.
DDSCAPS_ALLOCONLOAD
Indicates that memory for the surface is not allocated until the surface is loaded by using the IDirect3DTexture2::Load.
DDSCAPS_ALPHA
Indicates that this surface contains alpha-only information.
DDSCAPS_BACKBUFFER
Indicates that this surface is the back buffer of a surface flipping structure. Typically, this capability is set by the CreateSurface method when the DDSCAPS_FLIP flag is used. Only the surface that immediately precedes the DDSCAPS_FRONTBUFFER surface has this capability set. The other surfaces are identified as back buffers by the presence of the DDSCAPS_FLIP flag, their attachment order, and the absence of the DDSCAPS_FRONTBUFFER and DDSCAPS_BACKBUFFER capabilities. If this capability is sent to the CreateSurface method, a stand-alone back buffer is being created. After this method is called, this surface could be attached to a front buffer, another back buffer, or both to form a flipping surface structure. For more information, see IDirectDrawSurface4::AddAttachedSurface. DirectDraw supports an arbitrary number of surfaces in a flipping structure.
DDSCAPS_COMPLEX
Indicates that a complex surface is being described. A complex surface results in the creation of more than one surface. The additional surfaces are attached to the root surface. The complex structure can be destroyed only by destroying the root.
DDSCAPS_FLIP
Indicates that this surface is a part of a surface flipping structure. When this capability is passed to the CreateSurface method, a front buffer and one or more back buffers are created. DirectDraw sets the DDSCAPS_FRONTBUFFER bit on the front-buffer surface and the DDSCAPS_BACKBUFFER bit on the surface adjacent to the front-buffer surface. The dwBackBufferCount member of the DDSURFACEDESC structure must be set to at least 1 in order for the method call to succeed. The DDSCAPS_COMPLEX capability must always be set when creating multiple surfaces by using the CreateSurface method.
DDSCAPS_FRONTBUFFER
Indicates that this surface is the front buffer of a surface flipping structure. This flag is typically set by the CreateSurface method when the DDSCAPS_FLIP capability is set. If this capability is sent to the CreateSurface method, a stand-alone front buffer is created. This surface will not have the DDSCAPS_FLIP capability. It can be attached to other back buffers to form a flipping structure by using IDirectDrawSurface4::AddAttachedSurface.
DDSCAPS_HWCODEC
Indicates that this surface should be able to have a stream decompressed to it by the hardware.
DDSCAPS_LIVEVIDEO
Indicates that this surface should be able to receive live video.
DDSCAPS_LOCALVIDMEM
Indicates that this surface exists in true, local video memory rather than non-local video memory. If this flag is specified then DDSCAPS_VIDEOMEMORY must be specified as well. This flag cannot be used with the DDSCAPS_NONLOCALVIDMEM flag.
DDSCAPS_MIPMAP
Indicates that this surface is one level of a mipmap. This surface will be attached to other DDSCAPS_MIPMAP surfaces to form the mipmap. This can be done explicitly by creating a number of surfaces and attaching them by using the IDirectDrawSurface4::AddAttachedSurface method, or implicitly by the CreateSurface method. If this capability is set, DDSCAPS_TEXTURE must also be set.
DDSCAPS_MODEX
Indicates that this surface is a 320×200 or 320×240 Mode X surface.
DDSCAPS_NONLOCALVIDMEM
Indicates that this surface exists in non-local video memory rather than true, local video memory. If this flag is specified, then DDSCAPS_VIDEOMEMORY flag must be specified as well. This cannot be used with the DDSCAPS_LOCALVIDMEM flag.
DDSCAPS_OFFSCREENPLAIN
Indicates that this surface is any off-screen surface that is not an overlay, texture, z-buffer, front-buffer, back-buffer, or alpha surface. It is used to identify plain surfaces.
DDSCAPS_OPTIMIZED
Not currently implemented.
DDSCAPS_OVERLAY
Indicates that this surface is an overlay. It may or may not be directly visible depending on whether it is currently being overlaid onto the primary surface. DDSCAPS_VISIBLE can be used to determine if it is being overlaid at the moment.
DDSCAPS_OWNDC
Indicates that this surface will have a device context (DC) association for a long period.
DDSCAPS_PALETTE
Indicates that this device driver allows unique DirectDrawPalette objects to be created and attached to this surface.
DDSCAPS_PRIMARYSURFACE
Indicates the surface is the primary surface. It represents what is visible to the user at the moment.
DDSCAPS_PRIMARYSURFACELEFT
Indicates that this surface is the primary surface for the left eye. It represents what is visible to the user's left eye at the moment. When this surface is created, the surface with the DDSCAPS_PRIMARYSURFACE capability represents what is seen by the user's right eye.
DDSCAPS_STANDARDVGAMODE
Indicates that this surface is a standard VGA mode surface, and not a Mode X surface. This flag cannot be used in combination with the DDSCAPS_MODEX flag.
DDSCAPS_SYSTEMMEMORY
Indicates that this surface memory was allocated in system memory.
DDSCAPS_TEXTURE
Indicates that this surface can be used as a 3-D texture. It does not indicate whether the surface is being used for that purpose.
DDSCAPS_VIDEOMEMORY
Indicates that this surface exists in display memory.
DDSCAPS_VIDEOPORT
Indicates that this surface can receive data from a video port.
DDSCAPS_VISIBLE
Indicates that changes made to this surface are immediately visible. It is always set for the primary surface, as well as for overlays while they are being overlaid and texture maps while they are being textured.
DDSCAPS_WRITEONLY
Indicates that only write access is permitted to the surface. Read access from the surface may generate a general protection (GP) fault, but the read results from this surface will not be meaningful.
DDSCAPS_ZBUFFER
Indicates that this surface is the z-buffer. The z-buffer contains information that cannot be displayed. Instead, it contains bit-depth information that is used to determine which pixels are visible and which are obscured.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDSCAPS2

The DDSCAPS2 structure defines the capabilities of a DirectDrawSurface object. This structure is part of the DDSURFACEDESC2 structure.

typedef struct _DDSCAPS2 {
    DWORD    dwCaps;   // Surface capabilities
    DWORD    dwCaps2;  // More surface capabilities
    DWORD    dwCaps3;  // Not currently used
    DWORD    dwCaps4;  // .
} DDSCAPS2, FAR* LPDDSCAPS2;

Members

dwCaps
One or more flag values representing the capabilities of the surface. (The flags in this member are identical to those in the corresponding member of the DDSCAPS structure.)
DDSCAPS_3D
Unsupported. Use the DDSCAPS_3DDEVICE instead.
DDSCAPS_3DDEVICE
Indicates that this surface can be used for 3-D rendering. Applications can use this flag to ensure that a device that can only render to a certain heap has off-screen surfaces allocated from the correct heap. If this flag is set for a heap, the surface is not allocated from that heap.
DDSCAPS_ALLOCONLOAD
Indicates that memory for the surface is not allocated until the surface is loaded by using the IDirect3DTexture2::Load.
DDSCAPS_ALPHA
Indicates that this surface contains alpha-only information.
DDSCAPS_BACKBUFFER
Indicates that this surface is the back buffer of a surface flipping structure. Typically, this capability is set by the CreateSurface method when the DDSCAPS_FLIP flag is used. Only the surface that immediately precedes the DDSCAPS_FRONTBUFFER surface has this capability set. The other surfaces are identified as back buffers by the presence of the DDSCAPS_FLIP flag, their attachment order, and the absence of the DDSCAPS_FRONTBUFFER and DDSCAPS_BACKBUFFER capabilities. If this capability is sent to the CreateSurface method, a stand-alone back buffer is being created. After this method is called, this surface could be attached to a front buffer, another back buffer, or both to form a flipping surface structure. For more information, see IDirectDrawSurface4::AddAttachedSurface. DirectDraw supports an arbitrary number of surfaces in a flipping structure.
DDSCAPS_COMPLEX
Indicates that a complex surface is being described. A complex surface results in the creation of more than one surface. The additional surfaces are attached to the root surface. The complex structure can be destroyed only by destroying the root.
DDSCAPS_FLIP
Indicates that this surface is a part of a surface flipping structure. When this capability is passed to the CreateSurface method, a front buffer and one or more back buffers are created. DirectDraw sets the DDSCAPS_FRONTBUFFER bit on the front-buffer surface and the DDSCAPS_BACKBUFFER bit on the surface adjacent to the front-buffer surface. The dwBackBufferCount member of the DDSURFACEDESC structure must be set to at least 1 in order for the method call to succeed. The DDSCAPS_COMPLEX capability must always be set when creating multiple surfaces by using the CreateSurface method.
DDSCAPS_FRONTBUFFER
Indicates that this surface is the front buffer of a surface flipping structure. This flag is typically set by the CreateSurface method when the DDSCAPS_FLIP capability is set. If this capability is sent to the CreateSurface method, a stand-alone front buffer is created. This surface will not have the DDSCAPS_FLIP capability. It can be attached to other back buffers to form a flipping structure by using IDirectDrawSurface4::AddAttachedSurface.
DDSCAPS_HWCODEC
Indicates that this surface should be able to have a stream decompressed to it by the hardware.
DDSCAPS_LIVEVIDEO
Indicates that this surface should be able to receive live video.
DDSCAPS_LOCALVIDMEM
Indicates that this surface exists in true, local video memory rather than non-local video memory. If this flag is specified then DDSCAPS_VIDEOMEMORY must be specified as well. This flag cannot be used with the DDSCAPS_NONLOCALVIDMEM flag.
DDSCAPS_MIPMAP
Indicates that this surface is one level of a mipmap. This surface will be attached to other DDSCAPS_MIPMAP surfaces to form the mipmap. This can be done explicitly by creating a number of surfaces and attaching them by using the IDirectDrawSurface4::AddAttachedSurface method, or implicitly by the CreateSurface method. If this capability is set, DDSCAPS_TEXTURE must also be set.
DDSCAPS_MODEX
Indicates that this surface is a 320×200 or 320×240 Mode X surface.
DDSCAPS_NONLOCALVIDMEM
Indicates that this surface exists in non-local video memory rather than true, local video memory. If this flag is specified, then DDSCAPS_VIDEOMEMORY flag must be specified as well. This cannot be used with the DDSCAPS_LOCALVIDMEM flag.
DDSCAPS_OFFSCREENPLAIN
Indicates that this surface is any off-screen surface that is not an overlay, texture, z-buffer, front-buffer, back-buffer, or alpha surface. It is used to identify plain surfaces.
DDSCAPS_OPTIMIZED
Not currently implemented.
DDSCAPS_OVERLAY
Indicates that this surface is an overlay. It may or may not be directly visible depending on whether it is currently being overlaid onto the primary surface. DDSCAPS_VISIBLE can be used to determine if it is being overlaid at the moment.
DDSCAPS_OWNDC
Indicates that this surface will have a device context (DC) association for a long period.
DDSCAPS_PALETTE
Indicates that this device driver allows unique DirectDrawPalette objects to be created and attached to this surface.
DDSCAPS_PRIMARYSURFACE
Indicates the surface is the primary surface. It represents what is visible to the user at the moment.
DDSCAPS_PRIMARYSURFACELEFT
Indicates that this surface is the primary surface for the left eye. It represents what is visible to the user's left eye at the moment. When this surface is created, the surface with the DDSCAPS_PRIMARYSURFACE capability represents what is seen by the user's right eye.
DDSCAPS_STANDARDVGAMODE
Indicates that this surface is a standard VGA mode surface, and not a Mode X surface. This flag cannot be used in combination with the DDSCAPS_MODEX flag.
DDSCAPS_SYSTEMMEMORY
Indicates that this surface memory was allocated in system memory.
DDSCAPS_TEXTURE
Indicates that this surface can be used as a 3-D texture. It does not indicate whether the surface is being used for that purpose.
DDSCAPS_VIDEOMEMORY
Indicates that this surface exists in display memory.
DDSCAPS_VIDEOPORT
Indicates that this surface can receive data from a video port.
DDSCAPS_VISIBLE
Indicates that changes made to this surface are immediately visible. It is always set for the primary surface, as well as for overlays while they are being overlaid and texture maps while they are being textured.
DDSCAPS_WRITEONLY
Indicates that only write access is permitted to the surface. Read access from the surface may generate a general protection (GP) fault, but the read results from this surface will not be meaningful.
DDSCAPS_ZBUFFER
Indicates that this surface is the z-buffer. The z-buffer contains information that cannot be displayed. Instead, it contains bit-depth information that is used to determine which pixels are visible and which are obscured.
dwCaps2
Additional surface capabilities. This member can contain one or more of the following capability flags or, when using this structure with the IDirectDrawSurface4::SetSurfaceDesc method, this member can contain an additional flag to indicate how the surface memory was allocated:
Capability flags
DDSCAPS2_HARDWAREDEINTERLACE
Indicates that this surface will receive data from a video port using the de-interlacing hardware. This allows the driver to allocate memory for any extra buffers that may be required. The DDSCAPS_VIDEOPORT and DDSCAPS_OVERLAY flags must also be set.
DDSCAPS2_HINTANTIALIASING
Indicates that the application intends to use antialiasing. Only valid if DDSCAPS_3DDEVICE is also set.
DDSCAPS2_HINTDYNAMIC
Indicates to the driver that this surface will be locked very frequently (for procedural textures, dynamic light maps, and so on). This flag can only be used for texture surfaces (DDSCAPS_TEXTURE flag set in the dwCaps member). This flag cannot be used with the DDSCAPS2_HINTSTATIC or DDSCAPS2_OPAQUE flags.
DDSCAPS2_HINTSTATIC
Indicates to the driver that this surface can be reordered or retiled on load. This operation will not change the size of the texture. It is relatively fast and symmetrical, since the application may lock these bits (although it will take a performance hit when doing so).

This flag can only be used for texture surfaces (DDSCAPS_TEXTURE flag set in the dwCaps member). This flag cannot be used with the DDSCAPS2_HINTDYNAMIC or DDSCAPS2_OPAQUE flags.

DDSCAPS2_OPAQUE
Indicates to the driver that this surface will never be locked again. The driver is free to optimize this surface by retiling and actual compression. Such a surface cannot be locked or used in blit operations, attempts to lock or blit a surface with this capability will fail. This flag can only be used for texture surfaces (DDSCAPS_TEXTURE flag set in the dwCaps member). This flag cannot be used with the DDSCAPS2_HINTDYNAMIC or DDSCAPS2_HINTSTATIC flags.
DDSCAPS2_TEXTUREMANAGE
Indicates that the client would like this texture surface to be managed by DirectDraw and Direct3D Immediate Mode. This flag can only be used for texture surfaces (DDSCAPS_TEXTURE flag set in the dwCaps member). For more information, see Automatic Texture Management in the Direct3D Immediate Mode documentation. Do not use this flag if your application uses Direct3D Retained Mode. Instead, create textures in system memory and allow Retained Mode to manage them.
dwCaps3 and dwCaps4
Not currently used.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDSURFACEDESC

The DDSURFACEDESC structure contains a description of a surface. This structure is passed to the IDirectDraw2::CreateSurface method. The relevant members differ for each potential type of surface.

When using the IDirectDraw4 interface, this structure is superseded by the DDSURFACEDESC2 structure.

typedef struct _DDSURFACEDESC {
    DWORD          dwSize;
    DWORD          dwFlags;
    DWORD          dwHeight;
    DWORD          dwWidth;
    union
    {
        LONG       lPitch;
        DWORD      dwLinearSize;
    };
    DWORD          dwBackBufferCount;
    union
    {
        DWORD      dwMipMapCount;
        DWORD      dwZBufferBitDepth;
        DWORD      dwRefreshRate;
    };
    DWORD          dwAlphaBitDepth;
    DWORD          dwReserved;
    LPVOID         lpSurface;
    DDCOLORKEY     ddckCKDestOverlay;
    DDCOLORKEY     ddckCKDestBlt;
    DDCOLORKEY     ddckCKSrcOverlay;
    DDCOLORKEY     ddckCKSrcBlt;
    DDPIXELFORMAT  ddpfPixelFormat;
    DDSCAPS        ddsCaps;
} DDSURFACEDESC, FAR* LPDDSURFACEDESC;

Members

dwSize
Size of the structure, in bytes. This member must be initialized before the structure is used.
dwFlags
Optional control flags. One or more of the following flags:
DDSD_ALL
Indicates that all input members are valid.
DDSD_ALPHABITDEPTH
Indicates that the dwAlphaBitDepth member is valid.
DDSD_BACKBUFFERCOUNT
Indicates that the dwBackBufferCount member is valid.
DDSD_CAPS
Indicates that the ddsCaps member is valid.
DDSD_CKDESTBLT
Indicates that the ddckCKDestBlt member is valid.
DDSD_CKDESTOVERLAY
Indicates that the ddckCKDestOverlay member is valid.
DDSD_CKSRCBLT
Indicates that the ddckCKSrcBlt member is valid.
DDSD_CKSRCOVERLAY
Indicates that the ddckCKSrcOverlay member is valid.
DDSD_HEIGHT
Indicates that the dwHeight member is valid.
DDSD_LINEARSIZE
Indicates that dwLinearSize member is valid.
DDSD_LPSURFACE
Indicates that the lpSurface member is valid.
DDSD_MIPMAPCOUNT
Indicates that the dwMipMapCount member is valid.
DDSD_PITCH
Indicates that the lPitch member is valid.
DDSD_PIXELFORMAT
Indicates that the ddpfPixelFormat member is valid.
DDSD_REFRESHRATE
Indicates that the dwRefreshRate member is valid.
DDSD_WIDTH
Indicates that the dwWidth member is valid.
DDSD_ZBUFFERBITDEPTH
Indicates that the dwZBufferBitDepth member is valid.
dwHeight and dwWidth
Dimensions of the surface to be created, in pixels.
lPitch
Distance, in bytes, to the start of next line. When used with the IDirectDrawSurface4::GetSurfaceDesc method, this is a return value. When creating a surface from existing memory or when calling the IDirectDrawSurface4::SetSurfaceDesc method, this is an input value that must be a DWORD multiple.
dwLinearSize
The size of the buffer. Currently returned only for compressed texture surfaces.
dwBackBufferCount
Number of back buffers.
dwMipMapCount
Number of mipmap levels.
dwZBufferBitDepth
Depth of z-buffer. This member is obsolete for DirectX 6.0 and later. Use the IDirect3D3::EnumZBufferFormats to retrieve information about supported depth buffer formats.
dwRefreshRate
Refresh rate (used when the display mode is described). The value of 0 indicates an adapter fault.
dwAlphaBitDepth
Depth of alpha buffer.
dwReserved
Reserved.
lpSurface
Address of the associated surface memory. When calling IDirectDrawSurface4::Lock, this member contains a valid pointer to surface memory after the call returns. When creating a surface from existing memory or when using the IDirectDrawSurface4::SetSurfaceDesc method, this member is an input value that is the address of system memory allocated by the calling application. Do not set this member if your application needs DirectDraw to allocate and manage surface memory.
ddckCKDestOverlay
DDCOLORKEY structure that describes the destination color key to be used for an overlay surface.
ddckCKDestBlt
DDCOLORKEY structure that describes the destination color key for blit operations.
ddckCKSrcOverlay
DDCOLORKEY structure that describes the source color key to be used for an overlay surface.
ddckCKSrcBlt
DDCOLORKEY structure that describes the source color key for blit operations.
ddpfPixelFormat
DDPIXELFORMAT structure that describes the surface's pixel format.
ddsCaps
DDSCAPS structure containing the surface's capabilities.

备注

This structure is similar to the DDSURFACEDESC2 structure, but contains a DDSCAPS structure as the ddsCaps member, rather than a DDSCAPS2 structure. Unlike DDSURFACEDESC2, this structure contains the dwZBufferBitDepth member.

QuickInfo

Windows NT/2000: Requires Windows NT 4.0 SP3 or later.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDSURFACEDESC2

The DDSURFACEDESC2 structure contains a description of a surface. This structure is used to pass surface parameters to the IDirectDraw4::CreateSurface and IDirectDrawSurface4::SetSurfaceDesc methods. It is also used to retrieve information about a surface in calls to IDirectDrawSurface4::Lock and IDirectDrawSurface4::GetSurfaceDesc. The relevant members differ for each potential type of surface.

typedef struct _DDSURFACEDESC2 {
    DWORD         dwSize;
    DWORD         dwFlags;
    DWORD         dwHeight;
    DWORD         dwWidth;
    union
    {
        LONG      lPitch;
        DWORD     dwLinearSize;
    } DUMMYUNIONNAMEN(1);
    DWORD         dwBackBufferCount;
    union
    {
        DWORD     dwMipMapCount;
        DWORD     dwRefreshRate;
    } DUMMYUNIONNAMEN(2);
    DWORD         dwAlphaBitDepth;
    DWORD         dwReserved;
    LPVOID        lpSurface;
    DDCOLORKEY    ddckCKDestOverlay;
    DDCOLORKEY    ddckCKDestBlt;
    DDCOLORKEY    ddckCKSrcOverlay;
    DDCOLORKEY    ddckCKSrcBlt;
    DDPIXELFORMAT ddpfPixelFormat;
    DDSCAPS2      ddsCaps;
    DWORD         dwTextureStage;
} DDSURFACEDESC2, FAR* LPDDSURFACEDESC2;

Members

dwSize
Size of the structure, in bytes. This member must be initialized before the structure is used.
dwFlags
Optional control flags. One or more of the following flags:
DDSD_ALL
Indicates that all input members are valid.
DDSD_ALPHABITDEPTH
Indicates that the dwAlphaBitDepth member is valid.
DDSD_BACKBUFFERCOUNT
Indicates that the dwBackBufferCount member is valid.
DDSD_CAPS
Indicates that the ddsCaps member is valid.
DDSD_CKDESTBLT
Indicates that the ddckCKDestBlt member is valid.
DDSD_CKDESTOVERLAY
Indicates that the ddckCKDestOverlay member is valid.
DDSD_CKSRCBLT
Indicates that the ddckCKSrcBlt member is valid.
DDSD_CKSRCOVERLAY
Indicates that the ddckCKSrcOverlay member is valid.
DDSD_HEIGHT
Indicates that the dwHeight member is valid.
DDSD_LINEARSIZE
Indicates that the dwLinearSize member is valid.
DDSD_LPSURFACE
Indicates that the lpSurface member is valid.
DDSD_MIPMAPCOUNT
Indicates that the dwMipMapCount member is valid.
DDSD_PITCH
Indicates that the lPitch member is valid.
DDSD_PIXELFORMAT
Indicates that the ddpfPixelFormat member is valid.
DDSD_REFRESHRATE
Indicates that the dwRefreshRate member is valid.
DDSD_TEXTURESTAGE
Indicates that the dwTextureStage member is valid.
DDSD_WIDTH
Indicates that the dwWidth member is valid.
DDSD_ZBUFFERBITDEPTH
Obsolete; see remarks.
dwHeight and dwWidth
Dimensions of the surface to be created, in pixels.
lPitch
Distance, in bytes, to the start of next line. When used with the IDirectDrawSurface4::GetSurfaceDesc method, this is a return value. When used with the IDirectDrawSurface4::SetSurfaceDesc method, this is an input value that must be a DWORD multiple. See remarks for more information.
dwLinearSize
The size of the buffer. Currently returned only for compressed texture surfaces.
dwBackBufferCount
Number of back buffers.
dwMipMapCount
Number of mipmap levels.
dwRefreshRate
Refresh rate (used when the display mode is described). The value of 0 indicates an adapter fault.
dwAlphaBitDepth
Depth of alpha buffer.
dwReserved
Reserved.
lpSurface
Address of the associated surface memory. When calling IDirectDrawSurface4::Lock, this member is a valid pointer to surface memory. When calling IDirectDrawSurface4::SetSurfaceDesc, this member is a pointer to system memory that the caller explicitly allocates for the DirectDrawSurface object. See remarks for more information.
ddckCKDestOverlay
DDCOLORKEY structure that describes the destination color key to be used for an overlay surface.
ddckCKDestBlt
DDCOLORKEY structure that describes the destination color key for blit operations.
ddckCKSrcOverlay
DDCOLORKEY structure that describes the source color key to be used for an overlay surface.
ddckCKSrcBlt
DDCOLORKEY structure that describes the source color key for blit operations.
ddpfPixelFormat
DDPIXELFORMAT structure that describes the surface's pixel format.
ddsCaps
DDSCAPS2 structure containing the surface's capabilities.
dwTextureStage
Stage identifier used to bind a texture to a specific stage in 3-D device's multitexture cascade. Although not required for all hardware, setting this member is recommended for best performance on the largest variety of 3-D accelerators. Hardware that requires explicitly assigned textures will expose the D3DDEVCAPS_SEPARATETEXTUREMEMORIES 3-D device capability in the D3DDEVICEDESC structure that is filled by the IDirect3DDevice3::GetCaps method.

备注

The lPitch and lpSurface members are output values when calling the IDirectDrawSurface4::GetSurfaceDesc method. When creating surfaces from existing memory, or updating surface characteristics, these members are input values that describe the pitch and location of memory allocated by the calling application for use by DirectDraw. DirectDraw does not attempt to manage or free memory allocated by the application. For more information, see Creating Client Memory Surfaces and Updating Surface Characteristics.

This structure is nearly identical to the DDSURFACEDESC structure, but contains a DDSCAPS2 structure as the ddsCaps member. Unlike DDSURFACEDESC, this structure doesn't contain the dwZBufferBitDepth member. Z-buffer depth is provided in the ddpfPixelFormat member.

The unions in this structure were written to work with compilers that don't support nameless unions. If your compiler doesn't support nameless unions, define the NONAMELESSUNION token before including the Ddraw.h header file.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in ddraw.h.


DDVIDEOPORTBANDWIDTH

The DDVIDEOPORTBANDWIDTH structure describes the bandwidth characteristics of an overlay surface when used with a particular video port and pixel format configuration. This structure is used with the IDirectDrawVideoPort::GetBandwidthInfo method.

typedef struct _DDVIDEOPORTBANDWIDTH {
    DWORD dwSize;
    DWORD dwCaps;
    DWORD dwOverlay;
    DWORD dwColorkey;
    DWORD dwYInterpolate;
    DWORD dwYInterpAndColorkey;
    DWORD dwReserved1;
    DWORD dwReserved2;
} DDVIDEOPORTBANDWIDTH,*LPDDVIDEOPORTBANDWIDTH;

Members

dwSize
Size of this structure, in bytes. This member must be initialized before use.
dwCaps
Flag values specifying device dependency. This member can be one of the following values:
DDVPBCAPS_DESTINATION
This device's capabilities are described in terms of the overlay's minimum stretch factor. Bandwidth information provided for this device refers to the destination overlay size.
DDVPBCAPS_SOURCE
This device's capabilities are described in terms of the required source overlay size. Bandwidth information provided for this device refers to the source overlay size.
dwOverlay
Stretch factor or overlay source size at which an overlay is supported multiplied by 1000. For example 1.3 = 1300, or .75 = 750.
dwColorkey
Stretch factor or overlay source size at which an overlay with color keying is supported multiplied by 1000. For example 1.3 = 1300, or .75 = 750.
dwYInterpolate
Stretch factor or overlay source size at which an overlay with y-axis interpolation is supported multiplied by 1000. For example 1.3 = 1300, or .75 = 750.
dwYInterpAndColorkey
Stretch factor or overlay source size at which an overlay with y-axis interpolation and color keying is supported multiplied by 1000. For example 1.3 = 1300, or .75 = 750.
dwReserved1 and dwReserved2
Reserved; set to zero.

备注

When DDVPBCAPS_DESTINATION is specified, the stretch factors described in the other members describe the minimum stretch factor required to display an overlay with the dimensions given when calling the GetBandwidthInfo method. Stretch factor values under 1000 mean that the video port is capable of shrinking an overlay when displayed, and values over 1000 mean that the overlay must be stretched larger than their source to be displayed.

When DDVPBCAPS_SOURCE is specified, the stretch factors described in the other members describe how much you must shrink the overlay source in order for it to be displayed. In this case, the best possible value is 1000, meaning that no shrinking is required. Smaller values tell you that the source rectangle you specified when calling GetBandwidthInfo were too large and must be smaller. For example, if the stretch factor is 750 and you specified 320 pixels for the dwWidth parameter, then you will not be able to display the overlay at that size. To successfully display the overlay, you must use a source rectangle 240 pixels wide to successfully display the overlay.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.


DDVIDEOPORTCAPS

The DDVIDEOPORTCAPS structure describes the capabilities and alignment restrictions of a video port. This structure is used with the IDDVideoPortContainer::EnumVideoPorts method.

typedef struct _DDVIDEOPORTCAPS {
    DWORD dwSize;
    DWORD dwFlags;
    DWORD dwMaxWidth;
    DWORD dwMaxVBIWidth;
    DWORD dwMaxHeight;
    DWORD dwVideoPortID;
    DWORD dwCaps;
    DWORD dwFX;
    DWORD dwNumAutoFlipSurfaces;
    DWORD dwAlignVideoPortBoundary;
    DWORD dwAlignVideoPortPrescaleWidth;
    DWORD dwAlignVideoPortCropBoundary;
    DWORD dwAlignVideoPortCropWidth;
    DWORD dwPreshrinkXStep;
    DWORD dwPreshrinkYStep;
    DWORD dwNumVBIAutoFlipSurfaces;
    DWORD dwNumPreferredAutoflip;
    WORD  wNumFilterTapsX;
    WORD  wNumFilterTapsY;
} DDVIDEOPORTCAPS, *LPDDVIDEOPORTCAPS;

Members

dwSize
Size of the structure, in bytes. This must be initialized before use.
dwFlags
Flag values indicating the fields that contain valid data. The following flags are defined:
DDVPD_AUTOFLIP
The dwNumAutoFlipSurfaces member is valid.
DDVPD_ALIGN
The dwAlignVideoPortBoundary, dwAlignVideoPortPrescaleWidth, dwAlignVideoPortCropBoundary, and dwAlignVideoPortCropWidth are valid.
DDVPD_CAPS
The dwCaps member is valid.
DDVPD_FILTERQUALITY
The wNumFilterTapsX and wNumFilterTapsY members are valid.
DDVPD_FX
The dwFX member is valid.
DDVPD_HEIGHT
The dwMaxHeight member is valid.
DDVPD_ID
The dwVideoPortID member is valid.
DDVPD_PREFERREDAUTOFLIP
The dwNumPreferredAutoflip member is valid.
DDVPD_WIDTH
The dwMaxWidth member is valid.
dwMaxWidth
Maximum width of the video port field.
dwMaxVBIWidth
Maximum width of the VBI data.
dwMaxHeight
Maximum height of the video port field.
dwVideoPortID
Zero-based index identifying the video port.
dwCaps
Video port capabilities.
DDVPCAPS_AUTOFLIP
Flip can be performed automatically to avoid tearing when a VREF occurs. If the data is being interleaved in memory, it will flip on every other VREF.
DDVPCAPS_COLORCONTROL
Can perform color control operations on incoming data before writing to the frame buffer.
DDVPCAPS_INTERLACED
Supports interlaced video.
DDVPCAPS_NONINTERLACED
Supports non-interlaced video.
DDVPCAPS_OVERSAMPLEDVBI
Can accept VBI data in a different format or width than the regular video data.
DDVPCAPS_READBACKFIELD
Supports the IDirectDrawVideoPort::GetFieldPolarity method.
DDVPCAPS_READBACKLINE
Supports the IDirectDrawVideoPort::GetVideoLine method.
DDVPCAPS_SHAREABLE
Supports two genlocked video streams that share the video port, where one stream uses the even fields and the other uses the odd fields. Separate parameters (including address, scaling, cropping, and so on) are maintained for both fields.
DDVPCAPS_SKIPEVENFIELDS
Even fields of video can be automatically discarded.
DDVPCAPS_SKIPODDFIELDS
Odd fields of video can be automatically discarded.
DDVPCAPS_SYNCMASTER
Can drive the graphics sync (refresh rate) based on the video port sync.
DDVPCAPS_SYSTEMMEMORY
Capable of writing to surfaces created in system memory.
DDVPCAPS_VBIANDVIDEOINDEPENDENT
Indicates that the VBI and video portions of the video stream can be controlled by independent processes.
DDVPCAPS_VBISURFACE
Data within the VBI can be written to a different surface.
dwFX
Additional video port capabilities.
DDVPFX_CROPTOPDATA
Limited cropping is available to crop VBI data.
DDVPFX_CROPX
Incoming data can be cropped in the x-direction before it is written to the surface.
DDVPFX_CROPY
Incoming data can be cropped in the y-direction before it is written to the surface.
DDVPFX_IGNOREVBIXCROP
The video port can ignore the left and right cropping coordinates when cropping oversampled VBI data.
DDVPFX_INTERLEAVE
Supports interleaving interlaced fields in memory.
DDVPFX_MIRRORLEFTRIGHT
Supports mirroring left to right as the video data is written into the frame buffer.
DDVPFX_MIRRORUPDOWN
Supports mirroring top to bottom as the video data is written into the frame buffer.
DDVPFX_PRESHRINKX
Data can be arbitrarily shrunk in the x-direction before it is written to the surface.
DDVPFX_PRESHRINKY
Data can be arbitrarily shrunk in the y-direction before it is written to the surface.
DDVPFX_PRESHRINKXB
Data can be binary shrunk (1/2, 1/4, 1/8, and so on) in the x-direction before it is written to the surface.
DDVPFX_PRESHRINKYB
Data can be binary shrunk (1/2, 1/4, 1/8, and so on) in the y-direction before it is written to the surface.
DDVPCAPS_PRESHRINKXS
Data can be shrunk in the x-direction by increments of 1/x, where x is specified in the dwShrinkXStep member.
DDVPCAPS_PRESHRINKYS
Data can be shrunk in the y-direction by increments of 1/y, where y is specified in the dwShrinkYStep
DDVPFX_PRESTRETCHX
Data can be arbitrarily stretched in the x-direction before it is written to the surface.
DDVPFX_PRESTRETCHY
Data can be arbitrarily stretched in the y-direction before it is written to the surface.
DDVPFX_PRESTRETCHXN
Data can be integer stretched in the x-direction before it is written to the surface. (1x, 2x, 3x, and so forth)
DDVPFX_PRESTRETCHYN
Data can be integer stretched in the y-direction before it is written to the surface. (1x, 2x, 3x, and so forth)
DDVPFX_VBICONVERT
Data within the VBI can be converted independently of the remaining video data.
DDVPFX_VBINOINTERLEAVE
Interleaving can be disabled for data within the VBI.
DDVPFX_VBINOSCALE
Scaling can be disabled for data within the VBI.
dwNumAutoFlipSurfaces
Maximum number of auto-flippable surfaces supported by the video port.
dwAlignVideoPortBoundary
Byte restriction of placement within the surface.
dwAlignVideoPortPrescaleWidth
Byte restriction of width after prescaling.
dwAlignVideoPortCropBoundary
Byte restriction of left cropping.
dwAlignVideoPortCropWidth
Byte restriction of cropping width.
dwPreshrinkXStep
Width can be shrunk in the x-direction in steps of 1/dwPreshrinkXStep.
dwPreshrinkYStep
Height can be shrunk in the y-direction in steps of 1/dwPreshrinkYStep.
dwNumVBIAutoFlipSurfaces
Maximum number of auto-flipping surfaces capable of receiving data transmitted during the vertical blanking interval (VBI) independent from the remainder of the video stream. When constructing the auto-flip chain, the number of VBI surfaces must equal the number of surfaces receiving the remainder of the video data.
dwNumPreferredAutoflip
Optimal number of auto-flippable surfaces supported by the hardware.
wNumFilterTapsX and wNumFilterTapsY
Number of taps the prescaler filter uses in the x- and y-directions. The value of 0 indicates that no prescaling is performed in that direction, 1 indicates that the prescaler performs replication, 2 indicates that the prescaler uses two taps, and so on.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.


DDVIDEOPORTCONNECT

The DDVIDEOPORTCONNECT structure describes a video port connection. This structure is used with the IDDVideoPortContainer::GetVideoPortConnectInfo method.

typedef struct _DDVIDEOPORTCONNECT{
    DWORD dwSize;
    DWORD dwPortWidth;
    GUID  guidTypeID;
    DWORD dwFlags;
    ULONG_PTR dwReserved1;
} DDVIDEOPORTCONNECT,*LPDDVIDEOPORTCONNECT;

Members

dwSize
Size of the structure, in bytes. This member must be initialized before use.
dwPortWidth
Width of the video port. This value represents the number of physical pins on the video port, not the width of a surface in memory. This member must always be set, even when the value in the guidTypeID member assumes a certain size.
guidTypeID
A GUID that describes the sync characteristics of the video port. The following port types are predefined:
DDVPTYPE_E_HREFH_VREFH
External syncs where HREF is active high and VREF is active high.
DDVPTYPE_E_HREFH_VREFL
External syncs where HREF is active high and VREF is active low.
DDVPTYPE_E_HREFL_VREFH
External syncs where HREF is active low and VREF is active high.
DDVPTYPE_E_HREFL_VREFL
External syncs where HREF is active low and VREF is active low.
DDVPTYPE_CCIR656
Sync information is embedded in the data stream according to the CCIR656 specification.
DDVPTYPE_BROOKTREE
Sync information is embedded in the data stream using the Brooktree definition.
DDVPTYPE_PHILIPS
Sync information is embedded in the data stream using the Philips definition.
dwFlags
Flags describing the capabilities of the video-port connection. This member can be set by DirectDraw when connection information is being retrieved or by the client when connection information is being set. This member can be a combination of the following flags:
DDVPCONNECT_DOUBLECLOCK
Indicates that the video port either supports double-clocking data or should double-clock data. This flag is only valid with an external sync.
DDVPCONNECT_VACT
Indicates that the video port either supports using an external VACT signal or should use the external VACT signal. This flag is only valid with an external sync.
DDVPCONNECT_INVERTPOLARITY
Indicates that the video port is capable of inverting the field polarities or is to invert field polarities.

When a video port inverts field polarities, it treats even fields as odd fields and vice versa.

DDVPCONNECT_DISCARDSVREFDATA
The video port discards any data written during the VREF period, causing it to not be written to the frame buffer. This flag is read-only.
DDVPCONNECT_HALFLINE
The video port will write half lines into the frame buffer, sometimes causing the data to be displayed incorrectly. This flag is read-only.
DDVPCONNECT_INTERLACED
Indicates that the signal is interlaced. This flag is only used by the client when creating a video port object.
DDVPCONNECT_SHAREEVEN
The physical video port is shareable, and that this video port object will use the even fields. This flag is only used by the client when creating the video port object.
DDVPCONNECT_SHAREODD
The physical video port is shareable, and that this video port object will use the odd fields. This flag is only used by the client when creating the video port object.
dwReserved1
Reserved; set to zero.

备注

This structure is used independently and as a member of the DDVIDEOPORTDESC structure.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.


DDVIDEOPORTDESC

The DDVIDEOPORTDESC structure describes a video-port object to be created. This structure is used with the IDDVideoPortContainer::CreateVideoPort method.

typedef struct _DDVIDEOPORTDESC {
    DWORD dwSize;
    DWORD dwFieldWidth;
    DWORD dwVBIWidth;
    DWORD dwFieldHeight;
    DWORD dwMicrosecondsPerField;
    DWORD dwMaxPixelsPerSecond;
    DWORD dwVideoPortID;
    DWORD dwReserved1;
    DDVIDEOPORTCONNECT VideoPortType;
    ULONG_PTR dwReserved2;
    ULONG_PTR dwReserved3;
 } DDVIDEOPORTDESC, *LPDDVIDEOPORTDESC;

Members

dwSize
Size of this structure, in bytes. This member must be initialized before use.
dwFieldWidth
Width of incoming video stream, in pixels.
dwVBIWidth
Width of the VBI data in the incoming video stream, in pixels.
dwFieldHeight
Field height for fields in the incoming video stream, in scan lines.
dwMicrosecondsPerField
Time interval, in microseconds, between live video VREF periods. This number should be rounded up to the nearest microsecond.
dwMaxPixelsPerSecond
Maximum pixel rate per second.
dwVideoPortID
The zero-based ID of the physical video port to be used.
dwReserved1
Reserved; set to zero.
VideoPortType
A DDVIDEOPORTCONNECT structure describing the connection characteristics of the video port.
dwReserved2 and dwReserved3
Reserved; set to zero.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.


DDVIDEOPORTINFO

The DDVIDEOPORTINFO structure describes the transfer of video data to a surface. This structure is used with the IDirectDrawVideoPort::StartVideo method.

typedef struct _DDVIDEOPORTINFO{
    DWORD dwSize;
    DWORD dwOriginX;
    DWORD dwOriginY;
    DWORD dwVPFlags;
    RECT rCrop;
    DWORD dwPrescaleWidth;
    DWORD dwPrescaleHeight;
    LPDDPIXELFORMAT lpddpfInputFormat;
    LPDDPIXELFORMAT lpddpfVBIInputFormat;
    LPDDPIXELFORMAT lpddpfVBIOutputFormat;
    DWORD dwVBIHeight;
    ULONG_PTR dwReserved1;
    ULONG_PTR dwReserved2;
} DDVIDEOPORTINFO,*LPDDVIDEOPORTINFO;

Members

dwSize
Size of this structure, in bytes. This member must be initialized before use.
dwOriginX and dwOriginY
X- and y-coordinates for the origin of the video data in the surface.
dwVPFlags
Video port options.
DDVP_AUTOFLIP
Perform automatic flipping. For more information, see Auto-flipping.
DDVP_CONVERT
Perform conversion using the information in the lpddpfVBIOutputFormat member.
DDVP_CROP
Perform cropping using the rectangle specified by the rCrop member.
DDVP_IGNOREVBIXCROP
The video port should ignore left and right cropping coordinates when cropping oversampled VBI data.
DDVP_INTERLEAVE
Interlaced fields should be interleaved in memory.
DDVP_MIRRORLEFTRIGHT
Mirror image data from left to right as it is written into the frame buffer.
DDVP_MIRRORUPDOWN
Mirror image data from top to bottom as it is written into the frame buffer.
DDVP_OVERRIDEBOBWEAVE
Override automatic display method chosen by the driver, using only the display method set by the caller when creating the overlay surface.
DDVP_PRESCALE
Perform pre-scaling or pre-zooming based on the values in the dwPrescaleHeight and dwPrescaleWidth members.
DDVP_SKIPEVENFIELDS
Ignore input of even fields.
DDVP_SKIPODDFIELDS
Ignore input of odd fields.
DDVP_SYNCMASTER
Indicates that the video port VREF should drive the graphics VREF, locking the refresh rate to the video port.
DDVP_VBICONVERT
The lpddpfVBIOutputFormat member contains data that should be used to convert VBI data.
DDVP_VBINOSCALE
VBI data should not be scaled.
DDVP_VBINOINTERLEAVE
Interleaving can be disabled for data within the VBI.
rCrop
Cropping rectangle. This member is optional.
dwPrescaleWidth
Pre-scaling or zooming in the x-direction. This member is optional.
dwPrescaleHeight
Pre-scaling or zooming in the y-direction. This member is optional.
lpddpfInputFormat
A DDPIXELFORMAT structure describing the pixel format to be written to the video port. This will often be identical to the surface's pixel format, but can differ if the video port is to perform conversion.
lpddpfVBIInputFormatand lpddpfVBIOutputFormat
DDPIXELFORMAT structures describing the input and output pixel formats of the data within the vertical blanking interval.
dwVBIHeight
The amount of data within the vertical blanking interval, in scan lines.
dwReserved1 and dwReserved2
Reserved; set to zero.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.


DDVIDEOPORTSTATUS

The DDVIDEOPORTSTATUS structure describes the status of a video-port object. This structure is used with the IDDVideoPortContainer::QueryVideoPortStatus method.

typedef struct _DDVIDEOPORTSTATUS {
    DWORD dwSize;
    BOOL  bInUse;
    DWORD dwFlags;
    DWORD dwReserved1;
    DDVIDEOPORTCONNECT VideoPortType;
    ULONG_PTR dwReserved2;
    ULONG_PTR dwReserved3;
} DDVIDEOPORTSTATUS, *LPDDVIDEOPORTSTATUS;

Members

dwSize
Size of this structure, in bytes. This member must be initialized before use.
bInUse
Value indicating the current status of the video port. This member is TRUE if the video port is currently being used, and FALSE otherwise.
dwFlags
Flags
DDVPSTATUS_VBIONLY
The video port interface is only controlling the VBI portion of the video stream.
DDVPSTATUS_VIDEOONLY
The video port interface is only controlling the video portion of the video stream.
dwReserved1
Reserved; set to zero.
VideoPortType
A DDVIDEOPORTCONNECT structure that receives information about the video-port connection.
dwReserved2 and dwReserved3
Reserved; set to zero.

QuickInfo

Windows NT/2000: Requires Windows 2000.
Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
Header: Declared in dvp.h.


返回值

Errors are represented by negative values and cannot be combined. This table lists the values that can be returned by all methods of the IDirectDraw4, IDirectDrawSurface4, IDirectDrawPalette, IDirectDrawClipper, IDDVideoPortContainer, and IDirectDrawVideoPort interfaces. For a list of the error codes that each method can return, see the method description.

DD_OK
The request completed successfully.
DDERR_ALREADYINITIALIZED
The object has already been initialized.
DDERR_BLTFASTCANTCLIP
A DirectDrawClipper object is attached to a source surface that has passed into a call to the IDirectDrawSurface4::BltFast method.
DDERR_CANNOTATTACHSURFACE
A surface cannot be attached to another requested surface.
DDERR_CANNOTDETACHSURFACE
A surface cannot be detached from another requested surface.
DDERR_CANTCREATEDC
Windows can not create any more device contexts (DCs), or a DC was requested for a palette-indexed surface when the surface had no palette and the display mode was not palette-indexed (in this case DirectDraw cannot select a proper palette into the DC).
DDERR_CANTDUPLICATE
Primary and 3-D surfaces, or surfaces that are implicitly created, cannot be duplicated.
DDERR_CANTLOCKSURFACE
Access to this surface is refused because an attempt was made to lock the primary surface without DCI support.
DDERR_CANTPAGELOCK
An attempt to page lock a surface failed. Page lock will not work on a display-memory surface or an emulated primary surface.
DDERR_CANTPAGEUNLOCK
An attempt to page unlock a surface failed. Page unlock will not work on a display-memory surface or an emulated primary surface.
DDERR_CLIPPERISUSINGHWND
An attempt was made to set a clip list for a DirectDrawClipper object that is already monitoring a window handle.
DDERR_COLORKEYNOTSET
No source color key is specified for this operation.
DDERR_CURRENTLYNOTAVAIL
No support is currently available.
DDERR_DCALREADYCREATED
A device context (DC) has already been returned for this surface. Only one DC can be retrieved for each surface.
DDERR_DEVICEDOESNTOWNSURFACE
Surfaces created by one DirectDraw device cannot be used directly by another DirectDraw device.
DDERR_DIRECTDRAWALREADYCREATED
A DirectDraw object representing this driver has already been created for this process.
DDERR_EXCEPTION
An exception was encountered while performing the requested operation.
DDERR_EXCLUSIVEMODEALREADYSET
An attempt was made to set the cooperative level when it was already set to exclusive.
DDERR_EXPIRED
The data has expired and is therefore no longer valid.
DDERR_GENERIC
There is an undefined error condition.
DDERR_HEIGHTALIGN
The height of the provided rectangle is not a multiple of the required alignment.
DDERR_HWNDALREADYSET
The DirectDraw cooperative level window handle has already been set. It cannot be reset while the process has surfaces or palettes created.
DDERR_HWNDSUBCLASSED
DirectDraw is prevented from restoring state because the DirectDraw cooperative level window handle has been subclassed.
DDERR_IMPLICITLYCREATED
The surface cannot be restored because it is an implicitly created surface.
DDERR_INCOMPATIBLEPRIMARY
The primary surface creation request does not match with the existing primary surface.
DDERR_INVALIDCAPS
One or more of the capability bits passed to the callback function are incorrect.
DDERR_INVALIDCLIPLIST
DirectDraw does not support the provided clip list.
DDERR_INVALIDDIRECTDRAWGUID
The globally unique identifier (GUID) passed to the DirectDrawCreate function is not a valid DirectDraw driver identifier.
DDERR_INVALIDMODE
DirectDraw does not support the requested mode.
DDERR_INVALIDOBJECT
DirectDraw received a pointer that was an invalid DirectDraw object.
DDERR_INVALIDPARAMS
One or more of the parameters passed to the method are incorrect.
DDERR_INVALIDPIXELFORMAT
The pixel format was invalid as specified.
DDERR_INVALIDPOSITION
The position of the overlay on the destination is no longer legal.
DDERR_INVALIDRECT
The provided rectangle was invalid.
DDERR_INVALIDSTREAM
The specified stream contains invalid data.
DDERR_INVALIDSURFACETYPE
The requested operation could not be performed because the surface was of the wrong type.
DDERR_LOCKEDSURFACES
One or more surfaces are locked, causing the failure of the requested operation.
DDERR_MOREDATA
There is more data available than the specified buffer size can hold.
DDERR_NO3D
No 3-D hardware or emulation is present.
DDERR_NOALPHAHW
No alpha acceleration hardware is present or available, causing the failure of the requested operation.
DDERR_NOBLTHW
No blitter hardware is present.
DDERR_NOCLIPLIST
No clip list is available.
DDERR_NOCLIPPERATTACHED
No DirectDrawClipper object is attached to the surface object.
DDERR_NOCOLORCONVHW
The operation cannot be carried out because no color-conversion hardware is present or available.
DDERR_NOCOLORKEY
The surface does not currently have a color key.
DDERR_NOCOLORKEYHW
The operation cannot be carried out because there is no hardware support for the destination color key.
DDERR_NOCOOPERATIVELEVELSET
A create function is called without the IDirectDraw4::SetCooperativeLevel method being called.
DDERR_NODC
No DC has ever been created for this surface.
DDERR_NODDROPSHW
No DirectDraw raster operation (ROP) hardware is available.
DDERR_NODIRECTDRAWHW
Hardware-only DirectDraw object creation is not possible; the driver does not support any hardware.
DDERR_NODIRECTDRAWSUPPORT
DirectDraw support is not possible with the current display driver.
DDERR_NOEMULATION
Software emulation is not available.
DDERR_NOEXCLUSIVEMODE
The operation requires the application to have exclusive mode, but the application does not have exclusive mode.
DDERR_NOFLIPHW
Flipping visible surfaces is not supported.
DDERR_NOFOCUSWINDOW
An attempt was made to create or set a device window without first setting the focus window.
DDERR_NOGDI
No GDI is present.
DDERR_NOHWND
Clipper notification requires a window handle, or no window handle has been previously set as the cooperative level window handle.
DDERR_NOMIPMAPHW
The operation cannot be carried out because no mipmap capable texture mapping hardware is present or available.
DDERR_NOMIRRORHW
The operation cannot be carried out because no mirroring hardware is present or available.
DDERR_NONONLOCALVIDMEM
An attempt was made to allocate non-local video memory from a device that does not support non-local video memory.
DDERR_NOOPTIMIZEHW
The device does not support optimized surfaces.
DDERR_NOOVERLAYDEST
The IDirectDrawSurface4::GetOverlayPosition method is called on an overlay that the IDirectDrawSurface4::UpdateOverlay method has not been called on to establish a destination.
DDERR_NOOVERLAYHW
The operation cannot be carried out because no overlay hardware is present or available.
DDERR_NOPALETTEATTACHED
No palette object is attached to this surface.
DDERR_NOPALETTEHW
There is no hardware support for 16- or 256-color palettes.
DDERR_NORASTEROPHW
The operation cannot be carried out because no appropriate raster operation hardware is present or available.
DDERR_NOROTATIONHW
The operation cannot be carried out because no rotation hardware is present or available.
DDERR_NOSTRETCHHW
The operation cannot be carried out because there is no hardware support for stretching.
DDERR_NOT4BITCOLOR
The DirectDrawSurface object is not using a 4-bit color palette and the requested operation requires a 4-bit color palette.
DDERR_NOT4BITCOLORINDEX
The DirectDrawSurface object is not using a 4-bit color index palette and the requested operation requires a 4-bit color index palette.
DDERR_NOT8BITCOLOR
The DirectDrawSurface object is not using an 8-bit color palette and the requested operation requires an 8-bit color palette.
DDERR_NOTAOVERLAYSURFACE
An overlay component is called for a non-overlay surface.
DDERR_NOTEXTUREHW
The operation cannot be carried out because no texture-mapping hardware is present or available.
DDERR_NOTFLIPPABLE
An attempt has been made to flip a surface that cannot be flipped.
DDERR_NOTFOUND
The requested item was not found.
DDERR_NOTINITIALIZED
An attempt was made to call an interface method of a DirectDraw object created by CoCreateInstance before the object was initialized.
DDERR_NOTLOADED
The surface is an optimized surface, but it has not yet been allocated any memory.
DDERR_NOTLOCKED
An attempt is made to unlock a surface that was not locked.
DDERR_NOTPAGELOCKED
An attempt is made to page unlock a surface with no outstanding page locks.
DDERR_NOTPALETTIZED
The surface being used is not a palette-based surface.
DDERR_NOVSYNCHW
The operation cannot be carried out because there is no hardware support for vertical blank synchronized operations.
DDERR_NOZBUFFERHW
The operation to create a z-buffer in display memory or to perform a blit using a z-buffer cannot be carried out because there is no hardware support for z-buffers.
DDERR_NOZOVERLAYHW
The overlay surfaces cannot be z-layered based on the z-order because the hardware does not support z-ordering of overlays.
DDERR_OUTOFCAPS
The hardware needed for the requested operation has already been allocated.
DDERR_OUTOFMEMORY
DirectDraw does not have enough memory to perform the operation.
DDERR_OUTOFVIDEOMEMORY
DirectDraw does not have enough display memory to perform the operation.
DDERR_OVERLAPPINGRECTS
Operation could not be carried out because the source and destination rectangles are on the same surface and overlap each other.
DDERR_OVERLAYCANTCLIP
The hardware does not support clipped overlays.
DDERR_OVERLAYCOLORKEYONLYONEACTIVE
An attempt was made to have more than one color key active on an overlay.
DDERR_OVERLAYNOTVISIBLE
The IDirectDrawSurface4::GetOverlayPosition method is called on a hidden overlay.
DDERR_PALETTEBUSY
Access to this palette is refused because the palette is locked by another thread.
DDERR_PRIMARYSURFACEALREADYEXISTS
This process has already created a primary surface.
DDERR_REGIONTOOSMALL
The region passed to the IDirectDrawClipper::GetClipList method is too small.
DDERR_SURFACEALREADYATTACHED
An attempt was made to attach a surface to another surface to which it is already attached.
DDERR_SURFACEALREADYDEPENDENT
An attempt was made to make a surface a dependency of another surface to which it is already dependent.
DDERR_SURFACEBUSY
Access to the surface is refused because the surface is locked by another thread.
DDERR_SURFACEISOBSCURED
Access to the surface is refused because the surface is obscured.
DDERR_SURFACELOST
Access to the surface is refused because the surface memory is gone. Call the IDirectDrawSurface4::Restore method on this surface to restore the memory associated with it.
DDERR_SURFACENOTATTACHED
The requested surface is not attached.
DDERR_TOOBIGHEIGHT
The height requested by DirectDraw is too large.
DDERR_TOOBIGSIZE
The size requested by DirectDraw is too large. However, the individual height and width are valid sizes.
DDERR_TOOBIGWIDTH
The width requested by DirectDraw is too large.
DDERR_UNSUPPORTED
The operation is not supported.
DDERR_UNSUPPORTEDFORMAT
The pixel format requested is not supported by DirectDraw.
DDERR_UNSUPPORTEDMASK
The bitmask in the pixel format requested is not supported by DirectDraw.
DDERR_UNSUPPORTEDMODE
The display is currently in an unsupported mode.
DDERR_VERTICALBLANKINPROGRESS
A vertical blank is in progress.
DDERR_VIDEONOTACTIVE
The video port is not active.
DDERR_WASSTILLDRAWING
The previous blit operation that is transferring information to or from this surface is incomplete.
DDERR_WRONGMODE
This surface cannot be restored because it was created in a different mode.
DDERR_XALIGN
The provided rectangle was not horizontally aligned on a required boundary.


Pixel Format Masks

This section contains information about the pixel formats supported by the hardware-emulation layer (HEL). The following topics are discussed:

  • Texture Map Formats
  • Off-Screen Surface Formats


Texture Map Formats

A wide range of texture pixel formats are supported by the HEL. The following table shows these formats. The Masks column contains the red, green, blue, and alpha masks for each set of pixel format flags and bit depths.

Pixel format flags | Bit depth | Masks
DDPF_RGB | | 1 | R: 0x00000000
DDPF_PALETTEINDEXED1 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 1 | R: 0x00000000
DDPF_PALETTEINDEXED1 | |  | G: 0x00000000
DDPF_PALETTEINDEXEDTO8 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 2 | R: 0x00000000
DDPF_PALETTEINDEXED2 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 2 | R: 0x00000000
DDPF_PALETTEINDEXED2 | |  | G: 0x00000000
DDPF_PALETTEINDEXEDTO8 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 4 | R: 0x00000000
DDPF_PALETTEINDEXED4 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 4 | R: 0x00000000
DDPF_PALETTEINDEXED4 | |  | G: 0x00000000
DDPF_PALETTEINDEXEDTO8 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 8 | R: 0x00000000
DDPF_PALETTEINDEXED8 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | 8 | R: 0x000000E0
 |  | G: 0x0000001C
 |  | B: 0x00000003
 |  | A: 0x00000000
DDPF_RGB | | 16 | R: 0x00000F00
DDPF_ALPHAPIXELS |  | G: 0x000000F0
 |  | B: 0x0000000F
 |  | A: 0x0000F000
DDPF_RGB | 16 | R: 0x0000F800
 |  | G: 0x000007E0
 |  | B: 0x0000001F
 |  | A: 0x00000000
DDPF_RGB | 16 | R: 0x0000001F
 |  | G: 0x000007E0
 |  | B: 0x0000F800
 |  | A: 0x00000000
DDPF_RGB | 16 | R: 0x00007C00
 |  | G: 0x000003E0
 |  | B: 0x0000001F
 |  | A: 0x00000000
DDPF_RGB | | 16 | R: 0x00007C00
DDPF_ALPHAPIXELS |  | G: 0x000003E0
 |  | B: 0x0000001F
 |  | A: 0x00008000
DDPF_RGB | 24 | R: 0x00FF0000
 |  | G: 0x0000FF00
 |  | B: 0x000000FF
 |  | A: 0x00000000
DDPF_RGB | 24 | R: 0x000000FF
 |  | G: 0x0000FF00
 |  | B: 0x00FF0000
 |  | A: 0x00000000
DDPF_RGB | 32 | R: 0x00FF0000
 |  | G: 0x0000FF00
 |  | B: 0x000000FF
 |  | A: 0x00000000
DDPF_RGB | 32 | R: 0x000000FF
 |  | G: 0x0000FF00
 |  | B: 0x00FF0000
 |  | A: 0x00000000
DDPF_RGB | | 32 | R: 0x00FF0000
DDPF_ALPHAPIXELS |  | G: 0x0000FF00
 |  | B: 0x000000FF
 |  | A: 0xFF000000
DDPF_RGB | | 32 | R: 0x000000FF
DDPF_ALPHAPIXELS |  | G: 0x0000FF00
 |  | B: 0x00FF0000
 |  | A: 0xFF000000

The HEL can create these formats in system memory. The DirectDraw device driver for a 3-D朼ccelerated display card may create textures of other formats in display memory. Such a driver exports the DDSCAPS_TEXTURE flag to indicate that it can create textures.


Off-Screen Surface Formats

The following table shows the pixel formats for off-screen plain surfaces supported by the DirectX� 5 HEL. The Masks column contains the red, green, blue, and alpha masks for each set of pixel format flags and bit depths.

Pixel format flags | Bit depth | Masks
DDPF_RGB | | 1 | R: 0x00000000
DDPF_PALETTEINDEXED1 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 2 | R: 0x00000000
DDPF_PALETTEINDEXED2 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 4 | R: 0x00000000
DDPF_PALETTEINDEXED4 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | | 8 | R: 0x00000000
DDPF_PALETTEINDEXED8 |  | G: 0x00000000
 |  | B: 0x00000000
 |  | A: 0x00000000
DDPF_RGB | 16 | R: 0x0000F800
 |  | G: 0x000007E0
 |  | B: 0x0000001F
 |  | A: 0x00000000
DDPF_RGB | 16 | R: 0x00007C00
 |  | G: 0x000003E0
 |  | B: 0x0000001F
 |  | A: 0x00000000
DDPF_RGB | 24 | R: 0x00FF0000
 |  | G: 0x0000FF00
 |  | B: 0x000000FF
 |  | A: 0x00000000
DDPF_RGB | 24 | R: 0x000000FF
 |  | G: 0x0000FF00
 |  | B: 0x00FF0000
 |  | A: 0x00000000
DDPF_RGB | 32 | R: 0x00FF0000
 |  | G: 0x0000FF00
 |  | B: 0x000000FF
 |  | A: 0x00000000
DDPF_RGB | 32 | R: 0x000000FF
 |  | G: 0x0000FF00
 |  | B: 0x00FF0000
 |  | A: 0x00000000
DDPF_RGB | | 32 | R: 0x0000F800
DDPF_ZPIXELS |  | G: 0x000007E0
 |  | B: 0x0000001F
 |  | Z: 0xFFFF0000
DDPF_RGB | | 32 | R: 0x00007C00
DDPF_ZPIXELS |  | G: 0x000003E0
 |  | B: 0x0000001F
 |  | Z: 0xFFFF0000

In addition to supporting a wide range of off-screen surface formats, the HEL also supports surfaces intended for use by Direct3D, or other 3-D renderers.


Four Character Codes (FOURCC)

DirectDraw utilizes a special set of codes that are four characters in length. These codes, called four character codes or FOURCCs, are stored in file headers of files containing multimedia data such as bitmap images, sound, or video. FOURCCs describe the software technology that was used to produce multimedia data. By implication, they also describe the format of the data itself.

DirectDraw applications use FOURCCs for image color and format conversion. If an application calls the IDirectDrawSurface4::GetPixelFormat method to request the pixel format of a surface whose format is not RGB, the dwFourCC member of the DDPIXELFORMAT structure identifies the FOURCC when the method returns. For more information, see Converting Color and Format.

In addition, the biCompression member of the BITMAPINFOHEADER structure can be set to a FOURCC to indicate the codec used to compress or decompress an image.

FOURCCs are registered with Microsoft by the vendors of the respective multimedia software technologies. Some common FOURCCs appear in the following list.

FOURCC | Company | Technology Name
AUR2 | AuraVision Corporation | AuraVision Aura 2: YUV 422
AURA | AuraVision Corporation | AuraVision Aura 1: YUV 411
CHAM | Winnov, Inc. | MM_WINNOV_CAVIARA_CHAMPAGNE
CVID | Supermac | Cinepak by Supermac
CYUV | Creative Labs, Inc | Creative Labs YUV
DXT1 | Microsoft Corporation | DirectX Texture Compression format 1
DXT2 | Microsoft Corporation | DirectX Texture Compression format 2
DXT3 | Microsoft Corporation | DirectX Texture Compression format 3
DXT4 | Microsoft Corporation | DirectX Texture Compression format 4
DXT5 | Microsoft Corporation | DirectX Texture Compression format 5
FVF1 | Iterated Systems, Inc. | Fractal Video Frame
IF09 | Intel Corporation | Intel Intermediate YUV9
IV31 | Intel Corporation | Indeo 3.1
JPEG | Microsoft Corporation | Still Image JPEG DIB
MJPG | Microsoft Corporation | Motion JPEG Dib Format
MRLE | Microsoft Corporation | Run Length Encoding
MSVC | Microsoft Corporation | Video 1
PHMO | IBM Corporation | Photomotion
RT21 | Intel Corporation | Indeo 2.1
ULTI | IBM Corporation | Ultimotion
V422 | Vitec Multimedia | 24 bit YUV 4:2:2
V655 | Vitec Multimedia | 16 bit YUV 4:2:2
VDCT | Vitec Multimedia | Video Maker Pro DIB
VIDS | Vitec Multimedia | YUV 4:2:2 CCIR 601 for V422
YU92 | Intel Corporation | YUV
YUV8 | Winnov, Inc. | MM_WINNOV_CAVIAR_YUV8
YUV9 | Intel Corporation | YUV9
YUYV | Canopus, Co., Ltd. | BI_YUYV, Canopus
ZPEG | Metheus | Video Zipper


Glossary

This section provides a glossary of technical terms used in the DirectX Programmer's Reference documentation. Entries are grouped by letter in alphabetical order.

A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z


A

alpha channel
The opacity of an image defined by an alpha value per pixel interleaved with the color components (for example, ARGB), an alpha value per pixel stored in a separate alpha surface, or a constant alpha value for the entire surface.
alpha color component
The portion of a 32-bit color that determines its opacity. In this case, the alpha value per pixel is interleaved with the color components (for example, ARGB). Less commonly, this term can also refer to an image with an alpha value per pixel stored in a separate alpha surface.
alpha constant
A level of opacity (alpha value) applied to an entire surface.
alpha edge blend
A particular use of alpha blending (and alpha channel information) to reduce aliasing by blending edges based on pixel coverage information.
ambient
A light source that illuminates everything in a scene, regardless of the orientation, position, and surface characteristics of the objects in the scene. Because this illuminates a scene with equal strength everywhere, the position and orientation of the frame it is attached to are inconsequential. Multiple ambient light sources are combined within a scene.
anisotropic filtering
A mipmap filtering mode that compensates for anisotropy, which is the distortion visible in the texels of a 3-D object whose surface is oriented at an angle with respect to the plane of the screen. The anisotropy is measured as the elongation (length divided by width) of a screen pixel that is inverse-mapped into texture space.
anisotropy
The distortion visible in the image of a 3-D object whose surface is oriented at an angle with respect to the viewing plane.
array object
A group of objects organized into an array. Array objects make it simpler to apply operations to the entire group. The COM interfaces that allow you to work with array objects contain the GetElement and GetSize methods. These methods retrieve a pointer to an element in the array and the size of the array, respectively.
attach
To connect multiple DirectDrawSurface objects into complex structures, like those needed to support 3-D page flipping with z-buffers. Attachment is not bidirectional, and a surface cannot be attached to itself. Emulated surfaces (in system memory) cannot be attached to nonemulated surfaces. Unless one surface is a texture map, the two attached surfaces must be the same size.
attached
Physically connected to the system. A device may be installed but not currently attached.
attack
The period at the beginning of a force-feedback effect when the magnitude is reaching its basic or sustain level.
audio stream
Sound data, mixed or unmixed. DirectSound mixes audio streams from each secondary sound buffer that is playing and writes the result to the primary sound buffer, which supplies the sound hardware with audio data.


B

back buffer
A nonvisible surface that bitmaps and other images can be drawn to while the primary surface displays the currently visible image.
back clipping plane
The far boundary of a viewing frustum beyond which objects are not rendered. See also front clipping plane.
bank select
A MIDI controller that allows instruments to be chosen from different groups or banks, each identified by a two-byte code.
billboard
A primitive inserted into a 3-D scene that is oriented so that one face is toward the viewer. A texture, usually an animated sprite, is applied to the billboard to give the appearance of a 3-D object in the scene.
billboarding
A 2-D technique of simulating the appearance of a 3-D object in a scene. An application inserts a primitive, typically rectangular, into the scene oriented so that one face is toward the viewer and applies a texture or a set of textures. The texture or set of textures gives the appearance of an animated 3-D object.
blend factor
The description of how each color component is blended in texture blending.
blend mode
The algorithm used to determine how a texture is blended with the colors of the surface to which the texture is applied.
blending stage
One step in a texture cascade. A blending stage includes one texture and a set of texture blending operations that are used when blending multiple textures.
blit
A bit block transfer.
bounds checking
The process of checking that an on-screen image is displayed within the bounds of the screen.
bump mapping
A technique for simulating the appearance of rough surfaces in 3-D scenes. Variations in depth are stored in a texture and applied to a primitive using standard texture-blending techniques.


C

camera
A Direct3DRMFrame object used by the viewport to define the viewing position and direction. The viewport renders only what is visible along the positive z-axis of the camera frame, with the up direction being in the direction of the positive y-axis.
camera space
The frame of reference where the viewer is at the origin, looking in the direction of the positive z-direction. Objects are transformed from world space to camera space by using the view transformation.
clip list
A series of rectangles that describes the visible areas of the surface. The clip list cannot be set if a window handle is already associated with the DirectDrawClipper object.
clipper
A DirectDrawClipper object.
codec
Represents the phrase "compressor and decompressor."
collision detection
The process of determining if any pixels for two images share the same location on the screen. See also hit detection.
color key
A value indicating the color to be used for transparent or translucent effects. When using a hardware blitter, for example, all of the pixels of a rectangular area will be blitted except for the value that was set as the color key, thereby creating nonrectangular sprites on a surface.
color space
A model for representing color as three or more coordinates. Color-space models map color components onto a Cartesian coordinate system in three or more dimensions. A color space may use any of several types of color encoding and visualizing color. The two most common types of color space models are RGB and YUV.
color-space conversion
A technique for converting a color in one color space to another color space. Typically, this conversion is from YUV colors from a video source to RGB for display.
color table
An array of n color values (normally RGB triples).
complex surface
The collective term for several DirectDrawSurface objects, all of which are attached to a root surface. The complex-surface structure can be destroyed only by destroying the root.
cull
Skipping a back face of a 3-D primitive during the rendering process.
current play position
The location in a DirectSound buffer where a sound is being played.
current write position
The location in a DirectSound buffer where it is safe to change data in that buffer.


D

dark light
A light source that removes illumination from a scene, created by specifying negative values for the colors of the light.
DCI
Acronym for Display Control Interface. Defined by the Intel and Microsoft corporations, DCI in an interface that offers improved graphics performance as a result of direct video memory access.
dead zone
An area within the range of an axis where the axis is considered to be at the center.
decal
A texture that is rendered directly, as a visual. Decals are rendered into a viewport-aligned rectangle.
destination color key
The color that, in the case of blitting, will be replaced or, in the case of overlays, be covered up on the destination surface.
device window
A visible application window that DirectDraw uses for display. Applications can have a device window for each display device in a machine. See also focus window.
directional
A light source that is attached to a frame but appears to illuminate all objects with equal intensity, as if it were at an infinite distance from the objects. Directional light has orientation but no position, and it is commonly used to simulate distant light sources, such as the sun.
DLS
Downloadable sounds (sometimes called downloadable samples). Digital samples in software that are used by a synthesizer to create instrument timbres.


E

emissive property
The material property that determines whether a material emits light. The emissive property of a material is one of two properties that determines how the material reflects light. See also specular property.
emissive setting
See emissive property.
enable frame
The frame to which a light applies.
envelope
A set of values that defines the shape of a force-feedback effect by modifying the magnitude at the beginning (attack) and end (fade).
even field
The second field comprising a video frame in an odd/even field set. Also known as field 2.
execute buffer
A fully self-contained, independent packet of information that describes a 3-D scene. An execute buffer contains a vertex list followed by an instruction stream. The instruction stream consists of operation codes, or opcodes, and the data that is operated on by those opcodes.


F

face
A single polygon in a mesh.
fade
The period between the central, or sustain, portion of a force feedback effect and its end.
falloff
Light attenuation that occurs between a spotlight's inner and outer cones.
field
Data for one-half of a single video frame within a video stream. Each field contains data for every other scan line. Fields are sent and received in odd field, even field order.
field polarity
Quality determining whether a field is an even field or an odd field. Odd fields are defined when the trailing edge of VREF does not occur during a scan line. Even fields are defined as when the trailing edge of VREF occurs during a scan line.
flimmering
A shimmering appearance on 3-D primitives that results from a poor separation of z values when doing decaling. Some pixels from the back texture are rendered onto the front texture and visa versa.
flip
The process of swapping the addresses associated with the back and front buffers. This effectively swaps the image in the back buffer to the front buffer, thereby displaying the image.
flipping chain
A series of surfaces, attached to each other, that can be flipped. See also flip.
flipping surface
Any piece of memory that can be flipped. See also flip.
focus window
An application window, visible or not visible, that DirectDraw uses to hook window messages. The focus window's message handler receives input messages as forwarded by DirectDraw. Applications can have only one focus window. See also device window.
frame
An invisible box that provides a frame of reference for objects in a scene. Objects can be placed in a scene by specifying their spatial relationship to a relevant reference frame. Visual objects take their positions and orientations from frames. Also, a single image from a movie or animation.
front buffer
The first buffer in a flipping chain. In many cases, this will be the visible primary surface. In other cases, such as a flipping chain of textures, the front buffer is the surface the 3-D engine will get the texture from, but it is not the primary surface and is not displayed. In the case of flipping overlay surfaces, the front buffer is displayed, but is only a surface overlaid on the primary surface. See also primary surface.
front clipping plane
The near boundary of a viewing frustum. Any object closer to the camera than the front clipping plane is not rendered. The height of the front clipping plane defines the field of view. See also back clipping plane.


G

genlocking
The process of synchronizing one video signal with another. Because they are synchronized, the genlocked signal can be mixed with the original signal, allowing dissolves, wipes, and other transition effects.
grid
Subdivision of a beat. The number of grids per beat is part of the DirectMusic time signature.
groove level
A value given to the music during style playback, determining which patterns can be selected at any given time. The author assigns a range of groove levels to each pattern.
group
A number of players arranged together as a set in a DirectPlay session.


H

HAL
The hardware-abstraction layer. Consists of hardware and device driver mechanisms that insulate applications from device-specific implementation details. If a capability requested by an application is not implemented by the current hardware, the capability will be emulated by the software.
hardware blitter
A hardware component, built into the display adapter, that performs efficient blit operations.
HEL
The hardware-emulation layer. Provides software-based emulation of features that are not present in hardware.
hit detection
See collision detection.
host
In DirectPlay, a virtual player whose ID is DPID_SYSMSG. System messages and messages sent to all players in a session are managed by the host.
HREF
Acronym for horizontal refresh. In a video stream, the HREF is active to signal that the display is to begin a new scan line. See also VREF.


I

index palette
A DirectDrawPalette object whose entries are indices into another palette object.
IRE
IRE, an acronym for International Radio Engineers, is a scale of values ranging from 0 to 100 that defines the brightness level of a broadcast video signal. The spectrum of low-to-high IRE values describes increasing brightness levels in a video signal. At 7.5 IRE brightness units — the "black cut-off" threshold for an NTSC signal — the electron guns of an NTSC display device are cut-off and do not display images.


L

latency
A delay in response; for example, the interval between the time that a sound buffer plays and the time that the speakers actually reproduce the sound.
light map
A texture or group of textures that contain lighting information for a 3-D scene.
lobby client
Lobby management routines associated with the user's computer, including launching applications, updating the user interface, and communicating with the lobby server.
lobby server
Lobby management routines associated with a remote server. The lobby server coordinates all the information about the users connected to a specific application.


M

Mach bands
Bands of color that are not smoothly blended across a 3-D primitive.
material
A property that determines how a surface reflects light. A material has two components: an emissive property (whether it emits light) and a specular property, whose brightness is determined by a power setting.
mesh
A set of faces, each of which is described by a simple polygon.
mipmap
Also known as MIP map (Latin: multum in parvo, translated "much in little"). A sequence of textures, each of which is a progressively lower-resolution, prefiltered representation of the same image. A higher-resolution image is used when a visible object is close to the viewer; as the object moves farther away (and gets smaller), lower-resolution images are used.
mixing
In DirectSound, the process of combining sound buffers that are playing and writing the result to the primary sound buffer, which supplies the sound hardware with audio data. There are no limitations to the number of buffers that can be mixed, except the practicalities of available processing time.
Mode X
A hybrid display mode derived from the standard VGA Mode 13. This mode allows the use of up to 256 KB of display memory (rather than 64 KB allowed by Mode 13) by using the VGA display adapter's EGA multiple video plane system.
model coordinates
Coordinates that are relative to local origin. See also model space and world coordinates.
model space
The frame of reference, used by model coordinates, that uses vertices relative to a single 3-D model's local origin.
multipass texture blending
The repeated rendering of a 3-D primitive while blending on a texture with each pass. This technique is widely used to achieve a variety of special effects.


N

normal vector
An imaginary ray extending perpendicularly from a surface that defines the face's orientation.


O

odd field
The first field comprising a video frame in an odd/even field set.
off-screen surface
A conceptually rectangular area in memory that is generally used to store bitmaps that will be blitted to a back buffer before being displayed. Commonly used to store sprites.
opcode
Operation code that defines how the vertices in an execute buffer should be interpreted or how the state of the system should be changed.
overdraw
The average number of times to which a screen pixel is written.
overlay surface
A conceptually rectangular area in memory whose stored image information will cover the image information of the primary surface to which it is applied. Overlays are assumed to be on top of all other screen components.
overlay z-order
Determines the order in which overlays clip each other, enabling a hardware sprite system to be implemented under DirectDraw.


P

page flipping
See flip.
palette
The set of colors used by an object or application. In DirectX, a DirectDrawPalette object.
palette index
An integer index into the palette table array that is used to select a particular color.
palettized surface
A DirectDrawSurface object that uses an attached palette to contain color information.
pan value
The relative volume, measured in hundredths of decibels, between the left and right audio channels.
parallel point
A light source that illuminates objects with parallel light, but the orientation of the light is taken from the position of the parallel point light source. For example, two meshes on either side of a parallel point light source are lit on the side that faces the position of the source.
PChannel
Abbreviation for performance channel. A PChannel is a MIDI channel in a particular channel group on a particular port.
perspective correction
The technique of applying a texture map to a polygon that is angled away from the camera, interpolating so that the texture is stretched onto the polygon appropriately for the apparent depth of the polygon. Direct3D supplies perspective correction automatically.
pick
To search for visuals in a scene given a 2-D coordinate in a viewport.
pitch
The distance, in bytes, between an address that represents the beginning of a bitmap line and the beginning of the next line. Do not confuse memory pitch and memory width, since not all display memory is laid out as one linear block. For example, with rectangular memory, the pitch of the display memory could include the width of the bitmap plus part of a cache. See also width and stride.
player
A single participant in a DirectPlay session. Each player is associated with a player ID that enables messages to be exchanged among players.
player ID
A unique number that is assigned to each participant in a DirectPlay session when the participant is created. The application can exchange messages among players by using player IDs. The host is always assigned the DPID_SYSMSG player ID.
point light
A light source that radiates equally in all directions from its origin.
point list
The simplest 3-D primitive. A collection of unconnected points in 3-D space.
power
In the specular property of a material, the value that determines the sharpness of specular highlights. A value of 5 gives a metallic appearance, and higher values give a more plastic appearance.
primary sound buffer
The buffer the user hears when a game is playing. The primary buffer is generally used to mix sound from secondary buffers, but it can be accessed directly for custom mixing or other specialized activities.
primary surface
The area in memory containing the image being displayed on the monitor. In DirectX, the primary surface is represented by the primary DirectDrawSurface object.
projection space
Frame of reference containing vertices after they are modified from their world space locations by the projection transformation. Projection space is a homogeneous cuboid space where all vertices in a scene have x- and y-coordinates that range from -1.0 to 1.0, and a z-coordinate that ranges from 0.0 to 1.0. Projection space is sometimes referred to as "post-perspective homogeneous space."
projection transformation
The application of a matrix to vertices to change them from camera space to projection space.


Q

quaternion
A fourth element added to the [x, y, z] values that define a vector. Quaternions define a 3-D axis and a rotation around that axis.


R

reference count
A control for a component object model (COM) object. When an object is created, its reference count is set to 1. Every time an interface is bound to the object, its reference count is incremented; when the interface connection is destroyed, the reference count is decremented. The object is destroyed when the reference count reaches 0. All interfaces to that object are then invalid.
region
A range of notes for which a particular digital sample will be used in synthesizing an instrument's timbre.
root frame
A frame in Direct3D that has no parent frame; a frame at the top of a hierarchy of frames. The root frame contains the entire set of objects that make up a scene. See also scene.


S

saturation
Adjustment to the extreme value of a range when the actual value approaches the extreme. If the maximum value in a range is 1,000 and the maximum saturation point is set to 900, then any value greater than 899 is adjusted to 1,000.
scene
The entire set of objects that make up a virtual environment, including visible objects, sounds, lights, and frames. In Direct3D, the entire set of objects is contained by a root frame.
screen space
Frame of reference in which coordinates are related directly to two dimensional locations in the frame buffer, to be displayed on a monitor or other viewing device. Projection space coordinates are converted to screen space coordinates using a transformation matrix created from the viewport parameters.
secondary sound buffer
A section of audio memory that stores individual sounds that are played throughout an application. The sound can be played as a single event or as a looping sound that plays repeatedly. Secondary buffers can also play sounds that are larger than available sound-buffer memory; the buffer serves as a queue that stores the portions of the sound about to be played.
service provider
A dynamic-link library used by DirectPlay to communicate over a network. The service provider contains all the network-specific code required to send and receive messages. Online services and network operators can supply service providers to use specialized hardware, protocols, communications media, and network resources.
session
In DirectPlay, an instance of several applications on remote machines communicating with each other.
sound buffer
A segment of memory that stores DirectSound audio data. Sound buffers can be primary or secondary, static or streaming.
source color key
A color that, in the case of blitting, will not be copied, or, in the case of overlays, not be visible on the destination.
specular property
The material property that determines how a point of light on a shiny object corresponds to the reflected light source. The specular property of a material is one of two properties that determines how a material reflects light. See also emissive property.
spotlight
A light source that emits a cone of light. Only objects within the cone are illuminated. The cone produces light of two degrees of intensity, with a central brightly lit section that acts as a point source, and a surrounding dimly lit section that merges with the surrounding deep shadow.
static sound buffer
A section of memory that contains a complete sound. These buffers are convenient because the entire sound can be written once to the buffer.
sticky focus
In DirectSound, the capability to play sound buffers when the owning application does not have the input focus. For example, a DirectSound application could continue to play a sound buffer while the user was working in another application.
streaming sound buffer
A small sound buffer that can play lengthy sounds because the application dynamically loads audio data into the buffer as it plays. For example, an application could use a buffer that can hold 3 seconds of audio data to play a 2-minute sound. A streaming buffer requires much less memory than a static buffer.
stretching
Blitting an image into a destination with different dimensions. This operation is supported directly by some hardware.
stride
Synonymous with pitch. See also width.
surface
Memory that represents visual images. This is often display memory, but it can be system memory. See also complex surface, off-screen surface, overlay surface, and primary surface.
sustain
The period when the basic magnitude of a force feedback effect is attained, after the attack and before the fade.


T

tearing
A visual artifact produced when the screen refresh rate is out of sync with an application's frame rate. The top portion of one frame is displayed at the same time as the bottom portion of another frame, with a discernible tear between the two partial images.
tessellate
Breaking an image into small, square regions for processing or output.
texel
A single element in a texture. When a texture has been applied to an object, the texels rarely correspond to pixels on the screen. Applications can use texture filtering to control how texels are interpolated to pixels.
texture
A rectangular array of pixels that is applied to a visual object in Direct3D.
texture blending
The technique of combining the colors of a texture with the colors of the surface to which the texture is applied.
texture coordinates
The coordinates that determine which texel in each texture is assigned to each vertex in an object.
texture filtering
The process of mapping texel colors from one or more textures onto the pixels that comprise the image of a 3-D primitive.
texture mapping
The application of a texture to an object. Because a texture is a flat image and the object is often not, the texture must be mapped to the surface of the object, using texture coordinates and wrapping flags. See also texture coordinates and wrap.


V

VBI
Abbreviation for Vertical Blanking Interval.
velocity
In music, the speed at which a key is struck; roughly equivalent to the volume of a note.

In 3-D sound, the speed at which a sound source or listener is considered to be moving, for the purpose of calculating Doppler shift.

vertex
A point in 3-D space.
video frame
A single image in a video stream, comprised of one odd field and one even field. See also field.
view space
See camera space.
view transformation
The application of a matrix to a model's vertices to change its orientation from world space to view space.
viewing frustum
A 3-D volume in a scene positioned relative to the viewport's camera. Objects within the frustum are visible. For perspective viewing, the viewing frustum is the volume of an imaginary pyramid that is between the front clipping plane and the back clipping plane. For orthographic viewing, the viewing frustum is cuboid.
viewport
A rectangle that defines how a 3-D scene is rendered into a 2-D window. A viewport also defines an area on a device into which objects will be rendered.
VREF
Acronym for vertical refresh. In a video stream, the VREF is active to signal that the display is to begin a new screen. See also HREF.


W

width
The distance between two addresses in memory that represent the beginning of a line and the end of the line of a stored bitmap. This distance represents only the width of the bitmap in memory; it does not include any extra memory required to reach the beginning of the next line of the bitmap, such as a cache in rectangular memory.
world coordinates
Coordinates that are relative to the origin of a scene. See also model coordinates and world space.
world space
The frame of reference, used by world coordinates, that declares vertices relative to a single origin within a 3-D scene.
world transformation
The application of a matrix to a model's vertices to change its orientation from model space to world space.
wrap
The procedure used to calculate texture coordinates for a face or mesh. The basic wrapping types are flat, cylindrical, spherical, and chrome.


Z

z-buffer
A buffer that stores a depth value for each pixel in a scene. Pixels with a small z-value overwrite pixels with a large z-value.
z fighting
See flimmering.