GPUQueue: метод writeTexture()

Метод writeTexture() интерфейса GPUQueue записывает указанный источник данных в заданную GPUTexture.

Это удобная функция, предоставляющая альтернативу установке данных текстуры с помощью буферирования и копирования данных из буфера в текстуру. Она позволяет агенту пользователя определить наиболее эффективный способ копирования данных.

destination

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

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

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

"all"

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

"depth-only"

Записывается только глубинная часть формата глубины или стереоскопического изображения.

"stencil-only"

Записывается только стереоскопическая часть формата глубины или стереоскопического изображения.

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

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

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

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

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

Пример массива:

origin: [0, 0, 0];

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

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

texture

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

data

Объект, представляющий источник данных для записи в GPUTexture. Может быть ArrayBuffer, TypedArray или DataView.

dataLayout

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

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

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

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

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

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

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

size

Объект или массив, определяющий размер области копирования — противоположный угол региона текстуры для записи данных. Вместе с destination.origin, это определяет весь регион для копирования. См. destination.origin для примеров структуры объекта/массива.

Ничего (Undefined).

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

• mipLevel должно быть меньше, чем количество уровней mip-мапы назначения GPUTexture.mipLevelCount.
• origin.x должно быть кратно ширине блока текстуры назначения GPUTexture.format.
• origin.y должно быть кратно высоте блока текстуры назначения GPUTexture.format.
• Если формат назначения GPUTexture.format является форматом глубины или стереоскопического изображения или GPUTexture.sampleCount больше 1, размер подресурса должен быть равен size.
• Использование назначения GPUTexture.usage должно включать флаг GPUTextureUsage.COPY_DST.
• Количество выборок назначения GPUTexture.sampleCount должно быть равно 1.
• destination.origin.x + destination GPUTexture.width должно быть меньше или равно ширине подресурса для записи в destination GPUTexture.
• destination.origin.y + destination GPUTexture.height должно быть меньше или равно высоте подресурса для записи в destination GPUTexture.
• destination.origin.z + destination GPUTexture.depthOrArrayLayers должно быть меньше или равно глубине или количеству слоёв массива подресурса для записи в destination GPUTexture.
• Ширина подресурса назначения GPUTexture.width должна быть кратна ширине блока текстуры назначения GPUTexture.format.
• Высота подресурса назначения GPUTexture.height должна быть кратна высоте блока текстуры назначения GPUTexture.format.
• destination.aspect ссылается на один аспект формата назначения GPUTexture.format.
• Этот аспект является допустимым назначением копирования изображения согласно форматам глубины или стереоскопического изображения.
• destination совместим с форматом назначения GPUTexture.format.

В эффективном рендеринге моделей glTF определена функция для создания текстуры твёрдого цвета:

function createSolidColorTexture(r, g, b, a) {
  const data = new Uint8Array([r * 255, g * 255, b * 255, a * 255]);
  const texture = device.createTexture({
    size: { width: 1, height: 1 },
    format: "rgba8unorm",
    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
  });
  device.queue.writeTexture({ texture }, data, {}, { width: 1, height: 1 });
  return texture;
}

Это можно использовать для определения стандартных текстур для использования в библиотеках материалов:

const opaqueWhiteTexture = createSolidColorTexture(1, 1, 1, 1);
const transparentBlackTexture = createSolidColorTexture(0, 0, 0, 0);
const defaultNormalTexture = createSolidColorTexture(0.5, 0.5, 1, 1);

• API WebGPU