PFND3DDDI_ALLOCATECB funzione di callback (d3dumddi.h)

Articolo
02/25/2024

La funzione pfnAllocateCb alloca memoria video o di sistema.

Sintassi

PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;

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

Parametri

[in] hDevice

Handle per il dispositivo di visualizzazione (contesto grafico).

unnamedParam2

pData [in, out]

Puntatore a una struttura D3DDDICB_ALLOCATE che descrive l'allocazione.

Valore restituito

pfnAllocateCb restituisce uno dei valori seguenti:

Codice restituito	Descrizione
S_OK	Memoria allocata correttamente.
E_INVALIDARG	I parametri sono stati convalidati e sono stati determinati come non corretti.
E_OUTOFMEMORY	PfnAllocateCb non è riuscito ad allocare memoria necessaria per il completamento.
D3DERR_OUTOFVIDEOMEMORY	PfnAllocateCb non è riuscito a completare a causa di memoria video insufficiente. Il gestore della memoria video tenta di virtualizzare la memoria video; Tuttavia, se la virtualizzazione ha esito negativo (ad esempio, quando si esaurisce lo spazio degli indirizzi virtuali), la gestione memoria potrebbe restituire questo codice di errore.
D3DDDIERR_DEVICEREMOVED	PfnAllocateCb non è stato in grado di avviare una chiamata alla funzione DxgkDdiCreateAllocation del driver miniport di visualizzazione perché si è verificato un evento di arresto di Plug and Play (PnP) o un evento TDR (Timeout Detection and Recovery). La funzione del driver di visualizzazione in modalità utente che ha chiamato pfnAllocateCb (in genere, la funzione CreateResource, CreateResource(D3D10)o CreateResource(D3D11) deve restituire questo codice di errore al runtime Direct3D. Direct3D versione 9 Nota: per altre informazioni sulla restituzione di codici di errore, vedere Restituzione dei codici di errore ricevuti dalle funzioni di runtime. Direct3D versioni 10 e 11 Nota: se la funzione driver non restituisce un valore ,ovvero ha VOID per un tipo di parametro restituito, la funzione driver chiama la funzione pfnSetErrorCb per inviare un codice di errore al runtime. Per altre informazioni sulla gestione dei codici di errore, vedere Gestione degli errori.

Questa funzione potrebbe anche restituire altri valori HRESULT.

Commenti

Un driver di visualizzazione in modalità utente chiama pfnAllocateCb per allocare memoria di sistema o video (nota anche come allocazione). Il sottosistema kernel grafico Microsoft DirectX (Dxgkrnl.sys) chiama quindi la funzione DxgkDdiCreateAllocation del driver miniport di visualizzazione per interpretare e archiviare i dati privati passati nella richiesta pfnAllocateCb . Il driver miniport di visualizzazione restituisce informazioni dalla chiamata DxgkDdiCreateAllocation utilizzata dal gestore di memoria video (che fa parte di Dxgkrnl.sys) per allocare effettivamente la memoria.

Il driver di visualizzazione in modalità utente crea in genere un'allocazione in risposta a una chiamata alla relativa funzione CreateResource, CreateResource(D3D10)o CreateResource(D3D11). Tuttavia, il driver di visualizzazione in modalità utente può creare un'allocazione in qualsiasi momento, ad esempio, quando la funzione CreateDevice del driver di visualizzazione in modalità utente o CreateDevice(D3D10) crea aree scratch-pad in memoria video.

Il driver di visualizzazione in modalità utente può creare i tipi di allocazioni seguenti:

Allocazioni di memoria di sistema in cui il runtime di Microsoft Direct3D prealloca la memoria di sistema. In questo caso, il driver di visualizzazione in modalità utente non può impostare l'allineamento o qualsiasi altro parametro. Se il driver di visualizzazione in modalità utente richiede una memoria di sistema preallocata accessibile dall'hardware, chiama pfnAllocateCb. Il runtime Direct3D restituisce il puntatore alla memoria di sistema nel membro pSystemMem della struttura D3DDDI_ALLOCATIONINFO per gli elementi nel membro pAllocationInfo della struttura D3DDDICB_ALLOCATE a cui punta pData. Se il driver di visualizzazione in modalità utente non richiede memoria di sistema preallocata accessibile dall'hardware, non deve chiamare pfnAllocateCb per questo tipo di memoria.
Allocazioni di memoria video e di sistema in cui il driver di visualizzazione in modalità utente può partecipare alla creazione.

Quando il driver tenta di creare più allocazioni, il driver può associare tutte le allocazioni a una risorsa padre, ad esempio quando si crea una catena di capovolgimento in cui ogni backbuffer è una singola allocazione. Il driver può eseguire tale associazione impostando il membro hResource della struttura D3DDDICB_ALLOCATE a cui punta pData al valore passato alla funzione CreateResource, CreateResource(D3D10)o CreateResource(D3D11) del driver. In risposta, il runtime Direct3D restituisce un handle di risorsa in modalità kernel (che è del tipo di dati D3DKMT_HANDLE) nel membro hKMResource di D3DDDICB_ALLOCATE. Il driver di visualizzazione in modalità utente può successivamente inserire questo handle di risorsa in modalità kernel nel flusso di comando da usare dal driver miniport di visualizzazione.

Il driver miniport di visualizzazione può chiamare la funzione DxgkCbGetHandleData su questo handle di risorse in modalità kernel (in genere all'interno della funzione DxgkDdiRender ) per ottenere dati privati associati alla risorsa o il driver miniport di visualizzazione può chiamare la funzione DxgkCbEnumHandleChildren per ottenere tutte le allocazioni associate alla risorsa. Il driver miniport di visualizzazione può anche chiamare la funzione DxgkCbGetHandleParent per ottenere l'handle di risorsa in modalità kernel padre da un handle di allocazione figlio.

Si noti che se il membro hResource di D3DDDICB_ALLOCATE è impostato su NULL quando il driver di visualizzazione in modalità utente chiama pfnAllocateCb, l'allocazione è associata al dispositivo anziché a una risorsa. Il driver può determinare solo che la differenza è semantica. L'associazione di allocazioni a una risorsa è facoltativa, ma consigliata per scopi di debug e diagnostica.

Nota direct3D versione 9: Per altre informazioni sulla creazione e l'eliminazione delle risorse, vedere Gestione della creazione e della distruzione delle risorse.

Nota direct3D versione 11: Per altre informazioni su come il driver chiama pfnAllocateCb, vedere Modifiche da Direct3D 10.

Nell'esempio di codice seguente viene illustrato come allocare memoria per una risorsa.

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

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows Vista e versioni successive dei sistemi operativi Windows.
Piattaforma di destinazione	Desktop
Intestazione	d3dumddi.h (include D3dumddi.h)