GPUQueue: copyExternalImageToTexture() Methode

source

Ein Objekt, das die Quelle zum Schreiben an das Ziel und dessen Ursprung darstellt. Dies kann die folgenden Eigenschaften haben:

source

Ein Objekt, das die Quelle des Snapshots zum Kopieren bereitstellt. Dies kann ein HTMLCanvasElement, HTMLImageElement, HTMLVideoElement, ImageBitmap, ImageData, OffscreenCanvas oder VideoFrame Objekt sein. Die Bildquelldaten 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 zu kopierenden Quellunterbereichs. Zusammen mit copySize definiert dies den gesamten Umfang des Quellunterbereichs. Die x- und y-Werte standardisieren auf 0, wenn origin ganz oder teilweise weggelassen wird.

Im Folgenden ein Beispielarray:

js

origin: [0, 0];

Das entsprechende Objekt sähe so aus:

js

origin: {
  x: 0,
  y: 0
}

flipY Optional

Ein Boolean. Wenn auf true gesetzt, wird der Bildausschnitt vertikal gespiegelt. Wenn es weggelassen wird, wird flipY standardmäßig auf false gesetzt.

destination

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

aspect Optional

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, was alle oder einige von Farbe, Tiefe und Schablone bedeuten kann, abhängig davon, um welche Art von Format es sich handelt.

"depth-only"

Nur der Tiefenaspekt eines Tiefen-oder-Schablonenformats wird beschrieben.

"stencil-only"

Nur der Schablonaspekt eines Tiefen-oder-Schablonenformats wird beschrieben.

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

colorSpace Optional

Ein enumerierter Wert, der den Farbraum und die Codierung beschreibt, die verwendet werden, um Daten in die Zieltextur zu codieren. Mögliche Werte sind "srgb" und "display-p3". Wird es weggelassen, ist colorSpace standardmäßig "srgb".

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

mipLevel Optional

Eine Zahl, die die Mip-Map-Ebene der Textur repräsentiert, in die das Bild geschrieben wird. Wenn es weggelassen wird, wird mipLevel standardmäßig auf 0 gesetzt.

origin Optional

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

Im Folgenden ein Beispielarray:

js

origin: [0, 0, 0];

Das entsprechende Objekt sähe so aus:

js

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

premultipliedAlpha Optional

Ein Boolean. Wenn auf true gesetzt, haben die im Textur geschriebenen Bilddaten ihre RGB-Kanäle bereits mit dem Alphakanal multipliziert. Wird es nicht angegeben, ist premultipliedAlpha standardmäßig false.

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

texture

Ein GPUTexture Objekt, das die Textur repräsentiert, in die die Daten geschrieben werden sollen.

copySize

Ein Objekt oder Array, das width, height und depthOrArrayLayers des Bereichs, von dem kopiert werden soll, angibt.

Im Folgenden ein Beispielarray:

js

origin: [16, 1, 1];

Das entsprechende Objekt sähe so aus:

js

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

Der width-Wert muss enthalten sein. Wenn die height- oder depthOrArrayLayers-Werte weggelassen werden, standardisieren sie auf 1.

Keiner (Undefined).

OperationError DOMException

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

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

SecurityError DOMException

Wird ausgelöst, wenn die Bildquelldaten Cross-Origin sind.

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 ZielGPUTexture.format.
• origin.y ist ein Vielfaches der Texelblockhöhe des ZielGPUTexture.format.
• Wenn das ZielGPUTexture.format ein Tiefen-oder-Schablonenformat ist, entspricht die Bildaufnahmengröße size.
• Die ZielGPUTexture.usage umfasst die GPUTextureUsage.COPY_DST und GPUTextureUsage.RENDER_ATTACHMENT Flags.
• Die ZielGPUTexture.dimension ist "2d".
• Die ZielGPUTexture.sampleCount ist 1.
• Das ZielGPUTexture.format ist eines der folgenden (welche 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 als oder gleich destination GPUTexture width.
• destination.origin.y + copySize.height ist kleiner als oder gleich destination GPUTexture height.
• destination.origin.z + copySize.depthOrArrayLayers ist kleiner als oder gleich destination GPUTexture depthOrArrayLayers.
• Die destination GPUTexture.width ist ein Vielfaches der Texelblockbreite des ZielGPUTexture.format.
• Die destination GPUTexture.height ist ein Vielfaches der Texelblockhöhe des ZielGPUTexture.format.

Im WebGPU Samples Textured Cube Beispiel, wird der folgende Ausschnitt verwendet, um ein Bild abzurufen und es 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