DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP callback function (dispmprt.h)

Article
01/07/2025

A kernel-mode display miniport driver (KMD) calls Dxgkrnl's DxgkCbAcquirePostDisplayOwnership routine 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 KMD previously obtained this handle in the DeviceHandle member of the DXGKRNL_INTERFACE structure that was passed to DxgkDdiStartDevice.

[out] DisplayInfo

Pointer to a DXGK_DISPLAY_INFORMATION structure that is allocated by the KMD. 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

Calling DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP ensures that the driver correctly initializes the display settings based on the current or most recent display configuration, especially after system start-up, device plug-in events, or resuming from hibernation.

Allowed color formats

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

D3DDDIFMT_X8R8G8B8
D3DDDIFMT_A8R8G8B8

If the OS reports back the D3DDDIFMT_R8G8B8 format, the KMD should ignore it.

Video present target initialization

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

Similarly, it's possible that the DisplayInfo->AcpiId member isn't 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 KMD 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.
KMD can optionally call DxgkCbAcquirePostDisplayOwnership. However, the OS might still call KMD'sDxgkDdiStopDeviceAndReleasePostDisplayOwnership function, even if the driver didn't previously call DxgkCbAcquirePostDisplayOwnership, and the driver must handle that call appropriately. If the driver's DxgkDdiStopDeviceAndReleasePostDisplayOwnership function doesn't complete successfully, the OS will call the driver's DxgkDdiStopDevice function.
The KMD 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 KMD 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 KMD must only call the DxgkCbAcquirePostDisplayOwnership function if it's running at least Windows 8. The KMD can call RtlGetVersion to determine the version of the OS.
DxgkCbAcquirePostDisplayOwnership can return a DXGK_DISPLAY_INFORMATION structure with the Width member set to zero. This value indicates that either the current display device isn't capable of POST operations or the OS doesn't have the current display information for the current POST device.

Requirements

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

Share via