DXGKDDI_STOP_DEVICE_AND_RELEASE_POST_DISPLAY_OWNERSHIP callback function (dispmprt.h)

Article
10/21/2021

Called by the operating system to request the display miniport driver to reset the display device and to release ownership of the current power-on self-test (POST) device.

Starting with Windows 8, the operating system calls this function during a Plug and Play (PnP) stop operation.

To indicate to the operating system that this function is supported, the driver must set the NonVGASupport member of the DXGK_DRIVERCAPS structure when the DxgkDdiQueryAdapterInfo function is called.

Syntax

DXGKDDI_STOP_DEVICE_AND_RELEASE_POST_DISPLAY_OWNERSHIP DxgkddiStopDeviceAndReleasePostDisplayOwnership;

NTSTATUS DxgkddiStopDeviceAndReleasePostDisplayOwnership(
  [in]  PVOID MiniportDeviceContext,
  [in]  D3DDDI_VIDEO_PRESENT_TARGET_ID TargetId,
  [out] PDXGK_DISPLAY_INFORMATION DisplayInfo
)
{...}

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 Remarks section.

[out] DisplayInfo

A pointer to a DXGK_DISPLAY_INFORMATION structure that is allocated by the operating system.

Return value

Returns STATUS_SUCCESS if it succeeds. Otherwise, it returns one of the error codes defined in Ntstatus.h. For more information, see the following Remarks section.

Remarks

Allowed color formats

The display miniport driver should report only a 32-bit color format. Therefore the DisplayInfo->ColorFormat member must include only one of the following two formats:

D3DDDIFMT_X8R8G8B8
D3DDDIFMT_A8R8G8B8

Video present target initialization

The display miniport driver must set the DisplayInfo->TargetId member to the target identifier of the display that remains active. Typically, this identifier will be the value of the TargetId parameter that the operating system passed to the driver.

Similarly, the display miniport driver must set the DisplayInfo->AcpiId member to the ACPI identifier of the display that remains active.

Required steps by display miniport driver

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

The driver must stop the display device associated with the video present target indicated by the TargetId parameter but must keep the display associated with this target powered on and visible.
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 select an alternate active target and attempt to maintain the current resolution of that target. If that is not possible, the driver should attempt to set the display to its native resolution or to a high-resolution mode. In this case, the display resolution must be set to at least 800 x 600 pixels in either D3DDDIFMT_R8G8B8 (24 bits per pixel) or D3DDDIFMT_X8R8G8B8 (32 bpp) color formats of the D3DDDIFORMAT enumeration.
If no target is active, the driver should attempt to enable a target, preferably the internal panel, if it is available.
If possible, the driver must clear the current frame buffer and disable the hardware cursor and all display overlays.
If possible, the driver must set the gamma ramp of the device to its default values.
The driver must set the current frame buffer to be in a linear mode. The driver does this either by using the default swizzle range or by disabling swizzle mode.
The driver must make the current frame buffer accessible to the CPU by mapping the current frame buffer linearly into the CPU address space.
The driver must ensure that the visibility of the indicated target is set to "enabled."

After the display miniport driver performs these steps, it must return the current display settings for the device. The driver returns this information by setting the members of the DXGK_DISPLAY_INFORMATION structure that is referenced by the DisplayInfo parameter.

Note After the device has been stopped, this display information might be used by the Windows generic display driver to manage the display device.

Other requirements

On systems that support the Unified Extensible Firmware Interface (UEFI), a VGA basic input/output system (BIOS) does not exist. To support PnP stop operations on these systems, Windows Display Driver Model (WDDM) 1.2 and later provides support for the operating system to reset the POST device and to get its display information during a PnP stop operation. The operating system does this by calling the display miniport driver's DxgkDdiStopDeviceAndReleasePostDisplayOwnership function.

A PnP stop operation can occur in response to requests by processes such as the Device Manager, or during a driver upgrade process.

Starting with Windows 8, the operating system calls the driver's DxgkDdiStopDeviceAndReleasePostDisplayOwnership function only on the POST device during a PnP stop operation.

Note It is optional for the display miniport driver to call DxgkCbAcquirePostDisplayOwnership. However, the operating system might still call the DxgkDdiStopDeviceAndReleasePostDisplayOwnership function of the device driver if the driver did not previously call DxgkCbAcquirePostDisplayOwnership.

If the driver successfully completes a call to this function, the operating system will not call the DxgkDdiStopDevice function. If the driver fails to complete a call to this function, the operating system will call the DxgkDdiStopDevice function, and device behavior will be the same as in Windows 7.

On UEFI-only systems, if the display miniport driver fails a call to this function, a black screen is displayed and the IHV driver is not installed. The workaround to this scenario is for the user to reboot the computer.

For more information on how this function is used in PnP scenarios, see Plug and Play (PnP) in WDDM 1.2 and later.

Requirements

Requirement	Value
Minimum supported client	Windows 8
Minimum supported server	Windows Server 2012
Target Platform	Desktop
Header	dispmprt.h
IRQL	PASSIVE_LEVEL