DXGKDDI_PRESENT回呼函式 (d3dkmddi.h)

發行項
02/23/2024

DxgkDdiPresent 函式會將來源配置的內容複製到主要介面 (，有時也會複製到螢幕外系統記憶體配置) 。

語法

DXGKDDI_PRESENT DxgkddiPresent;

NTSTATUS DxgkddiPresent(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_PRESENT pPresent
)
{...}

參數

[in] hContext

複製資訊的裝置內容句柄。顯示迷你埠驅動程式的 DxgkDdiCreateContext 函式先前在 dxgkDdiCreateContext 參數指向的 DXGKARG_CREATECONTEXT 結構 hContext 成員中傳回此句柄。

如果驅動程式不支持內容建立，Microsoft DirectX 圖形核心子系統會將內容的句柄取代為裝置的句柄。顯示迷你連接埠驅動程式的 DxgkDdiCreateDevice 函式先前傳回DXGKARG_CREATEDEVICE 結構之 pCreateDevice 參數指向的 hDevice 成員中的裝置句柄。

[in/out] pPresent

包含複製作業相關信息之DXGKARG_PRESENT 結構的指標。

傳回值

DxgkDdiPresent 會傳回下列其中一個值：

傳回碼	Description
STATUS_SUCCESS	DxgkDdiPresent 已成功複製內容。
STATUS_NO_MEMORY或STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent 無法配置完成所需的記憶體。
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	目前直接記憶體存取 (DMA) 緩衝區已耗盡。
STATUS_GRAPHICS_CANNOTCOLORCONVERT	顯示迷你埠驅動程式偵測到位區塊傳輸 (bitblt) 裝置無法執行的色彩轉換。 Microsoft Direct3D 運行時間可防止應用程式繼續，而且應用程式收到無法複製內容。
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent 偵測到非特殊許可權的指令 (，也就是存取記憶體超出目前中央處理單位 [CPU] 進程許可權的指示) 。
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent 偵測到圖形硬體不支援的指示。
STATUS_INVALID_HANDLE	DxgkDdiPresent 偵測到命令緩衝區中的無效句柄。
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	顯示迷你埠驅動程式在 DMA 數據流中偵測到錯誤。如果驅動程式傳回此錯誤碼，圖形內容裝置會處於遺失狀態。

備註

DirectX 圖形核心子系統會呼叫顯示迷你埠驅動程式的 DxgkDdiPresent 函式，以將內容從來源配置通常複製到主要介面。 (此函式也可以將內容複製到螢幕外系統記憶體配置。) 因為主要介面已鬆散定義，因此可以針對下列案例實作 DxgkDdiPresent ：

視視窗的位置而定， DxgkDdiPresent 函式必須在位於相同適配卡或不同適配卡的不同主要上執行。
主要復本位於遠端監視器上，可透過終端機服務用戶端或 Microsoft NetMeeting 存取。
最近發生模式切換，且主要格式與來源格式不同，因此需要色彩轉換。此外，因為視窗裁剪和排序，所以可以裁剪 DxgkDdiPresent 作業。

由於上述案例可以異步變更，因此使用者模式顯示驅動程式無法事先編譯顯示迷你埠驅動程式 DxgkDdiPresent 函式的硬體指示。顯示迷你埠驅動程式必須針對實際的 DxgkDdiPresent 作業建立硬體命令，而且必須放在輸出 DMA 緩衝區中。呼叫顯示迷你埠驅動程式的 DxgkDdiPresent 函式以產生 DMA 緩衝區之後，操作系統會保證在轉譯該緩衝區之前不會發生案例變更。

只要驅動程序支援下列抽象概念，就不需要顯示迷你埠驅動程式，才能注意上述案例的詳細數據：

在從視訊記憶體來源複製到主要視訊或系統記憶體目的地的複製作業中，從螢幕外系統記憶體來源複製到主要目的地、從主要來源到主要目的地的複本，或從主要來源複製到非螢幕系統記憶體目的地的複本，來源是由 pAllocationList[DXGK_PRESENT_SOURCE_INDEX] 陣列元素的 hDeviceSpecificAllocation 成員指定，而 pPresent 結構之DXGKARG_PRESENT結構的 hDeviceSpecificAllocation 成員會指定來源DxgkDdiPresent 的參數指向。目的地是裝置的目前主要或螢幕外系統記憶體配置，是由 pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] 陣列 DXGKARG_PRESENT元素的 hDeviceSpecificAllocation 成員所指定。如果目的地等於來源 (，也就是目的地 == 來源) ，則複製作業是螢幕對螢幕位區塊傳輸 (bitblt) 。因此，圖形子系統會將來源和目的地設定為下列值：
- destination ！= NULL (也就是 destination == nonNULL)
- source ！= NULL (也就是 source == nonNULL)
在從目前配置翻轉到另一個配置的視訊記憶體中，可由操作系統指定來源，並在 pAllocationList[DXGK_PRESENT_SOURCE_INDEX] 陣列元素的 hDeviceSpecificAllocation 成員中設定DXGKARG_PRESENT。圖形子系統會將來源和目的地設定為下列值：
- destination == NULL
- source ！= NULL (也就是 source == nonNULL)
注意您可以從與目前掃描輸出配置相同的來源設定執行無作業翻轉。無作業翻轉可用來在轉譯數據流中插入佇列等候垂直空白。顯示迷你埠驅動程序應該插入硬體翻轉命令，就像是翻轉到另一個配置一樣。
在主要介面的色彩填滿作業中，不需要任何來源配置，而目的地是由 pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] 陣列元素 DXGKARG_PRESENT的 hDeviceSpecificAllocation 成員所指定的主要配置句柄。 DXGKARG_PRESENT的 Color 成員通常是來自 D3DDDIFORMAT 列舉類型的D3DDDIFMT_A8R8G8B8格式。不過，當主要格式為 Palettized RGB 時， Color 會包含調色盤索引。因此，圖形子系統會將來源和目的地設定為下列值：
- destination ！= NULL (也就是 destination == nonNULL)
- source == NULL

若要讓所有 DxgkDdiPresent 案例正常運作，顯示迷你埠驅動程式的 DxgkDdiCreateDevice 函式應該將DXGK_DEVICEINFO結構的 DmaBufferSize 成員設定為夠大，以保存至少一個 RECT 矩形到顯示器或螢幕外目標所需的硬體命令。不過，如果 DxgkDdiPresent 案例中的子節點數目耗用目前的 DMA 緩衝區，且驅動程式需要另一個 DMA 緩衝區才能繼續，則驅動程式可以傳回STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER。

然後，圖形子系統會取得新的 DMA 緩衝區，並以與先前 DxgkDdiPresent 呼叫相同的 RECT 結構清單再次呼叫驅動程式的 DxgkDdiPresent 函式。驅動程式必須使用 pPresent 所指向之DXGKARG_PRESENT結構的 MultipassOffset 成員，以記錄在先前呼叫 DxgkDdiPresent 中完成 RECT 列表的進度量，讓驅動程式可以從停止新的 DMA 緩衝區的位置繼續。當驅動程式的 DxgkDdiPresent 函式完成 RECT 結構清單時，它會傳回STATUS_SUCCESS。

除了產生 DMA 緩衝區之外，顯示迷你埠驅動程式還必須產生修補程式位置清單，指出 DMA 緩衝區中稍後在已知配置實體地址時必須修補的各種位移。有時候，視訊記憶體管理員會提供驅動程序預先修補的資訊 (，也就是配置清單中來源和目的地) 的最後一個已知實體位址。

當視訊記憶體管理員提供這項資訊時，驅動程式必須判斷這些實體位址是 DirectX 圖形核心子系統將提供的最終位址，以產生 DMA 緩衝區。圖形子系統可能不會在 DMA 緩衝區上呼叫 DxgkDdiPatch 函式，稍後再修補。因此，驅動程式必須使用預先修補資訊來正確產生 DMA 緩衝區。 DXGKARG_PRESENT pAllocationList 陣列中第 N個元素的 SegmentId 成員為非零時，會針對元素 N 提供預先修補的資訊。

注意即使驅動程式的 DxgkDdiPresent 函式會預先修補 DMA 緩衝區，驅動程式仍必須將配置的所有參考插入 pPatchLocationListOut 成員 DXGKARG_PRESENT所指定的輸出修補程式位置清單中。驅動程式必須插入這些參考，因為配置位址可能會在 DMA 緩衝區提交至 GPU 之前變更;因此，DirectX 圖形核心子系統會呼叫 DxgkDdiPatch 函式來重新修補 DMA 緩衝區。

如果驅動程式支援輪替 (，則報告在呼叫其 DxgkDdiEnumVidPnCofuncModality 函式) 中， (bitblt) 的旋轉 D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION模式支援，驅動程式必須能夠執行旋轉的位區塊傳輸 (bitblt) 。當DXGKARG_PRESENT之 Flags 成員的DXGK_PRESENTFLAGS結構中指定旋轉位欄位旗標時，驅動程式應該套用旋轉方式，就像從非旋轉表面移至目前來源的最終方向一樣。

來源的主要配置是在 DxgkDdiCommitVidPn 函式中指定。如果多個路徑源自指定的來源 (複製模式) ，則顯示迷你埠驅動程序必須確定輸出已正確旋轉，因為不同目標的路徑旋轉模式。提供給 DxgkDdiPresent 的所有參數都是無從回應的旋轉。來源和目標矩形可能是整個畫面，因為客戶端認為它 (例如 768 x 1024) 。

注意這種情況不會解決旋轉模式中的全螢幕 Direct3D 應用程式。

如果先前指出的顯示迷你埠驅動程式，請在呼叫其 DxgkDdiQueryAdapterInfo 函式中，它支援記憶體對應 I/O (MMIO) 型翻轉 (，方法是將 DXGK_DRIVERCAPS 結構 FlipCaps 成員的 FlipOnVSyncMmIo 位字段旗標設定為 TRUE) ，接著會呼叫驅動程式的 DxgkDdiPresent 函式，並將 DXGKARG_PRESENT 的 pDmaBuffer 成員設定為 NULL因為 MMIO 型翻轉不需要在 GPU 上執行 DMA 緩衝區。相反地，驅動程式的 DxgkDdiPresent 函式必須視需要驗證來源介面和程式翻轉硬體。 DirectX 圖形核心子系統會呼叫驅動程式的 DxgkDdiSetVidPnSourceAddress 函式來執行這種類型的翻轉。

DxgkDdiPresent 應設為可分頁。