Memory2D<T>

O Memory2D<T> é um tipo que espelha a funcionalidade do tipo Memory<T>, com a diferença de que ele pode ser usado para representar locais de memória 2D. Ele é extremamente flexível e é capaz de encapsular vários tipos diferentes, incluindo matrizes ND (com suporte explícito para matrizes 1D, 2D e 3D) ou instâncias Memory<T>. Esse tipo deve ser usado junto com o tipo Span2D<T>, da mesma forma que Memory<T> é usado junto com Span<T>. Para obter mais informações sobre as principais diferenças e cenários de caso de uso desses dois tipos, você pode ler esta página de documentos.

APIs de Plataforma: Memory2D<T>, Span2D<T>, ReadOnlyMemory2D<T>

Como ele funciona

O tipo Memory2D<T> acompanha internamente a área de memória 2D mapeada por meio de uma referência ao objeto encapsulado, aos parâmetros de altura e largura e a um parâmetro de ângulo especial. A altura e a largura indicam o comprimento das linhas e colunas na área de memória 2D, enquanto o ângulo indica o deslocamento entre o final de cada linha e o início da seguinte.

Aqui está um diagrama simples que ilustra essa configuração (as células "XX" na grade representam itens pertencentes à área de memória 2D de destino):

//                _____________________stride_____...
//  reference__  /________width_________  ________...
//             \/                       \/
// | -- | -- | |- | -- | -- | -- | -- | -- | -- | -- |_
// | -- | -- | XX | XX | XX | XX | XX | XX | -- | -- | |
// | -- | -- | XX | XX | XX | XX | XX | XX | -- | -- | |
// | -- | -- | XX | XX | XX | XX | XX | XX | -- | -- | |_height
// | -- | -- | XX | XX | XX | XX | XX | XX | -- | -- |_|
// | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
// | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- |
// ...__pitch__/
// ...________/

Essa configuração permite que Memory2D<T> sejam extremamente flexíveis na maneira como mapeia buffers existentes para áreas de memória 2D, pois possibilita também representar buffers descontínuos como um local de memória 2D "virtual". Por exemplo, aqui estão alguns exemplos de tipos de buffer que uma instância de Memory2D pode mapear para:

• Uma matriz de T[] 1D mapeada como uma área de memória 2D em ordem principal de linha.
• Uma matriz de T[,] 2D, mapeada diretamente para uma instância de Memory2D<T>.
• Uma matriz de T[,,] 3D, com uma instância de Memory2D<T> que representa uma determinada fatia de profundidade (uma camada).

O tipo Memory<T> também expõe vários métodos utilitários, incluindo a maioria da mesma superfície de API que o Memory<T> padrão implementa. Por exemplo, ele inclui um método Slice(int, int) que facilita a realização de operações de fatiamento 2D diretamente no local de memória 2D virtual, com a instância de Memory2D<T> ajustando automaticamente os parâmetros necessários internamente para deslocar seu mapeamento nas áreas de memória corretas correspondentes ao resultado solicitado.

Sintaxe

Veja como você pode criar uma instância de Memory2D<T> de uma matriz 2D:

int[,] array =
{
    { 1, 2, 3 },
    { 4, 5, 6 },
    { 7, 8, 9 }
};

Memory2D<int> memory = array;

// The memory directly maps the 2*3 array here

Memory2D<int> slice = memory.Slice(0, 1, 2, 2);

// We create a slice from row 0 and column 1, of size 2*2

int[,] copy = slice.ToArray();

// { 2, 3 }
// { 5, 6 }

// If on a supported runtime, we can also slice using a range

Memory2D<int> test = memory[.., ..2];

// { 1, 2 }
// { 4, 5 }
// { 7, 8 }

Span2D<int> span = memory.Span;

// We can use the span to perform operations on the underlying
// data for the memory instance. All the available APIs are
// documented in the docs about the Span2D<T> type.

ReadOnlyMemory2D<T>

O ReadOnlyMemory2D<T> é para o tipo Memory2D<T> o que o ReadOnlyMemory<T> é para o Memory<T>. Ele expõe as mesmas funcionalidades (menos as APIs que envolvem a modificação do conteúdo da área de memória encapsulada) e fornece uma exibição somente leitura para locais arbitrários de memória 2D. Para obter mais informações sobre como esse tipo funciona, você pode consultar o parágrafo no tipo Memory2D<T> acima.

Exemplos

Você pode encontrar mais exemplos nos testes de unidade.