DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP回调函数 (dispmprt.h)

内核模式显示微型端口驱动程序(KMD)调用 DxgkrnlDxgkCbAcquirePostDisplayOwnership 例程,以获取当前开机自测试(POST)显示设备或以前运行的 WDDM 驱动程序的显示信息。

驱动程序必须在启动显示设备后使用此显示信息来优化初始模式更改请求。

语法

DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP DxgkcbAcquirePostDisplayOwnership;

NTSTATUS DxgkcbAcquirePostDisplayOwnership(
  [in]  HANDLE DeviceHandle,
  [out] PDXGK_DISPLAY_INFORMATION DisplayInfo
)
{...}

参数

[in] DeviceHandle

表示显示适配器的句柄。 KMD 以前在传递给 DxgkDdiStartDeviceDXGKRNL_INTERFACE 结构的 DeviceHandle 成员中获取此句柄。

[out] DisplayInfo

指向 KMD 分配的 DXGK_DISPLAY_INFORMATION 结构的指针。 如果 DxgkCbAcquirePostDisplayOwnership 返回STATUS_SUCCESS,则此结构包含用于 POST 操作的当前显示设备的显示信息。

返回值

DxgkCbAcquirePostDisplayOwnership 如果成功,则返回STATUS_SUCCESS。 否则,它将返回 Ntstatus.h中定义的错误代码之一。

言论

调用 DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP 可确保驱动程序根据当前或最近的显示配置正确初始化显示设置,尤其是在系统启动、设备插件事件或从休眠状态恢复之后。

允许的颜色格式

DisplayInfo->ColorFormat 成员必须包含以下两种 D3DDDIFORMAT 格式的按位 OR 组合:

  • D3DDDIFMT_X8R8G8B8
  • D3DDDIFMT_A8R8G8B8

如果 OS 报告回 D3DDDIFMT_R8G8B8 格式,KMD 应将其忽略。

视频演示目标初始化

无法初始化 DisplayInfo->TargetId 成员。 在这种情况下,视频演示目标的标识符 D3DDDI_ID_UNINITIALIZED。 通常情况下,这种情况发生在系统启动之后。

同样,无法初始化 DisplayInfo->AcpiId 成员。 在这种情况下,ACPI 标识符 AcpiId 的值为零。

对于驱动程序到驱动程序升级,以前的驱动程序将提供目标标识符和 ACPI 标识符。

实施指南

从 WDDM 1.2 开始,KMD 必须在调用 DxgkCbAcquirePostDisplayOwnership时遵循以下准则:

  • DxgkCbAcquirePostDisplayOwnership 函数的入口点是 DXGKRNL_INTERFACE 结构的一部分。 调用驱动程序的 DxgkDdiStartDevice 函数时,将通过 DxgkInterface 参数将此结构返回到驱动程序。

  • KMD 可以选择调用 DxgkCbAcquirePostDisplayOwnership。 但是,OS 仍可能调用 KMD 的DxgkDdiStopDeviceAndReleasePostDisplayOwnership 函数,即使驱动程序之前未调用 DxgkCbAcquirePostDisplayOwnership,驱动程序也必须适当处理该调用。 如果驱动程序的 DxgkDdiStopDeviceAndReleasePostDisplayOwnership 函数未成功完成,则 OS 将调用驱动程序的 DxgkDdiStopDevice 函数。

  • 如果设备启动以响应即插即用(PnP)事件,KMD 可以调用 DxgkCbAcquirePostDisplayOwnership。 在这种情况下,驱动程序必须从调用 DxgkDdiStartDevice 函数的上下文中调用 DxgkCbAcquirePostDisplayOwnership

  • 如果设备在休眠状态后恢复 PowerDeviceD0 电源状态,KMD 可以调用 DxgkCbAcquirePostDisplayOwnership。 在这种情况下,驱动程序必须从调用 DxgkDdiSetPowerState 函数的上下文中调用 DxgkCbAcquirePostDisplayOwnership

  • KMD 必须仅在运行至少 Windows 8 的情况下调用 DxgkCbAcquirePostDisplayOwnership 函数。 KMD 可以调用 RtlGetVersion 来确定操作系统的版本。

  • DxgkCbAcquirePostDisplayOwnership 可以返回 Width 成员设置为零的 DXGK_DISPLAY_INFORMATION 结构。 此值指示当前显示设备无法执行 POST 操作,或者 OS 没有当前 POST 设备的当前显示信息。

要求

要求 价值
最低支持的客户端 Windows 8 (WDDM 1.2)
支持的最低服务器 Windows Server 2012
目标平台 桌面
标头 dispmprt.h (包括 Dispmprt.h)
IRQL <= APC_LEVEL

另请参阅

D3DDDIFORMAT

DXGKRNL_INTERFACE

DXGK_DISPLAY_INFORMATION

DxgkDdiSetPowerState

DxgkDdiStartDevice

DxgkDdiStopDeviceAndReleasePostDisplayOwnership

RtlGetVersion