运行时参考

本页只记录驱动演示运行时的模块。测试专用的验证辅助逻辑不再作为 API 展示；用于校验 WGSL 行为的 CPU 镜像，请看计算着色器说明。

配置

运行时常量与着色器前导代码位于 src/config/sim.ts。

常量	类型	默认值	描述
PARTICLE_COUNT	number	10000	默认粒子数量
PARTICLE_SIZE	number	16	每粒子字节数（4 个浮点）
WORKGROUP_SIZE	number	64	计算着色器工作组大小
GRAVITY	Vec2	{x: 0, y: 600}	重力加速度（px/s²）
DAMPING	number	0.9	边界反弹速度阻尼
REPULSION_RADIUS	number	200	鼠标影响半径（px）
REPULSION_STRENGTH	number	3000	鼠标排斥力强度
MAX_SPEED	number	800	最大速度（px/s）
TRAIL_FADE_ALPHA	number	0.05	每帧轨迹淡出

function buildComputeShaderPreamble(): string;
function buildRenderShaderPreamble(): string;
function buildTrailShaderPreamble(): string;

这些函数会在创建管线时，把 TypeScript 侧常量注入到 WGSL 中。

共享类型

src/types.ts 保存运行时、着色器配置和测试共用的契约。

interface Particle {
  x: number;
  y: number;
  vx: number;
  vy: number;
}

interface Vec2 {
  x: number;
  y: number;
}

interface Uniforms {
  width: number;
  height: number;
  mouseX: number;
  mouseY: number;
  deltaTime: number;
  _pad1: number;
  _pad2: number;
  _pad3: number;
}

interface WebGPUContext {
  adapter: GPUAdapter;
  device: GPUDevice;
  context: GPUCanvasContext;
  format: GPUTextureFormat;
  canvas: HTMLCanvasElement;
}

运行时模块

应用启动 (src/main.ts)

启动流程保持很薄：

1. 设置画布尺寸；
2. 初始化 WebGPU；
3. 解析自适应质量；
4. 创建 GPU 资源；
5. 挂接输入与叠层 UI；
6. 启动渲染器。

画布尺寸管理 (src/core/canvas.ts)

function setupCanvas(canvas: HTMLCanvasElement): void;

让画布始终与视口和设备像素比保持同步。

WebGPU 初始化 (src/core/webgpu.ts)

async function initWebGPU(canvas: HTMLCanvasElement): Promise<WebGPUContext>;
function reconfigureContext(ctx: WebGPUContext): void;

负责适配器/设备获取、画布上下文配置，以及 resize 后的重新配置。

运行时质量控制 (src/core/quality.ts)

type SimulationQualityTier = 'low' | 'medium' | 'high';

interface RuntimeSimulationSettings {
  particleCount: number;
  qualityTier: SimulationQualityTier;
  scale: number;
}

function resolveSimulationSettings(
  input: SimulationHeuristicsInput,
  preferredParticleCount?: number
): RuntimeSimulationSettings;
function readRuntimeHeuristics(adapter: GPUAdapter, device: GPUDevice): SimulationHeuristicsInput;

根据当前设备与视口推导安全的粒子预算。

GPU 资源装配 (src/core/simulation-resources.ts)

interface SimulationResources {
  buffers: ParticleBuffers;
  pipelines: Pipelines;
}

function createSimulationResources(
  device: GPUDevice,
  format: GPUTextureFormat,
  canvasSize: Vec2,
  particleCount?: number
): SimulationResources;
function destroySimulationResources(resources: SimulationResources): void;

将粒子缓冲区、uniform buffer、管线与 bind group 作为一个整体创建和销毁。

帧编排 (src/core/renderer.ts)

class Renderer {
  start(): void;
  stop(): void;
  destroy(): void;
}

function createRenderer(
  ctx: WebGPUContext,
  pipelines: Pipelines,
  buffers: ParticleBuffers,
  getMousePosition: () => Vec2,
  onFrame?: () => void
): Renderer;

负责渲染循环、离屏轨迹纹理生命周期，以及 GPU 提交。

输入与界面壳层 (src/core/input.ts, src/core/app-shell.ts)

这两部分保持极简：

• createMouseHandler() 负责追踪画布坐标系中的鼠标/触摸位置；
• createFPSCounter()、createInfoOverlay()、createLoadingIndicator() 和 showError() 负责最小 DOM 壳层。

数据布局

粒子缓冲区

偏移	大小	字段	类型
0	4	x	f32
4	4	y	f32
8	4	vx	f32
12	4	vy	f32

均匀缓冲区

偏移	大小	字段	类型
0	4	width	f32
4	4	height	f32
8	4	mouseX	f32
12	4	mouseY	f32
16	4	deltaTime	f32
20-28	12	_pad	f32