DXGKDDI_CREATEALLOCATION função de retorno de chamada (d3dkmddi.h)

Artigo
05/26/2023

A função DxgkDdiCreateAllocation cria alocações de memória de sistema ou vídeo.

Sintaxe

DXGKDDI_CREATEALLOCATION DxgkddiCreateallocation;

NTSTATUS DxgkddiCreateallocation(
  [in]     IN_CONST_HANDLE hAdapter,
  [in/out] INOUT_PDXGKARG_CREATEALLOCATION pCreateAllocation
)
{...}

Parâmetros

[in] hAdapter

Um identificador para um bloco de contexto associado a um adaptador de exibição. O driver de miniporta de exibição anteriormente forneceu esse identificador para o subsistema kernel de elementos gráficos do Microsoft DirectX no parâmetro de saída MiniportDeviceContext da função DxgkDdiAddDevice .

[in/out] pCreateAllocation

Um ponteiro para uma estrutura DXGKARG_CREATEALLOCATION que contém informações para criar alocações.

Retornar valor

DxgkDdiCreateAllocation retorna um dos seguintes valores:

Código de retorno	Descrição
STATUS_SUCCESS	DxgkDdiCreateAllocation criou com êxito a alocação.
STATUS_INVALID_PARAMETER	Os parâmetros passados para DxgkDdiCreateAllocation continham erros que impediam a conclusão.
STATUS_NO_MEMORY	DxgkDdiCreateAllocation não pôde alocar a memória necessária para que ela fosse concluída.
STATUS_GRAPHICS_DRIVER_MISMATCH	O driver de miniporta de exibição não é compatível com o driver de exibição do modo de usuário que iniciou a chamada para DxgkDdiCreateAllocation.

Comentários

Depois que o driver de exibição do modo de usuário chama a função pfnAllocateCb , o subsistema kernel de elementos gráficos DirectX chama a função DxgkDdiCreateAllocation do driver de miniporta de exibição para criar as alocações. O driver de miniporto de exibição deve interpretar os dados privados (no membro pPrivateDriverData da estrutura DXGK_ALLOCATIONINFO para cada alocação) que são passados do driver de exibição do modo de usuário e devem determinar a lista de parâmetros necessários para criar cada alocação por meio do gerenciador de memória de vídeo. Para obter mais informações sobre como o driver de miniporto de exibição fornece esses parâmetros para o gerenciador de memória de vídeo, consulte Especificando segmentos ao criar alocações.

O driver de miniporta de exibição deve retornar um identificador de alocação, que normalmente é um ponteiro para uma estrutura de dados de driver privado que contém informações sobre a alocação. O driver de miniporto de exibição pode chamar a função DxgkCbGetHandleData a qualquer momento para recuperar os dados privados de um identificador de alocação. Portanto, o driver de miniporta de exibição não é necessário para manter uma tabela de identificador de alocação privada. Na verdade, desencorajamos fortemente as tabelas de identificador privado porque elas podem ficar obsoletas ou fora de sincronia com o subsistema de kernel de elementos gráficos DirectX em cenários de comutador de modo de exibição, como comutador de usuário rápido, desconectamento frequente e assim por diante.

O driver de exibição do modo de usuário atribui uma alocação a um recurso ou a um dispositivo. Para determinar se a alocação pertence a um recurso, o driver de miniporto de exibição pode marcar se o sinalizador de campo de bits Resource está definido no membro Flags da estrutura DXGKARG_CREATEALLOCATION para a qual o parâmetro pCreateAllocation de DxgkDdiCreateAllocation aponta. Se a alocação pertencer a um recurso, o driver de miniporta de exibição poderá (mas não é necessário) retornar um identificador de recurso, que normalmente é um ponteiro para uma estrutura de dados de driver privado que descreve o recurso. Se o subsistema de kernel de elementos gráficos DirectX chamar DxgkDdiCreateAllocation para criar uma alocação adicional para um recurso existente, o membro hResource do DXGKARG_CREATEALLOCATION conterá o identificador retornado pela chamada DxgkDdiCreateAllocation anterior para esse recurso. Se necessário, o driver de miniporto de exibição pode alterar o identificador de recurso durante uma chamada para DxgkDdiCreateAllocation.

Se o driver de exibição do modo de usuário colocar um identificador de recurso em um buffer de comando, o driver de miniporta de exibição poderá recuperar os dados privados chamando DxgkCbGetHandleData. O driver de miniporto de exibição também pode enumerar todas as alocações filho do recurso chamando a função DxgkCbEnumHandleChildren .

A partir do Windows 7, se um driver de miniporto de exibição processar uma chamada para a função DxgkDdiCreateAllocation para criar alocações para aceleração de hardware GDI, o driver deverá definir o tamanho da alocação (incluindo o valor de tom para alocações visíveis da CPU), pCreateAllocation-pAllocationInfo-Size.>>

Os recursos criados na chamada DxgkDdiCreateAllocation pertencem ao adaptador e não ao dispositivo. O driver de miniporta de exibição não deve referenciar os dados do dispositivo em qualquer lugar dentro das estruturas de alocação privada e de dados de recurso. Devido ao compartilhamento de superfície, um recurso pode estar em uso após a destruição do dispositivo do qual o driver de exibição no modo de usuário criou o recurso.

DxgkDdiCreateAllocation deve ser tornado paginável.

Alocando buffers de histórico

Começando no Windows 8.1, quando DxgkDdiCreateAllocation é chamado, o driver de miniporto de exibição pode definir o DXGK_ALLOCATIONINFOFLAGS.Membro HistoryBuffer para indicar que o driver de modo de usuário pode gerenciar a criação e a destruição de buffers de histórico.