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 (的使用者模式顯示驅動程式函式,通常是 CreateResourceCreateResource (D3D10) CreateResource (D3D11) 函式) 必須將此錯誤碼傳回 Direct3D 執行時間。
Direct3D 第 9 版 注意:如需傳回錯誤碼的詳細資訊,請參閱 傳回從執行時間函式收到的錯誤碼
Direct3D 版本 10 和 11 注意:如果驅動程式函式未傳回值 (亦即,傳回參數類型為 void) ,驅動程式函式會呼叫 pfnSetErrorCb 函式,將錯誤碼傳回執行時間。 如需處理錯誤碼的詳細資訊,請參閱 處理錯誤

此函式也可能傳回其他 HRESULT 值。

備註

使用者模式顯示驅動程式會呼叫 pfnAllocateCb 來配置系統或視訊記憶體 (也稱為 配置) 。 Microsoft DirectX 圖形核心子系統 (Dxgkrnl.sys) 然後呼叫 display miniport 驅動程式的 DxgkDdiCreateAllocation 函式來解譯和儲存在 pfnAllocateCb 要求中傳遞的私人資料。 顯示迷你埠驅動程式會從 DxgkDdiCreateAllocation 呼叫傳回信息,視訊記憶體管理員 (Dxgkrnl.sys) 用來 實際配置記憶體。

使用者模式顯示驅動程式通常會建立配置,以回應呼叫其 CreateResourceCreateResource (D3D10) CreateResource (D3D11) 函式。 不過,當使用者模式顯示驅動程式的 CreateDeviceCreateDevice (D3D10) 函式在視訊記憶體中建立臨時板區域時,使用者模式顯示驅動程式可以隨時建立配置。

使用者模式顯示驅動程式可以建立下列類型的配置:

  • Microsoft Direct3D 執行時間預先配置系統記憶體的系統記憶體配置。 在此情況下,使用者模式顯示驅動程式無法設定對齊或任何其他參數。 如果使用者模式顯示驅動程式需要硬體可存取的預先配置系統記憶體,則會呼叫 pfnAllocateCb。 Direct3D 執行時間會針對pData所指向之 D3DDDICB_ALLOCATE結構之pAllocationInfo成員中的專案,傳回 D3DDDI_ALLOCATIONINFO 結構之pSystemMem成員中的系統記憶體指標。 如果使用者模式顯示驅動程式不需要硬體可存取的預先配置系統記憶體,它就不應該針對這種類型的記憶體呼叫 pfnAllocateCb
  • 使用者模式顯示驅動程式可以參與建立的系統和視訊記憶體配置。
當驅動程式嘗試建立多個配置時,驅動程式可以將所有配置與父資源產生關聯 (例如,在建立翻轉鏈結時,每個反緩衝器都是個別配置) 。 驅動程式可以藉由將pData指向之 D3DDDICB_ALLOCATE結構的hResource成員設定為傳遞給驅動程式CreateResourceCreateResource (D3D10) CreateResource (D3D11) 函式的值來執行這類關聯。 為了回應,Direct3D 執行時間會傳回核心模式資源控制碼 (,其屬於 D3DDDICB_ALLOCATE hKMResource 成員中的D3DKMT_HANDLE資料類型) 。 使用者模式顯示驅動程式隨後可以在命令資料流程中插入此核心模式資源控制碼,以供顯示迷你埠驅動程式使用。

顯示迷你埠驅動程式可以在此核心模式資源控制碼上呼叫 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)

另請參閱

CreateDevice

CreateDevice (D3D10)

CreateResource

CreateResource (D3D10)

CreateResource (D3D11)

D3DDDICB_ALLOCATE

D3DDDI_ALLOCATIONINFO

D3DDDI_DEVICECALLBACKS

DxgkCbEnumHandleChildren

DxgkCbGetHandleData

DxgkCbGetHandleParent

DxgkDdiCreateAllocation  

User-Mode顯示驅動程式呼叫的 Direct3D 執行時間函式