PFND3DDDI_ALLOCATECB回呼函式 (d3dumddi.h)
pfnAllocateCb 函式會配置系統或視訊記憶體。
語法
PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;
HRESULT Pfnd3dddiAllocatecb(
[in] HANDLE hDevice,
D3DDDICB_ALLOCATE *unnamedParam2
)
{...}
參數
[in] hDevice
顯示裝置的句柄 (圖形內容) 。
unnamedParam2
pData [in， out]
描述配置之D3DDDICB_ALLOCATE結構的指標。
傳回值
pfnAllocateCb 會傳回下列其中一個值：
| 傳回碼 | 描述 |
|---|---|
| S_OK | 已成功配置記憶體。 |
| E_INVALIDARG | 已驗證參數，並判斷為不正確。 |
| E_OUTOFMEMORY | pfnAllocateCb 無法配置完成所需的記憶體。 |
| D3DERR_OUTOFVIDEOMEMORY | pfnAllocateCb 無法完成，因為視訊記憶體不足。 視訊記憶體管理員會嘗試虛擬化視訊記憶體;不過，如果虛擬化 (失敗，例如虛擬位址空間用盡) 時，記憶體管理員可能會傳回此錯誤碼。 |
| D3DDDIERR_DEVICEREMOVED | pfnAllocateCb 無法起始對顯示迷你埠驅動程式 DxgkDdiCreateAllocation 函式的呼叫，因為發生 隨插即用 (PnP) 停止或逾時偵測和復原 (TDR) 事件。 呼叫 pfnAllocateCb (的使用者模式顯示驅動程式函式，通常是 CreateResource、 CreateResource (D3D10) 或 CreateResource (D3D11) 函式) 必須將此錯誤碼傳回 Direct3D 運行時間。 Direct3D 第 9 版 注意：如需傳回錯誤碼的詳細資訊，請參閱 傳回從運行時間函式收到的錯誤碼。 Direct3D 版本 10 和 11 注意：如果驅動程式函式未傳回值 (亦即，傳回參數類型為 void) ，驅動程式函式會呼叫 pfnSetErrorCb 函式，將錯誤碼傳回運行時間。 如需處理錯誤碼的詳細資訊，請參閱 處理錯誤。 |
此函式也可能傳回其他 HRESULT 值。
備註
使用者模式顯示驅動程式會呼叫 pfnAllocateCb 來配置系統或視訊記憶體 (也稱為 配置) 。 Microsoft DirectX 圖形核心子系統 (Dxgkrnl.sys) 然後呼叫 display miniport 驅動程式的 DxgkDdiCreateAllocation 函式來解譯和儲存在 pfnAllocateCb 要求中傳遞的私人數據。 顯示迷你埠驅動程式會從 DxgkDdiCreateAllocation 呼叫傳回資訊，視訊記憶體管理員 (Dxgkrnl.sys) 用來 實際配置記憶體。
使用者模式顯示驅動程式通常會建立配置，以回應呼叫其 CreateResource、 CreateResource (D3D10) 或 CreateResource (D3D11) 函式。 不過，當使用者模式顯示驅動程式的 CreateDevice 或 CreateDevice (D3D10) 函式在視訊記憶體中建立臨時板區域時，使用者模式顯示驅動程式可以隨時建立配置。
使用者模式顯示驅動程式可以建立下列類型的設定：
- Microsoft Direct3D 執行時間預先配置系統記憶體的系統記憶體配置。 在此情況下，使用者模式顯示驅動程式無法設定對齊或任何其他參數。 如果使用者模式顯示驅動程式需要硬體可存取的預先配置系統記憶體，則會呼叫 pfnAllocateCb。 Direct3D 運行時間會針對 pData 所指向之 D3DDDICB_ALLOCATE 結構之 pAllocationInfo 成員中的專案，傳回 D3DDDI_ALLOCATIONINFO 結構之 pSystemMem 成員中的系統記憶體指標。 如果使用者模式顯示驅動程式不需要硬體可存取的預先配置系統記憶體，它就不應該針對這種類型的記憶體呼叫 pfnAllocateCb 。
- 使用者模式顯示驅動程式可以參與建立的系統和視訊記憶體配置。
顯示迷你埠驅動程式可以在此核心模式資源句柄上呼叫 DxgkCbGetHandleData 函式 (通常在其 DxgkDdiRender 函式內) ，以取得與資源相關聯的私人數據，或者顯示迷你埠驅動程式可以呼叫 DxgkCbEnumHandleChildren 函式，以取得與資源相關聯的所有配置。 顯示迷你埠驅動程式也可以呼叫 DxgkCbGetHandleParent 函式，從子配置句柄取得父核心模式資源句柄。
請注意，如果使用者模式顯示驅動程式呼叫 pfnAllocateCb 時，D3DDDICB_ALLOCATE的 hResource 成員設定為 NULL，則配置會與裝置相關聯，而不是與資源相關聯。 驅動程式只能判斷差異是語意。 將配置與資源建立關聯是選擇性的，但建議用於偵錯和診斷用途。
Direct3D 第 9 版附注： 如需建立和終結資源的詳細資訊，請參閱 處理資源建立和解構。
Direct3D 版本 11 附注： 如需驅動程式如何呼叫 pfnAllocateCb 的詳細資訊，請參閱 Direct3D 10 的變更。
下列程式代碼範例示範如何配置資源的記憶體。
D3DDDICB_ALLOCATE allocCB;
D3DDDI_ALLOCATIONINFO allocInfo;
HRESULT hr;
memset(&allocInfo, 0, sizeof(allocInfo));
memset(&allocCB, 0, sizeof(allocCB));
// Set the VidPN source ID for the primary and fullscreen back buffer
if (m_dwCurResCaps.Primary) {
allocInfo.Flags.Primary = TRUE;
allocInfo.VidPnSourceId = m_VidPnSourceId;
}
// Check if the allocation is in system memory
if (pSysMem) {
allocInfo.pSystemMem = pSysMem;
}
// Use the runtime handle of the resource being created
// NOTE: This is critical for supporting a shared resource
allocCB.hResource = m_hCurResRuntime;
allocCB.NumAllocations = 1;
allocCB.pAllocationInfo = &allocInfo;
hr = m_d3dCallbacks.pfnAllocateCb(m_hD3D, &allocCB);
if (FAILED(hr)) {
allocInfo.hAllocation = NULL;
}
else {
*phAllocation = allocInfo.hAllocation;
}
return (hr);
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | 可在 Windows Vista 和更新版本的 Windows 作業系統中使用。 |
| 目標平台 | 桌面 |
| 標頭 | d3dumddi.h (包含 D3dumddi.h) |