DXGI_DDI_BASE_FUNCTIONS結構（dxgiddi.h）

發行項
02/06/2025

DXGI_DDI_BASE_FUNCTIONS 結構包含使用者模式顯示驅動程式可以實作的函式，以執行低階工作，例如將轉譯的畫面呈現至輸出、控制伽瑪，以及管理全螢幕轉換。

語法

typedef struct DXGI_DDI_BASE_FUNCTIONS {
  HRESULT()(DXGI_DDI_ARG_PRESENT *) * pfnPresent;
  HRESULT()(DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS *) * pfnGetGammaCaps;
  HRESULT()(DXGI_DDI_ARG_SETDISPLAYMODE *) * pfnSetDisplayMode;
  HRESULT()(DXGI_DDI_ARG_SETRESOURCEPRIORITY *) * pfnSetResourcePriority;
  HRESULT()(DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *) * pfnQueryResourceResidency;
  HRESULT()(DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES *) * pfnRotateResourceIdentities;
  HRESULT()(DXGI_DDI_ARG_BLT *) * pfnBlt;
} DXGI_DDI_BASE_FUNCTIONS;

成員

pfnPresent

PresentDXGI 函式的指標，通知使用者模式顯示驅動程式應用程式完成轉譯，並要求驅動程式顯示至目的地介面。

hDeviceDXGI_DDI_ARG_PRESENT 結構的成員，pPresentData 參數指向的句柄與驅動程式 CreateDevice（D3D10）函式 函式傳回 hDrvDevice 成員 D3D10DDIARG_CREATEDEVICE 結構中的運行時間相同。因此，驅動程式寫入器必須仔細定義此句柄的類型。此外，驅動程式還可以根據 DDI 實作處理對 createDevice（D3D10）呼叫，提供不同 PresentDXGI 函式的實作。運行時間絕不會混合 DDI 實作之間的驅動程式句柄。同樣地，hSurfaceToPresent 和 hDstResource 成員 DXGI_DDI_ARG_PRESENT 也是驅動程式定義資源句柄，驅動程式在先前呼叫驅動程式的 CreateResource（D3D10） 函式中傳回運行時間。

DXGI_DDI_ARG_PRESENT 的 pDXGIContext 成員是不透明的通訊機制。運行時間會將此 DXGI 內容傳遞至驅動程式。當驅動程式呼叫 pfnPresentCbDXGI 函式時，驅動程式應該將這個 DXGI 內容複製到 DXGIDDICB_PRESENT 結構的 pDXGIContext 成員。

驅動程式必須使用 pfnRenderCb 函式，提交所有部分建置的轉譯數據（命令緩衝區）。之後，驅動程式必須將資源句柄參數轉譯成核心句柄，並在呼叫 pfnPresentCbDXGI 時使用這些核心句柄。

注意

當驅動程式的 PresentDXGI 函式將 sRGB 格式的內容從來源介面複製到非 sRGB 目的地介面時，驅動程式應該將 sRGB 內容複製不變（也就是說，驅動程式不應該執行 sRGB 到線性轉換）。

pPresentData

[in]DXGI_DDI_ARG_PRESENT 結構的指標，描述如何顯示至目的地介面。

pfnGetGammaCaps

GetGammaCapsDXGI 函式會擷取 gamma 功能。

pGammaData

[in]包含 gamma 功能的 DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS 結構的指標。

pfnSetDisplayMode

驅動程式 SetDisplayModeDXGI 函式的指標。

pfnSetResourcePriority

SetResourcePriorityDXGI 函式會設定資源的收回記憶體優先順序。

Microsoft Direct3D 運行時間會呼叫 SetResourcePriorityDXGI，以設定資源的優先順序層級。使用者模式顯示驅動程式應該將 hResource 中提供的資源句柄轉譯為配置句柄 pPriority Data 所指向之DXGI_DDI_ARG_SETRESOURCEPRIORITY結構 成員。驅動程式進行此轉譯之後，驅動程式應該會在呼叫 pfnSetPriorityCb 函式時傳遞產生的句柄。

pPriorityData

[in]描述要設定資源之優先順序之 DXGI_DDI_ARG_SETRESOURCEPRIORITY 結構的指標。

pfnQueryResourceResidency

此函式會決定指定資源清單的落地。

Microsoft Direct3D 運行時間會呼叫使用者模式顯示驅動程式的 QueryResourceResidencyDXGI 函式，讓應用程式判斷如果系統必須讓資源可供 GPU 存取，作系統是否會在繪製時間產生重大停滯。從 QueryResourceResidencyDXGI 傳回的資訊是資源的落地近似值，因為資源可能會在應用程式使用資源之前降級。

QueryResourceResidencyDXGI 必須呼叫 pfnQueryResidencyCb函式。 pfnQueryResidencyCb 會傳回 D3DDDICB_QUERYRESIDENCY 結構 pResidencyStat us 所指定數位元素中資源的落地狀態。如果 pfnQueryResidencyCb 傳回任何查詢的D3DDDI_RESIDENCYSTATUS_NOTRESIDENT，QueryResourceResidencyDXGI 必須傳回S_NOT_RESIDENT。如果 pfnQueryResidencyCb 傳回任何查詢的D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY，而且不會傳回任何查詢的D3DDDI_RESIDENCYSTATUS_NOTRESIDENT，QueryResourceResidencyDXGI 必須傳回S_RESIDENT_IN_SHARED_MEMORY。只有在所有查詢的所有呼叫 都傳回 pfnQueryResidencyCb 時，QueryResourceResidencyDXGI 才會傳回 D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY S_OK。

針對運行時間透過呼叫查詢的每個資源，QueryResourceResidencyDXGI，使用者模式顯示驅動程式必須決定要透過呼叫 pfnQueryResidencyCb來查詢的資源所屬的資源配置。對於擁有單一配置的資源，判斷很簡單，驅動程式會查詢該配置。不過，如果資源擁有多個配置，則判斷比較困難。驅動程式必須判斷應用程式可能用於轉譯的配置，而驅動程式必須只查詢這些配置。例如，如果資源擁有用於轉譯的配置，以及處理鎖定作業的臨時配置，驅動程式應該只查詢第一個配置的落地，因為應用程式很可能不會使用第二個配置進行轉譯。

注意

由於運行時間不支援系統記憶體資源的落地查詢，因此運行時間一律會針對系統記憶體資源的落地狀態的應用程式失敗要求，而且永遠不會呼叫使用者模式顯示驅動程式的 QueryResourceResidencyDXGI 函式。

pResidencyData

[in]DXGI_DDI_ARG_QUERYRESOURCERESIDENCY 結構的指標，描述落地所驗證的資源清單。

pfnRotateResourceIdentities

輪替資源清單。

RotateResourceIdentitiesDXGI 函式必須交換 pRotateData 參數指向之 DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES 結構成員 pResource s 中傳遞之資源數位的身分識別。例如，如果資源數位參考資源 X、Y 和 Z，在增加數位件索引順序中，RotateResourceIdentitiesDXGI 必須輪替這些句柄，以遞增數位件索引順序參照 Y、Z 和 X。特別是，使用者模式顯示驅動程式應該交換對應資源的核心句柄。不過，驅動程式不應該交換對應的運行時間（RT）句柄。運行時間會呼叫 RotateResourceIdentitiesDXGI，在簡報期間輪替緩衝區。因此，RotateResourceIdentitiesDXGI 的呼叫不常。當運行時間呼叫驅動程式的 CreateResource（D3D10） 函式時，運行時間可以在 BindFlags 成員中指定 D3D10DDIARG_CREATERESOURCE D3D10_DDI_BIND_PRESENT 旗標，以指出資源可以參與輪替作業。

使用者模式顯示驅動程式也必須處理交換身分識別的其他層面。例如，在 Direct3D 第 10 版中，檢視可以參考資源;這類檢視可以內嵌在資源位址中。因此，驅動程式必須重新建立這類檢視。此外，可能需要驅動程式重新套用目前系結的檢視。

從 Windows 8 開始，驅動程式必須支援立體後台緩衝區的旋轉。

pRotateData

[in]DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES 結構的指標，描述要輪替的資源清單。

pfnBlt

將來源介面的內容複製到目的地介面，並可能旋轉內容。

Direct3D 運行時間可能會設定 Flags 成員，DXGI_DDI_ARG_BLT 結構的成員，pBltData 參數指向，以要求 BltDXGI 函式執行位區塊傳輸（bitblt）作業，以解析多重取樣資源、執行色彩格式轉換，和會一次執行一次伸展或壓縮。不過，Direct3D 運行時間永遠不會將 Flags 成員 DXGI_DDI_ARG_BLT 設定為零（也就是沒有設定旗標），以及 Rotate 成員中設定的 DXGI_DDI_MODE_ROTATION_IDENTITY 值，DXGI_DDI_ARG_BLT （也就是說，表示沒有旋轉）來執行直接記憶體複製作業。相反地，除非這兩個資源都是多重取樣，否則 Direct3D 運行時間會呼叫驅動程式的 ResourceCopy 或 ResourceCopyRegion 函式來執行直接記憶體複製作業。

使用者模式顯示驅動程式所執行的延展或壓縮質量必須和雙線性篩選執行的延展或壓縮一樣好。

Direct3D 執行時間會不常呼叫驅動程式的 BltDXGI 函式。也就是說，運行時間應該為每個畫面呼叫 BltDXGI 不超過一次或兩次，因為運行時間主要使用 BltDXGI 來支持簡報。

當運行時間呼叫簡報 BltDXGI 時，運行時間會在 FlagsDXGI_DDI_ARG_BLT成員中設定 Present 位欄位字段旗標。運行時間會設定 Present 位字段旗標，以通知驅動程式 bitblt 有額外的需求，而且可能需要額外的同步處理（例如，運行時間可能需要在包含兩個圖形適配卡的計算機設定中執行額外的同步處理，每個圖形適配卡都會處理顯示器的不同部分）。設定 Present 位欄位旗標時，驅動程式應該執行從應用程式的後台緩衝區複製到 DWM 共用介面的複製作業。由於這種複製作業的同步處理並不嚴重，因此撕裂成品應該是用戶體驗最差的成品類型。針對這種類型的複製作業，驅動程式不應該先解析至目的地介面，然後以色彩轉換結果就地，因為可能的成品會更糟。

如果驅動程式支援在建立主要介面期間傳回 DXGI_DDI_ERR_UNSUPPORTED ，也就是從呼叫其 CreateResource（D3D10）D3D10_DDI_BIND_PRESENT 函式傳 DXGI_DDI_ERR_UNSUPPORTED 回 DXGI_DDI_ERR_UNSUPPORTED，且 BindFlagsD3D10DDIARG_CREATERESOURCE 成員以及 D3D10DDIARG_CREATERESOURCE set pPrimaryDesc 成員若為非 NULL，驅動程式也必須在複製作業期間支援輪替。如果驅動程式永遠不會從呼叫其 CreateResource（D3D10） 函式傳回 DXGI_DDI_ERR_UNSUPPORTED，運行時間永遠不會將 DXGI_DDI_MODE_ROTATION_ROTATE90、DXGI_DDI_MODE_ROTATION_ROTATE180或 DXGI_DDI_MODE_ROTATION_ROTATE270 值傳遞至 DXGI_DDI_ARG_BLT的 Rotate 成員。因此，在此情況下，驅動程式的 BltDXGI 函式不需要支援旋轉。

運行時間會在 Rotate 成員 DXGI_DDI_ARG_BLT 中設定值，指出在驅動程式將內容複製到目的地之前，要逆時針旋轉來源內容的度數。旋轉是以90度增量指定。

注意

當驅動程式的 BltDXGI 函式將 sRGB 格式的內容從來源表面複製到非 sRGB 目的地介面時，驅動程式應該將 sRGB 內容複製不變（也就是說，驅動程式不應該執行 sRGB 到線性轉換）。

來源限制

BltDXGI 函式一律會使用整個來源子資源（與某些子矩形區域）來執行 bitblt 作業。此外，來源是 D3D10DDIRESOURCE_TEXTURE2D 表示法（在呼叫使用者模式顯示驅動程式 CreateResource（D3D10） 函式中建立來源時，D3D10DDIARG_CREATERESOURCE 的 ResourceDimension 成員）。當運行時間設定 DXGI_DDI_ARG_BLTFlags 成員中的 Resolve 位字段時，來源為多重取樣資源。來源資源僅限於在 BindFlags 成員中設定 D3D10_DDI_BIND_PRESENT 旗標 D3D10DDIARG_CREATERESOURCE的資源。來源的格式（以 D3D10DDIARG_CREATERESOURCE的 Format 成員所指定）限制為顯示模式格式，由下列來自 DXGI_FORMAT 列舉的值所指定：

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM （請參閱下面的附註。
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

注意

如果驅動程式支援來源格式 DXGI_FORMAT_B8G8R8A8_UNORM，則適用下列限制：

當驅動程式從浮點格式到整數格式執行 bitblt 運算時，例如BGRA8888，它必須隱含地將 gamma 編碼成結果。
相反地，當驅動程式從整數格式執行 bitblt 運算到浮點格式時，它必須隱含地從結果中移除 gamma 編碼。

目的地限制

目的地也是 D3D10DDIRESOURCE_TEXTURE2D 表示法。目的地的格式也限制為顯示模式格式。目的地資源受限於系結為轉譯目標的資源（D3D10_DDI_BIND_RENDER_TARGET 在 bindFlags D3D10DDIARG_CREATERESOURCE 或 D3D11DDIARG_CREATERESOURCE成員中設定）。

建立立體聲後台緩衝區

從 Windows 8 開始，如果驅動程式必須建立立體後台緩衝區，則應該分別設定 D3D10DDIARG_CREATERESOURCE 或 D3D11DDIARG_CREATERESOURCE 結構的成員，pCreateResource 參數所指向 CreateResource（D3D10） 或 CreateResource（D3D11） 函式，如下：