DXGI_DDI_BASE_FUNCTIONS 结构 (dxgiddi.h)

项目
08/07/2023

DXGI_DDI_BASE_FUNCTIONS结构包含用户模式显示驱动程序可实现的函数，以执行低级别任务，例如向输出呈现的帧、控制伽马以及管理全屏转换。

语法

typedef struct DXGI_DDI_BASE_FUNCTIONS {
  HRESULT()(DXGI_DDI_ARG_PRESENT *) * pfnPresent;
  HRESULT()(DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS *) * pfnGetGammaCaps;
  HRESULT()(DXGI_DDI_ARG_SETDISPLAYMODE *) * pfnSetDisplayMode;
  HRESULT()(DXGI_DDI_ARG_SETRESOURCEPRIORITY *) * pfnSetResourcePriority;
  HRESULT()(DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *) * pfnQueryResourceResidency;
  HRESULT()(DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES *) * pfnRotateResourceIdentities;
  HRESULT()(DXGI_DDI_ARG_BLT *) * pfnBlt;
} DXGI_DDI_BASE_FUNCTIONS;

成员

pfnPresent

指向 PresentDXGI 函数的指针，该函数通知用户模式显示驱动程序应用程序已完成呈现并请求驱动程序显示到目标图面。

pPresentData 参数指向的 DXGI_DDI_ARG_PRESENT 结构的 hDevice 成员与驱动程序的 CreateDevice (D3D10) 函数在 D3D10DDIARG_CREATEDEVICE 结构的 hDrvDevice 成员中传递回运行时的句柄相同。因此，驱动程序编写器必须仔细定义此句柄的类型。此外，驱动程序可以根据 DDI 实现处理对 CreateDevice (D3D10) 的调用提供 PresentDXGI 函数的不同实现。运行时永远不会在 DDI 实现中混合驱动程序句柄。同样，DXGI_DDI_ARG_PRESENT的 hSurfaceToPresent 和 hDstResource 成员也是驱动程序定义的资源句柄，驱动程序在先前调用驱动程序的 CreateResource (D3D10) 函数时返回到运行时。

DXGI_DDI_ARG_PRESENT 的 pDXGIContext 成员是一种不透明的通信机制。运行时将此 DXGI 上下文传递给驱动程序。当驱动程序调用 pfnPresentCbDXGI 函数时，驱动程序应将此 DXGI 上下文未更改复制到 DXGIDDICB_PRESENT 结构的 pDXGIContext 成员。

驱动程序必须使用 pfnRenderCb 函数) 提交所有部分生成的呈现数据 (命令缓冲区。此后，驱动程序必须将资源句柄参数转换为内核句柄，并在调用 pfnPresentCbDXGI 时使用这些内核句柄。

注意

当驱动程序的 PresentDXGI 函数将 sRGB 格式的内容从源图面复制到非 sRGB 目标图面时，驱动程序应将 sRGB 内容复制不变 (也就是说，驱动程序不应) 执行 sRGB 到线性转换。

pPresentData

[in]指向描述如何向目标图面显示DXGI_DDI_ARG_PRESENT结构的指针。

pfnGetGammaCaps

GetGammaCapsDXGI 函数检索 gamma 功能。

pGammaData

[in]指向包含伽玛功能的 DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS 结构的指针。

pfnSetDisplayMode

指向驱动程序的 SetDisplayModeDXGI 函数的指针。

pfnSetResourcePriority

SetResourcePriorityDXGI 函数设置资源的逐出优先级。

Microsoft Direct3D 运行时调用 SetResourcePriorityDXGI 来设置资源的优先级。用户模式显示驱动程序应将 pPriorityData 指向的 DXGI_DDI_ARG_SETRESOURCEPRIORITY 结构的 hResource 成员中提供的资源句柄转换为分配句柄。驱动程序进行此转换后，驱动程序应在调用 pfnSetPriorityCb 函数时传递生成的句柄。

pPriorityData

[in]指向 DXGI_DDI_ARG_SETRESOURCEPRIORITY 结构的指针，该结构描述要设置资源的优先级。

pfnQueryResourceResidency

此函数确定给定资源列表的驻留。

Microsoft Direct3D 运行时为应用程序调用用户模式显示驱动程序的 QueryResourceResidencyDXGI 函数，以确定如果系统必须使资源可通过 GPU 访问，操作系统是否会在绘图时出现严重停滞。从 QueryResourceResidencyDXGI 返回的信息是资源驻留的近似值，因为在应用程序使用资源之前，资源可能会降级。

QueryResourceResidencyDXGI 必须调用 pfnQueryResidencyCb 函数。 pfnQueryResidencyCb 返回由D3DDDICB_QUERYRESIDENCY结构的 pResidencyStatus 成员指定的数组元素中的资源的驻留状态。如果 pfnQueryResidencyCb 为任何查询返回D3DDDI_RESIDENCYSTATUS_NOTRESIDENT， 则 QueryResourceResidencyDXGI 必须返回S_NOT_RESIDENT。如果 pfnQueryResidencyCb 对任何查询返回D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY，并且不返回任何查询的D3DDDI_RESIDENCYSTATUS_NOTRESIDENT， 则 QueryResourceResidencyDXGI 必须返回S_RESIDENT_IN_SHARED_MEMORY。仅当所有查询对 pfnQueryResidencyCb 的所有调用都返回D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY时，QueryResourceResidencyDXGI 必须返回S_OK。

对于运行时通过对 QueryResourceResidencyDXGI 的调用查询的每个资源，用户模式显示驱动程序必须确定要通过调用 pfnQueryResidencyCb 查询属于该资源的分配。对于拥有单个分配的资源，确定很简单 -- 驱动程序将查询该分配。但是，如果资源拥有多个分配，则更难确定。驱动程序必须确定应用程序可能用于呈现的分配，并且驱动程序必须仅查询这些分配。例如，如果资源拥有用于呈现的分配和处理锁定操作的暂存分配，则驱动程序应仅查询第一个分配的驻留，因为应用程序很可能不使用第二个分配进行呈现。

注意

由于运行时不支持对系统内存资源进行驻留查询，因此运行时始终会失败应用程序中的系统内存资源的驻留状态请求，并且永远不会为这些系统内存资源调用用户模式显示驱动程序的 QueryResourceResidencyDXGI 函数。

pResidencyData

[in]指向 DXGI_DDI_ARG_QUERYRESOURCERESIDENCY 结构的指针，该结构描述验证驻留的资源列表。

pfnRotateResourceIdentities

轮换资源列表。

RotateResourceIdentitiesDXGI 函数必须交换在 pRotateData 参数指向的 DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES 结构的 pResources 成员中传递的资源数组的标识。例如，如果资源数组以递增数组索引顺序引用资源 X、Y 和 Z， 则 RotateResourceIdentitiesDXGI 必须旋转这些句柄以按数组索引递增顺序引用 Y、Z 和 X。具体而言，用户模式显示驱动程序应交换相应资源的内核句柄。但是，驱动程序不应交换相应的运行时 (RT) 句柄。运行时调用 RotateResourceIdentitiesDXGI 以在演示期间回转缓冲区。因此，很少调用 RotateResourceIdentitiesDXGI 。当运行时调用驱动程序的 CreateResource (D3D10) 函数以指示资源可以参与轮换操作时，运行时可以在 D3D10DDIARG_CREATERESOURCE 结构的 BindFlags 成员中指定D3D10_DDI_BIND_PRESENT标志。

用户模式显示驱动程序还必须处理交换标识的其他方面。例如，在 Direct3D 版本 10 中，视图可以引用资源;此类视图可以嵌入资源地址。因此，驱动程序必须重新创建此类视图。此外，驱动程序可能需要重新应用当前绑定的视图。

从 Windows 8 开始，驱动程序必须支持立体声后台缓冲区的旋转。

pRotateData

[in]指向描述要轮换的资源列表的 DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES 结构的指针。

pfnBlt

将源图面的内容复制到目标图面，并可能旋转内容。

Direct3D 运行时可能会设置 pBltData 参数指向的 DXGI_DDI_ARG_BLT 结构的 Flags 成员，以便要求 BltDXGI 函数执行位块传输 (bitblt) 操作，该操作解析多采样资源、执行颜色格式转换以及同时执行拉伸或收缩。但是，Direct3D 运行时永远不会将 DXGI_DDI_ARG_BLT 的 Flags 成员设置为零， (也就是说，) 不设置任何标志以及DXGI_DDI_ARG_BLT ( 的 Rotate 成员中设置的DXGI_DDI_MODE_ROTATION_IDENTITY值，即指示没有旋转) 执行直接内存复制操作。相反，除非这两个资源都是多采样的，否则 Direct3D 运行时会调用驱动程序的 ResourceCopy 或 ResourceCopyRegion 函数来执行直接的内存复制操作。

用户模式显示驱动程序执行的拉伸或收缩质量必须与双线性筛选器执行的拉伸或收缩质量一样好。

Direct3D 运行时不经常调用驱动程序的 BltDXGI 函数。也就是说，运行时应每帧调用 BltDXGI 不超过一次或两次，因为运行时主要使用 BltDXGI 来支持演示文稿。

当运行时为演示文稿调用 BltDXGI 时，运行时会在 DXGI_DDI_ARG_BLT 的 Flags 成员中设置 Present 位字段标志。运行时设置 Present 位字段标志以通知驱动程序 bitblt 有额外的要求，并且可能需要额外的同步 (例如，运行时可能需要在包含两个图形适配器的计算机配置中执行额外的同步，每个适配器处理显示) 的不同部分。设置 Present 位字段标志后，驱动程序应执行从应用程序的后台缓冲区到 DWM 的共享图面的复制操作。由于此类复制操作的同步不精确，因此撕裂项目应该是用户遇到的最差项目类型。对于这种类型的复制操作，驱动程序不应使用多传递方法，方法是先解析到目标图面，然后就地对结果进行颜色转换，因为可能的项目会更糟。

如果驱动程序支持在创建主图面 (期间返回DXGI_DDI_ERR_UNSUPPORTED，则从调用其 CreateResource (D3D10) 函数返回DXGI_DDI_ERR_UNSUPPORTED，该函数在 D3D10DDIARG_CREATERESOURCE 的 BindFlags 成员中设置了 D3D10_DDI_BIND_PRESENT 标志以及 D3D10DDIARG_CREATERESOURCE 的 pPrimaryDesc 成员设置为非 NULL) ，驱动程序还必须在复制操作期间支持旋转。如果驱动程序从不从调用其 CreateResource (D3D10) 函数返回DXGI_DDI_ERR_UNSUPPORTED，则运行时永远不会将DXGI_DDI_MODE_ROTATION_ROTATE90、DXGI_DDI_MODE_ROTATION_ROTATE180或DXGI_DDI_MODE_ROTATION_ROTATE270值传递给 DXGI_DDI_ARG_BLT 的 Rotate 成员。因此，在这种情况下，不需要驱动程序的 BltDXGI 函数来支持旋转。

运行时在 DXGI_DDI_ARG_BLT 的 Rotate 成员中设置一个值，以指示在驱动程序将内容复制到目标之前，要逆时针旋转源内容的度数。旋转以 90 度为增量指定。

注意

当驱动程序的 BltDXGI 函数将 sRGB 格式的内容从源图面复制到非 sRGB 目标图面时，驱动程序应将 sRGB 内容复制不变 (也就是说，驱动程序不应) 执行 sRGB 到线性转换。

源限制

BltDXGI 函数始终使用整个源子资源 (而不是某些子矩形区域) 来执行 bitblt 操作。此外，源是在调用用户模式显示驱动程序的CreateResource ( (D3D10 ) 函数) 中创建源时，在 D3D10DDIARG_CREATERESOURCE 的 ResourceDimension 成员中指定的D3D10DDIRESOURCE_TEXTURE2D表示形式。当运行时在 DXGI_DDI_ARG_BLT 的 Flags 成员中设置 Resolve 位域时，源是多采样资源。源资源仅限于在 D3D10DDIARG_CREATERESOURCE 的 BindFlags 成员中设置了D3D10_DDI_BIND_PRESENT标志的资源。 D3D10DDIARG_CREATERESOURCE) 的 Format 成员中指定的 源 (的格式 限制为显示模式格式，由 DXGI_FORMAT 枚举中的以下值指定：

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM (请参阅下面的说明。)
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

注意

如果驱动程序支持 源格式DXGI_FORMAT_B8G8R8A8_UNORM，则以下限制适用：

当驱动程序执行从浮点格式到整数格式（如BGRA8888）的位运算时，它必须将 gamma 隐式编码到结果中。
相反，当驱动程序执行从整数格式到浮点格式的 bitblt 运算时，它必须从结果中隐式删除伽玛编码。

目标限制

目标也是 D3D10DDIRESOURCE_TEXTURE2D 表示形式。目标的格式也限制为显示模式格式。目标资源限制为作为呈现目标绑定的资源， (D3D10_DDI_BIND_RENDER_TARGET在 D3D10DDIARG_CREATERESOURCE 或 D3D11DDIARG_CREATERESOURCE) 的 BindFlags 成员中设置。

创建立体声后台缓冲区

从 Windows 8 开始，如果驱动程序必须创建立体声后台缓冲区，则应分别设置由CreateResource (D3D10) 或 CreateResource (D3D11 ) 函数指向的 D3D10DDIARG_CREATERESOURCE 或 D3D11DDIARG_CREATERESOURCE 结构的成员，如下所示：