DiecopyExternalImageToTexture() Methode desGPUQueue-Interfaces kopiert einen Schnappschuss, der von einem Quellbild, Video oder Canvas aufgenommen wurde, in eine gegebeneGPUTexture.

Durch die Verwendung dieser Funktion kann der Benutzeragent die effizienteste Methode zum Übertragen der Daten für jeden Quelltyp bestimmen.

Syntax

copyExternalImageToTexture(source, destination, copySize)

Parameter

source

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

source

Ein Objekt, das die Quelle des Schnappschusses bereitstellt, der kopiert werden soll. Dies kann einHTMLCanvasElement,HTMLImageElement,HTMLVideoElement,ImageBitmap,ImageData,OffscreenCanvas oderVideoFrame-Objekt sein. Die Bildquelldaten werden genau in dem Moment erfasst, wenncopyExternalImageToTexture() aufgerufen wird.

originOptional

Ein Objekt oder Array, das den Ursprung der Kopie spezifiziert – die obere linke Ecke des Quellsubbereichs, von dem kopiert werden soll. Zusammen mitcopySize definiert dies das volle Ausmaß des Quellsubbereichs. Diex- undy-Werte standardisieren auf 0, wennorigin vollständig oder teilweise weggelassen wird.

Zum Beispiel können Sie ein Array wie[0, 0] oder das entsprechende Objekt{ x: 0, y: 0 } übergeben.

flipYOptional

Ein boolescher Wert. Wenn auftrue gesetzt, wird die Bildaufnahme vertikal gespiegelt. Wenn ausgelassen, standardisiertflipY auffalse.

destination

Ein Objekt, das die Textur-Subressource und den Ursprung definiert, um das aufgenommene Bild zu schreiben, sowie Metadaten zur Kodierung. Dies kann die folgenden Eigenschaften haben:

aspectOptional

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

"all"

Alle verfügbaren Aspekte des Texturformats werden beschrieben, das kann Farb-, Tiefen- und Stencil-Aspekte bedeuten, abhängig von dem verwendeten Format.

"depth-only"

Nur der Tiefenaspekt einesdepth-or-stencil format wird beschrieben.

"stencil-only"

Nur der Stencil-Aspekt eines Depth-or-Stencil-Formats wird beschrieben.

Wenn ausgelassen, nimmtaspect den Wert"all" an.

colorSpaceOptional

Ein enumerierter Wert, der den Farbraum und die Kodierung beschreibt, die verwendet werden, um Daten in die Zieltextur zu kodieren. Mögliche Werte sind"srgb" und"display-p3". Wenn ausgelassen, standardisiertcolorSpace auf"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 beschränkt. Eine Konvertierung ist möglicherweise nicht notwendig, wenncolorSpace mit dem Farbraum des Quellbilds übereinstimmt.

mipLevelOptional

Eine Zahl, die das Mip-Map-Level der Textur darstellt, auf das das Bild geschrieben werden soll. Wenn ausgelassen, standardisiertmipLevel auf 0.

originOptional

Ein Objekt oder Array, das den Ursprung der Kopie spezifiziert – die minimale Ecke des Texturbereichs, in den die Bilddaten geschrieben werden sollen. Zusammen mitcopySize definiert dies das volle Ausmaß des Bereichs, in den kopiert werden soll. Diex-,y- undz-Werte standardisieren auf 0, wennorigin vollständig oder teilweise weggelassen wird.

Zum Beispiel können Sie ein Array wie[0, 0, 0] oder das entsprechende Objekt{ x: 0, y: 0, z: 0 } übergeben.

premultipliedAlphaOptional

Ein boolescher Wert. Wenn auftrue gesetzt, werden die RGB-Kanäle der Bilddaten, die in die Textur geschrieben wurden, mit dem Alphakanal vorvermultipliziert. Wenn ausgelassen, standardisiertpremultipliedAlpha auffalse.

Hinweis:Wenn diese Option auftrue gesetzt ist und diesource auch vorvermultipliziert ist, müssen die Quell-RGB-Werte beibehalten werden, selbst wenn sie ihre entsprechenden Alphawerte überschreiten.

texture

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

copySize

Ein Objekt oder Array, daswidth,height unddepthOrArrayLayers — des Bereichs, von dem/zu dem kopiert werden soll, spezifiziert.

Zum Beispiel können Sie ein Array wie[16, 1, 1] oder das entsprechende Objekt{ width: 16, height: 1, depthOrArrayLayers: 1 } übergeben.

Derwidth-Wert muss angegeben werden. Wenn dieheight- oderdepthOrArrayLayers-Werte ausgelassen werden, standardisieren sie auf 1.

Rückgabewert

Keiner (Undefined).

Ausnahmen

OperationErrorDOMException

Die Methode wirft einenOperationError, wenn die folgenden Kriterien nicht erfüllt sind:

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

SecurityErrorDOMException

Wird ausgelöst, wenn die Bildquelldaten plattformübergreifend sind.

Validierung

Die folgenden Kriterien müssen erfüllt sein, wennwriteTexture() aufgerufen wird, andernfalls wird einGPUValidationError generiert und dieGPUQueue wird ungültig:

• mipLevel ist kleiner als die DestinationGPUTexture.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 eindepth-or-stencil format ist, ist die Bildgrößenaufnahme gleichsize.
• Die Ziel-GPUTexture.usage beinhaltet dieGPUTextureUsage.COPY_DST undGPUTextureUsage.RENDER_ATTACHMENT Flags.
• Die Ziel-GPUTexture.dimension ist"2d".
• Die Ziel-GPUTexture.sampleCount ist 1.
• Die Ziel-GPUTexture.format ist eines der folgenden (die denGPUTextureUsage.RENDER_ATTACHMENT-Einsatz 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 derdestinationGPUTexturewidth.
• destination.origin.y +copySize.height ist kleiner oder gleich derdestinationGPUTextureheight.
• destination.origin.z +copySize.depthOrArrayLayers ist kleiner oder gleich derdestinationGPUTexturedepthOrArrayLayers.
• DiedestinationGPUTexture.width ist ein Vielfaches der Texelblockbreite des Ziel-GPUTexture.format.
• DiedestinationGPUTexture.height ist ein Vielfaches der Texelblockhöhe des Ziel-GPUTexture.format.

Beispiele

Im WebGPU SamplesTextured Cube-Beispiel wird das folgende Snippet verwendet, um ein Bild abzurufen und es in eineGPUTexture 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],  );}

Spezifikationen

Browser-Kompatibilität

Siehe auch

• DieWebGPU API