DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP callback function (dispmprt.h)

Article
10/21/2021

Called by a Windows Display Driver Model (WDDM) 1.2 or later display miniport driver to obtain the display information from the current power-on self-test (POST) display device or the previously running WDDM driver.

The driver must use this display information to optimize the initial mode change request after the display device has been started.

Syntax

DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP DxgkcbAcquirePostDisplayOwnership;

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

Parameters

[in] DeviceHandle

A handle that represents a display adapter. The display miniport driver previously obtained this handle in the DeviceHandle member of the DXGKRNL_INTERFACE structure that was passed to DxgkDdiStartDevice.

[out] DisplayInfo

A pointer to a DXGK_DISPLAY_INFORMATION structure that is allocated by the display miniport driver. If DxgkCbAcquirePostDisplayOwnership returns STATUS_SUCCESS, this structure contains display information for the current display device that is used for POST operations.

Return value

DxgkCbAcquirePostDisplayOwnership returns STATUS_SUCCESS if it succeeds. Otherwise, it returns one of the error codes defined in Ntstatus.h.

Remarks

Allowed color formats

The DisplayInfo->ColorFormat member must include a bitwise-OR combination of the following two formats:

D3DDDIFMT_X8R8G8B8
D3DDDIFMT_A8R8G8B8

If the operating system reports back the D3DDDIFMT_R8G8B8 format, the display miniport driver should ignore it.

Video present target initialization

It is possible that the DisplayInfo->TargetId member is not initialized. In this case, the identifier of the video present target is D3DDDI_ID_UNINITIALIZED. Typically, this occurs after a system boot.

Similarly, it is possible that the DisplayInfo->AcpiId member is not initialized. In this case, the ACPI identifier AcpiId has a value of zero.

In the case of a driver-to-driver upgrade, the previous driver will have provided the target identifier and the ACPI identifier.

Implementation guidelines

Starting with WDDM 1.2, the display miniport driver must follow these guidelines when it calls DxgkCbAcquirePostDisplayOwnership:

The entry point for the DxgkCbAcquirePostDisplayOwnership function is part of the DXGKRNL_INTERFACE structure. This structure is returned to the driver through the DxgkInterface parameter when the driver's DxgkDdiStartDevice function is called.
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.
The display miniport driver can call DxgkCbAcquirePostDisplayOwnership if the device is started in response to a Plug and Play (PnP) event. In this case, the driver must call DxgkCbAcquirePostDisplayOwnership from within the context of the call to the DxgkDdiStartDevice function.
The display miniport driver can call DxgkCbAcquirePostDisplayOwnership if the device resumes a PowerDeviceD0 power state after a hibernation state. In this case, the driver must call DxgkCbAcquirePostDisplayOwnership from within the context of the call to the DxgkDdiSetPowerState function.
The display miniport driver must only call the DxgkCbAcquirePostDisplayOwnership function if the driver is running under Windows 8 or a later version of the Windows operating system.
Note The display miniport driver can call RtlGetVersion to determine the version of the operating system.
DxgkCbAcquirePostDisplayOwnership may return a DXGK_DISPLAY_INFORMATION structure with the Width member set to zero. This indicates that either the current display device is not capable of POST operations or the operating system does not have the current display information for the current POST device.

Requirements

Requirement	Value
Minimum supported client	Windows 8
Minimum supported server	Windows Server 2012
Target Platform	Desktop
Header	dispmprt.h (include Dispmprt.h)
IRQL	<= APC_LEVEL