DXGI_DDI_BASE_FUNCTIONS結構 (dxgiddi.h)

發行項
02/29/2024

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

語法

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 函式的指標，通知使用者模式顯示驅動程式應用程式已完成轉譯，並要求驅動程序顯示至目的地介面。

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

DXGI_DDI_ARG_PRESENT的 pDXGIContext 成員是不透明的通訊機制。運行時間會將此 DXGI 內容傳遞至驅動程式。當驅動程式呼叫 pfnPresentCbDXGIGI 函式時，驅動程式應該將此 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 來設定資源的優先順序層級。使用者模式顯示驅動程式應該將 pPriorityData 所指向之DXGI_DDI_ARG_SETRESOURCEPRIORITY結構 hResource 成員中提供的資源句柄轉譯為配置句柄。驅動程式進行此轉譯之後，驅動程式應該會在 呼叫 pfnSetPriorityCb 函式時傳遞產生的句柄。

pPriorityData

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

pfnQueryResourceResidency

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

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

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

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

注意

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

pResidencyData

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

pfnRotateResourceIdentities

輪替資源清單。

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

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

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

pRotateData

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

pfnBlt

將來源表面的內容複製到目的地介面，而且可能會旋轉內容。

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

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

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

當運行時間呼叫 BltDXGI 進行簡報時，運行時間會在 DXGI_DDI_ARG_BLT 的 Flags 成員中設定 Present 位字段旗標。運行時間會設定 Present 位字段旗標，通知驅動程式 bitblt 有額外的需求，而且可能需要額外的同步處理 (例如，運行時間可能需要在包含兩個圖形適配卡的計算機組態中執行額外的同步處理，這些適配卡各處理顯示) 的個別部分。設定 Present 位字段旗標時，驅動程式應該從應用程式的後台緩衝區執行複製作業，到 DWM 的共用介面。因為這種複製作業的同步處理不嚴重，所以卸除成品應該是用戶體驗最差的成品類型。針對這種類型的複製作業，驅動程式不應該先解析到目的地介面，然後就地著色轉換結果，因為可能的成品會更糟，所以驅動程式不應該使用多傳遞方法。

如果驅動程式支援在建立主要表面 (期間傳回DXGI_DDI_ERR_UNSUPPORTED，則從呼叫其 CreateResource (D3D10) 函式傳 DXGI_DDI_ERR_UNSUPPORTED回D3D10_DDI_BIND_PRESENT旗標，以及 D3D10DDIARG_CREATERESOURCE D3D10DDIARG_CREATERESOURCE 的 pPrimaryDesc成員所設定的 D3D10_DDI_BIND_PRESENT 旗標設定為非 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 函式不需要支援旋轉。

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

注意

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

來源限制

BltDXGI 函式一律會使用整個來源子資源 (與某些子矩形區域) 來執行 bitblt 作業。此外，當來源是在呼叫使用者模式顯示驅動程式的 CreateResource (D3D10) ) 時，D3D10DDIARG_CREATERESOURCE ResourceDimension 成員中指定的D3D10DDIRESOURCE_TEXTURE2D (表示法。當運行時間在 DXGI_DDI_ARG_BLT 的 Flags 成員中設定 Resolve 位欄位時，來源是多重取樣的資源。來源資源僅限於D3D10DDIARG_CREATERESOURCE BindFlags 成員中設定D3D10_DDI_BIND_PRESENT旗標的資源。 D3D10DDIARG_CREATERESOURCE ) 格式成員中指定的來源 (格式限制為顯示模式格式，由下列來自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在D3D10DDIARG_CREATERESOURCE或 D3D11DDIARG_CREATERESOURCE) 的 BindFlags 成員中設定。

建立立體後端緩衝區

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