DXGKDDI_SYSTEM_DISPLAY_ENABLE callback function (dispmprt.h)

Artikel
01/15/2025

The OS calls the kernel-mode display driver's (KMD) DxgkddiSystemDisplayEnable function to request that KMD reset the current display device to a specified state.

Syntax

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
)
{...}

Parameters

[in] MiniportDeviceContext

Handle to a context block associated with a display adapter. KMD's DxgkDdiAddDevice function previously provided this handle to Dxgkrnl.

[in] TargetId

A D3DDDI_VIDEO_PRESENT_TARGET_ID value that specifies the identifier of the video present target on the display adapter that the display device is connected to. This identifier could be for the target that was left in the current video present network (VidPn) state during the previous call to DxgkDdiCommitVidPn.

[in] Flags

Pointer to a DXGKARG_SYSTEM_DISPLAY_ENABLE_FLAGS value that contains a bitwise OR of flags. This member is reserved by the OS.

[out] Width

Width of the display mode of the specified device, in pixels.

[out] Height

Height of the display mode of the specified device, in pixels.

[out] ColorFormat

Pointer to a D3DDDIFORMAT value that specifies the color format of the display device.

Return value

DxgkDdiSystemDisplayEnable returns STATUS_SUCCESS if it succeeds. If the target specified by the TargetId parameter isn't connected to a display device, the function returns STATUS_NOT_SUPPORTED. Otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

The OS calls DxgkddiSystemDisplayEnable during a bugcheck operation following a system stop error.

Required steps by KMD

The KMD must follow these steps when its DxgkDdiSystemDisplayEnable function is called:

Cancel all GPU operations or reset the GPU to the idle state.
The OS indicates the video present target through the TargetId parameter. The driver must keep the display associated with this target powered on and visible. If the driver can't power on the display, it must fail the call to this function. In such a failure case, the OS might call DxgkDdiResetDevice and cause a system bugcheck to occur.
Check the connectivity of the display associated with this target. If the target doesn't have a display connected, the driver must complete the call to this function and return the STATUS_NOT_SUPPORTED error code.
Disable the signal to all other displays that are connected to the display adapter. If this isn't possible, the driver should attempt to place a blank image on all other displays. If this isn't possible, the driver must leave the last image on the screen unchanged.
Keep the current display mode on the indicated target and provide this mode back to the OS as part of this function call.
If the driver can't maintain the current display mode, or if the target is not part of the active topology, the driver should attempt to set a frame buffer on another target that is capable of a display resolution of at least 640 x 480 pixels in a format of 24 bits per pixel. If this isn't possible, the driver can fail this function call, which will result in a system bugcheck and the display of a black screen.

KMD doesn't have to use a linear frame buffer mode. However, KMD should support write operations to this frame buffer from sources that have the D3DDDIFMT_A8R8G8B8 format of the D3DDDIFORMAT enumeration.

Source image restrictions

After KMD gives the OS control over display functionality, the OS can call the DxgkDdiSystemDisplayWrite function to update the screen image and to write a block of images from specified sources to the screen that was reset by the DxgkDdiSystemDisplayEnable function.

DxgkDdiSystemDisplayWrite provides the driver with the starting address of the source image as well as the stride, width, and height. The color format of the source image is always D3DDDIFMT_X8R8G8B8. The OS guarantees that the source image is in non-paged memory.

KMD must write this source image to the current screen starting at the positions specified by the PositionX and PositionY parameters of the DxgkDdiSystemDisplayWrite function.

It's recommended that the driver use the CPU to write the image from the source to the frame buffer because a system bugcheck might be caused by repeated Timeout Detection and Recovery (TDR) instances that result in the GPU being in an unknown condition.

Use non-paged memory

Windows kernel-mode functions might not be available while this function is being called.

DxgkDdiSystemDisplayEnable can be called at any IRQL, so it must be in nonpageable memory. DxgkDdiSystemDisplayEnable must not call any code that is in pageable memory and must not manipulate any data that is in pageable memory.

Automatic display switching

An automatic display switch driver's DxgkDdiSystemDisplayEnable DDI must ensure that panel self refresh (PSR) is disabled at the end of the call to it. For more information, see Automatic Display Switch.

Requirements

Requirement	Value
Minimum supported client	Windows 8 (WDDM 1.2)
Minimum supported server	Windows Server 2012
Target Platform	Desktop
Header	dispmprt.h
IRQL	Any level (see Remarks section)

Delen via