Web 图形与 3D / 系统课时
接入轨道相机鼠标控制
接入轨道相机鼠标控制
本课为 WebGPU 三维画布加入轨道相机:按住鼠标左键拖动即可绕物体观察,滚轮可以拉近或拉远。我们将把输入转换成 yaw、pitch 和观察距离,限制俯仰角,再把更新后的视图投影矩阵传入 GPU,用彩色立方体验证操作效果。
学习目标
- 使用
pointermove、wheel更新水平角、俯仰角和观察距离。 - 计算相机位置与视图投影矩阵,并通过 Uniform 更新 WebGPU 画面。
- 验证极角限制、距离边界和鼠标释放后的交互状态。
三个状态量如何决定观察位置
轨道相机始终朝向固定观察中心 target = (0, 0, 0)。使用世界 Y 轴作为竖直方向,yaw 控制绕 Y 轴的水平旋转,pitch 控制高低视角,distance 是相机到中心的距离。本例初始值分别为 0.6 rad、0.35 rad 和 5 个世界单位。
设 为 distance、 为 pitch、 为 yaw,相机相对目标点的坐标为 、、。将三个分量加到目标点即可得到 eye,再由 lookAt(eye, target, up) 得到视图矩阵。up 固定为 (0, 1, 0),不会引入横滚角。
俯仰角限制为 ,约为 。到达正上方或正下方时,观察方向会与 up 平行,容易造成 lookAt 的右方向基向量无法归一化;保留 0.05 rad 的余量可以避免这一奇异点。

将输入接入 WebGPU 绘制
把下面的完整示例保存为 index.html。示例不依赖第三方矩阵库,以 depth24plus 深度缓冲渲染六色立方体;每帧计算投影矩阵与视图矩阵的乘积 并写入 64 字节的 Uniform Buffer。浏览器需要支持 WebGPU,并通过 localhost 或 HTTPS 的安全上下文访问页面。
<!doctype html>
<html lang='zh-CN'>
<head>
<meta charset='utf-8'>
<title>WebGPU 轨道相机</title>
<style>
body { margin: 0; background: #f5f8fa; font: 16px sans-serif; }
canvas { display: block; width: min(92vw, 860px); height: min(66vh, 540px);
margin: 20px auto 8px; touch-action: none; }
p { text-align: center; margin: 8px; }
</style>
</head>
<body>
<canvas id='scene'></canvas>
<p>左键拖动环绕 · 滚轮缩放</p>
<p id='status'></p>
<script type='module'>
const canvas = document.querySelector('#scene');
const status = document.querySelector('#status');
if (!navigator.gpu) throw new Error('需要支持 WebGPU 的浏览器与安全上下文');
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) throw new Error('无法获取 GPUAdapter');
const device = await adapter.requestDevice();
const context = canvas.getContext('webgpu');
const format = navigator.gpu.getPreferredCanvasFormat();
context.configure({ device, format, alphaMode: 'opaque' });
const faces = [
[[-1,-1,1],[1,-1,1],[1,1,1],[-1,1,1]],
[[1,-1,-1],[-1,-1,-1],[-1,1,-1],[1,1,-1]],
[[-1,-1,-1],[-1,-1,1],[-1,1,1],[-1,1,-1]],
[[1,-1,1],[1,-1,-1],[1,1,-1],[1,1,1]],
[[-1,1,1],[1,1,1],[1,1,-1],[-1,1,-1]],
[[-1,-1,-1],[1,-1,-1],[1,-1,1],[-1,-1,1]]
];
const vertices = new Float32Array(
faces.flatMap(f => [0,1,2,0,2,3].flatMap(i => f[i]))
);
const vertexBuffer = device.createBuffer({
size: vertices.byteLength,
usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST
});
device.queue.writeBuffer(vertexBuffer, 0, vertices);
const cameraBuffer = device.createBuffer({
size: 64, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
});
const shader = device.createShaderModule({ code: `
struct Camera { viewProj: mat4x4f, };
@group(0) @binding(0) var<uniform> camera: Camera;
struct VertexOut {
@builtin(position) clip: vec4f,
@location(0) color: vec3f,
};
@vertex fn vs(@location(0) pos: vec3f,
@builtin(vertex_index) id: u32) -> VertexOut {
let colors = array<vec3f, 6>(
vec3f(0.13,0.67,0.72), vec3f(0.25,0.42,0.72),
vec3f(0.85,0.53,0.30), vec3f(0.20,0.74,0.49),
vec3f(0.72,0.48,0.72), vec3f(0.34,0.57,0.62)
);
var out: VertexOut;
out.clip = camera.viewProj * vec4f(pos, 1.0);
out.color = colors[id / 6u];
return out;
}
@fragment fn fs(input: VertexOut) -> @location(0) vec4f {
return vec4f(input.color, 1.0);
}` });
const pipeline = device.createRenderPipeline({
layout: 'auto',
vertex: { module: shader, entryPoint: 'vs', buffers: [{
arrayStride: 12,
attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }]
}] },
fragment: { module: shader, entryPoint: 'fs', targets: [{ format }] },
primitive: { topology: 'triangle-list', cullMode: 'back' },
depthStencil: {
format: 'depth24plus', depthWriteEnabled: true, depthCompare: 'less'
}
});
const bindGroup = device.createBindGroup({
layout: pipeline.getBindGroupLayout(0),
entries: [{ binding: 0, resource: { buffer: cameraBuffer } }]
});
// 相机始终看向原点;角度以弧度表示。
let yaw = 0.6, pitch = 0.35, distance = 5;
const clamp = (n, min, max) => Math.max(min, Math.min(max, n));
let active = null, lastX = 0, lastY = 0;
canvas.addEventListener('pointerdown', e => {
if (e.button !== 0 || active !== null) return;
active = e.pointerId;
lastX = e.clientX; lastY = e.clientY;
canvas.setPointerCapture(e.pointerId);
});
canvas.addEventListener('pointermove', e => {
if (e.pointerId !== active) return;
const dx = e.clientX - lastX, dy = e.clientY - lastY;
lastX = e.clientX; lastY = e.clientY;
yaw -= dx * 0.006;
// 保留距极点 0.05 rad,防止观察方向与 up 平行。
const limit = Math.PI / 2 - 0.05;
pitch = clamp(pitch - dy * 0.006, -limit, limit);
});
for (const type of ['pointerup', 'pointercancel']) {
canvas.addEventListener(type, e => {
if (e.pointerId === active && canvas.hasPointerCapture(e.pointerId))
canvas.releasePointerCapture(e.pointerId);
});
}
canvas.addEventListener('lostpointercapture', e => {
if (e.pointerId === active) active = null;
});
canvas.addEventListener('wheel', e => {
e.preventDefault();
const delta = e.deltaY * (e.deltaMode === 1 ? 16 :
e.deltaMode === 2 ? canvas.clientHeight : 1);
distance = clamp(distance * Math.exp(delta * 0.001), 2, 14);
}, { passive: false });
const dot = (a,b) => a[0]*b[0] + a[1]*b[1] + a[2]*b[2];
const cross = (a,b) => [
a[1]*b[2]-a[2]*b[1], a[2]*b[0]-a[0]*b[2], a[0]*b[1]-a[1]*b[0]
];
const unit = a => { const d = Math.hypot(...a); return a.map(v => v/d); };
function lookAt(eye, target) {
const z = unit(eye.map((v,i) => v - target[i]));
const x = unit(cross([0,1,0], z));
const y = cross(z, x);
return [
x[0],y[0],z[0],0, x[1],y[1],z[1],0, x[2],y[2],z[2],0,
-dot(x,eye),-dot(y,eye),-dot(z,eye),1
];
}
function perspective(aspect) {
const f = 1 / Math.tan(Math.PI / 6), near = 0.1, far = 100;
// WebGPU 的 NDC 深度范围为 0 到 1。
return [
f/aspect,0,0,0, 0,f,0,0,
0,0,far/(near-far),-1,
0,0,far*near/(near-far),0
];
}
function mul(a,b) {
const out = new Float32Array(16);
for (let c=0; c<4; c++)
for (let r=0; r<4; r++)
for (let k=0; k<4; k++)
out[c*4+r] += a[k*4+r] * b[c*4+k];
return out;
}
let depthTexture;
function render() {
const dpr = Math.min(window.devicePixelRatio || 1, 2);
const max = device.limits.maxTextureDimension2D;
const w = Math.min(max, Math.max(1, Math.round(canvas.clientWidth*dpr)));
const h = Math.min(max, Math.max(1, Math.round(canvas.clientHeight*dpr)));
if (!depthTexture || w !== canvas.width || h !== canvas.height) {
canvas.width = w; canvas.height = h;
depthTexture?.destroy();
depthTexture = device.createTexture({
size: [w,h], format: 'depth24plus',
usage: GPUTextureUsage.RENDER_ATTACHMENT
});
}
const eye = [
distance * Math.cos(pitch) * Math.sin(yaw),
distance * Math.sin(pitch),
distance * Math.cos(pitch) * Math.cos(yaw)
];
// 列主序矩阵:先 View,再 Projection;立方体的 Model 为单位矩阵。
const vp = mul(perspective(w/h), lookAt(eye, [0,0,0]));
status.textContent = `yaw=${yaw.toFixed(2)} pitch=${pitch.toFixed(2)} distance=${distance.toFixed(2)}`;
device.queue.writeBuffer(cameraBuffer, 0, vp);
const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
colorAttachments: [{
view: context.getCurrentTexture().createView(),
clearValue: { r: 0.96, g: 0.98, b: 1, a: 1 },
loadOp: 'clear', storeOp: 'store'
}],
depthStencilAttachment: {
view: depthTexture.createView(), depthClearValue: 1,
depthLoadOp: 'clear', depthStoreOp: 'store'
}
});
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);
pass.setVertexBuffer(0, vertexBuffer);
pass.draw(vertices.length / 3);
pass.end();
device.queue.submit([encoder.finish()]);
requestAnimationFrame(render);
}
requestAnimationFrame(render);
</script>
</body>
</html>预期结果:用 python -m http.server 8000 在文件目录启动本地服务,打开 http://localhost:8000/,画布会显示不同颜色的立方体,页面下方显示 yaw=0.60 pitch=0.35 distance=5.00。左键拖动时立方体观察角度改变;向上滚动会拉近,向下滚动会拉远。数值显示用于检查输入是否真正改变了相机状态。
验证角度、距离和捕获释放
- 水平旋转:在画布内按住左键向右拖动约 100 CSS 像素,
yaw约减小0.60 rad;它不随设备像素比改变,因为采样使用的是clientX。 - 俯仰极限:持续向上拖动,
pitch最终停在约1.52 rad;持续向下拖动会停在约-1.52 rad,画面不应突然倒转。 - 距离限制:反复向上滚轮,
distance不小于2.00;向下滚轮不大于14.00。使用Math.exp实现按比例缩放,使不同观察距离下的滚轮手感更一致。 - 释放测试:按住左键拖出画布再松开,回到画布后仅移动鼠标不应继续旋转。
setPointerCapture让拖出画布后仍能收到同一次拖动事件,lostpointercapture负责清除拖动状态。
移植到已有场景
保留现有模型数据、着色器和渲染管线,只把示例中的指针事件状态、eye 计算、lookAt 与 Uniform 写入逻辑接入每帧更新。若场景有模型矩阵,顶点最终按 的矩阵顺序变换;本例立方体位于原点,因此 Model 是单位矩阵。
不要把拖动量直接累加到视图矩阵,这样会使旋转中心和缩放半径逐渐失控。正确做法是仅修改 yaw、pitch、distance,每帧重算相机位置。若对象不在原点,把 target 改为包围盒中心,并根据对象大小调整 2~14 的距离限制。