> ## 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.

# WriteToSubresource

> Usa a CPU para copiar dados para um sub-recurso, permitindo que a CPU modifique o conteúdo da maioria das texturas com layouts indefinidos.

Usa a CPU para copiar dados para um sub-recurso, permitindo que a CPU modifique o conteúdo da maioria das texturas com layouts indefinidos.

## Sintaxe

```cpp theme={null}
HRESULT WriteToSubresource(
    UINT DstSubresource,
    const D3D12_BOX  pDstBox,
    const void  pSrcData,
    UINT SrcRowPitch,
    UINT SrcDepthPitch
)
```

### Parâmetros

*DstSubresource*\
Tipo: UINT

Especifica o índice do sub-recurso.

*pDstBox \[in, optional]*\
Tipo: const D3D12\_BOX \*

Um ponteiro para uma caixa que define a parte do sub-recurso de destino para a qual copiar os dados do recurso.
Se for NULL, os dados serão gravados no sub-recurso de destino sem deslocamento.
As dimensões da origem devem caber no destino (consulte
[D3D12\_BOX](/pt-BR/reference/graphics/d3d12/structs/d3d12_box_public)).

Uma caixa vazia resulta em nenhuma operação.
Uma caixa está vazia se o valor superior for maior ou igual ao valor inferior, ou se o valor esquerdo for maior ou igual ao valor direito,
ou se o valor frontal for maior ou igual ao valor traseiro.
Quando a caixa está vazia, este método não executa nenhuma operação.

*pSrcData \[in]*\
Tipo: const void \*

Um ponteiro para os dados de origem na memória.

*SrcRowPitch*\
Tipo: UINT

A distância de uma linha de dados de origem até a próxima linha.

*SrcDepthPitch*\
Tipo: UINT

A distância de uma fatia de profundidade de dados de origem até a próxima.

### Valor retornado

Tipo: HRESULT

Este método retorna um dos [Códigos de retorno do Direct3D 12](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/d3d12-graphics-reference-returnvalues).

## Comentários

<Note>
  ***OBSERVAÇÃO:*** No momento, não há suporte para isso nos consoles XBOX Series e na família XBOX One.
</Note>

O recurso deve primeiro ser mapeado usando
[Map](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public). As texturas devem estar no estado [D3D12\_RESOURCE\_STATE\_COMMON](/pt-BR/reference/graphics/d3d12_x/enums/d3d12_resource_states) para que o acesso da CPU por meio de **WriteToSubresource** e [ReadFromSubresource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_readfromsubresource_public) seja válido; mas os buffers não precisam.

Para maior eficiência, garanta que os limites e o alinhamento das extensões dentro da caixa sejam de ( 64 / \[bytes por pixel] ) pixels na horizontal.
Os limites e o alinhamento verticais devem ser de 2 linhas, exceto quando formatos de 1 byte por pixel forem usados; nesse caso, 4 linhas são recomendadas.
Fatias de profundidade únicas por chamada são tratadas com eficiência.
É recomendado, mas não necessário, fornecer ponteiros e passos alinhados a 128 bytes.

Ao gravar em subníveis de mipmap, é recomendável usar larguras e alturas maiores do que as descritas acima.
Isso ocorre porque níveis de mipmap pequenos podem, na verdade, ser armazenados dentro de um bloco maior de memória, com uma quantidade opaca de deslocamento que pode interferir no alinhamento com as linhas de cache.

**WriteToSubresource** e [ReadFromSubresource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_readfromsubresource_public) permitem otimizações de cópia quase zero para adaptadores UMA, mas podem prejudicar de forma proibitiva a eficiência de adaptadores discretos/NUMA, pois os dados de textura não podem residir na memória de vídeo local. Aplicativos típicos devem se ater a técnicas de upload adequadas a adaptadores discretos, a menos que reconheçam que a arquitetura do adaptador é UMA. Para obter mais detalhes sobre upload, consulte [CopyTextureRegion](/pt-BR/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist/methods/id3d12graphicscommandlist_copytextureregion_public) e, para obter mais detalhes sobre UMA, consulte [D3D12\_FEATURE\_DATA\_ARCHITECTURE](/pt-BR/reference/graphics/d3d12/structs/d3d12_feature_data_architecture_public).

Em sistemas UMA, esta rotina pode ser usada para minimizar o custo da cópia de memória por meio da otimização de loop conhecida como [loop tiling](https://en.wikipedia.org/wiki/Loop_tiling). Ao dividir o upload em blocos que caibam confortavelmente no cache da CPU, a largura de banda efetiva entre a CPU e a memória principal se aproxima mais dos máximos teóricos.

## Requisitos

**Cabeçalho:** d3d12\_xs.h ou d3d12\_x.h\
**Biblioteca:** d3d12\_xs.lib ou d3d12\_x.lib\
**Plataformas com suporte**: atualmente sem suporte nos consoles XBOX Series e na família XBOX One

## Confira também

[ID3D12Resource](/pt-BR/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs)

[Sub-recursos](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/subresources)


## Related topics

- [ReadFromSubresource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_readfromsubresource_public.md)
- [D3D12_BOX](/pt-BR/reference/graphics/d3d12/structs/d3d12_box_public.md)
- [Map](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_map_public.md)
- [D3D12_FEATURE_DATA_ARCHITECTURE1](/pt-BR/reference/graphics/d3d12/structs/d3d12_feature_data_architecture1_public.md)
- [ResolveSubresourceRegion](/pt-BR/reference/graphics/d3d12/interfaces/id3d12graphicscommandlist1/methods/id3d12graphicscommandlist1_resolvesubresourceregion_public.md)