Метод GPUQueue: copyExternalImageToTexture()

Метод copyExternalImageToTexture() интерфейса GPUQueue копирует снимок, взятый из исходного изображения, видео или холста, в заданный GPUTexture.

Использование этой функции позволяет агенту пользователя определить наиболее эффективный способ копирования данных для каждого типа источника.

source

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

source

Объект, предоставляющий источник снимка для копирования. Он может быть объектом HTMLCanvasElement, HTMLImageElement, HTMLVideoElement, ImageBitmap, ImageData, OffscreenCanvas или VideoFrame. Данные изображения-источника захватываются в точный момент вызова copyExternalImageToTexture().

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

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

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

origin: [0, 0];

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

origin: {
  x: 0,
  y: 0
}

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

Булево значение. Если установлено в true, захват изображения переворачивается по вертикали. Если опущено, flipY по умолчанию равно false.

destination

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

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

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

"all"

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

"depth-only"

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

"stencil-only"

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

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

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

Перечислимое значение, описывающее цветовое пространство и кодирование, используемые для кодирования данных в целевой текстуре. Возможные значения: "srgb" и "display-p3".

Если опущено, colorSpace по умолчанию равно "srgb".

Примечание: Кодирование может привести к записи в целевую текстуру значений за пределами диапазона [0, 1], если ее формат их может представить. В противном случае результаты ограничены диапазоном формата целевой текстуры. Преобразование может не потребоваться, если colorSpace соответствует цветовому пространству исходного изображения.

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

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

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

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

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

origin: [0, 0, 0];

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

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

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

Булево значение. Если установлено в true, данные изображения, записанные в текстуру, будут иметь цветовые каналы RGB, умноженные на альфа-канал. Если опущено, premultipliedAlpha по умолчанию равно false.

Примечание: Если этот параметр установлен в true и source также умножено, исходные цветовые значения RGB должны быть сохранены, даже если они превышают соответствующие значения альфа.

texture

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

copySize

Объект или массив, определяющий width, height, и depthOrArrayLayers — для области копирования.

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

origin: [16, 1, 1];

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

origin: {
  width: 16,
  height: 1,
  depthOrArrayLayers: 1
}

Значение width должно быть включено. Если значения height или depthOrArrayLayers опущены, они по умолчанию равны 1.

Нет (Undefined).

OperationError DOMException

Метод выбрасывает OperationError если не выполнены следующие условия:

• source.origin.x + ширина области, в которую копируется изображение, меньше или равна ширине исходного изображения.
• source.origin.y + высота области, в которую копируется изображение, меньше или равна высоте исходного изображения.
• source.origin.z + глубина или количество слоёв массива области, в которую копируется изображение, меньше или равна 1.
• dataOffset равно или меньше размера data.
• Размер data (при преобразовании в байты, в случае TypedArrays) кратен 4.

SecurityError DOMException

Выбрасывается, если данные исходного изображения имеют другой источник.

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

• mipLevel меньше, чем целевое значение GPUTexture.mipLevelCount.
• origin.x кратно ширине блока текселя целевого GPUTexture.format.
• origin.y кратно высоте блока текселя целевого GPUTexture.format.
• Если целевой GPUTexture.format — это формат глубины или трафарета, размер захвата изображения равен size.
• Целевое значение GPUTexture.usage включает флаги GPUTextureUsage.COPY_DST и GPUTextureUsage.RENDER_ATTACHMENT.
• Целевое значение GPUTexture.dimension равно "2d".
• Целевое значение GPUTexture.sampleCount равно 1.
• Целевой GPUTexture.format — один из следующих (поддерживающих использование GPUTextureUsage.RENDER_ATTACHMENT):
  • "r8unorm"
  • "r16float"
  • "r32float"
  • "rg8unorm"
  • "rg16float"
  • "rg32float"
  • "rgba8unorm"
  • "rgba8unorm-srgb"
  • "bgra8unorm"
  • "bgra8unorm-srgb"
  • "rgb10a2unorm"
  • "rgba16float"
  • "rgba32float"
• destination.origin.x + copySize.width меньше или равно destination GPUTexture width.
• destination.origin.y + copySize.height меньше или равно destination GPUTexture height.
• destination.origin.z + copySize.depthOrArrayLayers меньше или равно destination GPUTexture depthOrArrayLayers.
• Ширина destination GPUTexture.width кратна ширине блока текселя целевого GPUTexture.format.
• Высота destination GPUTexture.height кратна высоте блока текселя целевого GPUTexture.format.

В примере «Куб с текстурой» (Textured Cube) в примерах WebGPU Textured Cube example используется следующий фрагмент для извлечения изображения и загрузки его в GPUTexture:

let cubeTexture;
{
  const img = document.createElement("img");
  img.src = new URL(
    "../../../assets/img/Di-3d.png",
    import.meta.url,
  ).toString();
  await img.decode();
  const imageBitmap = await createImageBitmap(img);

  cubeTexture = device.createTexture({
    size: [imageBitmap.width, imageBitmap.height, 1],
    format: "rgba8unorm",
    usage:
      GPUTextureUsage.TEXTURE_BINDING |
      GPUTextureUsage.COPY_DST |
      GPUTextureUsage.RENDER_ATTACHMENT,
  });

  device.queue.copyExternalImageToTexture(
    { source: imageBitmap },
    { texture: cubeTexture },
    [imageBitmap.width, imageBitmap.height],
  );
}

• API WebGPU