方向立方体工具栏是 CAD 查看器(如 FreeCAD 的导航立方体)里那一排小 3D 立方体,每个立方体高亮不同的面。点击某个立方体把主 3D 视图对齐到那个方向——顶视图、前视图、右视图、等轴等。与上一篇里单个可拖动的方向立方体不同,这个组件是按钮网格:七个立方体渲染到同一个 canvas,每个都预旋转到相同的等轴视角,但高亮不同的面。
下面的实时演示加载 /scripts/direction-cubes-webgpu.js。点击任意立方体,选中的方向会显示在 canvas 下方。
点击立方体选择视图方向。
工作原理
组件是单个自包含脚本。除了上一篇里基本的 WebGPU 初始化之外,有意思的部分是:
- 一个 canvas,viewport 切出七个立方体。 单个渲染通道画全部七个立方体。每个立方体 draw 调用前,
pass.setViewport()和pass.setScissorRect()把渲染限制在该立方体的网格单元。这比七个独立 canvas 或七个渲染通道便宜得多。 - 一个 bind group,动态 uniform 偏移。 所有立方体共享同一个 bind group;每次 draw 只有 uniform buffer 里的偏移变化(
pass.setBindGroup(0, bindGroup, [i * UNIFORM_SLOT_SIZE]))。WebGPU 要求动态偏移的 uniform 槽 256 字节对齐,所以即使实际 uniform 数据只有 80 字节(一个mat4x4<f32>+ 一个f32+ 填充),UNIFORM_SLOT_SIZE = 256。 - 共享等轴视角,逐立方体高亮。 每个立方体用同一个
viewProj矩阵(相机在(2, -2, 2)看向原点,up = +Z)。唯一变化的逐立方体 uniform 是highlightedFace,一个i32,选择片元着色器把哪个面渲染得更亮更实。iso立方体用-1,不高亮任何面。 - 两条管线,一个 shader。 WGSL 模块含两个顶点和两个片元入口。面管线画半透明三角形,用预乘 alpha 混合;边管线把立方体线框画成
line-list,用depthCompare: 'always'让边始终叠在面上可见。面用depthWriteEnabled: false,边永不被面几何遮挡。 - 点击 → 网格单元 → 方向。 canvas 点击处理器把 canvas 分成 4×2 网格,把点击映射到单元格索引,再从
['iso','top','front','right','left','back','bottom']查出方向名。脚本在 canvas 上派发directionselectedCustomEvent,并可选调用 canvasdata-onselect属性指定的全局回调。
透明度分层——未标记面 10%、边 50%、高亮面 65%——让选中的面无需逐面颜色就能突出。高亮面无论朝向如何都用固定浅灰(0.85),所以它在每个立方体里永远是最亮的面。
在你自己的页面上使用
把 /scripts/direction-cubes-webgpu.js 放进你的静态目录,加一个带 nav-dircubes-canvas 类的 canvas,并用 data-onselect 接回调:
<canvas class="nav-dircubes-canvas"
data-onselect="onDirSelected"
style="width:640px;height:160px;"></canvas>
<p id="result"></p>
<script>
function onDirSelected(dir) {
document.getElementById('result').textContent =
'Selected: ' + dir;
}
</script>
<script src="/scripts/direction-cubes-webgpu.js" defer></script>回调收到 'iso'、'top'、'front'、'right'、'left'、'back'、'bottom' 之一。也可以直接在 canvas 上监听 directionselected CustomEvent(选中的方向在 event.detail 里)。
用 CSS 定 canvas 尺寸;devicePixelRatio 缩放和深度纹理重设尺寸由脚本内部处理。
完整源码
// SPDX-FileCopyrightText: 2026 Uli Köhler <gitlab@techoverflow.net>
// SPDX-License-Identifier: CC0-1.0
//
// Minimal WebGPU "direction cubes" navigation toolbar.
// Renders a 4x2 grid of small isometric cubes on a single canvas. Each cube
// highlights a different face (or none for the iso cube) to indicate which
// view direction it will snap the camera to. Clicking a cube emits a
// 'directionselected' CustomEvent on the canvas.
//
// Auto-initializes every <canvas class="nav-dircubes-canvas"> on the page.
// Optional: set data-onselect="myCallback" on the canvas to receive the
// selected direction name as a string ('iso','top','front','right','left',
// 'back','bottom').
//
// Why an IIFE? We wrap everything in an immediately-invoked function
// expression so that none of the helpers, constants, or the WGSL source
// leak into the global scope. The script is intended to be included
// verbatim with <script src=... defer>, possibly alongside other scripts
// on the same page, so isolation matters.
(function () {
'use strict';
// ─────────────────────────────────────────────────────────────────────
// Minimal mat4 helpers (column-major, WebGPU NDC z in [0,1])
// ─────────────────────────────────────────────────────────────────────
// WebGPU / WGSL stores matrices column-major, i.e. element [col*4+row].
// We mirror that layout here so we can upload the Float32Array directly
// to a uniform buffer without any transpose step.
// We only implement the handful of matrices we need: identity, multiply,
// perspective, and lookAt. No dependency on gl-matrix or similar — the
// goal is a single self-contained file.
function mat4Identity() {
const m = new Float32Array(16);
m[0] = m[5] = m[10] = m[15] = 1;
return m;
}
// Returns a * b in the sense that (a * b) * v applies b first, then a.
// This is the convention used everywhere in this file: the view-projection
// is built as proj * view, so a point is transformed view→clip.
function mat4Multiply(a, b) {
const r = new Float32Array(16);
for (let col = 0; col < 4; col++) {
for (let row = 0; row < 4; row++) {
let s = 0;
for (let k = 0; k < 4; k++) s += a[k * 4 + row] * b[col * 4 + k];
r[col * 4 + row] = s;
}
}
return r;
}
// Right-handed perspective projection matrix.
// The camera looks down -Z, so visible points have z < 0.
// This is the WebGPU convention: clip space z is in [0, 1] (not [-1, 1]
// as in OpenGL), which is why m[10] = far/(near-far) and m[14] has the
// extra near*far term. Getting this wrong is the #1 source of "my
// geometry disappeared" bugs when porting WebGL code to WebGPU.
function mat4Perspective(fovy, aspect, near, far) {
const f = 1 / Math.tan(fovy / 2);
const m = new Float32Array(16);
m[0] = f / aspect;
m[5] = f;
m[10] = far / (near - far);
m[11] = -1;
m[14] = (far * near) / (near - far);
return m;
}
// Right-handed lookAt matrix: places the camera at 'eye' looking toward
// 'target' with 'up' as the screen-up direction. Returns a view matrix
// (world→view). eye, target, up are plain {x,y,z} objects.
//
// The math:
// forward = normalize(eye - target) (points from target to eye)
// right = normalize(cross(up, forward))
// trueUp = cross(forward, right) (re-orthogonalized up)
// The matrix rows are [right | trueUp | forward], and the translation
// column is -dot(axis, eye) for each axis, which moves the world so the
// camera sits at the origin.
function mat4LookAt(eye, target, up) {
const zx = eye.x - target.x, zy = eye.y - target.y, zz = eye.z - target.z;
let zl = Math.hypot(zx, zy, zz);
const fx = zx / zl, fy = zy / zl, fz = zz / zl;
// right = normalize(cross(up, forward))
let rx = up.y * fz - up.z * fy;
let ry = up.z * fx - up.x * fz;
let rz = up.x * fy - up.y * fx;
let rl = Math.hypot(rx, ry, rz);
// Degenerate case: up is parallel to forward. Fall back to (1,0,0)
// so we don't produce NaNs.
if (rl < 1e-6) { rx = 1; ry = 0; rz = 0; rl = 1; }
rx /= rl; ry /= rl; rz /= rl;
// trueUp = cross(forward, right) — already unit length.
const ux = fy * rz - fz * ry;
const uy = fz * rx - fx * rz;
const uz = fx * ry - fy * rx;
const m = mat4Identity();
m[0] = rx; m[1] = ux; m[2] = fx;
m[4] = ry; m[5] = uy; m[6] = fy;
m[8] = rz; m[9] = uz; m[10] = fz;
m[12] = -(rx * eye.x + ry * eye.y + rz * eye.z);
m[13] = -(ux * eye.x + uy * eye.y + uz * eye.z);
m[14] = -(fx * eye.x + fy * eye.y + fz * eye.z);
return m;
}
// ─────────────────────────────────────────────────────────────────────
// Direction metadata
// ─────────────────────────────────────────────────────────────────────
// Each cube in the grid corresponds to one view direction. The cube
// highlights the face that the camera will be looking at when snapped
// to that direction. The 'iso' cube highlights no face (all faces are
// equally faint) because the isometric view doesn't look straight at
// any single face.
// Face indices — these must match the order in which faces are defined
// in buildCubeFaces() below, because the faceIdx attribute stored in
// each vertex is compared against these in the fragment shader.
const FACE_PX = 0, FACE_NX = 1, FACE_PY = 2, FACE_NY = 3, FACE_PZ = 4, FACE_NZ = 5;
// Which face to highlight for each direction (-1 = none / iso).
// The mapping is intuitive: 'top' looks down at the +Z face, 'front'
// looks at the -Y face (because the camera looks down -Y in our
// coordinate system), etc.
const HIGHLIGHT = {
iso: -1,
top: FACE_PZ,
bottom: FACE_NZ,
front: FACE_NY,
back: FACE_PY,
right: FACE_PX,
left: FACE_NX,
};
// Grid layout: 4 columns x 2 rows = 8 cells, but we only use 7
// (the 8th cell is left empty). The order of DIRECTIONS determines
// which cube appears in which cell, left-to-right, top-to-bottom.
const COLS = 4, ROWS = 2;
const DIRECTIONS = ['iso', 'top', 'front', 'right', 'left', 'back', 'bottom'];
// All cubes share the same isometric view; only the highlighted face
// differs. The eye position (2, -2, 2) looks at the origin from the
// front-right-top corner, which is the standard CAD isometric view.
// Up = +Z so the Z axis points up on screen.
const ISO_EYE = { x: 2, y: -2, z: 2 };
const ISO_UP = { x: 0, y: 0, z: 1 };
// Styling constants. The cubes are rendered semi-transparent so they
// look like ghosted wireframe boxes with one highlighted face, similar
// to the navigation cube in FreeCAD / Fusion 360.
const GRAY = [0.6, 0.6, 0.6];
const ALPHA_EDGE = 0.5; // edges — most visible
const ALPHA_FACE = 0.1; // normal faces — barely visible
const ALPHA_MARKED = 0.65; // highlighted face — clearly visible
// ─────────────────────────────────────────────────────────────────────
// Cube geometry: 6 faces x 4 verts (pos, normal, faceIdx) + 36 indices
// ─────────────────────────────────────────────────────────────────────
// Each face is a quad (4 vertices) with an outward normal and a faceIdx
// attribute. The faceIdx is what the fragment shader uses to decide
// whether this face is the highlighted one for the current cube.
//
// The vertex layout per vertex is 7 floats:
// [px, py, pz, nx, ny, nz, faceIdx]
// = 28 bytes, matching arrayStride: 7*4 in the pipeline.
function buildCubeFaces() {
const S = 0.5; // half-edge length → cube spans [-0.5, 0.5] on each axis
// Each face: 4 verts, [px,py,pz, nx,ny,nz, faceIdx]
// The winding is chosen so that triangles face outward, but since we
// render with cullMode: 'none' it doesn't strictly matter.
const data = [
// +X (right) - faceIdx 0
[ S,-S,-S, 1, 0, 0, 0], [ S, S,-S, 1, 0, 0, 0], [ S, S, S, 1, 0, 0, 0], [ S,-S, S, 1, 0, 0, 0],
// -X (left) - faceIdx 1
[-S,-S, S, -1, 0, 0, 1], [-S, S, S, -1, 0, 0, 1], [-S, S,-S, -1, 0, 0, 1], [-S,-S,-S, -1, 0, 0, 1],
// +Y (back) - faceIdx 2
[-S, S,-S, 0, 1, 0, 2], [-S, S, S, 0, 1, 0, 2], [ S, S, S, 0, 1, 0, 2], [ S, S,-S, 0, 1, 0, 2],
// -Y (front) - faceIdx 3
[-S,-S, S, 0,-1, 0, 3], [ S,-S, S, 0,-1, 0, 3], [ S,-S,-S, 0,-1, 0, 3], [-S,-S,-S, 0,-1, 0, 3],
// +Z (top) - faceIdx 4
[-S,-S, S, 0, 0, 1, 4], [-S, S, S, 0, 0, 1, 4], [ S, S, S, 0, 0, 1, 4], [ S,-S, S, 0, 0, 1, 4],
// -Z (bottom) - faceIdx 5
[ S,-S,-S, 0, 0,-1, 5], [ S, S,-S, 0, 0,-1, 5], [-S, S,-S, 0, 0,-1, 5], [-S,-S,-S, 0, 0,-1, 5],
];
// Flatten the nested array into a contiguous Float32Array.
const verts = new Float32Array(data.length * 7);
for (let i = 0; i < data.length; i++) verts.set(data[i], i * 7);
// 6 faces × 2 triangles × 3 indices = 36 indices.
// Each face's 4 vertices are split into two triangles: (0,1,2) and (0,2,3).
const indices = new Uint32Array([
0,1,2, 0,2,3, 4,5,6, 4,6,7, 8,9,10, 8,10,11,
12,13,14, 12,14,15, 16,17,18, 16,18,19, 20,21,22, 20,22,23,
]);
return { vertices: verts, indices };
}
// 12 edges × 2 endpoints = 24 line vertices.
// The edges are the cube's wireframe, drawn on top of the faces with
// higher opacity so the cube outline is always clearly visible.
function buildCubeEdges() {
const S = 0.5;
// 8 corner positions of the cube.
const c = [
[-S,-S,-S],[ S,-S,-S],[ S, S,-S],[-S, S,-S], // bottom face (z = -S)
[-S,-S, S],[ S,-S, S],[ S, S, S],[-S, S, S], // top face (z = +S)
];
// 12 edges as pairs of corner indices:
// 4 bottom edges, 4 top edges, 4 vertical edges.
const edges = [
[0,1],[1,2],[2,3],[3,0], // bottom face
[4,5],[5,6],[6,7],[7,4], // top face
[0,4],[1,5],[2,6],[3,7], // vertical edges
];
// Flatten into a Float32Array of positions (no colors — the edge
// fragment shader uses a fixed color from the uniform/constants).
const verts = new Float32Array(edges.length * 2 * 3);
let i = 0;
for (const [a, b] of edges) {
verts[i++] = c[a][0]; verts[i++] = c[a][1]; verts[i++] = c[a][2];
verts[i++] = c[b][0]; verts[i++] = c[b][1]; verts[i++] = c[b][2];
}
return verts;
}
// ─────────────────────────────────────────────────────────────────────
// WGSL shader
// ─────────────────────────────────────────────────────────────────────
// One shader module, two pipelines (faces + edges). The shader has
// four entry points: vs_face/fs_face for the semi-transparent cube
// faces, and vs_edge/fs_edge for the wireframe edges.
//
// The uniform struct contains:
// viewProj — the view-projection matrix (same for all cubes)
// highlightedFace — which face index to highlight (-1 = none)
//
// The ${...} template literals below are interpolated by JavaScript at
// shader creation time, baking the opacity/color constants directly
// into the WGSL source. This avoids extra uniforms and keeps the
// per-frame uniform data minimal (just viewProj + highlightedFace).
const SHADER = /* wgsl */ `
struct Uniforms {
viewProj: mat4x4<f32>,
highlightedFace: f32,
_pad0: f32,
_pad1: f32,
_pad2: f32,
};
@group(0) @binding(0) var<uniform> uniforms: Uniforms;
// ── Face pipeline ──
// Each face vertex carries a position, a normal (for lighting), and a
// faceIdx (to check if this face is the highlighted one).
struct FaceVertexInput {
@location(0) position: vec3<f32>,
@location(1) normal: vec3<f32>,
@location(2) faceIdx: f32,
};
struct FaceVertexOutput {
@builtin(position) clipPosition: vec4<f32>,
@location(0) normal: vec3<f32>,
@location(1) faceIdx: f32,
};
@vertex
fn vs_face(input: FaceVertexInput) -> FaceVertexOutput {
var out: FaceVertexOutput;
out.clipPosition = uniforms.viewProj * vec4<f32>(input.position, 1.0);
out.normal = input.normal;
out.faceIdx = input.faceIdx;
return out;
}
@fragment
fn fs_face(input: FaceVertexOutput) -> @location(0) vec4<f32> {
let faceIdx = i32(input.faceIdx);
let highlighted = i32(uniforms.highlightedFace);
var alpha = ${ALPHA_FACE.toFixed(2)};
var color: vec3<f32>;
if (highlighted >= 0 && faceIdx == highlighted) {
// Highlighted face: fixed light color so it is always clearly the
// lightest face, regardless of which face it is or its orientation
// relative to the light direction. Without this, a highlighted
// face that happens to face away from the light would look darker
// than an unhighlighted face facing toward it, which is confusing.
color = vec3<f32>(0.85, 0.85, 0.85);
alpha = ${ALPHA_MARKED.toFixed(2)};
} else {
// Normal faces: simple Lambertian shading with a fixed light
// direction. The 0.5 ambient term ensures even back-facing faces
// are partially visible.
let lightDir = normalize(vec3<f32>(0.4, -0.4, 0.8));
let ndotl = max(dot(normalize(input.normal), lightDir), 0.0);
let base = vec3<f32>(${GRAY[0].toFixed(1)}, ${GRAY[1].toFixed(1)}, ${GRAY[2].toFixed(1)});
color = base * (0.5 + 0.5 * ndotl);
}
// Premultiplied alpha: the pipeline blend state expects color values
// to be multiplied by alpha before output. This is why we return
// (color * alpha, alpha) rather than (color, alpha).
return vec4<f32>(color * alpha, alpha);
}
// ── Edge pipeline ──
// Edges only need a position; the color is fixed (derived from GRAY
// and ALPHA_EDGE, baked in at compile time).
struct EdgeVertexInput {
@location(0) position: vec3<f32>,
};
struct EdgeVertexOutput {
@builtin(position) clipPosition: vec4<f32>,
};
@vertex
fn vs_edge(input: EdgeVertexInput) -> EdgeVertexOutput {
var out: EdgeVertexOutput;
out.clipPosition = uniforms.viewProj * vec4<f32>(input.position, 1.0);
return out;
}
@fragment
fn fs_edge(input: EdgeVertexOutput) -> @location(0) vec4<f32> {
let alpha = ${ALPHA_EDGE.toFixed(2)};
let base = vec3<f32>(${GRAY[0].toFixed(1)}, ${GRAY[1].toFixed(1)}, ${GRAY[2].toFixed(1)});
// Premultiplied alpha, same as faces.
return vec4<f32>(base * alpha, alpha);
}
`;
// ─────────────────────────────────────────────────────────────────────
// Dynamic uniform offset constant
// ─────────────────────────────────────────────────────────────────────
// WebGPU requires that uniform buffer offsets used with dynamic offset
// bind groups be multiples of 256 bytes. Our actual uniform data is
// only 80 bytes (one mat4x4 + one f32 + padding), but we must pad each
// slot to 256 bytes. The uniform buffer is therefore allocated as
// 256 * 7 = 1792 bytes, with each cube's data at offset i * 256.
const UNIFORM_SLOT_SIZE = 256;
// ─────────────────────────────────────────────────────────────────────
// Per-canvas initialization
// ─────────────────────────────────────────────────────────────────────
// Called once for each <canvas class="nav-dircubes-canvas"> on the page.
// Sets up the WebGPU device, pipelines, geometry buffers, click handler,
// and starts the render loop. All GPU resources are captured in the
// closure so the render loop can access them without global state.
async function initCanvas(canvas) {
// --- WebGPU bootstrap ---
// navigator.gpu is the entry point. If it's missing, the browser
// does not support WebGPU at all. We replace the canvas with a text
// node so the page doesn't show a broken empty rectangle.
if (!navigator.gpu) {
canvas.replaceWith(document.createTextNode('WebGPU is not supported in this browser.'));
return;
}
const adapter = await navigator.gpu.requestAdapter();
if (!adapter) {
canvas.replaceWith(document.createTextNode('No WebGPU adapter available.'));
return;
}
const device = await adapter.requestDevice();
// Configure the canvas's WebGPU context. alphaMode: 'premultiplied'
// lets the canvas blend with the page background — important here
// because we clear to transparent and want the canvas background to
// show through between the cube grid cells.
const ctx = canvas.getContext('webgpu');
const format = navigator.gpu.getPreferredCanvasFormat();
ctx.configure({ device, format, alphaMode: 'premultiplied' });
// Compile the WGSL shader and build the geometry.
const shader = device.createShaderModule({ code: SHADER });
const faces = buildCubeFaces();
const edges = buildCubeEdges();
// --- Upload geometry to GPU buffers ---
// All geometry is static — uploaded once, never modified.
// Face vertex buffer: 24 vertices × 7 floats × 4 bytes = 672 bytes.
const faceVbuf = device.createBuffer({
size: faces.vertices.byteLength,
usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
});
device.queue.writeBuffer(faceVbuf, 0, faces.vertices);
// Edge vertex buffer: 24 vertices × 3 floats × 4 bytes = 288 bytes.
const edgeVbuf = device.createBuffer({
size: edges.byteLength,
usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
});
device.queue.writeBuffer(edgeVbuf, 0, edges);
// Index buffer for faces: 36 uint32 indices.
const ibuf = device.createBuffer({
size: faces.indices.byteLength,
usage: GPUBufferUsage.INDEX | GPUBufferUsage.COPY_DST,
});
device.queue.writeBuffer(ibuf, 0, faces.indices);
// --- Uniform buffer ---
// One 256-byte slot per cube, 7 cubes total = 1792 bytes.
// Each frame we write each cube's viewProj + highlightedFace into
// its slot, then use dynamic offsets to select the right slot per
// draw call.
const ubuf = device.createBuffer({
size: UNIFORM_SLOT_SIZE * DIRECTIONS.length,
usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});
// --- Bind group with dynamic offset ---
// We create a SINGLE bind group that references the entire uniform
// buffer. At draw time we pass a dynamic offset (i * 256) to select
// which cube's data to use. This is much cheaper than creating 7
// separate bind groups and is the idiomatic WebGPU pattern for
// rendering many instances with per-instance uniforms.
//
// hasDynamicOffset: true tells WebGPU that the offset will be
// supplied at setBindGroup() time rather than being fixed at bind
// group creation time.
const bindGroupLayout = device.createBindGroupLayout({
entries: [{
binding: 0,
visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
buffer: { type: 'uniform', hasDynamicOffset: true },
}],
});
const bindGroup = device.createBindGroup({
layout: bindGroupLayout,
entries: [{ binding: 0, resource: { buffer: ubuf, offset: 0, size: UNIFORM_SLOT_SIZE } }],
});
// --- Blend state ---
// Premultiplied alpha blending: the fragment shader outputs
// (color * alpha, alpha), and the blend state uses srcFactor: 'one'
// (not 'src-alpha') to match. This is the correct blend setup for
// premultiplied alpha and avoids double-darkening at overlap edges.
const blendState = {
color: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
alpha: { srcFactor: 'one', dstFactor: 'one-minus-src-alpha', operation: 'add' },
};
// --- Pipelines ---
// Two pipelines sharing the same bind group layout and shader module:
// facePipeline — renders semi-transparent triangles for cube faces
// edgePipeline — renders the wireframe edges as lines
//
// The face pipeline uses depthCompare: 'less' so that closer faces
// occlude farther ones (correct depth ordering), but
// depthWriteEnabled: false so faces don't write depth — this allows
// the edges (drawn after faces) to always pass the depth test.
//
// The edge pipeline uses depthCompare: 'always' so edges are never
// occluded by face geometry, giving the cube a clean wireframe
// outline regardless of viewing angle.
const facePipeline = device.createRenderPipeline({
layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
vertex: {
module: shader, entryPoint: 'vs_face',
// Vertex layout: 7 floats per vertex = 28 bytes.
// offset 0: position (float32x3)
// offset 12: normal (float32x3)
// offset 24: faceIdx (float32)
buffers: [{
arrayStride: 7 * 4,
attributes: [
{ shaderLocation: 0, offset: 0, format: 'float32x3' },
{ shaderLocation: 1, offset: 12, format: 'float32x3' },
{ shaderLocation: 2, offset: 24, format: 'float32' },
],
}],
},
fragment: {
module: shader, entryPoint: 'fs_face',
targets: [{ format, blend: blendState }],
},
primitive: { topology: 'triangle-list', cullMode: 'none' },
depthStencil: { format: 'depth24plus', depthCompare: 'less', depthWriteEnabled: false },
});
const edgePipeline = device.createRenderPipeline({
layout: device.createPipelineLayout({ bindGroupLayouts: [bindGroupLayout] }),
vertex: {
module: shader, entryPoint: 'vs_edge',
// Vertex layout: 3 floats per vertex = 12 bytes (position only).
buffers: [{ arrayStride: 12, attributes: [{ shaderLocation: 0, offset: 0, format: 'float32x3' }] }],
},
fragment: {
module: shader, entryPoint: 'fs_edge',
targets: [{ format, blend: blendState }],
},
primitive: { topology: 'line-list' },
depthStencil: { format: 'depth24plus', depthCompare: 'always', depthWriteEnabled: false },
});
// --- Depth texture ---
// Recreated whenever the canvas size changes. Even though edges use
// depthCompare: 'always', the face pipeline uses depthCompare: 'less'
// and thus needs a valid depth attachment.
let depthTex = null;
function ensureDepth(w, h) {
if (depthTex && depthTex.width === w && depthTex.height === h) return;
if (depthTex) depthTex.destroy();
depthTex = device.createTexture({
size: [w, h, 1], format: 'depth24plus', usage: GPUTextureUsage.RENDER_ATTACHMENT,
});
}
// --- Click handling: map canvas coords to grid cell → direction ---
// The canvas is divided into a COLS×ROWS grid. A click anywhere in
// cell (col, row) selects the direction at index row*COLS + col.
// This is a simple bounding-box hit test — no per-pixel picking
// needed, which keeps the code simple and fast.
function hitTest(clientX, clientY) {
const rect = canvas.getBoundingClientRect();
const x = clientX - rect.left;
const y = clientY - rect.top;
const cellW = rect.width / COLS;
const cellH = rect.height / ROWS;
const col = Math.floor(x / cellW);
const row = Math.floor(y / cellH);
const idx = row * COLS + col;
// idx 7 (the 8th cell) is empty, so reject it.
if (idx < 0 || idx >= DIRECTIONS.length) return null;
return DIRECTIONS[idx];
}
canvas.style.cursor = 'pointer';
canvas.addEventListener('click', (e) => {
const dir = hitTest(e.clientX, e.clientY);
if (!dir) return;
// Dispatch a CustomEvent so callers can use addEventListener.
canvas.dispatchEvent(new CustomEvent('directionselected', { detail: dir }));
// Also support the data-onselect attribute for simple use cases
// where the caller just wants to pass a global callback name.
const cbName = canvas.getAttribute('data-onselect');
if (cbName && typeof window[cbName] === 'function') window[cbName](dir);
});
// --- Render loop ---
// Runs once per animation frame. Each frame:
// 1. Resize canvas + depth texture if the CSS size changed.
// 2. Compute the shared view-projection matrix (same for all cubes).
// 3. Write per-cube uniform data (viewProj + highlightedFace).
// 4. Record a single render pass with 7 cubes, each in its own
// viewport cell, drawn as faces then edges.
// 5. Submit and schedule the next frame.
function frame() {
// Handle HiDPI: render at devicePixelResolution but cap at 2×.
const dpr = Math.min(window.devicePixelRatio || 1, 2);
const cw = Math.max(1, Math.floor(canvas.clientWidth * dpr));
const ch = Math.max(1, Math.floor(canvas.clientHeight * dpr));
if (canvas.width !== cw || canvas.height !== ch) {
canvas.width = cw; canvas.height = ch;
}
ensureDepth(cw, ch);
// Each cube occupies one cell of the grid. The viewport and
// scissor rect for each cube are set to its cell's pixel bounds.
const cellW = cw / COLS;
const cellH = ch / ROWS;
// The aspect ratio for the perspective projection is per-cell,
// not per-canvas, because each cube is rendered into its own
// square-ish viewport.
const aspect = cellW / cellH;
// All cubes share the same isometric view. Only the highlighted
// face differs per cube, and that's a uniform, not a matrix.
const view = mat4LookAt(ISO_EYE, { x: 0, y: 0, z: 0 }, ISO_UP);
const proj = mat4Perspective(35 * Math.PI / 180, aspect, 0.1, 10);
const viewProj = mat4Multiply(proj, view);
// Write per-cube uniform data. Each cube gets its own 256-byte
// slot in the uniform buffer. We only write the first 20 floats
// (80 bytes): 16 for viewProj + 1 for highlightedFace + 3 padding.
// The rest of the 256-byte slot is unused but must be allocated
// due to the 256-byte alignment requirement for dynamic offsets.
const slot = new Float32Array(UNIFORM_SLOT_SIZE / 4);
for (let i = 0; i < DIRECTIONS.length; i++) {
slot.set(viewProj, 0);
slot[16] = HIGHLIGHT[DIRECTIONS[i]];
// writeBuffer with offset=i*256, data=slot, length=20 floats=80 bytes.
device.queue.writeBuffer(ubuf, i * UNIFORM_SLOT_SIZE, slot, 0, 20);
}
// Record the render pass. Clear to transparent so the canvas
// background shows through between and around the cubes.
const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
colorAttachments: [{
view: ctx.getCurrentTexture().createView(),
clearValue: { r: 0, g: 0, b: 0, a: 0 },
loadOp: 'clear', storeOp: 'store',
}],
depthStencilAttachment: {
view: depthTex.createView(),
depthClearValue: 1.0, depthLoadOp: 'clear', depthStoreOp: 'store',
},
});
// Draw each cube into its grid cell.
// The key technique here: setViewport + setScissorRect restrict
// rendering to the cell's pixel bounds, then the dynamic offset
// in setBindGroup selects the per-cube uniform data. All 7 cubes
// are drawn in a single render pass, which is much more efficient
// than 7 separate passes.
for (let i = 0; i < DIRECTIONS.length; i++) {
const col = i % COLS;
const row = Math.floor(i / COLS);
// Viewport: maps NDC [-1,1] to the cell's pixel rectangle.
// Scissor: clips rasterization to the same rectangle, so cubes
// never bleed into neighboring cells.
pass.setViewport(col * cellW, row * cellH, cellW, cellH, 0, 1);
pass.setScissorRect(col * cellW, row * cellH, cellW, cellH);
// Draw faces: 36 indices (6 faces × 2 triangles × 3 indices).
// The dynamic offset [i * 256] selects this cube's uniform slot.
pass.setPipeline(facePipeline);
pass.setBindGroup(0, bindGroup, [i * UNIFORM_SLOT_SIZE]);
pass.setVertexBuffer(0, faceVbuf);
pass.setIndexBuffer(ibuf, 'uint32');
pass.drawIndexed(faces.indices.length);
// Draw edges: 24 vertices (12 edges × 2 endpoints).
// Same dynamic offset — the edge shader also reads viewProj
// from the uniform buffer.
pass.setPipeline(edgePipeline);
pass.setBindGroup(0, bindGroup, [i * UNIFORM_SLOT_SIZE]);
pass.setVertexBuffer(0, edgeVbuf);
pass.draw(edges.length / 3);
}
pass.end();
device.queue.submit([encoder.finish()]);
requestAnimationFrame(frame);
}
requestAnimationFrame(frame);
}
// ─────────────────────────────────────────────────────────────────────
// Auto-initialization
// ─────────────────────────────────────────────────────────────────────
// Find every <canvas class="nav-dircubes-canvas"> on the page and
// initialize it. If the document is still loading (script ran from
// <head> or with defer), wait for DOMContentLoaded so the canvases
// exist. If the document is already ready (script injected late),
// initialize immediately.
function initAll() {
document.querySelectorAll('canvas.nav-dircubes-canvas').forEach(initCanvas);
}
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initAll);
} else {
initAll();
}
})();该脚本与上面的内联代码完全相同,均以 CC0-1.0 发布。这里的版本是精简零依赖移植,保留了让这个组件渲染成本低的两个关键技术(WebGPU viewport 切网格单元、动态 uniform 偏移供逐立方体数据)。