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

Artigo
08/07/2023

A função CreateResource cria um recurso.

Sintaxe

PFND3DDDI_CREATERESOURCE Pfnd3dddiCreateresource;

HRESULT Pfnd3dddiCreateresource(
  HANDLE hDevice,
  D3DDDIARG_CREATERESOURCE *unnamedParam2
)
{...}

Parâmetros

hDevice

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

unnamedParam2

pResource [in, out]

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

Retornar valor

CreateResource retorna um dos seguintes valores:

Código de retorno	Descrição
S_OK	O recurso foi criado com êxito.
E_OUTOFMEMORY	CreateResource não pôde alocar a memória necessária para que ela fosse concluída.
D3DERR_NOTAVAILABLE	CreateResource não pôde criar o recurso por motivos diferentes de não poder alocar memória. CreateResourcecan retornará esse erro somente ao criar buffers de vértice ou de índice.

Comentários

A chamada para CreateResource pode conter uma lista de superfícies. O membro SurfCount da estrutura D3DDDIARG_CREATERESOURCE especificada pelo parâmetro pResource 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 estão definidos como 9. Um mapa de cubos 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 CreateResource , 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 ele 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 CreateResource 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_CREATERESOURCE é 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 CreateResource e substituir o valor por outro valor que o runtime do Microsoft Direct3D pode usar quando a chamada CreateResource 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 CreateResource; 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 retornado de CreateResource. 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 de D3DDDIARG_CREATERESOURCE.

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 bit SharedResource no membro Flags do D3DDDIARG_CREATERESOURCE. 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 no 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 do modo de usuário é chamada para um recurso compartilhado que foi criado ou aberto por meio de uma chamada para a função CreateResource 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 bits especificados na estrutura D3DDDI_RESOURCEFLAGS são passados no membro Flags do D3DDDIARG_CREATERESOURCE.

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 bitblt (transferência de bloco de bits). No entanto, essas superfícies não podem ser usadas para qualquer outra coisa.

Nota Superfícies simples são diferenciadas de texturas ou destinos de renderização autônomos pela ausência do sinalizador de campo de bits Texture ou Primary . 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 traseiro.

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_CREATERESOURCE em chamadas à função CreateResource 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 bit 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.

A nova DDI CreateResource difere da DDI DdCreateSurface para o modelo de driver de exibição do Microsoft Windows 2000 das seguintes maneiras:

Na nova DDI CreateResource , as superfícies nunca são explicitamente anexadas. Todos os anexos são implícitos pela criação atômica.
Na nova DDI CreateResource , a criação parcial de mapas de cubo não é permitida.

Para um recurso de memória do sistema, o driver de miniporto de exibição pode 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 miniporto 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 o encapsulamento falhar, o driver ainda deverá ter êxito na criação do recurso e usar a CPU para acessar o recurso.

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

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)