DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP回呼函式（dispmprt.h）

發行項
01/07/2025

內核模式顯示迷你埠驅動程式（KMD）會呼叫 Dxgkrnl的 DxgkCbAcquirePostDisplayOwnership 例程，以從目前電源上自我測試（POST）顯示裝置或先前執行的 WDDM 驅動程式取得顯示資訊。

驅動程式必須使用此顯示資訊，在啟動顯示裝置之後優化初始模式變更要求。

語法

DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP DxgkcbAcquirePostDisplayOwnership;

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

參數

[in] DeviceHandle

表示顯示配接器的句柄。 KMD 先前在傳遞至 dxgkDdiStartDeviceDxgkDdiStartDevice 的 DXGKRNL_INTERFACE 結構成員中取得此句柄。

[out] DisplayInfo

KMD 所設定之 DXGK_DISPLAY_INFORMATION 結構的指標。如果 DxgkCbAcquirePostDisplayOwnership 傳回STATUS_SUCCESS，則此結構會包含用於 POST 作業之目前顯示裝置的顯示資訊。

傳回值

DxgkCbAcquirePostDisplayOwnership 如果成功，則會傳回STATUS_SUCCESS。否則，它會傳回 Ntstatus.h中定義的其中一個錯誤碼。

言論

呼叫 DXGKCB_ACQUIRE_POST_DISPLAY_OWNERSHIP 可確保驅動程式會根據目前或最近的顯示組態正確初始化顯示設定，特別是在系統啟動、裝置外掛程式事件或從休眠狀態繼續之後。

允許的色彩格式

DisplayInfo->ColorFormat 成員必須包含下列兩種 D3DDDIFORMAT 格式的位 OR 組合：

D3DDDIFMT_X8R8G8B8
D3DDDIFMT_A8R8G8B8

如果 OS 回報 D3DDDIFMT_R8G8B8 格式，KMD 應該忽略它。

影片呈現目標初始化

DisplayInfo->TargetId 成員可能未初始化。在這裡情況下，影片呈現目標的識別碼 D3DDDI_ID_UNINITIALIZED。一般而言，這種情況會在系統開機之後發生。

同樣地，DisplayInfo->AcpiId 成員可能尚未初始化。在此情況下，ACPI識別碼 AcpiId 值為零。

在驅動程式對驅動程式升級的情況下，先前的驅動程式會提供目標標識碼和ACPI標識符。

實作指導方針

從 WDDM 1.2 開始，KMD 必須在呼叫 DxgkCbAcquirePostDisplayOwnership時遵循下列指導方針：

DxgkCbAcquirePostDisplayOwnership 函式的進入點是 DXGKRNL_INTERFACE 結構的一部分。呼叫驅動程式的 DxgkDdiStartDevice 函式時，會透過 DxgkInterface 參數將這個結構傳回給驅動程式。
KMD 可以選擇性地呼叫 DxgkCbAcquirePostDisplayOwnership。不過，OS 可能仍會呼叫 KMD 的DxgkDdiStopDeviceAndReleasePostDisplayOwnership 函式，即使驅動程式先前未呼叫 DxgkCbAcquirePostDisplayOwnership，驅動程式也必須適當處理該呼叫。如果驅動程式的 DxgkDdiStopDeviceAndReleasePostDisplayOwnership 函式未順利完成，OS 會呼叫驅動程式的 DxgkDdiStopDevice 函式。
KMD 可以呼叫 DxgkCbAcquirePostDisplayOwnership，如果裝置已啟動以回應即插即用（PnP）事件。在此情況下，驅動程式必須從呼叫 DxgkDdiStartDevice 函式的內容中呼叫 DxgkCbAcquirePostDisplayOwnership。
如果裝置在休眠狀態之後繼續 PowerDeviceD0 電源狀態，KMD 可以呼叫 DxgkCbAcquirePostDisplayOwnership。在此情況下，驅動程式必須在呼叫 DxgkDdiSetPowerState 函式的內容中呼叫 DxgkCbAcquirePostDisplayOwnership。
KMD 只有在至少執行 Windows 8 時，才能呼叫 DxgkCbAcquirePostDisplayOwnership 函式。 KMD 可以呼叫 RtlGetVersion，以判斷 OS 的版本。
DxgkCbAcquirePostDisplayOwnership 可以傳回 DXGK_DISPLAY_INFORMATION 結構，Width 成員設定為零。這個值表示目前的顯示裝置無法執行 POST 作業，或作業系統沒有目前 POST 裝置目前的顯示資訊。

要求

要求	價值
最低支援的用戶端	Windows 8 （WDDM 1.2）
支援的最低伺服器	Windows Server 2012
目標平臺	桌面
標頭	dispmprt.h （包括 Dispmprt.h）
IRQL	<= APC_LEVEL