GPUQueue: copyExternalImageToTexture() 方法

語法

copyExternalImageToTexture(source, destination, copySize)

引數

source

一個表示要寫入目標的資料來源及其原點的物件。它可以具有以下屬性：

source

一個提供要複製快照的源的物件。它可以是 HTMLCanvasElement、HTMLImageElement、HTMLVideoElement、ImageBitmap、ImageData、OffscreenCanvas 或 VideoFrame 物件。影像源資料在呼叫 copyExternalImageToTexture() 時即時捕獲。

origin 可選

一個指定複製原點的物件或陣列 — 即要從中複製的源子區域的左上角。與 copySize 一起，這定義了源子區域的完整範圍。如果省略了 origin 的任何部分，則 x 和 y 值預設為 0。

例如，您可以傳遞一個數組，如 [0, 0]，或其等效物件 { 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-map 級別。如果省略，mipLevel 預設為 0。

origin 可選

一個指定複製原點的物件或陣列 — 即要將影像資料寫入的紋理區域的最小角點。與 copySize 一起，這定義了要複製到的區域的完整範圍。如果省略了 origin 的任何部分，則 x、y 和 z 值預設為 0。

例如，您可以傳遞一個數組，如 [0, 0, 0]，或其等效物件 { x: 0, y: 0, z: 0 }。

premultipliedAlpha 可選

一個布林值。如果設定為 true，則寫入紋理的影像資料將使用 alpha 通道預乘其 RGB 通道。如果省略，premultipliedAlpha 預設為 false。

注意：如果此選項設定為 true 且 source 也預乘了 alpha，則即使源 RGB 值超過其相應的 alpha 值，也必須保留它們。

texture

一個表示要寫入資料的 GPUTexture 物件。

copySize

一個指定要複製的區域的 width、height 和 depthOrArrayLayers 的物件或陣列。

例如，您可以傳遞一個數組，如 [16, 1, 1]，或其等效物件 { width: 16, height: 1, depthOrArrayLayers: 1 }。

必須包含 width 值。如果省略了 height 或 depthOrArrayLayers 值，則它們預設為 1。

返回值

無 (Undefined)。

異常

OperationError DOMException

如果未滿足以下條件，則該方法會丟擲 OperationError：

• source.origin.x + 要複製區域的寬度 小於或等於 源影像的寬度。
• source.origin.y + 要複製區域的高度 小於或等於 源影像的高度。
• source.origin.z + 要複製區域的 depthOrArrayLayers 小於或等於 1。
• dataOffset 等於或小於 data 的大小。
• data 的大小（轉換為位元組後，對於 TypedArrays）是 4 的倍數。

SecurityError DOMException

如果影像源資料是跨域的，則會丟擲此錯誤。

驗證

呼叫 writeTexture() 時必須滿足以下條件，否則會生成 GPUValidationError 並且 GPUQueue 會失效：

• mipLevel 小於目標 GPUTexture.mipLevelCount。
• origin.x 是目標 GPUTexture.format 的 texel 塊寬度的倍數。
• origin.y 是目標 GPUTexture.format 的 texel 塊高度的倍數。
• 如果目標 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 小於或等於 目標 GPUTexture 的 width。
• destination.origin.y + copySize.height 小於或等於 目標 GPUTexture 的 height。
• destination.origin.z + copySize.depthOrArrayLayers 小於或等於 目標 GPUTexture 的 depthOrArrayLayers。
• 目標 GPUTexture.width 是目標 GPUTexture.format 的 texel 塊寬度的倍數。
• 目標 GPUTexture.height 是目標 GPUTexture.format 的 texel 塊高度的倍數。

示例

在 WebGPU 示例的 紋理立方體示例 中，使用了以下程式碼段來獲取影像並將其上傳到 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],
  );
}

規範

瀏覽器相容性

另見

• WebGPU API