estrutura DXGI_DDI_BASE_FUNCTIONS (dxgiddi.h)

Artigo
03/08/2023

A estrutura DXGI_DDI_BASE_FUNCTIONS contém funções que o driver de exibição do modo de usuário pode implementar para executar tarefas de baixo nível, como apresentar quadros renderizados em uma saída, controlar gama e gerenciar uma transição de tela inteira.

Sintaxe

typedef struct DXGI_DDI_BASE_FUNCTIONS {
  HRESULT()(DXGI_DDI_ARG_PRESENT *) * pfnPresent;
  HRESULT()(DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS *) * pfnGetGammaCaps;
  HRESULT()(DXGI_DDI_ARG_SETDISPLAYMODE *) * pfnSetDisplayMode;
  HRESULT()(DXGI_DDI_ARG_SETRESOURCEPRIORITY *) * pfnSetResourcePriority;
  HRESULT()(DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *) * pfnQueryResourceResidency;
  HRESULT()(DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES *) * pfnRotateResourceIdentities;
  HRESULT()(DXGI_DDI_ARG_BLT *) * pfnBlt;
} DXGI_DDI_BASE_FUNCTIONS;

Membros

pfnPresent

Ponteiro para a função PresentDXGI que notifica o driver de exibição do modo de usuário de que um aplicativo terminou de renderizar e solicita que o driver seja exibido para a superfície de destino.

O membro hDevice da estrutura DXGI_DDI_ARG_PRESENT para a qual o parâmetro pPresentData aponta é o mesmo identificador para o qual a função CreateDevice(D3D10) do driver passou de volta para o runtime no membro hDrvDevice da estrutura D3D10DDIARG_CREATEDEVICE . Portanto, os gravadores de driver devem definir o tipo desse identificador com cuidado. Além disso, os drivers podem fornecer diferentes implementações da função PresentDXGI com base na qual a implementação de DDI lidou com a chamada para CreateDevice(D3D10). O runtime nunca misturará identificadores de driver entre implementações de DDI. Da mesma forma, os membros hSurfaceToPresent e hDstResource do DXGI_DDI_ARG_PRESENT também são identificadores de recursos definidos pelo driver que o driver retornou ao runtime em chamadas anteriores para a função CreateResource(D3D10) do driver.

O membro pDXGIContext do DXGI_DDI_ARG_PRESENT é um mecanismo de comunicação opaco. O runtime passa esse contexto DXGI para o driver. O driver deve copiar esse contexto DXGI inalterado para o membro pDXGIContext da estrutura DXGIDDICB_PRESENT quando o driver chama a função pfnPresentCbDXGI .

O driver deve enviar todos os dados de renderização parcialmente criados (buffers de comando) usando a função pfnRenderCb . Depois disso, o driver deve converter os parâmetros de identificador de recurso em identificadores de kernel e usar esses identificadores de kernel em uma chamada para pfnPresentCbDXGI.

Observação

Quando a função PresentDXGI do driver copia o conteúdo formatado em sRGB de uma superfície de origem para uma superfície de destino não sRGB, o driver deve copiar o conteúdo sRGB inalterado (ou seja, o driver não deve executar o sRGB para conversão linear).

pPresentData

[in] Um ponteiro para uma estrutura DXGI_DDI_ARG_PRESENT que descreve como exibir para a superfície de destino.

pfnGetGammaCaps

A função GetGammaCapsDXGI recupera recursos gama.

pGammaData

[in] Um ponteiro para uma estrutura DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS que contém recursos gama.

pfnSetDisplayMode

Um ponteiro para a função SetDisplayModeDXGI do driver.

pfnSetResourcePriority

A função SetResourcePriorityDXGI define a prioridade de remoção da memória para um recurso.

O runtime do Microsoft Direct3D chama SetResourcePriorityDXGI para definir o nível de prioridade de um recurso. O driver de exibição do modo de usuário deve traduzir o identificador de recurso fornecido no membro hResource da estrutura DXGI_DDI_ARG_SETRESOURCEPRIORITY apontada por pPriorityData para um identificador de alocação. Depois que o driver fizer essa tradução, o driver deverá passar o identificador resultante em uma chamada para a função pfnSetPriorityCb .

pPriorityData

[in] Um ponteiro para uma estrutura DXGI_DDI_ARG_SETRESOURCEPRIORITY que descreve o nível de prioridade para o qual definir um recurso.

pfnQueryResourceResidency

Essa função determina a residência da lista de recursos fornecida.

O runtime do Microsoft Direct3D chama a função QueryResourceResidencyDXGI do driver de exibição no modo de usuário para que os aplicativos determinem se o sistema operacional incorrerá em uma parada significativa no momento do desenho se o sistema precisar tornar os recursos acessíveis por GPU. As informações retornadas de QueryResourceResidencyDXGI são uma aproximação da residência de recursos porque os recursos podem ser rebaixados antes que os aplicativos usem os recursos.

QueryResourceResidencyDXGI deve chamar a função pfnQueryResidencyCb . pfnQueryResidencyCb retorna a status de residência de um recurso nos elementos da matriz especificada pelo membro pResidencyStatus da estrutura D3DDDICB_QUERYRESIDENCY. Se pfnQueryResidencyCb retornar D3DDDI_RESIDENCYSTATUS_NOTRESIDENT para qualquer consulta, QueryResourceResidencyDXGI deverá retornar S_NOT_RESIDENT. Se pfnQueryResidencyCb retornar D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY para qualquer consulta e não retornar D3DDDI_RESIDENCYSTATUS_NOTRESIDENT para nenhuma consulta, QueryResourceResidencyDXGI deverá retornar S_RESIDENT_IN_SHARED_MEMORY. QueryResourceResidencyDXGI só deverá retornar S_OK se todas as chamadas para pfnQueryResidencyCb para todas as consultas retornarem D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY.

Para cada recurso que o runtime consulta por meio de uma chamada para QueryResourceResidencyDXGI, o driver de exibição do modo de usuário deve determinar quais alocações pertencem ao recurso a serem consultadas por meio de uma chamada para pfnQueryResidencyCb. Para um recurso que possui uma única alocação, a determinação é simples– o driver consultará essa alocação. No entanto, se um recurso possui várias alocações, a determinação é mais difícil. O driver deve determinar quais alocações um aplicativo provavelmente usará para renderização e o driver deve consultar apenas essas alocações. Por exemplo, se um recurso possui uma alocação que é usada para renderização e uma alocação de rascunho que manipula uma operação de bloqueio, o driver deve consultar apenas a residência da primeira alocação, porque um aplicativo provavelmente não usará a segunda alocação para renderização.

Observação

Como o runtime não dá suporte à consulta de residência de recursos de memória do sistema, o runtime sempre falhará nas solicitações de aplicativos para o status de residência dos recursos de memória do sistema e nunca chamará a função QueryResourceResidencyDXGI do driver de exibição no modo de usuário para esses recursos de memória do sistema.

pResidencyData

[in] Um ponteiro para uma estrutura DXGI_DDI_ARG_QUERYRESOURCERESIDENCY que descreve uma lista de recursos em que a residência é verificada.

pfnRotateResourceIdentities

Gira uma lista de recursos.

A função RotateResourceIdentitiesDXGI deve trocar identidades da matriz de recursos que são passados no membro pResources da estrutura DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES para a qual o parâmetro pRotateData aponta. Por exemplo, se a matriz de recursos se referir aos recursos X, Y e Z, em ordem de índice de matriz crescente, RotateResourceIdentitiesDXGI deverá girar esses identificadores para se referir a Y, Z e X, em aumentar a ordem de índice da matriz. Em particular, o driver de exibição do modo de usuário deve trocar os identificadores de kernel dos recursos correspondentes. No entanto, o driver não deve trocar as alças de runtime (RT) correspondentes. O runtime chama RotateResourceIdentitiesDXGI para girar buffers de volta durante a apresentação. Portanto, uma chamada para RotateResourceIdentitiesDXGI é pouco frequente. O runtime pode especificar o sinalizador D3D10_DDI_BIND_PRESENT no membro BindFlags da estrutura D3D10DDIARG_CREATERESOURCE quando o runtime chama a função CreateResource(D3D10) do driver para indicar que o recurso pode participar de uma operação de rotação.

O driver de exibição do modo de usuário também deve lidar com outros aspectos da troca de identidades. Por exemplo, no Direct3D versão 10, as exibições podem se referir a recursos; e essas exibições podem ter endereços de recurso inseridos neles. Portanto, o driver deve recriar essas exibições. Além disso, o driver pode ser necessário para reaplicar as exibições vinculadas no momento.

A partir de Windows 8, o driver deve dar suporte à rotação de buffers traseiros estéreo.

pRotateData

[in] Um ponteiro para uma estrutura DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES que descreve uma lista de recursos a serem girados.

pfnBlt

Copia o conteúdo de uma superfície de origem para uma superfície de destino e pode girar o conteúdo.

O runtime do Direct3D pode definir o membro Flags da estrutura DXGI_DDI_ARG_BLT para a qual o parâmetro pBltData aponta de forma a exigir que a função BltDXGI execute uma operação de transferência de bits (bitblt) que resolve recursos de várias amostras, executa a conversão de formato de cor e executa um alongamento ou redução de uma só vez. No entanto, o runtime do Direct3D nunca definirá o membro Flags de DXGI_DDI_ARG_BLT como zero (ou seja, nenhum conjunto de sinalizadores) junto com o valor de DXGI_DDI_MODE_ROTATION_IDENTITY definido no membro Rotate de DXGI_DDI_ARG_BLT (ou seja, para indicar nenhuma rotação) para executar uma operação de cópia de memória reta. Em vez disso, a menos que ambos os recursos sejam de várias amostras, o runtime do Direct3D chama a função ResourceCopy ou ResourceCopyRegion do driver para executar uma operação de cópia de memória direta.

A qualidade do alongamento ou redução que o driver de exibição do modo de usuário executa deve ser tão boa quanto o alongamento ou redução que um filtro bilinear executa.

O runtime do Direct3D chamará a função BltDXGI do driver com pouca frequência. Ou seja, o runtime deve chamar BltDXGI no máximo uma ou duas vezes por quadro, pois o runtime usa bltDXGI principalmente para dar suporte a uma apresentação.

Quando o runtime chama BltDXGI para uma apresentação, o runtime define o sinalizador Apresentar campo de bits no membro Flags do DXGI_DDI_ARG_BLT. O runtime define o sinalizador Apresentar campo de bits para informar ao driver que há requisitos extras para o bitblt e que a sincronização extra pode ser necessária (por exemplo, o runtime pode precisar executar uma sincronização extra nas configurações do computador que contêm dois adaptadores gráficos que manipulam partes separadas da exibição). Quando o sinalizador Apresentar campo de bits estiver definido, o driver deverá executar uma operação de cópia dos buffers de fundo de um aplicativo para a superfície compartilhada do DWM. Como a sincronização para esse tipo de operação de cópia é inexata, rasgar artefatos deve ser o pior tipo de artefato que um usuário experimenta. Para esse tipo de operação de cópia, o driver não deve usar uma abordagem de várias passões resolvendo primeiro na superfície de destino e, em seguida, convertendo os resultados in-loco porque os artefatos possíveis seriam muito piores.

Se o driver der suporte ao retorno DXGI_DDI_ERR_UNSUPPORTED durante a criação de uma superfície primária (ou seja, retornar DXGI_DDI_ERR_UNSUPPORTED de uma chamada para sua função CreateResource(D3D10) com o sinalizador D3D10_DDI_BIND_PRESENT definido no membro BindFlags do D3D10DDIARG_CREATERESOURCE juntamente com o membro pPrimaryDesc de D3D10DDIARG_CREATERESOURCE definido como não NULL), o driver também deve dar suporte à rotação durante uma operação de cópia. Se o driver nunca retornar DXGI_DDI_ERR_UNSUPPORTED de uma chamada para sua função CreateResource(D3D10), o runtime nunca passará o valor DXGI_DDI_MODE_ROTATION_ROTATE90, DXGI_DDI_MODE_ROTATION_ROTATE180 ou DXGI_DDI_MODE_ROTATION_ROTATE270 para o membro Rotate de DXGI_DDI_ARG_BLT. Portanto, nessa situação, a função BltDXGI do driver não é necessária para dar suporte à rotação.

O runtime define um valor no membro Rotate de DXGI_DDI_ARG_BLT para indicar o número de graus para girar no sentido anti-horário o conteúdo da origem antes que o driver copie o conteúdo para o destino. A rotação é especificada em incrementos de 90 graus.

Observação

Quando a função BltDXGI do driver copia o conteúdo formatado em sRGB de uma superfície de origem para uma superfície de destino não sRGB, o driver deve copiar o conteúdo sRGB inalterado (ou seja, o driver não deve executar o sRGB para conversão linear).

Restrições de origem

A função BltDXGI sempre usa um sub-recurso de origem inteiro (versus alguma área sub-retangular) para executar a operação bitblt. Além disso, a origem é uma representação D3D10DDIRESOURCE_TEXTURE2D (especificada no membro ResourceDimension do D3D10DDIARG_CREATERESOURCE quando a origem é criada em uma chamada para a função CreateResource(D3D10) do driver de exibição no modo de usuário). Quando o runtime define o campo de bitsResolver no membro Flags do DXGI_DDI_ARG_BLT, a origem é um recurso de várias amostras. O recurso de origem é restrito a um recurso no qual o sinalizador D3D10_DDI_BIND_PRESENT foi definido no membro BindFlags do D3D10DDIARG_CREATERESOURCE. O formato da origem (especificado no membro Format de D3D10DDIARG_CREATERESOURCE) é restrito aos formatos de modo de exibição, especificados pelos seguintes valores da enumeração DXGI_FORMAT :

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM (veja a observação abaixo.)
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

Observação

Se o driver der suporte ao formato de origem DXGI_FORMAT_B8G8R8A8_UNORM, as seguintes restrições se aplicarão:

Quando o driver executa uma operação bitblt de um formato de ponto flutuante para um formato inteiro, como BGRA8888, ele deve codificar implicitamente gama nos resultados.
Por outro lado, quando o driver executa uma operação bitblt de um formato inteiro para um formato de ponto flutuante, ele deve remover implicitamente a codificação gama dos resultados.

Restrições de destino

O destino também é uma representação D3D10DDIRESOURCE_TEXTURE2D . O formato do destino também é restrito a formatos de modo de exibição. O recurso de destino é restrito a um recurso associado como um destino de renderização (D3D10_DDI_BIND_RENDER_TARGET definido no membro BindFlags de D3D10DDIARG_CREATERESOURCE ou D3D11DDIARG_CREATERESOURCE).

Criando um buffer de fundo estéreo

A partir de Windows 8, se o driver precisar criar um buffer de fundo estéreo, ele deverá definir membros da estrutura D3D10DDIARG_CREATERESOURCE ou D3D11DDIARG_CREATERESOURCE, respectivamente, apontados pelo parâmetro pCreateResource das funções CreateResource(D3D10) ou CreateResource(D3D11), da seguinte maneira:

Defina o membro ArraySize como um valor de 2.
Defina o valor do sinalizador D3D10_DDI_BIND_PRESENT no membro BindFlags .

Além disso, para dar suporte à apresentação estéreo, a função BltDXGI deve permitir quaisquer valores para os membros DstSubresource e SrcSubresource da estrutura DXGI_DDI_ARG_BLT que estão dentro do intervalo dos recursos de origem e destino.