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

Artigo
08/07/2023

Cria um recurso. Implementado pelo WDDM (Modelo de Driver de Exibição do Windows) 1.2 e posteriores drivers de exibição do modo de usuário.

Sintaxe

PFND3DDDI_CREATERESOURCE2 Pfnd3dddiCreateresource2;

HRESULT Pfnd3dddiCreateresource2(
  [in] HANDLE hDevice,
       D3DDDIARG_CREATERESOURCE2 *unnamedParam2
)
{...}

Parâmetros

[in] hDevice

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

unnamedParam2

pResource2 [in, out]

Um ponteiro para uma estrutura D3DDDIARG_CREATERESOURCE2 que descreve o recurso que é criado.

Retornar valor

Retorna S_OK ou um resultado de erro apropriado. Os drivers WDDM 1.3 e posteriores do Direct3D Nível 9 devem retornar este código de erro:

Código de retorno	Descrição
E_INVALIDARG	O D3DDDIARG_CREATERESOURCE2 . Flagsmember tem o valor do sinalizador CaptureBuffer definido e o recurso excede o que o driver pode dar suporte.

Comentários

A chamada para CreateResource2 pode conter uma lista de superfícies. O membro SurfCount da estrutura D3DDDIARG_CREATERESOURCE2 especificada pelo parâmetro pResource2 especifica o número de superfícies, incluindo níveis de mapa MIP, a serem criadas. Por exemplo, um recurso MIP-map de textura 256x256x9 contém uma lista de nove superfícies em que o membro SurfCount e o número de níveis de mapa MIP são definidos como 9. Um mapa de cubo que contém nove níveis de mapa MIP deve ter o número de níveis de mapa MIP definidos como 9 e SurfCount definido como 54. Uma cadeia de troca de três superfícies deve ter SurfCount definido como 3 e o número de níveis de mapa MIP definido como 0. Observe que o número de níveis de mapa MIP é sempre menor ou igual ao valor em SurfCount.

Em resposta à chamada CreateResource2 , o driver de exibição do modo de usuário pode chamar a função pfnAllocateCb para criar uma ou mais alocações de memória. O driver de exibição do modo de usuário deve determinar se deve criar várias alocações por superfície, uma alocação para todas as superfícies ou uma alocação por superfície. Para obter mais informações sobre alocações, consulte Gerenciamento de Memória de Vídeo e Agendamento de GPU.

Nota A função CreateResource2 do driver não é necessária para chamar pfnAllocateCb antes de retornar; Em vez disso, o driver pode adiar a criação da alocação.

Nota Um recurso só poderá ser compartilhado se todas as alocações do recurso forem feitas atomicamente em uma única chamada para pfnAllocateCb.

O membro hResource na estrutura D3DDDIARG_CREATERESOURCE2 é um identificador usado para identificar o recurso. O driver de exibição do modo de usuário deve armazenar o valor de hResource que foi passado na chamada CreateResource2 e substituir o valor por outro valor que o runtime do Microsoft Direct3D pode usar quando a chamada CreateResource2 retorna. Em outras palavras, em chamadas para o runtime, o driver de exibição do modo de usuário usa o valor hResource que foi passado para CreateResource2; em chamadas para o driver de exibição do modo de usuário (por exemplo, em chamadas para as funções SetTexture ou SetStreamSource ), o runtime usa o valor hResource que foi retornado de CreateResource2. Observe que cada superfície não tem um identificador explícito; se a superfície precisar ser referenciada individualmente (por exemplo, em uma chamada para a função Blt ), ela será referenciada por um identificador e um índice. O índice identifica a superfície dentro do recurso. O índice é o mesmo que o índice da superfície na matriz contida no membro pSurfList do D3DDDIARG_CREATERESOURCE2.

Os recursos podem ser compartilhados por vários dispositivos (hDevice) e processos. O runtime especifica que um recurso é compartilhado definindo o sinalizador de campo de bits SharedResource no membro Flags do D3DDDIARG_CREATERESOURCE2. Se esse sinalizador de campo de bits estiver definido, o driver de exibição do modo de usuário deverá seguir as seguintes restrições em recursos compartilhados:

O driver de exibição do modo de usuário pode chamar as funções pfnAllocateCb e pfnDeallocateCb exatamente uma vez cada.
O driver de exibição do modo de usuário não pode criar alocações adicionais para o recurso depois que o recurso é criado inicialmente e, da mesma forma, pode destruir as alocações de recursos somente no momento em que o próprio recurso é destruído.
Quando a função DestroyResource do driver de exibição no modo de usuário é chamada para um recurso compartilhado que foi criado ou aberto por meio de uma chamada para a função CreateResource2 ou OpenResource do driver, o driver deve definir o membro hResource da estrutura D3DDDICB_DEALLOCATE como não NULL e o membro NumAllocations de D3DDDICB_DEALLOCATE como zero em uma chamada para a função pfnDeallocateCb para destruir ou fechar o recurso. Ou seja, as alocações associadas a um recurso compartilhado não podem ser destruídas ou fechadas individualmente; o recurso deve ser destruído ou fechado atomicamente em uma chamada para pfnDeallocateCb.
O número de alocações deve ser consistente para o tipo de recurso (ou seja, outro processo que está criando o mesmo tipo de recurso deve gerar o mesmo número e tipo de alocações). Além disso, a renomeação não é permitida para esses recursos.

Os sinalizadores de campo de bit especificados na estrutura D3DDDI_RESOURCEFLAGS2 são passados no membro Flags do D3DDDIARG_CREATERESOURCE2.

Nota Um recurso pode ser criado sem especificar nenhum sinalizador. Superfícies associadas a esse recurso podem ser potencialmente bloqueadas e podem ser uma origem ou destino em uma operação de transferência de bits (bitblt). No entanto, essas superfícies não podem ser usadas para mais nada.

Nota Superfícies simples são diferenciadas de texturas ou destinos de renderização autônomas pela ausência do sinalizador de campo de bits Textura ou Primário . Por exemplo, a presença do sinalizador de campo de bit primário indica um destino de renderização autônomo e a ausência desse sinalizador indica um destino de renderização que é um buffer de fundo.

Nota Para garantir que as alterações no runtime não interrompa os drivers existentes, os drivers não devem usar os seguintes membros reservados da estrutura D3DDDIARG_CREATERESOURCE2 em chamadas à função CreateResource2 para afetar o comportamento dos drivers:

Os bits indefinidos do membro Flags são reservados.
Se o sinalizador de campo de bit primário não estiver definido em Sinalizadores, os membros RefreshRate e Output serão reservados.
Se o sinalizador de campo de bits RenderTarget, DecodeRenderTarget ou VideoProcessRenderTarget não estiver definido em Sinalizadores, os membros MultisampleType e MultisampleQuality serão reservados.
Se o sinalizador de campo de bits VertexBuffer não estiver definido em Sinalizadores, o membro Fvf será reservado.
Se os sinalizadores de campo de bits Texture, CubeMap e Volume não estiverem definidos em Sinalizadores, o membro MipLevels será reservado.

Para obter mais informações sobre como criar e destruir recursos, consulte Manipulando a criação e a destruição de recursos.

Para um recurso de memória do sistema, o driver de miniporto de exibição poderá optar por encapsular uma alocação em torno da memória do sistema se a memória do sistema estiver corretamente alinhada para acesso direto pela GPU (unidade de processamento gráfico). O driver de miniporta de exibição encapsula uma alocação em torno da memória do sistema definindo o sinalizador ExistingSysMem no membro Flags da estrutura DXGK_ALLOCATIONINFO ao criar a alocação usando sua função DxgkDdiCreateAllocation . Se o driver de miniporto de exibição não puder encapsular uma alocação em torno da memória do sistema ou a disposição falhar, o driver ainda deverá ter sucesso na criação do recurso e usar a CPU para acessar o recurso.

Se o runtime solicitar a criação de um vértice ou buffer de índice e se o driver de exibição do modo de usuário não puder criar o buffer por motivos diferentes de memória insuficiente (por exemplo, falta de suporte de hardware), o driver deverá falhar com D3DERR_NOTAVAILABLE.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8
Servidor mínimo com suporte	Windows Server 2012
Plataforma de Destino	Área de Trabalho
Cabeçalho	d3dumddi.h (inclua D3dumddi.h)