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 绑定到片元着色器。

这里选择 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 这样的安全上下文。
<!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() 的数据布局参数混用。
排查空白、倒置与颜色异常
- 选图后画布没有变化:先看状态栏和开发者工具控制台。确认不是 WebGPU 不可用、图片解码失败或尺寸超过设备上限;检查
COPY_DST、RENDER_ATTACHMENT是否同时存在。 - 图片上下颠倒:本例上传时
flipY: false,在顶点阶段把屏幕上方向映射为纹理的uv.y=0。如果自行改了 UV 的 Y 计算,不要再盲目叠加一次翻转;只在上传阶段或采样映射阶段选一处处理方向。 - 透明边缘或颜色不对:这里使用
premultipliedAlpha: false,展示时未开启混合。需要透明混合时,应同时检查源图、目标纹理的预乘 Alpha 约定以及渲染管线的混合设置。进行线性空间的光照和颜色计算时,再评估rgba8unorm-srgb等带 sRGB 解码的格式。
还可以用一张左上角为红色、右下角为蓝色的测试图检查方向:屏幕的红蓝位置保持不变,就说明本例的复制方向与 UV 映射相互匹配。完成上传以后,GPUTexture 可在后续帧重复创建视图并采样;只要图片不变,就不需要每帧再次解码或复制。