企业官网建设流程全解析

在Diffusion Studio中嵌入three.js、WebGPU与WGSL着色器：视频画布终极玩法

【免费下载链接】editorAn open-source video editor built for agents. Edits become code, code becomes video.项目地址: https://gitcode.com/gh_mirrors/editor94/editor

Diffusion Studio 是一款面向 AI Agent 的开源视频编辑器：每一次剪辑都会写成真实的代码，代码又实时渲染成视频。本文带你用 three.js、WebGPU 和 WGSL 着色器玩转它的视频画布——让 3D 模型、GPU 三角形和实时滤镜成为时间线上的一等公民，导出时依然逐帧精准。

为什么视频画布能跑 GPU 渲染

Diffusion Studio 用 SolidJS 模块作为"文档源"：一个项目就是一个 JSX 文件，根元素是<stage>，里面每个<scene>对应你剪出的一帧画面。它像 IDE，但渲染的不是文本而是视频画布——在画布上拖拽一个矩形，代码会同步更新；反过来改代码，画布也会重绘。

在这种架构下，画布上的任何元素都可以是"活的"：

• <surface>：一块由你自己绘制的 canvas，支持 2d、WebGL（three.js）、WebGPU 任意上下文，引擎每帧把它采样进合成画面。
• <shaderPaint>：一段 WGSL 片元着色器，直接后处理下方视频或图像的每一帧。
• useTicker：唯一的"时钟"。播放头位置驱动所有动画，因此拖拽进度条和离线导出都保持逐帧精准。

快速开始：复制一个示例就能跑

官方仓库自带一组可运行的完整示例，位于 docs/examples/，每个文件就是一个项目的入口文件。跑法只有两步：

cp docs/examples/06-three.tsx ~/Projects/three/index.tsx dapi open ~/Projects/three

dapi是内置的命令行工具，会在任何目录启动应用并打开项目文件夹（完整命令见 docs/reference/tools/open.md）。

three.js：让 WebGL 接管一块

docs/examples/06-three.tsx 演示了完整套路：一个科幻头盔 glTF 模型，由播放头驱动自转。核心思路只有三步：

1. 接管画布：<surface ref={surfaceRef} />的ref会收到一个SceneNode，它的element就是一块独立的 canvas。onMount里把WebGLRenderer挂上去即可。
2. 统一时钟：在createEffect里读取useTicker()的time()，用它计算旋转角度——6 秒转一圈。不用requestAnimationFrame，所以导出渲染的每一帧都精确对应播放头。
3. 等待资源：hold(ready)把"模型加载完成"的 Promise 交给编码器，导出时会等模型下载完再采样，避免前几帧是黑屏。

两个容易踩的坑：WebGL 必须开preserveDrawingBuffer: true（否则引擎逐帧读回时可能拿到空白缓冲）；浏览器限制每个页面最多约 16 个 WebGL 上下文，多个 three.js 场景请共享一个 renderer。

小技巧：示例用RoomEnvironment在内存里烘焙 PBR 反射贴图，金属质感不用额外下载 HDR 文件。

原生 WebGPU：在视频画布上直接写 WGSL

如果不想引入 three.js，docs/examples/07-webgpu.tsx 展示了最裸的玩法：直接在<surface>上初始化 WebGPU 设备、编译一段 WGSL、画一个颜色随时间循环的三角形。

流程是标准的 WebGPU 套路：requestAdapter()→requestDevice()→getContext("webgpu")→ 创建着色器模块与渲染管线。亮点在于着色器里声明了一个timeuniform，每帧用writeBuffer写入合成时间，片元着色器用它算出一组余弦调色板。设备初始化是异步的，同样用hold()挂起，保证导出时管线就绪才出画。若运行环境不支持 WebGPU，示例会在控制台抛出明确错误而不是静默失败。

WGSL 后期处理： 给视频加滤镜

docs/examples/08-shader-paint.tsx 演示了最"视频编辑"的用法：给一段视频套上色散脉冲 + 暗角效果。写法出乎意料地简洁——把<shaderPaint>作为<video>的子元素，传入 WGSL 源码和 uniforms：

<video src="sintel-short.mp4" width={1920} height={1080}> <shaderPaint wgsl={ABERRATION} uniforms={{ strength: 1.5, vignette: 0.6 }} /> </video>

引擎会自动为你准备好一组"契约"（完整说明见 docs/reference/jsx/shader-paint.md）：

更妙的是热更新：uniforms 的值如果由 Solid 信号驱动，拖动就即时生效，无需重编译；没有媒体源时，<shaderPaint>还能在<rect>里纯程序化运行，当作生成式填充使用。

进阶玩法：TypeGPU 与 @inspect 变量

• 用 TypeScript 写着色器：docs/examples/10-typegpu.tsx 用 TypeGPU 把标有'use gpu'的函数在编译期转成 WGSL，做出水下焦散 + 雾 + 体积光的效果，比手写 WGSL 更舒服。
• 侧边栏控件直写源码：给顶层常量加一行/** @inspect number min=0 max=3 step=0.1 */注释，右侧面板就会长出对应的滑块，调好的值直接写回源文件——原理见 docs/examples/09-inspect-variables.tsx。
• 高分辨率导出：用useResolution()把 canvas 位图按导出倍率放大，1080p 导出时 960×540 的 surface 也不会糊。

实战避坑清单

1. ⏱️只用useTicker的时间：setInterval、requestAnimationFrame是墙钟，预览能动但导出无效。
2. ⏳异步资源必须hold()：模型、纹理、GPU 设备都要等，否则导出会写出未就绪的黑帧。
3. 🖼️WebGL 记得preserveDrawingBuffer: true，这是<surface>上跑 three.js 的硬性要求。
4. 🔍调试用dapi capture：按场景 ID 渲染几帧成联系表，不导出整片就能验证着色器效果（docs/reference/tools/capture.md）；WGSL 编译报错会带行号输出到控制台，可用dapi logs查看。

文档与源码地图

• 📚 示例总览：docs/examples/README.md
• 📖<surface>参考：docs/reference/jsx/surface-paint.md
• 📖<shaderPaint>参考：docs/reference/jsx/shader-paint.md
• 🧩 JSX 组件词汇表：docs/reference/jsx/README.md
• 🧠 无头运行时（ECS、媒体解码、帧采样）：packages/runtime/src/
• ✍️ 创作 API（useTicker、hold、useResolution）：packages/jsx/src/

从 three.js 3D 场景到一行 WGSL 滤镜，Diffusion Studio 的视频画布本质上就是一块"可被代码完全接管、又能随时在 UI 里拾起"的 GPU 画布。把示例拷进项目文件夹、dapi open一下，今晚就能让你的时间线上跑出 3D 和着色器。🎬

【免费下载链接】editorAn open-source video editor built for agents. Edits become code, code becomes video.项目地址: https://gitcode.com/gh_mirrors/editor94/editor