DXGKDDI_RENDERKM回调函数 (d3dkmddi.h)

项目
06/10/2023

对于支持 GDI 硬件加速的显示适配器， DxgkDdiRenderKm 函数从内核模式规范显示驱动程序 (CDD) 传递的命令缓冲区生成直接内存访问 (DMA) 缓冲区。

语法

DXGKDDI_RENDERKM DxgkddiRenderkm;

NTSTATUS DxgkddiRenderkm(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_RENDER pRenderKmArgs
)
{...}

参数

[in] hContext

DMA 和命令缓冲区的设备上下文的句柄。显示微型端口驱动程序的 DxgkDdiCreateContext 函数以前在 dxgkDdiCreateContext 的 pCreateContext 参数指向的 DXGKARG_CREATECONTEXT 结构的 hContext 成员中返回此句柄。

如果驱动程序不支持上下文创建，Microsoft DirectX 图形内核子系统会将上下文的句柄替换为设备的句柄。显示微型端口驱动程序的 DxgkDdiCreateDevice 函数之前返回了 dxgkDdiCreateDevice 的 pCreateDevice 参数指向的 DXGKARG_CREATEDEVICE 结构的 hDevice 成员中的设备句柄。

[in/out] pRenderKmArgs

指向 DXGKARG_RENDER 结构的指针，该结构包含有关 DMA 缓冲区和格式化命令缓冲区的信息。

如果显示微型端口驱动程序支持 GDI 硬件加速，pRenderKmArgs-pCommand> 指向DXGK_RENDERKM_COMMAND命令缓冲区。

驱动程序必须将输入命令缓冲区转换为 DMA 缓冲区命令，并生成修补程序位置列表。

返回值

DxgkDdiRenderKm 返回以下值之一：

返回代码	说明
STATUS_SUCCESS	已转换整个命令缓冲区。
STATUS_NO_MEMORY	DxgkDdiRenderKm 无法分配完成该操作所需的内存。
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	当前 DMA 缓冲区已耗尽。
STATUS_INVALID_PARAMETER	DxgkDdiRenderKm 检测到图形硬件不支持的指令参数;但是，图形硬件本身可以支持指令。驱动程序不需要返回此错误代码。相反，它可以在检测到不受支持的指令参数时返回STATUS_ILLEGAL_INSTRUCTION。
STATUS_INVALID_USER_BUFFER	DxgkDdiRenderKm 检测到数据或指令不足或溢出。也就是说，驱动程序收到的指令或数据少于或多于预期。驱动程序不需要返回此错误代码。相反，当检测到数据或指令不足或溢出时，它可以返回STATUS_ILLEGAL_INSTRUCTION。
STATUS_INVALID_HANDLE	DxgkDdiRenderKm 在命令缓冲区中检测到无效句柄。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	显示微型端口驱动程序在 DMA 流中检测到错误。如果驱动程序返回此错误代码，则图形上下文设备将处于丢失状态。

注解

DirectX 图形内核子系统调用显示微型端口驱动程序的 DxgkDdiRenderKm 函数，以从操作系统提供的内核模式规范显示驱动程序 (CDD) 传递的命令缓冲区生成 DMA 缓冲区。除了输出 DMA 缓冲区外，显示微型端口驱动程序还应生成输出修补程序位置的列表。视频内存管理器使用此列表相应地拆分和修补 DMA 缓冲区。

访问内核缓冲区不需要代码 try/except 保护。

如果显示微型端口驱动程序可以更优化地重新创建信息，则不需要使用 CDD 提供的信息。例如，如果 pRender-pPatchLocationListIn> 成员为空，因为用户模式显示驱动程序未提供输入修补程序位置列表，则显示微型端口驱动程序可以根据命令缓冲区的内容生成 pRender-pPatchLocationListOut> 成员的内容。

除了特定于设备的句柄，DirectX 图形内核子系统还为显示微型端口驱动程序提供每个分配的最后一个已知 GPU 段地址。如果分配索引 N 当前已分页，则 DirectX 图形内核子系统将 DXGKARG_RENDERpAllocationList 成员的第 N个元素的 SegmentId 成员设置为零。如果分配列表的第 N个元素的 SegmentId 成员未设置为零，则在 DirectX 图形内核子系统调用 DxgkDdiPatch 函数以重新修补 DMA 缓冲区之前，显示微型端口驱动程序必须使用提供的段地址信息修补生成的 DMA 缓冲区。驱动程序必须在请求时执行此初始修补，因为 DirectX 图形内核子系统可能不会在驱动程序应正确修补的 DMA 缓冲区上调用 DxgkDdiPatch 函数。

即使驱动程序的 DxgkDdiRenderKm 函数执行上述初始 DMA 缓冲区修补，驱动程序仍必须将对分配的所有引用插入到DXGKARG_RENDER的 pPatchLocationListOut 成员指定的输出修补程序位置列表中。此列表必须包含所有引用，因为在将 DMA 缓冲区提交到 GPU 之前，分配的地址可能会更改;因此，DirectX 图形内核子系统将调用 DxgkDdiPatch 函数来重新修补 DMA 缓冲区。

若要取消绑定分配，显示微型端口驱动程序可以在分配列表中指定引用 NULL 句柄的元素，然后使用引用该 NULL 分配的修补程序位置元素。通常，驱动程序应使用分配列表的第一个元素 (元素 0) 作为 NULL 元素。

在有保证的协定 DMA 模式下，当显示微型端口驱动程序将命令缓冲区转换为 DMA 缓冲区时，CDD 必须保证翻译命令有足够的资源。如果没有足够的资源用于转换，则显示微型端口驱动程序必须拒绝 DMA 缓冲区。有关详细信息，请参阅使用保证协定 DMA 缓冲区模型。

DxgkDdiRenderKm 应可分页。