Web 图形与 3D / 系统课时
绑定 Sampler 并读取纹理颜色
绑定 Sampler 并读取纹理颜色
这篇使用一张 2×2 的 RGBA 测试纹理铺满画布,演示如何创建纹理视图和 Sampler、绑定到渲染管线,并让 WGSL 片元着色器用 UV 坐标读取颜色。完成后可以看到红、绿、蓝、白四个色块,直接验证绑定和坐标方向。
学习目标
- 区分
GPUTexture、GPUTextureView与GPUSampler的职责。 - 将纹理与采样器绑定到指定的
@group、@binding,调用textureSample。 - 用四象限颜色和过滤参数确认实际采样行为。
纹理数据怎样到达片元着色器
GPUTexture 存放像素;texture.createView() 产生可供着色器访问的视图;device.createSampler() 决定过滤和纹理边界的寻址方式。视图和 Sampler 是不同的绑定资源:本例把视图放在 @group(0) @binding(0),采样器放在 @group(0) @binding(1)。
WGSL 中使用 texture_2d<f32> 接受可过滤的 rgba8unorm 颜色纹理,采样结果是 0~1 范围的 vec4f。UV 是归一化坐标:左上角为 (0,0),右下角为 (1,1)。textureSample(纹理, 采样器, uv) 读取的位置由 UV 确定,如何在相邻像素之间取值则由 Sampler 决定。

完整示例:绑定两种资源并采样
示例以浏览器原生 WebGPU API 为准。使用支持 WebGPU 的 Chrome 或 Edge,在安全上下文(HTTPS 或 localhost)打开页面。把以下内容保存为 index.html;在该目录运行 python3 -m http.server 8000,再访问 http://localhost:8000。Python 命令会启动本地 HTTP 服务,终端保持监听状态,端口被占用时请改用空闲端口。
<!doctype html>
<html lang="zh-CN">
<head><meta charset="utf-8"><title>WebGPU 纹理采样</title></head>
<body>
<canvas id="screen" width="480" height="320"></canvas>
<script type="module">
const canvas = document.querySelector("#screen");
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 format = navigator.gpu.getPreferredCanvasFormat();
context.configure({ device, format, alphaMode: "opaque" });
const texture = device.createTexture({
size: [2, 2],
format: "rgba8unorm",
usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
});
// 每个像素4字节RGBA,按从上到下逐行写入。
const pixels = new Uint8Array([
255, 0, 0, 255, 0, 255, 0, 255,
0, 0, 255, 255, 255, 255, 255, 255,
]);
device.queue.writeTexture(
{ texture }, pixels, { bytesPerRow: 8 }, [2, 2, 1]
);
const sampler = device.createSampler({
magFilter: "nearest",
minFilter: "nearest",
addressModeU: "clamp-to-edge",
addressModeV: "clamp-to-edge",
});
const shader = device.createShaderModule({ code: `
struct VSOutput {
@builtin(position) position: vec4f,
@location(0) uv: vec2f,
};
@group(0) @binding(0) var imageTex: texture_2d<f32>;
@group(0) @binding(1) var imageSampler: sampler;
@vertex
fn vsMain(@builtin(vertex_index) i: u32) -> VSOutput {
let points = array<vec2f, 6>(
vec2f(-1.0,-1.0), vec2f(1.0,-1.0), vec2f(-1.0,1.0),
vec2f(-1.0,1.0), vec2f(1.0,-1.0), vec2f(1.0,1.0)
);
let p = points[i];
var out: VSOutput;
out.position = vec4f(p, 0.0, 1.0);
// 屏幕朝上为正Y,纹理UV的V则从顶部向下增大。
out.uv = vec2f((p.x + 1.0) * 0.5, (1.0 - p.y) * 0.5);
return out;
}
@fragment
fn fsMain(input: VSOutput) -> @location(0) vec4f {
return textureSample(imageTex, imageSampler, input.uv);
}
` });
const pipeline = device.createRenderPipeline({
layout: "auto",
vertex: { module: shader, entryPoint: "vsMain" },
fragment: {
module: shader, entryPoint: "fsMain", targets: [{ format }]
},
primitive: { topology: "triangle-list" },
});
const bindGroup = 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",
clearValue: { r: 0, g: 0, b: 0, a: 1 },
storeOp: "store",
}],
});
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);
pass.draw(6);
pass.end();
device.queue.submit([encoder.finish()]);
</script>
</body>
</html>**预期结果:**页面出现一个 480×320 的矩形;左上红色、右上绿色、左下蓝色、右下白色,颜色块边缘清晰。两个三角形组成的矩形铺满画布,片元着色器依据插值后的 UV 逐片元采样,并非 JavaScript 逐像素绘制。
queue.writeTexture 的 bytesPerRow 在这里是 2 像素 × 4 字节 = 8 字节;常见的 256 字节行对齐限制适用于 copyBufferToTexture,不适用于本例的 queue.writeTexture。
通过修改参数检查采样行为
这个例子把 2×2 的纹理放大到 480×320,因此主要使用 magFilter。保持 nearest 时,UV (0.25,0.25) 得到红色,(0.75,0.25) 得到绿色,(0.25,0.75) 得到蓝色,(0.75,0.75) 得到白色。把 magFilter 改成 linear 后重新加载,中心交界附近会出现平滑的混合色;minFilter 只在纹理缩小时才成为主要因素。
| 要检查的现象 | 检查位置和修正 |
|---|---|
| 上下两行颜色颠倒 | 检查顶点阶段的 1.0 - p.y,漏掉它会翻转 V 方向 |
| 画面空白或出现绑定验证错误 | 检查纹理使用标志包含 TEXTURE_BINDING、两项 binding 均与 WGSL 一致,并查看浏览器开发者工具 Console |
| 修改采样器却没有变化 | 修改后须重新创建 Sampler 和 BindGroup,再绘制;只修改普通 JavaScript 变量不会改变已创建的 GPU 资源 |
| 纹理边缘出现重复或被夹住 | 检查 addressModeU / addressModeV;它们在 UV 超出 0~1 时区别明显 |
生产项目通常会从图片上传像素,并复用同一张纹理视图搭配不同的 Sampler。只要 WGSL 的绑定编号与 BindGroup 条目一致,过滤策略就能独立于纹理数据更换。