PFND3DDDI_ALLOCATECB função de retorno de chamada (d3dumddi.h)

Artigo
08/07/2023

A função pfnAllocateCb aloca memória de vídeo ou sistema.

Sintaxe

PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;

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

Parâmetros

[in] hDevice

Um identificador para o dispositivo de exibição (contexto gráfico).

unnamedParam2

pData [in, out]

Um ponteiro para uma estrutura D3DDDICB_ALLOCATE que descreve a alocação.

Retornar valor

pfnAllocateCb retorna um dos seguintes valores:

Código de retorno	Descrição
S_OK	A memória foi alocada com êxito.
E_INVALIDARG	Os parâmetros foram validados e determinados como incorretos.
E_OUTOFMEMORY	pfnAllocateCb não pôde alocar memória necessária para que ela fosse concluída.
D3DERR_OUTOFVIDEOMEMORY	pfnAllocateCb não pôde ser concluído devido à memória de vídeo insuficiente. O gerenciador de memória de vídeo tenta virtualizar a memória de vídeo; no entanto, se a virtualização falhar (como, quando o espaço de endereço virtual se esgotar), o gerenciador de memória poderá retornar esse código de erro.
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb não pôde iniciar uma chamada para a função DxgkDdiCreateAllocation do driver de miniporta de exibição porque ocorreu uma parada de Plug and Play (PnP) ou um evento TDR (Detecção e Recuperação de Tempo limite). A função de driver de exibição no modo de usuário que chamou pfnAllocateCb (normalmente, a função CreateResource, CreateResource(D3D10)ou CreateResource(D3D11) deve retornar esse código de erro de volta ao runtime do Direct3D. Direct3D Versão 9 Observação: para obter mais informações sobre como retornar códigos de erro, consulte Retornando códigos de erro recebidos de funções de runtime. Versões 10 e 11 do Direct3D Observação: se a função driver não retornar um valor (ou seja, tem VOID para um tipo de parâmetro de retorno), a função de driver chamará a função pfnSetErrorCb para enviar um código de erro de volta ao runtime. Para obter mais informações sobre como lidar com códigos de erro, consulte Tratamento de erros.

Essa função também pode retornar outros valores HRESULT.

Comentários

Um driver de exibição no modo de usuário chama pfnAllocateCb para alocar memória de vídeo ou sistema (também conhecida como alocação). O subsistema de kernel de elementos gráficos do Microsoft DirectX (Dxgkrnl.sys) chama a função DxgkDdiCreateAllocation do driver de miniporta de exibição para interpretar e armazenar os dados privados que foram passados na solicitação pfnAllocateCb . O driver de miniporto de exibição retorna informações da chamada DxgkDdiCreateAllocation que o gerenciador de memória de vídeo (que faz parte do Dxgkrnl.sys) usa para realmente alocar a memória.

O driver de exibição do modo de usuário normalmente cria uma alocação em resposta a uma chamada para sua função CreateResource, CreateResource(D3D10)ou CreateResource(D3D11). No entanto, o driver de exibição do modo de usuário pode criar uma alocação a qualquer momento , por exemplo, quando a função CreateDevice ou CreateDevice (D3D10) do driver de exibição do usuário cria áreas de scratch-pad na memória de vídeo.

O driver de exibição do modo de usuário pode criar os seguintes tipos de alocações:

Alocações de memória do sistema nas quais o runtime do Microsoft Direct3D pré-aloca a memória do sistema. Nessa situação, o driver de exibição do modo de usuário não pode definir o alinhamento ou qualquer outro parâmetro. Se o driver de exibição do modo de usuário exigir memória do sistema pré-alocada acessível pelo hardware, ele chamará pfnAllocateCb. O runtime do Direct3D retorna o ponteiro de memória do sistema no membro pSystemMem da estrutura D3DDDI_ALLOCATIONINFO para elementos no membro pAllocationInfo da estrutura de D3DDDICB_ALLOCATE apontada por pData. Se o driver de exibição do modo de usuário não exigir memória do sistema pré-alocada acessível pelo hardware, ele não deverá chamar pfnAllocateCb para esse tipo de memória.
Alocações de memória de sistema e vídeo nas quais o driver de exibição do modo de usuário pode participar da criação.

Quando o driver tenta criar várias alocações, o driver pode associar todas as alocações a um recurso pai (por exemplo, ao criar uma cadeia de inversão na qual cada backbuffer é uma alocação individual). O driver pode executar essa associação definindo o membro hResource da estrutura D3DDDICB_ALLOCATE que é apontado por pData para o valor que foi passado para a função CreateResource, CreateResource(D3D10) ou CreateResource(D3D11) do driver. Em resposta, o runtime do Direct3D retorna um identificador de recurso do modo kernel (que é do tipo de dados D3DKMT_HANDLE) no membro hKMResource de D3DDDICB_ALLOCATE. O driver de exibição do modo de usuário pode inserir posteriormente esse identificador de recurso do modo kernel no fluxo de comandos para uso pelo driver de miniporto de exibição.

O driver de miniporto de exibição pode chamar a função DxgkCbGetHandleData nesse identificador de recurso do modo kernel (normalmente dentro de sua função DxgkDdiRender ) para obter dados privados associados ao recurso ou o driver de miniporto de exibição pode chamar a função DxgkCbEnumHandleChildren para obter todas as alocações associadas ao recurso. O driver de miniporto de exibição também pode chamar a função DxgkCbGetHandleParent para obter o identificador de recurso do modo kernel pai de um identificador de alocação filho.

Observe que, se o membro hResource de D3DDDICB_ALLOCATE for definido como NULL quando o driver de exibição do modo de usuário chamar pfnAllocateCb, a alocação será associada ao dispositivo em vez de a um recurso. O driver pode determinar apenas que a diferença é semântica. Associar alocações a um recurso é opcional, mas recomendado para fins de depuração e diagnóstico.

Observação do Direct3D versão 9: Para obter mais informações sobre como criar e destruir recursos, consulte Manipulando a criação e a destruição de recursos.

Observação do Direct3D versão 11: Para obter mais informações sobre como o driver chama pfnAllocateCb, consulte Alterações do Direct3D 10.

O exemplo de código a seguir mostra como alocar memória para um recurso.

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

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows Vista e versões posteriores dos sistemas operacionais Windows.
Plataforma de Destino	Área de Trabalho
Cabeçalho	d3dumddi.h (inclua D3dumddi.h)