DXGKDDI_SYSTEM_DISPLAY_ENABLE callback function (dispmprt.h)

Article
10/21/2021

Called by the operating system to request the display miniport driver to reset the current display device to a specified state.

Starting with Windows 8, the operating system calls this function during a bugcheck operation following a system stop error.

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

A handle to a context block that is associated with a display adapter. The display miniport driver's DxgkDdiAddDevice function previously provided this handle to the Microsoft DirectX graphics kernel subsystem.

[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.

For more details about the use of the TargetId parameter, see the following "Video present target initialization" section.

[in] Flags

A pointer to a value that contains a bitwise OR of flags. This member is reserved by the operating system.

[out] Width

A UINT value that specifies the width of the display mode of the specified device in units of pixels.

[out] Height

A UINT value that specifies the height of the display mode of the specified device in units of pixels.

[out] ColorFormat

A 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 is not connected to a display device, the function returns STATUS_NOT_SUPPORTED. Otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

Required steps by display miniport driver

The display miniport driver must follow these steps when its DxgkDdiSystemDisplayEnable function is called:

The driver must cancel all graphics processing unit (GPU) operations or reset the GPU to the idle state.
The operating system 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 cannot power on the display, it must fail the call to this function. In such a failure case, the operating system might call the DxgkDdiResetDevice function and cause a system bugcheck to occur.
The driver must check the connectivity of the display associated with this target. If the target does not have a display connected, the driver must complete the call to this function and return the STATUS_NOT_SUPPORTED error code.
The driver must disable the signal to all other displays that are connected to the display adapter. If this is not possible, the driver should attempt to place a blank image on all other displays. If this is not possible, the driver must leave the last image on the screen unchanged.
The driver must keep the current display mode on the indicated target and provide this mode back to the operating system as part of this function call.
If the driver cannot 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 that is not possible, the driver can fail this function call, which will result in a system bugcheck and the display of a black screen.
It is not required that the driver use a linear frame buffer mode. However, the driver should support write operations to this frame buffer from sources that have the D3DDDIFMT_A8R8G8B8 format of the D3DDDIFORMAT enumeration.

Source image restrictions

After the driver gives the operating system control over display functionality, the operating system 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 operating system guarantees that the source image is in non-paged memory.

The driver 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 is 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.

Requirements

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