Web 图形与 3D / 系统课时

上传图片像素到 GPUTexture

上传图片像素到 GPUTexture

把本地 PNG、JPEG 或 WebP 图片变成可供 WGSL 采样的 GPU 纹理。本课会实际完成图片解码、纹理分配、像素复制和屏幕显示,并核对格式、用途标志与图片尺寸,避免出现上传成功但渲染为空白的问题。

学习目标

  • 使用 createImageBitmap() 获得已解码图片及其像素尺寸。
  • 使用 createTexture() 和 copyExternalImageToTexture() 上传图片。
  • 通过纹理采样确认数据可用,并定位尺寸、用途和方向错误。

区分解码、分配与复制

createImageBitmap(file) 将图片文件解码为 ImageBitmap;它仍不是 WebGPU 的纹理。device.createTexture() 只按宽、高、格式和用途分配 GPU 资源,不会自动填入原图。随后调用 device.queue.copyExternalImageToTexture(),才把图片内容写入纹理。渲染时再用 texture.createView() 与 GPUSampler 绑定到片元着色器。

本地图片解码为 ImageBitmap、复制到 GPUTexture 并通过着色器显示的数据流

这里选择 rgba8unorm(8 位 RGBA 归一化通道),便于直接采样显示。上传目标同时声明 COPY_DST 和 RENDER_ATTACHMENT;后者也是此复制接口要求的用途标志。由于还要在片元着色器读取纹理,额外声明 TEXTURE_BINDING。

运行完整的图片上传页面

把下面内容保存为 index.html。在该文件目录运行 python3 -m http.server 8000(Windows 也可使用 py -m http.server 8000),然后访问 http://localhost:8000。需要支持 WebGPU 的浏览器,页面应运行在 HTTPS 或 localhost 这样的安全上下文。

html
<!doctype html>
<html lang="zh-CN">
<meta charset="utf-8">
<title>WebGPU 图片上传</title>
<label>选择图片:<input id="file" type="file" accept="image/png,image/jpeg,image/webp"></label>
<p id="status">正在初始化 WebGPU...</p>
<canvas id="view" width="640" height="360" style="max-width:100%"></canvas>
<script type="module">
const input = document.querySelector("#file");
const status = document.querySelector("#status");
const canvas = document.querySelector("#view");

async function main() {
  if (!navigator.gpu) throw new Error("当前环境不支持 WebGPU");
  const adapter = await navigator.gpu.requestAdapter();
  if (!adapter) throw new Error("找不到可用的 GPU 适配器");
  const device = await adapter.requestDevice();
  const context = canvas.getContext("webgpu");
  const canvasFormat = navigator.gpu.getPreferredCanvasFormat();
  context.configure({ device, format: canvasFormat, alphaMode: "opaque" });

  // 全屏三角形将上传的纹理按 UV 映射到画布。
  const shader = device.createShaderModule({ code: `
struct VOut {
  @builtin(position) position: vec4f,
  @location(0) uv: vec2f,
}
@vertex fn vs(@builtin(vertex_index) i: u32) -> VOut {
  let positions = array<vec2f, 3>(
    vec2f(-1.0, -1.0), vec2f(3.0, -1.0), vec2f(-1.0, 3.0)
  );
  var out: VOut;
  let p = positions[i];
  out.position = vec4f(p, 0.0, 1.0);
  out.uv = vec2f((p.x + 1.0) * 0.5, (1.0 - p.y) * 0.5);
  return out;
}
@group(0) @binding(0) var tex: texture_2d<f32>;
@group(0) @binding(1) var texSampler: sampler;
@fragment fn fs(@location(0) uv: vec2f) -> @location(0) vec4f {
  return textureSample(tex, texSampler, uv);
}` });
  const pipeline = device.createRenderPipeline({
    layout: "auto",
    vertex: { module: shader, entryPoint: "vs" },
    fragment: { module: shader, entryPoint: "fs",
      targets: [{ format: canvasFormat }] },
    primitive: { topology: "triangle-list" }
  });
  const sampler = device.createSampler({
    magFilter: "linear", minFilter: "linear"
  });
  let currentTexture;

  input.addEventListener("change", async () => {
    const file = input.files?.[0];
    if (!file) return;
    let bitmap;
    try {
      bitmap = await createImageBitmap(file);
      const { width, height } = bitmap;
      if (width > device.limits.maxTextureDimension2D ||
          height > device.limits.maxTextureDimension2D) {
        throw new Error("图片尺寸超过设备纹理上限");
      }

      // 必须先分配有正确用途标志的目标纹理。
      const texture = device.createTexture({
        size: [width, height, 1],
        format: "rgba8unorm",
        usage: GPUTextureUsage.COPY_DST |
               GPUTextureUsage.RENDER_ATTACHMENT |
               GPUTextureUsage.TEXTURE_BINDING
      });
      device.queue.copyExternalImageToTexture(
        { source: bitmap, flipY: false },
        { texture, colorSpace: "srgb", premultipliedAlpha: false },
        [width, height]
      );

      // 用纹理视图和采样器绘制,证明数据已进入 GPU。
      canvas.width = width;
      canvas.height = height;
      const group = device.createBindGroup({
        layout: pipeline.getBindGroupLayout(0),
        entries: [
          { binding: 0, resource: texture.createView() },
          { binding: 1, resource: sampler }
        ]
      });
      const encoder = device.createCommandEncoder();
      const pass = encoder.beginRenderPass({
        colorAttachments: [{
          view: context.getCurrentTexture().createView(),
          loadOp: "clear", storeOp: "store",
          clearValue: [0, 0, 0, 1]
        }]
      });
      pass.setPipeline(pipeline);
      pass.setBindGroup(0, group);
      pass.draw(3);
      pass.end();
      device.queue.submit([encoder.finish()]);
      await device.queue.onSubmittedWorkDone();

      currentTexture?.destroy();
      currentTexture = texture;
      status.textContent = `已上传并显示 ${width} × ${height} 像素`;
    } catch (error) {
      status.textContent = `上传失败:${error.message}`;
      console.error(error);
    } finally {
      bitmap?.close();
    }
  });
  status.textContent = "请选择 PNG、JPEG 或 WebP 图片";
}
main().catch(error => {
  status.textContent = `初始化失败:${error.message}`;
  console.error(error);
});
</script>
</html>

预期结果:页面先显示“请选择 PNG、JPEG 或 WebP 图片”。选择一张 256×256 的 PNG 后,画布显示该图片,状态文字显示“已上传并显示 256 × 256 像素”;换用其他尺寸,显示数字随图片变化。queue.onSubmittedWorkDone() 在本例中用于等候已提交的绘制命令完成,便于进行验证,不是每帧绘制都必须调用。

核对纹理参数与结果

检查项 本例取值 不匹配时的影响
图片尺寸 bitmap.width、bitmap.height 拷贝范围越界会报错;超过 maxTextureDimension2D 无法创建纹理
纹理格式 rgba8unorm 应使用可接受外部图片复制的颜色格式,不可随意改成深度格式
上传用途 `COPY_DST RENDER_ATTACHMENT`
采样用途 TEXTURE_BINDING 无法把纹理视图作为采样纹理绑定
复制尺寸 [width, height] 宽、高必须同时落在源图片与目标纹理范围内

本例 canvasFormat 来自 getPreferredCanvasFormat(),是画布输出格式;图片纹理始终采用 rgba8unorm。两者不要求名称相同,因为片元着色器先采样纹理,再把颜色写到画布附件。copyExternalImageToTexture() 直接处理外部图片源,不需要手动准备 bytesPerRow;不要把它与 writeTexture() 的数据布局参数混用。

排查空白、倒置与颜色异常

  1. 选图后画布没有变化:先看状态栏和开发者工具控制台。确认不是 WebGPU 不可用、图片解码失败或尺寸超过设备上限;检查 COPY_DST、RENDER_ATTACHMENT 是否同时存在。
  2. 图片上下颠倒:本例上传时 flipY: false,在顶点阶段把屏幕上方向映射为纹理的 uv.y=0。如果自行改了 UV 的 Y 计算,不要再盲目叠加一次翻转;只在上传阶段或采样映射阶段选一处处理方向。
  3. 透明边缘或颜色不对:这里使用 premultipliedAlpha: false,展示时未开启混合。需要透明混合时,应同时检查源图、目标纹理的预乘 Alpha 约定以及渲染管线的混合设置。进行线性空间的光照和颜色计算时,再评估 rgba8unorm-srgb 等带 sRGB 解码的格式。

还可以用一张左上角为红色、右下角为蓝色的测试图检查方向:屏幕的红蓝位置保持不变,就说明本例的复制方向与 UV 映射相互匹配。完成上传以后,GPUTexture 可在后续帧重复创建视图并采样;只要图片不变,就不需要每帧再次解码或复制。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

上传图片像素到 GPUTexture

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通