Fonction D3DKMTCreateAllocation (d3dkmthk.h)

  • Article

La fonction D3DKMTCreateAllocation crée ou ajoute des allocations de mémoire système ou vidéo. Les pilotes clients graphiques en mode utilisateur doivent appeler D3DKMTCreateAllocation2 à la place (voir Remarques).

Syntaxe

NTSTATUS D3DKMTCreateAllocation(
  D3DKMT_CREATEALLOCATION *unnamedParam1
);

Paramètres

unnamedParam1

[in, out] pData : pointeur vers une structure D3DKMT_CREATEALLOCATION qui contient des informations pour la création d’allocations.

Valeur retournée

D3DKMTCreateAllocation retourne STATUS_SUCCESS si l’opération réussit. Sinon, il peut renvoyer un code NTSTATUS tel qu’une des valeurs suivantes :

Code de retour Description
STATUS_DEVICE_REMOVED La carte graphique a été arrêtée ou le périphérique d’affichage a été réinitialisé.
STATUS_INVALID_PARAMETER Les paramètres ont été validés et déterminés comme incorrects.
STATUS_NO_MEMORY Cette routine n’a pas pu se terminer en raison d’une mémoire système insuffisante.
STATUS_NO_VIDEO_MEMORY Cette routine n’a pas pu se terminer en raison d’une mémoire vidéo insuffisante. Le gestionnaire de mémoire vidéo tente de virtualiser la mémoire vidéo. Toutefois, si la virtualisation échoue (par exemple, lorsque l’espace d’adressage virtuel est vide), le gestionnaire de mémoire peut renvoyer ce code d’erreur.

Remarques

Les pilotes clients graphiques en mode utilisateur doivent appeler D3DKMTCreateAllocation2 à la place. L’une des raisons est que Sous-système Windows pour Linux (WSL) ne prend pas en charge D3DKMTCreateAllocation(nf-d3dkmthk-d3dkmtcreateallocation2.md).

Le mode utilisateur (dans ce cas, le runtime D3D) appelle D3DKMTCreateAllocation pour créer des allocations et des ressources. Une allocation peut être associée à une ressource ou elle peut être autonome.

Lorsque le mode utilisateur appelle D3DKMTCreateAllocation, l’UMD fournit des données de pilote privé décrivant l’allocation. Dxgkrnl prend ces données de pilote privé et les transmet au KMD qui remplit ensuite une description de chaque allocation d’une manière comprise par VidMm. Les données UMD contiennent des informations telles que le type de ressource (texture, swapchain, etc.). Le KMD traduit ces données en des éléments tels que la taille, l’alignement, un ensemble de segments de mémoire que l’allocation peut être localisée, les préférences pour ces segments, etc.

D3DKMTCreateAllocation peut également être appelé pour ajouter des allocations supplémentaires à une ressource à tout moment. Les seules restrictions sont que toutes les allocations partagées doivent être associées à une ressource et que des allocations supplémentaires ne peuvent pas être ajoutées à une ressource partagée existante.

Exemples

Création d’une allocation autonome dans la mémoire vidéo qui n’est pas associée à une ressource

L’exemple de code suivant montre comment D3DKMTCreateAllocation peut être utilisé pour créer une allocation autonome dans la mémoire vidéo qui n’est pas associée à une ressource.

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

Création d’une ressource avec une allocation de mémoire système unique

L’exemple de code suivant montre comment D3DKMTCreateAllocation peut être utilisé pour créer une ressource avec une allocation de mémoire système unique.

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

Création d’une allocation standard avec ExistingSysMem

L’exemple de code suivant montre les arguments à passer à D3DKMTCreateAllocation pour créer une allocation standard avec ExistingSysMem. La mémoire tampon système existante que le runtime fournit au noyau doit être alignée sur la page et un multiple de la taille de page ; sinon, le noyau échoue à l’appel.

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

Limitations de l’argument pour D3DKMTCreateAllocation :

  • ExistingSysMem (ou ExistingSection) est uniquement pris en charge avec StandardAllocation et vice versa.
  • NumAllocations prises en charge est 1.
  • Un seul des éléments ExistingSysMem ou ExistingSection peut être défini.
  • Lors de la création d’un StandardAllocation, les indicateurs CreateShared et CrossAdapter doivent toujours être définis.
  • ExistingSysMem (ou ExistingSection) ne peut pas être créé sur une ressource existante (D3DKMT_CREATALLOCATION ::hResource).

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows Vista
Plateforme cible Universal
En-tête d3dkmthk.h (inclure D3dkmthk.h)
Bibliothèque Gdi32.lib
DLL Gdi32.dll

Voir aussi

D3DKMT_CREATEALLOCATION

D3DKMTCreateAllocation2