GPUCommandEncoder: copyBufferToTexture() 方法

語法

copyBufferToTexture(source, destination, copySize)

引數

source

一個定義要從中複製資料的緩衝區，以及緩衝區中要複製到紋理的資料的佈局的物件。結合 copySize，它定義了源緩衝區的區域。source 可以包含以下屬性：

buffer

要從中複製資料的 GPUBuffer。

offset 可選

從 data 開始到要複製的影像資料開始處的位元組偏移量。如果省略，offset 預設為 0。

bytesPerRow 可選

一個數字，表示每個塊行（即，一個完整的 texel 塊行）和後續塊行之間的位元組步長。如果存在多個塊行（即，複製高度或深度大於一個塊），則此項是必需的。

rowsPerImage 可選

每張影像中的塊行數。bytesPerRow × rowsPerImage 將給出每張完整影像開始之間的位元組步幅。如果要複製多張影像，則需要此項。

destination

一個定義要將資料寫入的紋理的物件。結合 copySize，它定義了目標紋理子資源區域。destination 可以包含以下屬性：

aspect 可選

一個列舉值，定義了要將資料寫入紋理的哪個方面。可能的值為：

"all"

將寫入紋理格式的所有可用方面，這可能意味著顏色、深度和模板中的全部或任何一個，具體取決於您處理的格式型別。

"depth-only"

僅將資料寫入 深度或模板格式 的深度方面。

"stencil-only"

僅將資料寫入深度或模板格式的模板方面。

如果省略，aspect 的值為 "all"。

mipLevel 可選

一個數字，表示要將資料寫入紋理的 mipmap 級別。如果省略，mipLevel 預設為 0。

origin 可選

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

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

texture

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

copySize

一個物件或陣列，指定複製資料的寬度、高度和深度/陣列層數。寬度值必須始終指定，而高度和深度/陣列層數是可選的，如果省略則預設為 1。

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

返回值

無 (Undefined)。

驗證

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

對於 source：

• source.bytesPerRow 是 256 的倍數。
• source.buffer 的 GPUBuffer.usage 包含 GPUBufferUsage.COPY_SRC 標誌。

對於 destination：

• mipLevel 小於 GPUTexture.mipLevelCount。
• origin.x 是 GPUTexture.format 的 texel 塊寬度的倍數。
• origin.y 是 GPUTexture.format 的 texel 塊高度的倍數。
• 如果 GPUTexture.format 是 深度或模板格式，或者 GPUTexture.sampleCount 大於 1，則子資源大小等於 size。
• destination 的 GPUTexture.usage 包含 GPUTextureUsage.COPY_DST 標誌。
• destination 的 GPUTexture.sampleCount 為 1。
• destination.aspect 指的是 GPUTexture.format 的單個方面。
• 該方面根據 深度或模板格式 是有效的影像複製目標。
• destination 與 copySize 相容。

示例

commandEncoder.copyBufferToTexture(
  {
    buffer: sourceBuffer,
  },
  {
    texture: destinationTexture,
  },
  {
    width: 16,
    height: 16,
    depthOrArrayLayers: 2,
  },
);

規範

瀏覽器相容性

另見

• WebGPU API