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

Artigo
02/06/2025

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 de D3DDDIARG_CREATERESOURCE que descreve o recurso que é criado.

Valor de retorno

CreateResource retorna um dos seguintes valores:

Código de retorno	descrição
S_OK	O recurso é 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 índice.

Observações

A chamada para CreateResource pode conter uma lista de superfícies. O SurfCount membro da estrutura de 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 de mapa MIP de textura 256x256x9 contém uma lista de nove superfícies em que o SurfCount membro e o número de níveis de mapa MIP estã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 definidos 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 no 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 ede Agendamento de GPU.

Observação 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.

Observação 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 no modo de usuário deve armazenar o valor de hResource que foi passado na chamada CreateResource e substituir o valor com 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 no modo de usuário usa o hResource valor 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 hResource valor que foi 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 pSurfList membro do D3DDDIARG_CREATERESOURCE.

Os recursos podem ser compartilhados por vários dispositivos (hDevice) e processos. O runtime especifica que um recurso é compartilhado definindo o sinalizador SharedResource de campo de bits no Flags membro 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 o pfnAllocateCb e pfnDeallocateCb funções 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 recurso em si é 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 hResource membro 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 feche 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 de D3DDDI_RESOURCEFLAGS são passados no Flags membro do D3DDDIARG_CREATERESOURCE.

Observação Um recurso pode ser criado sem especificar sinalizadores. 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 bloco de bits (bitblt). No entanto, essas superfícies não podem ser usadas para qualquer outra coisa.

Observação superfícies simples são diferenciadas de texturas ou destinos de renderização autônomas pela ausência do sinalizador de textura ou principal campo de bits. Por exemplo, a presença do sinalizador de primário campo de bits 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.

Observação 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 para a função CreateResource para afetar o comportamento dos drivers:

Os bits indefinidos do Flags membro são reservados.
Se o sinalizador de campo de bits do Primário de não estiver definido em de Sinalizadores, os membros RefreshRate e Output serão reservados.
Se o RenderTarget, DecodeRenderTargetou VideoProcessRenderTarget sinalizador de campo de bit não estiver definido em Flags, os multisampleType e membros de multisampleQuality serão reservados.
Se o VertexBuffer sinalizador de campo de bits não estiver definido no Flags, o membro do Fvf será reservado.
Se os sinalizadores Texture, CubeMape Volume de campo de bits não forem definidos em sinalizadores de, o membro do MipLevels será reservado.

Para obter mais informações sobre como criar e destruir recursos, consulte Manipulandode Criação e Destruição de Recursos.

O novo CreateResource DDI difere da DDI de do DDCreateSurface para o modelo de driver de exibição Microsoft Windows 2000 das seguintes maneiras:

No novo CreateResource DDI, as superfícies nunca são anexadas explicitamente. Todos os anexos são implícitos pela criação atômica.
No novo CreateResource DDI, 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 de elementos gráficos). O driver de miniporto de exibição encapsula uma alocação em torno da memória do sistema definindo o sinalizador ExistingSysMem no Flags membro 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 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 da memória (por exemplo, falta de suporte a hardware), o driver deverá falhar com D3DERR_NOTAVAILABLE.

Requisitos

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