PFND3DDDI_CREATERESOURCE回呼函式 (d3dumddi.h)

發行項
02/23/2024

CreateResource 函式會建立資源。

語法

PFND3DDDI_CREATERESOURCE Pfnd3dddiCreateresource;

HRESULT Pfnd3dddiCreateresource(
  HANDLE hDevice,
  D3DDDIARG_CREATERESOURCE *unnamedParam2
)
{...}

參數

hDevice

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

unnamedParam2

pResource [in， out]

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

傳回值

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

傳回碼	描述
S_OK	已成功建立資源。
E_OUTOFMEMORY	CreateResource 無法配置所需的記憶體，使其完成。
D3DERR_NOTAVAILABLE	CreateResource 因無法配置記憶體以外的原因而無法建立資源。只有在建立頂點或索引緩衝區時，CreateResourcecan 才會傳回此錯誤。

備註

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

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

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

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

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

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

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

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

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

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

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

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

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

新的 CreateResource DDI 與 Microsoft Windows 2000 顯示器驅動程式模型的 DdCreateSurface DDI 不同：下列方式：

在新 CreateResource DDI 中，永遠不會明確附加表面。所有附件都會由不可部分完成的建立所隱含。
在新的 CreateResource DDI 中，不允許部分建立 Cube 對應。

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

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

規格需求

需求	值
最低支援的用戶端	可在 Windows Vista 和更新版本的 Windows 作業系統中使用。
目標平台	桌面
標頭	d3dumddi.h (包含 D3dumddi.h)