> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CreatePlacedResource

> ID3D12Device::CreatePlacedResource cria um recurso leve posicionado em um heap específico no Direct3D 12 do XBOX, o tipo de recurso mais rápido de criar.

Cria um recurso posicionado em um heap específico. Os recursos posicionados são os objetos de recurso mais leves disponíveis e são os mais rápidos de criar e destruir.

Seu aplicativo pode reutilizar a memória de vídeo sobrepondo vários recursos posicionados e reservados do Direct3D em regiões de heap. O modelo simples de reutilização de memória (descrito em [Comentários](#remarks)) existe para esclarecer qual recurso sobreposto é válido em um determinado momento. Para maximizar o suporte das ferramentas gráficas, com o modelo simples não há suporte para herança de dados, nem para a invalidação mais granular de blocos e sub-recursos. Ocorre apenas a invalidação completa do recurso sobreposto.

## Sintaxe

```cpp theme={null}
HRESULT CreatePlacedResource(
    ID3D12Heap  pHeap,
    UINT64 HeapOffset,
    const D3D12_RESOURCE_DESC  pDesc,
    D3D12_RESOURCE_STATES InitialState,
    const D3D12_CLEAR_VALUE  pOptimizedClearValue,
    const IID & riid,
    void  ppvResource
)
```

### Parâmetros

*pHeap*<br />Tipo: ID3D12Heap \*

Um ponteiro para a interface **ID3D12Heap** que representa o heap no qual o recurso é posicionado.

*HeapOffset*<br />Tipo: UINT64

O deslocamento, em bytes, até o recurso. O *HeapOffset* deve ser um múltiplo do alinhamento do recurso, e *HeapOffset* mais o tamanho do recurso deve ser menor ou igual ao tamanho do heap. [**GetResourceAllocationInfo**](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_getresourceallocationinfo_public) deve ser usado para entender os tamanhos dos recursos de textura.

*pDesc*<br />Tipo: const D3D12\_RESOURCE\_DESC \*

Um ponteiro para uma estrutura **D3D12\_RESOURCE\_DESC** que descreve o recurso.

*InitialState*<br />Tipo: D3D12\_RESOURCE\_STATES

O estado inicial do recurso, como uma combinação OR bit a bit de constantes de enumeração **D3D12\_RESOURCE\_STATES**.

Quando um recurso é criado junto com um heap **D3D12\_HEAP\_TYPE\_UPLOAD**, *InitialState* deve ser **D3D12\_RESOURCE\_STATE\_GENERIC\_READ**. Quando um recurso é criado junto com um heap **D3D12\_HEAP\_TYPE\_READBACK**, *InitialState* deve ser **D3D12\_RESOURCE\_STATE\_COPY\_DEST**.

*pOptimizedClearValue*<br />Tipo: const D3D12\_CLEAR\_VALUE \*

Especifica um **D3D12\_CLEAR\_VALUE** que descreve o valor padrão de uma cor de limpeza.

*pOptimizedClearValue* especifica um valor para o qual as operações de limpeza são mais otimizadas. Quando o recurso criado é uma textura com os sinalizadores **D3D12\_RESOURCE\_FLAG\_ALLOW\_RENDER\_TARGET** ou **D3D12\_RESOURCE\_FLAG\_ALLOW\_DEPTH\_STENCIL**, seu aplicativo deve escolher o valor com o qual a operação de limpeza será chamada com mais frequência.

As operações de limpeza podem ser chamadas com outros valores, mas essas operações não serão tão eficientes quanto quando o valor corresponde ao passado na criação do recurso.

*pOptimizedClearValue* deve ser NULL quando usado com **D3D12\_RESOURCE\_DIMENSION\_BUFFER**.

*riid*<br />Tipo: const IID &

O identificador global exclusivo (**GUID**) da interface do recurso. Este é um parâmetro de entrada.

O **REFIID**, ou **GUID**, da interface do recurso pode ser obtido usando a macro `__uuidof`. Por exemplo, `__uuidof(ID3D12Resource)` obtém o **GUID** da interface de um recurso. Embora **riid** seja, mais comumente, o GUID de [**ID3D12Resource**](/pt-BR/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs), ele pode ser qualquer **GUID** de qualquer interface. Se o objeto de recurso não der suporte à interface desse **GUID**, a criação falhará com **E\_NOINTERFACE**.

*ppvResource*<br />Tipo: void \*\*

Um ponteiro para um bloco de memória que recebe um ponteiro para o recurso. *ppvResource* pode ser NULL, para permitir o teste de funcionalidades. Quando *ppvResource* é NULL, nenhum objeto será criado e S\_FALSE será retornado quando *pResourceDesc* e os outros parâmetros forem válidos.

### Valor retornado

Tipo: HRESULT

Este método retorna **E\_OUTOFMEMORY** se não houver memória suficiente para criar o recurso. Confira [Códigos de retorno do Direct3D 12](https://learn.microsoft.com/en-us/windows/win32/direct3d12/d3d12-graphics-reference-returnvalues) para outros valores de retorno possíveis.

## Comentários

**CreatePlacedResource** é semelhante a mapear totalmente um recurso reservado para um deslocamento dentro de um heap; mas o espaço de endereço virtual associado a um heap também pode ser reutilizado.

Os recursos posicionados são mais leves de criar e destruir do que os recursos confirmados. Isso ocorre porque nenhum heap é criado nem destruído durante essas operações. Além disso, os recursos posicionados permitem uma técnica ainda mais leve de reutilizar memória do que a criação e destruição de recursos, ou seja, a reutilização por meio de aliasing e barreiras de aliasing. Vários recursos posicionados podem se sobrepor simultaneamente no mesmo heap, mas apenas um único recurso sobreposto pode ser usado por vez.

Há duas semânticas de uso de recursos posicionados: um modelo simples e um modelo avançado. Recomendamos que você escolha o modelo simples (ele maximiza o suporte das ferramentas gráficas em todo o ecossistema diversificado de GPUs), a menos que e até que você descubra que precisa do modelo avançado para seu aplicativo.

### Modelo simples

Nesse modelo, você pode considerar que um recurso posicionado está em um de dois estados: ativo ou inativo. É inválido que a GPU leia ou grave em um recurso inativo. Os recursos posicionados são criados no estado inativo.

Para ativar um recurso com uma barreira de aliasing em uma lista de comandos, seu aplicativo deve passar o recurso em [**D3D12\_RESOURCE\_ALIASING\_BARRIER::pResourceAfter**](/pt-BR/reference/graphics/d3d12/structs/d3d12_resource_aliasing_barrier_public). **pResourceBefore** pode ser deixado como NULL durante uma ativação. Todos os recursos que compartilham memória física com o recurso ativado passam a ficar inativos, o que inclui recursos posicionados e reservados sobrepostos.

As barreiras de aliasing devem ser agrupadas e enviadas juntas, para maximizar a eficiência.

Após a ativação, os recursos com os sinalizadores de destino de renderização ou de estêncil de profundidade devem ser inicializados adicionalmente. Confira as observações sobre a inicialização de recursos necessária abaixo.

#### Observações sobre a inicialização de recursos necessária

Certos tipos de recursos ainda exigem inicialização. Os recursos com os sinalizadores de destino de renderização ou de estêncil de profundidade devem ser inicializados com uma operação de limpeza ou com uma coleção de cópias completas de sub-recursos. Se uma barreira de aliasing tiver sido usada para indicar a transição entre dois recursos com aliasing, a inicialização deverá ocorrer após a barreira de aliasing. Essa inicialização ainda é necessária sempre que um recurso seria ativado no modelo simples.

Os recursos posicionados e reservados com os sinalizadores de destino de renderização ou de estêncil de profundidade devem ser inicializados com uma das operações a seguir antes que outras operações tenham suporte.

* Uma operação *Clear*; por exemplo, [ClearRenderTargetView](/pt-BR/reference/graphics/d3d12_xs/interfaces/ID3D12GraphicsCommandList/methods/id3d12graphicscommandlist_clearrendertargetview_xs) ou [ClearDepthStencilView](/pt-BR/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_cleardepthstencilview_public).
* Uma operação [DiscardResource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_discardresource_public).
* Uma operação *Copy*; por exemplo, [CopyBufferRegion](/pt-BR/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_copybufferregion_public), [CopyTextureRegion](/pt-BR/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_copytextureregion_public) ou [CopyResource](https://learn.microsoft.com/en-us/windows/win32/api/d3d12/nf-d3d12-id3d12graphicscommandlist-copyresource).

Os aplicativos devem preferir a operação mais explícita que resulte na menor quantidade de texels modificados. Considere os exemplos a seguir.

* Usar um buffer de profundidade para resolver a visibilidade de pixels normalmente exige que cada texel de profundidade comece em 1,0 ou 0. Portanto, uma operação *Clear* deve ser a opção mais eficiente para a inicialização de um buffer de profundidade com aliasing.
* Um aplicativo pode usar um destino de renderização com aliasing como destino para o mapeamento de tons. Como o aplicativo renderizará sobre cada pixel durante o mapeamento de tons, [DiscardResource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_discardresource_public) deve ser a opção mais eficiente para a inicialização.

### Modelo avançado

Nesse modelo, você pode ignorar a abstração de estado ativo/inativo. Em vez disso, você deve respeitar estas regras de nível inferior.

* Uma barreira de aliasing deve estar entre dois acessos diferentes de recursos de GPU à mesma memória física, desde que esses acessos estejam dentro da mesma chamada de [ExecuteCommandLists](/pt-BR/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists).
* A primeira operação de renderização em certos tipos de recursos com aliasing ainda deve ser uma inicialização, assim como no modelo simples.

As operações de inicialização devem ocorrer em um sub-recurso inteiro ou em uma granularidade de 64 KB. A inicialização de um sub-recurso inteiro tem suporte para todos os tipos de recursos. Uma granularidade de inicialização de 64 KB, alinhada em um deslocamento de 64 KB, tem suporte para buffers e texturas com o layout de textura 64KB\_UNDEFINED\_SWIZZLE ou 64KB\_STANDARD\_SWIZZLE (consulte [D3D12\_TEXTURE\_LAYOUT](/pt-BR/reference/graphics/d3d12_x/enums/d3d12_texture_layout)).

### Observações sobre a barreira de aliasing

A barreira de aliasing pode definir NULL tanto para *pResourceAfter* quanto para *pResourceBefore*. A definição de coerência de memória de [**ExecuteCommandLists**](/pt-BR/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists) e a de uma barreira de aliasing são iguais, de modo que dois acessos com aliasing à mesma memória física não precisam de barreira de aliasing quando os acessos estão em duas invocações diferentes de **ExecuteCommandLists**.

Para os modelos de uso avançado do D3D12, a definição de sincronização de [**ExecuteCommandLists**](/pt-BR/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists) é equivalente a uma barreira de aliasing. Portanto, os aplicativos podem inserir uma barreira de aliasing entre reutilizações de memória física ou garantir que os dois usos com aliasing da memória física ocorram em duas chamadas separadas para **ExecuteCommandLists**.

A quantidade de inativação varia de acordo com as propriedades do recurso. As texturas com layouts de memória indefinidos são o pior caso, pois a textura inteira deve ser inativada atomicamente. Para dois recursos sobrepostos com layouts definidos, a inativação pode resultar apenas nas regiões alinhadas sobrepostas de um recurso. A herança de dados pode até ser bem definida. Para obter mais detalhes, confira [Aliasing de memória e herança de dados](https://learn.microsoft.com/en-us/windows/win32/direct3d12/memory-aliasing-and-data-inheritance).

## Requisitos

**Cabeçalho:** d3d12\_xs.h ou d3d12\_x.h<br />**Biblioteca:** d3d12\_xs.lib ou d3d12\_x.lib<br />**Plataformas com suporte**: consoles XBOX Series e família XBOX One

## Confira também

[CreateCommittedResource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createcommittedresource_public)

[CreateReservedResource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createreservedresource_public)

[ID3D12Device](/pt-BR/reference/graphics/d3d12_x/interfaces/id3d12device/id3d12device)

[Heaps compartilhados](https://learn.microsoft.com/en-us/windows/win32/direct3d12/shared-heaps)


## Related topics

- [CreatePlacedResource2 (consoles XBOX Series)](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device10/methods/id3d12device10_createplacedresource2_public.md)
- [CreateReservedResource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createreservedresource_public.md)
- [CreateCommittedResource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device/methods/id3d12device_createcommittedresource_public.md)
- [CreateReservedResource2 (consoles XBOX Series)](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device10/methods/id3d12device10_createreservedresource2_public.md)
- [CreateReservedResource1 (consoles XBOX Series)](/pt-BR/reference/graphics/d3d12/interfaces/id3d12device4/methods/id3d12device4_createreservedresource1_public.md)