PFND3DDDI_CREATERESOURCE2回呼函式 (d3dumddi.h)

發行項
02/26/2024

建立資源。由 Windows 顯示驅動程式模型實作 (WDDM) 1.2 和更新版本的使用者模式顯示驅動程式。

語法

PFND3DDDI_CREATERESOURCE2 Pfnd3dddiCreateresource2;

HRESULT Pfnd3dddiCreateresource2(
  [in] HANDLE hDevice,
       D3DDDIARG_CREATERESOURCE2 *unnamedParam2
)
{...}

參數

[in] hDevice

用來建立資源的顯示裝置 (圖形內容) 句柄。

unnamedParam2

pResource2 [in， out]

描述所建立資源的 D3DDDIARG_CREATERESOURCE2 結構的指標。

傳回值

傳回 S_OK 或適當的錯誤結果。 WDDM 1.3 和更新版本的 Direct3D 層級 9 驅動程式必須傳回此錯誤碼：

傳回碼	描述
E_INVALIDARG	D3DDDIARG_CREATERESOURCE2 。Flagsmember 已設定 CaptureBuffer 旗標值，而且資源超過驅動程式可支持的內容。

備註

CreateResource2 的呼叫可以包含表面清單。 pResource2 參數所指定之D3DDDIARG_CREATERESOURCE2結構的 SurfCount 成員會指定要建立的介面數目，包括 MIP 對應層級。例如，256x256x9 紋理 MIP 對應資源包含9個表面的清單，其中 SurfCount 成員和 MIP 地圖層級數目都設定為9。包含九個 MIP 對應層級的 Cube 地圖應該將 MIP 對應層級的數目設定為 9， 而 SurfCount 設定為 54。三面交換鏈結應該將 SurfCount 設定為 3，並將 MIP 對應層級的數目設定為 0。請注意，MIP 對應層級的數目一律小於或等於 SurfCount 中的值。

為了回應 CreateResource2 呼叫，使用者模式顯示驅動程式可以呼叫 pfnAllocateCb 函式來建立一或多個記憶體配置。使用者模式顯示驅動程式必須判斷它是否必須為每個介面建立多個配置、所有介面的一個配置，或每個介面一個配置。如需配置的詳細資訊，請參閱視訊記憶體管理和 GPU 排程。

注意在傳回之前，不需要驅動程式的 CreateResource2 函式呼叫 pfnAllocateCb ;相反地，驅動程式可以延遲配置建立。

注意只有在對 pfnAllocateCb 的單一呼叫中以不可部分完成的方式建立資源的所有配置時，才能共享資源。

D3DDDIARG_CREATERESOURCE2 結構中的 hResource 成員是用來識別資源的句柄。使用者模式顯示驅動程式應該儲存在 CreateResource2 呼叫中傳遞的 hResource 值，並以 Microsoft Direct3D 運行時間傳回時可以使用的另一個值覆寫值。換句話說，在呼叫運行時間時，使用者模式顯示驅動程式會使用傳遞至 CreateResource2 的 hResource 值;在對使用者模式顯示驅動程式的呼叫 (例如，在呼叫 SetTexture 或 SetStreamSource 函式) 中，運行時間會使用從 CreateResource2 傳回的 hResource 值。請注意，每個表面沒有明確的句柄;如果介面必須個別 (參照，例如在呼叫 Blt 函式) 中，它是由句柄和索引所參考。索引會識別資源內的介面。索引與陣列中包含在 D3DDDIARG_CREATERESOURCE2 pSurfList 成員中的介面索引相同。

多個裝置可以共用資源， (hDevice) 和處理程式。運行時間會藉由在 D3DDDIARG_CREATERESOURCE2 的 Flags 成員中設定 SharedResource 位字段旗標來指定資源分享。如果已設定此位欄位字段旗標，則使用者模式顯示驅動程式必須遵守共用資源的下列限制：

使用者模式顯示驅動程式可以分別呼叫 pfnAllocateCb 和 pfnDeallocateCb 函式。
使用者模式顯示驅動程式在一開始建立資源之後，無法為資源建立額外的配置，同樣地，只能在資源本身終結時終結資源配置。
針對透過呼叫驅動程式的 CreateResource2 或 OpenResource 函式來建立或開啟的共用資源呼叫使用者模式顯示驅動程式的 DestroyResource 函式時，驅動程式必須將D3DDDICB_DEALLOCATE結構的 hResource 成員設定為非 NULL，而呼叫 pfnDeallocateCb 函式時，D3DDDICB_DEALLOCATE的 NumAllocations 成員會設定為零，以終結或關閉資源。也就是說，與共用資源相關聯的配置無法個別終結或關閉;資源必須在 pfnDeallocateCb 的一個呼叫中以不可部分完成的方式終結或關閉。
資源類型 (的配置數目必須一致，也就是說，建立相同資源類型的另一個程式應該產生相同數目和類型的配置) 。此外，這些資源不允許重新命名。

D3DDDI_RESOURCEFLAGS2 結構中指定的位字段旗標會傳入 D3DDDIARG_CREATERESOURCE2 的 Flags 成員。

注意您可以建立資源，而不需指定任何旗標。與這類資源相關聯的介面可能會遭到鎖定，而且可以是位區塊傳輸中的來源或目的地， (bitblt) 作業。不過，這類表面無法用於任何其他專案。

注意純文本表面與紋理或獨立轉譯目標不同，方法是沒有 [紋理] 或 [主要位欄位] 旗標。例如， 主要位欄位旗 標的存在表示獨立轉譯目標，而缺少此旗標則表示轉譯目標是後台緩衝區。

注意為了確保運行時間的變更不會中斷現有的驅動程式，驅動程式不得在呼叫其 CreateResource2 函式時使用下列保留成員D3DDDIARG_CREATERESOURCE2結構，以影響驅動程序的行為：

Flags 成員的未定義位會保留。
如果未在 [旗標] 中設定 [主要位字段] 旗標，則會保留 RefreshRate 和 Output 成員。
如果未在 Flags 中設定 RenderTarget、DecodeRenderTarget 或 VideoProcessRenderTarget 位欄位旗標，則會保留 MultisampleType 和 MultisampleQuality 成員。
如果未在 Flags 中設定 VertexBuffer 位字段旗標，則會保留 Fvf 成員。
如果未在 Flags 中設定 Texture、CubeMap 和 Volume 位欄位旗標，則會保留 MipLevels 成員。

如需建立和終結資源的詳細資訊，請參閱處理資源建立和解構。

針對系統記憶體資源，如果系統記憶體已正確對齊，顯示迷你埠驅動程式可以選擇將配置包裝在系統記憶體周圍，以便直接存取圖形處理單位 (GPU) 。顯示迷你埠驅動程式會在使用其 DxgkDdiCreateAllocation 函式建立配置時，在DXGK_ALLOCATIONINFO 結構的 Flags 成員中設定 ExistingSysMem 旗標，以包裝系統記憶體上的配置。如果顯示迷你埠驅動程式無法在系統記憶體周圍包裝配置，或包裝失敗，驅動程式仍應該會成功建立資源，並使用 CPU 來存取資源。

如果運行時間要求建立頂點或索引緩衝區，而且使用者模式顯示驅動程式因記憶體不足而無法建立緩衝區，例如記憶體不足 (，則缺少硬體支援) ，驅動程式必須失敗並 D3DERR_NOTAVAILABLE。