GPUQueue: copyExternalImageToTexture() Methode

source

Ein Objekt, das die Quelle darstellt, auf die in das Ziel geschrieben werden soll, und deren Ursprung. Dies kann die folgenden Eigenschaften haben:

source

Ein Objekt, das die Quelle des zu kopierenden Schnappschusses bereitstellt. Dies kann ein HTMLCanvasElement, HTMLImageElement, HTMLVideoElement, ImageBitmap, ImageData, OffscreenCanvas oder VideoFrame-Objekt sein. Die Bildquellendaten werden genau in dem Moment erfasst, in dem copyExternalImageToTexture() aufgerufen wird.

origin Optional

Ein Objekt oder Array, das den Ursprung der Kopie angibt — die obere linke Ecke des Quellunterbereichs, von dem kopiert werden soll. Zusammen mit copySize definiert dies den gesamten Umfang des Quellunterbereichs. Die x- und y-Werte haben Standardwerte von 0, wenn origin teilweise oder ganz weggelassen wird.

Zum Beispiel kann ein Array wie [0, 0] oder das entsprechende Objekt { x: 0, y: 0 } übergeben werden.

flipY Optional

Ein Boolean. Wenn auf true gesetzt, wird die Bildaufnahme vertikal gespiegelt. Wenn nicht angegeben, nimmt flipY standardmäßig den Wert false an.

destination

Ein Objekt, das die Texturunterressource und den Ursprung definiert, um das aufgenommene Bild zu schreiben, sowie die Kodierungsmetadaten. Dies kann die folgenden Eigenschaften haben:

aspect Optional

Ein enumerierter Wert, der angibt, welche Aspekte der Textur das Bild geschrieben werden soll. Mögliche Werte sind:

"all"

Alle verfügbaren Aspekte des Texturformats werden beschrieben, was je nach Format alle oder beliebige Farb-, Tiefen- und Schablonenaspekte bedeuten kann.

"depth-only"

Nur der Tiefenaspekt eines Tiefen- oder Schablonenformats wird beschrieben.

"stencil-only"

Nur der Schablonenaspekt eines Tiefen- oder Schablonenformats wird beschrieben.

Wenn weggelassen, nimmt aspect den Wert "all" an.

colorSpace Optional

Ein enumerierter Wert, der den Farbraum und die Kodierung beschreibt, die zur Kodierung der Daten in die Zieltextur verwendet werden. Mögliche Werte sind "srgb" und "display-p3". Wenn nicht angegeben, ist der Standardwert von colorSpace "srgb".

Hinweis: Die Kodierung kann dazu führen, dass Werte außerhalb des Bereichs [0, 1] in die Zieltextur geschrieben werden, wenn deren Format diese darstellen kann. Andernfalls werden die Ergebnisse auf den Bereich des Zieltexturformats geklammert. Eine Konvertierung ist möglicherweise nicht erforderlich, wenn colorSpace mit dem Farbraum des Quellbildes übereinstimmt.

mipLevel Optional

Eine Zahl, die das Mip-Map Level der Textur darstellt, in das das Bild geschrieben werden soll. Wenn nicht angegeben, wird mipLevel standardmäßig auf 0 gesetzt.

origin Optional

Ein Objekt oder Array, das den Ursprung der Kopie angibt — die minimale Ecke des Texturbereichs, in den die Bilddaten geschrieben werden sollen. Zusammen mit copySize definiert dies den gesamten Umfang des zu beschreibenden Bereichs. Die x-, y- und z-Werte haben Standardwerte von 0, wenn origin teilweise oder ganz weggelassen wird.

Zum Beispiel kann ein Array wie [0, 0, 0] oder das entsprechende Objekt { x: 0, y: 0, z: 0 } übergeben werden.

premultipliedAlpha Optional

Ein Boolean. Wenn auf true gesetzt, werden die in die Textur geschriebenen Bilddaten ihre RGB-Kanäle mit dem Alphakanal vorvervielfacht haben. Wenn nicht angegeben, wird premultipliedAlpha standardmäßig auf false gesetzt.

Hinweis: Wenn diese Option auf true gesetzt ist und die source auch vorvervielfacht ist, müssen die RGB-Werte der Quelle erhalten bleiben, auch wenn sie ihre entsprechenden Alphawerte überschreiten.

texture

Ein GPUTexture-Objekt, das die Textur darstellt, in die die Daten geschrieben werden sollen.

copySize

Ein Objekt oder Array, das width, height und depthOrArrayLayers des zu kopierenden Bereichs von/zum Ziel angibt.

Zum Beispiel kann ein Array wie [16, 1, 1] oder das entsprechende Objekt { width: 16, height: 1, depthOrArrayLayers: 1 } übergeben werden.

Der width-Wert muss enthalten sein. Wenn die height- oder depthOrArrayLayers-Werte fehlen, sind ihre Standardwerte 1.

Keiner (Undefined).

OperationError DOMException

Die Methode löst einen OperationError aus, wenn die folgenden Kriterien nicht erfüllt sind:

• source.origin.x + die Breite des zu kopierenden Bereichs ist kleiner oder gleich der Breite des Quellbildes.
• source.origin.y + die Höhe des zu kopierenden Bereichs ist kleiner oder gleich der Höhe des Quellbildes.
• source.origin.z + die depthOrArrayLayers des zu kopierenden Bereichs ist kleiner oder gleich 1.
• dataOffset ist gleich oder kleiner als die Größe von data.
• Die Größe von data (in Bytes konvertiert, im Fall von TypedArrays) ist ein Vielfaches von 4.

SecurityError DOMException

Ausgelöst, wenn die Bildquellendaten von einer anderen Herkunft stammen.

Die folgenden Kriterien müssen erfüllt sein, wenn writeTexture() aufgerufen wird, andernfalls wird ein GPUValidationError erzeugt und die GPUQueue wird ungültig:

• mipLevel ist kleiner als die Ziel GPUTexture.mipLevelCount.
• origin.x ist ein Vielfaches der Texelblockbreite des Ziel GPUTexture.format.
• origin.y ist ein Vielfaches der Texelblockhöhe des Ziel GPUTexture.format.
• Wenn das Ziel GPUTexture.format ein Tiefen- oder Schablonenformat ist, muss die Größe der Bildaufnahme gleich size sein.
• Die Ziel GPUTexture.usage enthält die Flags GPUTextureUsage.COPY_DST und GPUTextureUsage.RENDER_ATTACHMENT.
• Die Ziel GPUTexture.dimension ist "2d".
• Die Ziel GPUTexture.sampleCount ist 1.
• Das Ziel GPUTexture.format ist eines der folgenden (die GPUTextureUsage.RENDER_ATTACHMENT-Nutzung unterstützen):
  • "r8unorm"
  • "r16float"
  • "r32float"
  • "rg8unorm"
  • "rg16float"
  • "rg32float"
  • "rgba8unorm"
  • "rgba8unorm-srgb"
  • "bgra8unorm"
  • "bgra8unorm-srgb"
  • "rgb10a2unorm"
  • "rgba16float"
  • "rgba32float"
• destination.origin.x + copySize.width ist kleiner oder gleich der destination GPUTexture width.
• destination.origin.y + copySize.height ist kleiner oder gleich der destination GPUTexture height.
• destination.origin.z + copySize.depthOrArrayLayers ist kleiner oder gleich der destination GPUTexture depthOrArrayLayers.
• Die destination GPUTexture.width ist ein Vielfaches der Texelblockbreite des Ziel GPUTexture.format.
• Die destination GPUTexture.height ist ein Vielfaches der Texelblockhöhe des Ziel GPUTexture.format.

Im WebGPU Samples Textured Cube Beispiel wird der folgende Code verwendet, um ein Bild abzurufen und in eine GPUTexture hochzuladen:

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],
  );
}

• Die WebGPU API