DXGKDDI_SYSTEM_DISPLAY_ENABLE回调函数 (dispmprt.h)

项目
02/26/2024

由操作系统调用，以请求显示微型端口驱动程序将当前显示设备重置为指定状态。

从 Windows 8 开始，操作系统在出现系统停止错误后执行 bug 检查操作期间调用此函数。

语法

DXGKDDI_SYSTEM_DISPLAY_ENABLE DxgkddiSystemDisplayEnable;

NTSTATUS DxgkddiSystemDisplayEnable(
  [in]  PVOID MiniportDeviceContext,
  [in]  D3DDDI_VIDEO_PRESENT_TARGET_ID TargetId,
  [in]  PDXGKARG_SYSTEM_DISPLAY_ENABLE_FLAGS Flags,
  [out] UINT *Width,
  [out] UINT *Height,
  [out] D3DDDIFORMAT *ColorFormat
)
{...}

参数

[in] MiniportDeviceContext

与显示适配器关联的上下文块的句柄。显示微型端口驱动程序的 DxgkDdiAddDevice 函数以前向 Microsoft DirectX 图形内核子系统提供了此句柄。

[in] TargetId

一个 D3DDDI_VIDEO_PRESENT_TARGET_ID 值，该值指定显示设备连接到的显示适配器上的视频存在目标的标识符。此标识符可以是在上次调用 DxgkDdiCommitVidPn 期间，当前视频当前网络 (VidPn) 状态中留下的目标。

有关 使用 TargetId 参数的更多详细信息，请参阅以下“视频呈现目标初始化”部分。

[in] Flags

指向包含标志的按位 OR 的值的指针。此成员由操作系统保留。

[out] Width

一个 UINT 值，该值指定指定设备的显示模式的宽度（以像素为单位）。

[out] Height

一个 UINT 值，该值指定指定设备的显示模式的高度（以像素为单位）。

[out] ColorFormat

指向 D3DDDIFORMAT 值的指针，该值指定显示设备的颜色格式。

返回值

如果成功，DxgkDdiSystemDisplayEnable 将返回STATUS_SUCCESS。如果 TargetId 参数指定的目标未连接到显示设备，则函数返回STATUS_NOT_SUPPORTED。否则，它将返回 Ntstatus.h 中定义的错误代码之一。

注解

显示微型端口驱动程序所需的步骤

调用其 DxgkDdiSystemDisplayEnable 函数时，显示微型端口驱动程序必须遵循以下步骤：

驱动程序必须取消所有图形处理单元 (GPU) 操作或将 GPU 重置为空闲状态。
操作系统通过 TargetId 参数指示视频存在目标。驱动程序必须使与此目标关联的显示器保持打开并可见。如果驱动程序无法打开显示器，则必须使对此函数的调用失败。在此类故障情况下，操作系统可能会调用 DxgkDdiResetDevice 函数并导致发生系统 bug 检查。
驱动程序必须检查与此目标关联的显示器的连接。如果目标未连接显示器，驱动程序必须完成对此函数的调用并返回 STATUS_NOT_SUPPORTED 错误代码。
驱动程序必须禁用连接到显示适配器的所有其他显示器的信号。如果无法执行此操作，驱动程序应尝试在所有其他显示器上放置空白图像。如果无法执行此操作，驱动程序必须保留屏幕上的最后一个图像不变。
驱动程序必须在指示的目标上保留当前显示模式，并将此模式作为此函数调用的一部分提供给操作系统。
如果驱动程序无法维持当前显示模式，或者目标不是活动拓扑的一部分，则驱动程序应尝试在另一个目标上设置帧缓冲区，该目标的显示分辨率至少为 640 x 480 像素，格式为每像素 24 位。如果这不可行，驱动程序可能会使此函数调用失败，这将导致系统 bug 检查并显示黑屏。
驱动程序不需要使用线性帧缓冲模式。但是，驱动程序应支持从具有 D3DDDIFORMAT 枚举D3DDDIFMT_A8R8G8B8格式的源对此帧缓冲区执行写入操作。

源图像限制

在驱动程序为操作系统提供对显示功能的控制后，操作系统可以调用 DxgkDdiSystemDisplayWrite 函数来更新屏幕图像，并将指定源中的图像块写入由 DxgkDdiSystemDisplayEnable 函数重置的屏幕。

DxgkDdiSystemDisplayWrite 为驱动程序提供源图像的起始地址以及步幅、宽度和高度。源图像的颜色格式始终 D3DDDIFMT_X8R8G8B8。操作系统保证源映像位于非分页内存中。

驱动程序必须将此源图像写入当前屏幕，从 DxgkDdiSystemDisplayWrite 函数的 PositionX 和 PositionY 参数指定的位置开始。

建议驱动程序使用 CPU 将映像从源写入帧缓冲区，因为系统 bug 检查可能是由重复的超时检测和恢复 (TDR) 实例导致的，这些实例导致 GPU 处于未知状态。

使用非分页内存

调用此函数时，Windows 内核模式函数可能不可用。

可以在任何 IRQL 上调用 DxgkDdiSystemDisplayEnable，因此它必须位于不可分页的内存中。 DxgkDdiSystemDisplayEnable 不得调用可分页内存中的任何代码，也不得操作可分页内存中的任何数据。

要求

要求	值
最低受支持的客户端	Windows 8
最低受支持的服务器	Windows Server 2012
目标平台	桌面
标头	dispmprt.h
IRQL	任何级别 (请参阅“备注”部分)