GPUCommandEncoder: метод copyTextureToBuffer()

Метод copyTextureToBuffer() интерфейса GPUCommandEncoder кодирует команду, которая копирует данные из GPUTexture в GPUBuffer.

source

Объект, определяющий текстуру для копирования данных. В сочетании с copySize, определяет область подресурса исходной текстуры. source может принимать следующие свойства:

aspect Необязательно

Перечисление, определяющее, какие аспекты текстуры нужно скопировать. Возможные значения:

"all"

Будут скопированы все доступные аспекты формата текстуры, что может означать все или любые из цвет, глубина и трафарет, в зависимости от используемого формата.

"depth-only"

Будет скопирован только аспект глубины формата глубины или трафарета.

"stencil-only"

Будет скопирован только аспект трафарета формата глубины или трафарета.

Если опущено, aspect принимает значение "all".

mipLevel Необязательно

Число, представляющее уровень mip-маски текстуры для копирования данных. Если опущено, mipLevel по умолчанию равно 0.

origin Необязательно

Объект или массив, указывающий начало копирования — минимальную вершину области текстуры для копирования данных. Вместе с size, определяет полный объем области для копирования. Значения x, y, и z по умолчанию равны 0, если какой-либо или все origin опущено.

Вот пример массива:

[0, 0, 0];

Эквивалентный объект будет выглядеть так:

{
  x: 0,
  y: 0,
  z: 0
}

texture

Объект GPUTexture, представляющий текстуру для копирования данных.

destination

Объект, определяющий буфер для записи и структуру данных для записи в буфер. В сочетании с copySize, определяет область целевого буфера. source может принимать следующие свойства:

buffer

GPUBuffer для записи.

offset Необязательно

Смещение в байтах от начала data до начальной позиции для записи скопированных данных. Если опущено, offset по умолчанию равно 0.

bytesPerRow Необязательно

Число, представляющее шаг в байтах между началом каждой строки блоков (т.е. строки полных блоков текстурных элементов) и следующей строкой блоков. Требуется, если есть несколько строк блоков (т.е. высота или глубина копирования больше одного блока).

rowsPerImage Необязательно

Количество строк блоков на один образ внутри данных. bytesPerRow × rowsPerImage даст вам шаг в байтах между началом каждого целого изображения. Требуется, если нужно скопировать несколько изображений.

copySize

Объект или массив, определяющий ширину, высоту и глубину/количество слоев массива копируемых данных. Ширина должна всегда быть указана, а высота и глубина/количество слоев массива — необязательны и по умолчанию равны 1, если опущено.

Следующий пример массива copySize:

[16, 16, 2];

Эквивалентный объект:

{
  width: 16,
  height: 16,
  depthOrArrayLayers: 2
}

None (Undefined).

При вызове copyTextureToBuffer() должны быть выполнены следующие условия; в противном случае генерируется GPUValidationError, и GPUCommandEncoder становится недействительным.

Для source:

• mipLevel меньше GPUTexture.mipLevelCount.
• origin.x кратно ширине блока текстурного элемента GPUTexture.format.
• origin.y кратно высоте блока текстурного элемента GPUTexture.format.
• Если GPUTexture.format — формат глубины или трафарета или GPUTexture.sampleCount больше 1, размер подресурса равен size.
• source GPUTexture.usage включает флаг GPUTextureUsage.COPY_SRC.
• source GPUTexture.sampleCount равен 1.
• source.aspect относится к одному аспекту GPUTexture.format.
• Этот аспект является допустимым источником копирования изображения в соответствии с форматами глубины или трафарета.
• source совместимо с copySize.

Для destination:

• destination.bytesPerRow кратно 256.
• destination.buffer GPUBuffer.usage включает флаг GPUBufferUsage.COPY_DST.

• API WebGPU