PFND3DDDI_ALLOCATECB fonction de rappel (d3dumddi.h)

Article
08/07/2023

La fonction pfnAllocateCb alloue de 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 pour le périphérique d’affichage (contexte graphique).

unnamedParam2

pData [in, out]

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

Valeur retournée

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 la mémoire nécessaire pour qu’elle se termine.
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 retourner ce code d’erreur.
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb n’a pas pu lancer d’appel à la fonction DxgkDdiCreateAllocation du pilote miniport d’affichage, car un arrêt de Plug-and-Play (PnP) ou un événement de détection et de récupération (TDR) de délai d’expiration s’est produit. La fonction de pilote d’affichage en mode utilisateur qui a appelé pfnAllocateCb (généralement, la fonction CreateResource, CreateResource(D3D10) ou CreateResource(D3D11) doit renvoyer ce code d’erreur au runtime Direct3D. Direct3D version 9 Remarque : Pour plus d’informations sur le retour des codes d’erreur, consultez Renvoi de codes d’erreur reçus à partir de fonctions d’exécution. 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 de 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 qui ont été passées dans la requête pfnAllocateCb . Le pilote de miniport d’affichage retourne des informations à partir de l’appel DxgkDdiCreateAllocation que le gestionnaire de mémoire vidéo (qui fait partie de Dxgkrnl.sys) utilise pour allouer la mémoire.

Le pilote d’affichage en mode utilisateur crée généralement une allocation en réponse à un appel à sa fonction CreateResource, CreateResource(D3D10) ou CreateResource(D3D11). Toutefois, le pilote d’affichage en mode utilisateur peut créer une allocation à tout moment, par exemple, lorsque la fonction CreateDevice ou CreateDevice(D3D10) du pilote d’affichage en mode utilisateur crée des zones de pavé de travail 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, il 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, il 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 sur la valeur qui a été passée à la fonction CreateResource, CreateResource(D3D10) ou CreateResource(D3D11) du pilote. 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 ensuite insérer ce handle de ressource en mode noyau dans le flux de commandes à utiliser par le pilote miniport d’affichage.

Le pilote de miniport d’affichage peut appeler la fonction DxgkCbGetHandleData sur ce handle de ressource en mode noyau (généralement au sein de sa fonction DxgkDdiRender ) pour obtenir des données privées associées à la ressource, ou le pilote miniport d’affichage peut appeler la fonction DxgkCbEnumHandleChildren pour obtenir toutes les allocations associées à la ressource. Le pilote de 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.

Remarque de Direct3D version 9 : 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.

Remarque de Direct3D version 11 : 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 à 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);

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	d3dumddi.h (inclure D3dumddi.h)