PFND3DDDI_ALLOCATECB fonction de rappel (d3dumddi.h)

Article
02/06/2025

La fonction pfnAllocateCb alloue la mémoire système ou vidéo.

Syntaxe

PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;

HRESULT Pfnd3dddiAllocatecb(
  [in] HANDLE hDevice,
       D3DDDICB_ALLOCATE *unnamedParam2
)
{...}

Paramètres

[in] hDevice

Handle de l’appareil d’affichage (contexte graphique).

unnamedParam2

pData [in, out]

Pointeur vers une structure D3DDDICB_ALLOCATE qui décrit l’allocation.

Valeur de retour

pfnAllocateCb retourne l’une des valeurs suivantes :

code de retour	Description
S_OK	La mémoire a été correctement allouée.
E_INVALIDARG	Les paramètres ont été validés et déterminés comme incorrects.
E_OUTOFMEMORY	pfnAllocateCb n’a pas pu allouer de mémoire nécessaire pour qu’elle soit terminée.
D3DERR_OUTOFVIDEOMEMORY	pfnAllocateCb 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 insuffisant), le gestionnaire de mémoire peut renvoyer ce code d’erreur.
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb n’a pas pu lancer d’appel au du pilote miniport d’affichage DxgkDdiCreateAllocation fonction, car un arrêt Plug-and-Play (PnP) ou un événement TDR (Timeout Detection and Recovery) s’est produit. La fonction de pilote d’affichage en mode utilisateur qui a appelé pfnAllocateCb (généralement, le CreateResource, CreateResource(D3D10), ou CreateResource(D3D11) fonction) doit renvoyer ce code d’erreur au runtime Direct3D. Direct3D Version 9 Remarque : Pour plus d’informations sur le retour de codes d’erreur, consultez Retour de codes d’erreur reçus à partir de Runtime Functions. Direct3D Versions 10 et 11 Remarque : si la fonction de pilote ne retourne pas de valeur (autrement dit, a VOID pour un type de paramètre de retour), la fonction de pilote appelle la fonction pfnSetErrorCb pour renvoyer un code d’erreur au runtime. Pour plus d’informations sur la gestion des codes d’erreur, consultez Gestion des erreurs.

Cette fonction peut également retourner d’autres valeurs HRESULT.

Remarques

Un pilote d’affichage en mode utilisateur appelle pfnAllocateCb pour allouer la mémoire système ou vidéo (également appelée allocation). Le sous-système du noyau graphique Microsoft DirectX (Dxgkrnl.sys) appelle ensuite la fonction DxgkDdiCreateAllocation du pilote miniport d’affichage pour interpréter et stocker les données privées transmises dans la requête pfnAllocateCb. Le pilote miniport d’affichage retourne des informations de l'DxgkDdiCreateAllocation appeler que le gestionnaire de mémoire vidéo (qui fait partie de Dxgkrnl.sys) utilise pour allouer réellement la mémoire.

Le pilote d’affichage en mode utilisateur crée généralement une allocation en réponse à un appel à son CreateResource, CreateResource(D3D10)ou CreateResource(D3D11) fonction. Toutefois, le pilote d’affichage en mode utilisateur peut créer une allocation à tout moment, par exemple, lorsque le pilote d’affichage en mode utilisateur CreateDevice, ou fonction CreateDevice(D3D10) crée des zones de remplissage de zéro dans la mémoire vidéo.

Le pilote d’affichage en mode utilisateur peut créer les types d’allocations suivants :

Allocations de mémoire système dans lesquelles le runtime Microsoft Direct3D préalloue la mémoire système. Dans ce cas, le pilote d’affichage en mode utilisateur ne peut pas définir l’alignement ou tout autre paramètre. Si le pilote d’affichage en mode utilisateur nécessite une mémoire système préallouée accessible par le matériel, elle appelle pfnAllocateCb. Le runtime Direct3D retourne le pointeur de mémoire système dans le membre pSystemMem de la structure D3DDDI_ALLOCATIONINFO pour les éléments du membre pAllocationInfo de la structure D3DDDICB_ALLOCATE pointée par pData. Si le pilote d’affichage en mode utilisateur ne nécessite pas de mémoire système préallouée accessible par le matériel, il ne doit pas appeler pfnAllocateCb pour ce type de mémoire.
Allocations de mémoire système et vidéo dans lesquelles le pilote d’affichage en mode utilisateur peut participer à la création.

Lorsque le pilote tente de créer plusieurs allocations, le pilote peut associer toutes les allocations à une ressource parente (par exemple, lors de la création d’une chaîne de basculement dans laquelle chaque backbuffer est une allocation individuelle). Le pilote peut effectuer une telle association en définissant le membre hResource de la structure D3DDDICB_ALLOCATE pointée par pData à la valeur qui a été passée à la fonction CreateResourcedu pilote, CreateResource(D3D10)ou CreateResource(D3D11). En réponse, le runtime Direct3D retourne un handle de ressource en mode noyau (qui est du type de données D3DKMT_HANDLE) dans le membre hKMResource de D3DDDICB_ALLOCATE. Le pilote d’affichage en mode utilisateur peut par la suite insérer ce handle de ressource en mode noyau dans le flux de commandes à utiliser par le pilote display miniport.

Le pilote de miniport d’affichage peut appeler la fonction DxgkCbGetHandleData sur ce handle de ressource en mode noyau (généralement dans sa fonction DxgkDdiRender) pour obtenir des données privées associées à la ressource, ou le pilote de miniport d’affichage peut appeler la fonction DxgkCbEnumHandleChildren pour obtenir toutes les allocations associées à la ressource. Le pilote miniport d’affichage peut également appeler la fonction DxgkCbGetHandleParent pour obtenir le handle de ressource en mode noyau parent à partir d’un handle d’allocation enfant.

Notez que si le membre hResource de D3DDDICB_ALLOCATE est défini sur NULL lorsque le pilote d’affichage en mode utilisateur appelle pfnAllocateCb, l’allocation est associée à l’appareil au lieu d’une ressource. Le pilote peut déterminer uniquement que la différence est sémantique. L’association d’allocations à une ressource est facultative, mais recommandée à des fins de débogage et de diagnostic.

Direct3D Version 9 Remarque : Pour plus d’informations sur la création et la destruction de ressources, consultez Gestion de la création et de la destruction des ressources.

Direct3D Version 11 Remarque : Pour plus d’informations sur la façon dont le pilote appelle pfnAllocateCb, consultez modifications de Direct3D 10.

L’exemple de code suivant montre comment allouer de la mémoire pour une ressource.

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

Exigences

Exigence	Valeur
client minimum pris en charge	Disponible dans Windows Vista et versions ultérieures des systèmes d’exploitation Windows.
plateforme cible	Bureau
d’en-tête	d3dumddi.h (include D3dumddi.h)