D3DKMTCreateAllocation-Funktion (d3dkmthk.h)

Die D3DKMTCreateAllocation-Funktion erstellt oder fügt Zuordnungen des System- oder Videospeichers hinzu. Benutzermodus-Grafikclienttreiber sollten stattdessen D3DKMTCreateAllocation2 aufrufen (siehe Hinweise).

Syntax

NTSTATUS D3DKMTCreateAllocation(
  D3DKMT_CREATEALLOCATION *unnamedParam1
);

Parameter

unnamedParam1

[in, out] pData: Ein Zeiger auf eine D3DKMT_CREATEALLOCATION-Struktur , die Informationen zum Erstellen von Zuordnungen enthält.

Rückgabewert

D3DKMTCreateAllocation gibt STATUS_SUCCESS zurück, wenn der Vorgang erfolgreich ist. Andernfalls wird möglicherweise ein NTSTATUS-Code zurückgegeben, z. B. einer der folgenden Werte:

Rückgabecode	Beschreibung
STATUS_DEVICE_REMOVED	Die Grafikkarte wurde angehalten, oder das Anzeigegerät wurde zurückgesetzt.
STATUS_INVALID_PARAMETER	Die Parameter wurden überprüft und als falsch ermittelt.
STATUS_NO_MEMORY	Diese Routine konnte aufgrund eines unzureichenden Systemspeichers nicht abgeschlossen werden.
STATUS_NO_VIDEO_MEMORY	Diese Routine konnte aufgrund eines unzureichenden Videospeichers nicht abgeschlossen werden. Der Videospeicher-Manager versucht, den Videospeicher zu virtualisieren. Wenn die Virtualisierung jedoch fehlschlägt (z. B. wenn der virtuelle Adressraum nicht mehr verfügbar ist), gibt der Speicher-Manager möglicherweise diesen Fehlercode zurück.

Hinweise

Benutzermodus-Grafikclienttreiber sollten stattdessen D3DKMTCreateAllocation2 aufrufen. Ein Grund dafür ist, dass Windows-Subsystem für Linux (WSL) D3DKMTCreateAllocation(nf-d3dkmthk-d3dkmtcreateallocation2.md) nicht unterstützt.

Der Benutzermodus (in diesem Fall die D3D-Runtime) ruft D3DKMTCreateAllocation auf, um Zuordnungen und Ressourcen zu erstellen. Eine Zuordnung kann einer Ressource zugeordnet werden, oder sie kann eigenständig sein.

Wenn der Benutzermodus D3DKMTCreateAllocation aufruft, stellt UMD private Treiberdaten bereit, die die Zuordnung beschreiben. Dxgkrnl verwendet diese privaten Treiberdaten und übergibt sie an den KMD, der dann eine Beschreibung der einzelnen Zuordnungen auf eine weise ausfüllt, die von VidMm verstanden wird. Die UMD-Daten enthalten Informationen wie den Ressourcentyp (Textur, Swapchain usw.). Der KMD übersetzt diese Daten in Größen, Ausrichtung, eine Reihe von Speichersegmenten, die die Zuordnung finden kann, Einstellungen für diese Segmente usw.

D3DKMTCreateAllocation kann auch aufgerufen werden, um einer Ressource jederzeit zusätzliche Zuordnungen hinzuzufügen. Die einzigen Einschränkungen sind, dass alle freigegebenen Zuordnungen einer Ressource zugeordnet werden müssen und keine zusätzlichen Zuordnungen zu einer vorhandenen freigegebenen Ressource hinzugefügt werden können.

Beispiele

Erstellen einer eigenständigen Zuordnung im Videospeicher, die keiner Ressource zugeordnet ist

Im folgenden Codebeispiel wird veranschaulicht, wie D3DKMTCreateAllocation verwendet werden kann, um eine eigenständige Zuordnung im Videospeicher zu erstellen, die keiner Ressource zugeordnet ist.

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;
}

Erstellen einer Ressource mit einer einzelnen Systemspeicherbelegung

Im folgenden Codebeispiel wird veranschaulicht, wie D3DKMTCreateAllocation verwendet werden kann, um eine Ressource mit einer einzelnen Systemspeicherbelegung zu erstellen.

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;
}

Erstellen einer Standardzuordnung mit ExistingSysMem

Das folgende Codebeispiel zeigt die Argumente, die an D3DKMTCreateAllocation übergeben werden sollen, um eine Standardzuordnung mit ExistingSysMem zu erstellen. Der vorhandene Systemspeicherpuffer, den die Runtime für den Kernel bereitstellt, muss seitenbündig ausgerichtet sein und ein Vielfaches der Seitengröße aufweisen. Andernfalls schlägt der Kernel den Aufruf fehl.

    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);

Argumenteinschränkungen für D3DKMTCreateAllocation:

• ExistingSysMem (oder ExistingSection) wird nur mit StandardAllocation unterstützt und umgekehrt.
• NumAllocations wird unterstützt: 1.
• Es kann nur eine von ExistingSysMem oder ExistingSection festgelegt werden.
• Beim Erstellen einer StandardAllocation müssen immer die Flags CreateShared und CrossAdapter festgelegt werden.
• ExistingSysMem (oder ExistingSection) kann nicht für eine vorhandene Ressource (D3DKMT_CREATALLOCATION::hResource) erstellt werden.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Zielplattform	Universell
Header	d3dkmthk.h (include D3dkmthk.h)
Bibliothek	Gdi32.lib
DLL	Gdi32.dll

Weitere Informationen

D3DKMT_CREATEALLOCATION

D3DKMTCreateAllocation2