GPUQueue: writeTexture() 方法

語法

writeTexture(destination, data, dataLayout, size)

引數

destination

一個定義要寫入資料來源的紋理子資源和起點的物件，可以包含以下屬性：

aspect 可選

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

"all"

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

"depth-only"

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

"stencil-only"

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

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

mipLevel 可選

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

origin 可選

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

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

texture

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

data

一個物件，表示要寫入 GPUTexture 的資料來源。它可以是 ArrayBuffer、TypedArray 或 DataView。

dataLayout

一個物件，定義 data 中包含的內容的佈局。可能的值有：

offset 可選

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

bytesPerRow 可選

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

rowsPerImage 可選

單個紋理影像的塊行數。bytesPerRow × rowsPerImage 將給出每個完整影像開始之間的位元組步長。如果要複製多個影像，則此項是必需的。

size

一個物件或陣列，指定複製的範圍——要將資料寫入的紋理區域的最遠角。與 destination.origin 一起，這定義了要複製區域的完整範圍。有關物件/陣列結構的示例，請參見 destination.origin。

返回值

無 (Undefined)。

驗證

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

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

示例

在 高效渲染 glTF 模型 中，定義了一個用於建立純色紋理的函式。

function createSolidColorTexture(r, g, b, a) {
  const data = new Uint8Array([r * 255, g * 255, b * 255, a * 255]);
  const texture = device.createTexture({
    size: { width: 1, height: 1 },
    format: "rgba8unorm",
    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
  });
  device.queue.writeTexture({ texture }, data, {}, { width: 1, height: 1 });
  return texture;
}

這可用於為材質庫定義標準紋理。

const opaqueWhiteTexture = createSolidColorTexture(1, 1, 1, 1);
const transparentBlackTexture = createSolidColorTexture(0, 0, 0, 0);
const defaultNormalTexture = createSolidColorTexture(0.5, 0.5, 1, 1);

規範

瀏覽器相容性

另見

• WebGPU API