D3DKMTCreateAllocation 函式 (d3dkmthk.h)

發行項
02/25/2024

D3DKMTCreateAllocation 函式會建立或新增系統或視訊記憶體的配置。使用者模式圖形用戶端驅動程序應該改為呼叫 D3DKMTCreateAllocation2 ， (請參閱) 。

語法

NTSTATUS D3DKMTCreateAllocation(
  D3DKMT_CREATEALLOCATION *unnamedParam1
);

參數

unnamedParam1

[in， out] pData：包含建立配置資訊 之D3DKMT_CREATEALLOCATION 結構的指標。

傳回值

如果作業成功，D3DKMTCreateAllocation 會傳回STATUS_SUCCESS。否則，它可能會傳回 NTSTATUS 程式代碼，例如下列其中一個值：

傳回碼	Description
STATUS_DEVICE_REMOVED	圖形配接器已停止或顯示裝置已重設。
STATUS_INVALID_PARAMETER	已驗證參數，並判斷為不正確。
STATUS_NO_MEMORY	因為系統記憶體不足，所以無法完成此例程。
STATUS_NO_VIDEO_MEMORY	此例程因為視訊記憶體不足而無法完成。視訊記憶體管理員會嘗試虛擬化視訊記憶體。不過，如果虛擬化失敗 (，例如虛擬位址空間用完) 時，記憶體管理員可能會傳回此錯誤碼。

備註

使用者模式圖形客戶端驅動程序應該改為呼叫 D3DKMTCreateAllocation2 。其中一個原因是 Windows 子系統 Linux 版 (WSL) 不支援 D3DKMTCreateAllocation (nf-d3dkmthk-d3dkmtcreateallocation2.md) 。

在此情況下，使用者模式 (，D3D 運行時間) 呼叫 D3DKMTCreateAllocation 來建立配置和資源。配置可以與資源相關聯，也可以獨立配置。

當使用者模式呼叫 D3DKMTCreateAllocation 時，UMD 會提供描述配置的私人驅動程序數據。 Dxgkrnl 會採用此私人驅動程序數據，並將其傳遞至 KMD，然後以 VidMm 所瞭解的方式填入每個配置的描述。 UMD 數據包含資源類型 (紋理、交換鏈等資訊) 。 KMD 會將此數據轉譯成大小、對齊、一組記憶體區段，可供配置找到、這些區段的喜好設定等等。

您也可以呼叫 D3DKMTCreateAllocation ，隨時將額外的配置新增至資源。唯一的限制是所有共用配置都必須與資源相關聯，而且無法將其他配置新增至現有的共享資源。

範例

在與資源無關的視訊記憶體中建立獨立配置

下列程式代碼範例示範 如何使用 D3DKMTCreateAllocation 在與資源無關的視訊記憶體中建立獨立配置。

D3DKMT_HANDLE CreateStandAloneAllocation(D3DKMT_HANDLE hDevice, VOID* pPrivateAllocationInfo, UINT Size)
{
    D3DKMT_CREATEALLOCATION CreateAllocation;
    D3DDDI_ALLOCATIONINFO AllocationInfo;

    memset(&CreateAllocation, 0, sizeof(CreateAllocation));
    CreateAllocation.hDevice = hDevice;
    CreateAllocation.NumAllocations = 1;
    CreateAllocation.pAllocationInfo = &AllocationInfo;

    AllocationInfo.hAllocation = NULL;
    AllocationInfo.pSystemMem = NULL;  // Vidmem allocation
    AllocationInfo.pPrivateDriverData = pPrivateAllocationInfo;  // Contains format, size, and so on.
    AllocationInfo.PrivateDriverDataSize = Size;

    if (NT_SUCCESS((*pfnKTCreateAllocation)(&CreateAllocation))) {
        return AllocationInfo.hAllocation;
    }
    return 0;
}

使用單一系統記憶體配置建立資源

下列程式代碼範例示範 如何使用 D3DKMTCreateAllocation 來建立具有單一系統記憶體配置的資源。

HRESULT CreateSysmemResource(D3DKMT_HANDLE hDevice, 
                             UINT AllocationSize, 
                             VOID* pResourceData, 
                             UINT ResourceDataSize,
                             VOID* pAllocationData, 
                             UINT AllocationDataSize,
                             D3DKMT_HANDLE* phResource,
                             D3DKMT_HANDLE* phAllocation)
{
    D3DKMT_CREATEALLOCATION CreateAllocation;
    D3DDDI_ALLOCATIONINFO AllocationInfo;
    VOID* pSysMem;

    *phResource = NULL;
    *phAllocation = NULL;

    // For a sysmem allocation, preallocate the memory.
    pSysMem = MemAlloc(AllocationSize);
    if (pSysMem == NULL) {
        return E_OUTOFMEMORY;
    }
 
    memset(&CreateAllocation, 0, sizeof(CreateAllocation));
    CreateAllocation.hDevice = hDevice;
    CreateAllocation.Flags.CreateResource = TRUE;
    CreateAllocation.pPrivateDriverData = pResourceData;
    CreateAllocation.PrivateDriverDataSize = ResourceDataSize;
    CreateAllocation.NumAllocations = 1;
    CreateAllocation.pAllocationInfo = &AllocationInfo;

    AllocationInfo.hAllocation = NULL;
    AllocationInfo.pSystemMem = pSysMem;
    AllocationInfo.pPrivateDriverData = pAllocationData;
    AllocationInfo.PrivateDriverDataSize = AllocationDataSize;

    if (NT_SUCCESS((*pfnKTCreateAllocation)(&CreateAllocation))) {
        *phResource = CreateAllocation.hResource;
        *phAllocation = AllocationInfo.hAllocation;
        return S_OK;
    }
    MemFree(pSysMem);
    return E_FAIL;
}

使用 ExistingSysMem 建立標準配置

下列程式代碼範例顯示要傳遞至 D3DKMTCreateAllocation 的自變數，以使用 ExistingSysMem 建立標準配置。運行時間提供給核心的現有系統記憶體緩衝區必須對齊頁面，以及頁面大小的倍數;否則，核心會失敗呼叫。

    UINT PrivateDriverDataEstimate = 2048;

    D3DDDI_ALLOCATIONINFO2 AllocInfo = {};
    AllocInfo.pSystemMem = SomeValidPageAlignedSysMem;
    AllocInfo.VidPnSourceId = SomeVidPnSourceId;

    D3DKMDT_CREATESTANDARDALLOCATION StandardAlloc = {};
    StandardAlloc.Type = D3DKMT_STANDARDALLOCATIONTYPE_EXISTINGHEAP;
    StandardAlloc.ExistingHeapData.Size = SizeOfSystemMemBuffer; // Multiple of PAGE SIZE

    D3DKMT_CREATEALLOCATION CreateAlloc = {};
    CreateAlloc.hDevice = SomeDevice;
    CreateAlloc.NumAllocations = 1;
    CreateAlloc.pAllocationInfo2 = &AllocInfo;
    CreateAlloc.pStandardAllocation = &StandardAlloc;
    CreateAlloc.Flags.ExistingSysMem = TRUE;

    ntStatus = D3DKMTCreateAllocation(&CreateAlloc);

D3DKMTCreateAllocation 的自變數限制：

StandardAllocation 僅支援 ExistingSysMem (或 ExistingSection) ，反之亦然。
支援的 NumAllocations 為 1。
只能設定其中一個 ExistingSysMem 或 ExistingSection 。
建立 StandardAllocation 時，必須一律設定 CreateShared 和 CrossAdapter 旗標。
無法針對現有的資源建立 ExistingSysMem (或 ExistingSection) (D3DKMT_CREATALLOCATION：：hResource) 。

規格需求

需求	值
最低支援的用戶端	Windows Vista
目標平台	Universal
標頭	d3dkmthk.h (包含 D3dkmthk.h)
程式庫	Gdi32.lib
Dll	Gdi32.dll

另請參閱

D3DKMT_CREATEALLOCATION

D3DKMTCreateAllocation2

共用方式為