animaxxing-webgl

Animaxxing WebGL

使用原生 TypeScript 编写的方案，让 GSAP 驱动 WebGL。平面会在每张图片的精确盒子中绘制图片；带框视图会在元素的盒子中绘制场景、粒子或液体表面。GSAP 会补间它们的着色器 uniform。页面仍由 DOM 构成：真实的 <img> 或视图的海报 <img> 会保留其替代文本、布局和链接，并在 WebGL 无法绘制时显示自身。

先加载匹配的 gsap-<framework> 技能（纯网站使用 gsap-vanilla），如果缺少则先安装。它负责 mount → initial state → intro → settled → outro → end state → unmount、初始化、导航、恢复和清理时机。其 references/transition-archetypes.md 中的 Persistent WebGL canvas 介绍了如何让画布在路由切换时保持存活。仅使用 DOM 的效果由 animaxxing 技能提供；本技能不要求使用它。

渲染器：OGL

这些方案使用 OGL 1.x。使用 esbuild 对这些方案所用的类（renderer、program、mesh、plane geometry、texture、scene）进行测量，压缩并 gzip 后，OGL 1.0.11 为 14.5 KB，three.js r186 为 133 KB，因为 three.js 的 WebGLRenderer 会引入库中的大部分内容。图片方案需要在像素空间中绘制带自定义着色器的 2D 平面；带框视图会增加摄像机、渲染目标和点几何体，不需要灯光、材质或加载器。OGL 的 Program、Mesh、Plane、Camera、RenderTarget 和 Texture 与这些需求一一对应。它不处理上下文丢失，因此由舞台负责：上下文恢复时重建渲染器和每个图层。

如果项目已经引入 three.js，请移植这些方案，而不是再添加 OGL：用 ShaderMaterial 对应 Program（uniform 对象相同），用 PlaneGeometry 对应 Plane，用 Texture 对应 Texture，使用 Scene 和任意摄像机，并采用方案中的像素空间顶点着色器；删除时调用 dispose()。three.js 会自行恢复丢失的上下文，因此移除重建逻辑并保留 DOM 回退。

设置与适配

• 安装 gsap 3.13 或更高版本，以及 ogl 1.x。请先读取已安装版本和类型定义，再决定是否采用这些方案。效果会在模块作用域注册 ScrollTrigger；如果项目在中心位置注册插件，请移除此项。仅从客户端代码导入这些模块。
• 仅复制任务所需的模块，并使用以下文件名：始终需要 webgl-stage.ts；平面和任何会加载图片纹理的方案需要 image-planes.ts；图片效果需要 uniform-effects.ts；任何视图都需要 framed-views.ts；然后再添加 scene-flight.ts、particle-morph.ts、liquid-image.ts 或 metaballs.ts。每个模块只会导入列表中排在它前面的模块。
• 图片需要 CORS。同源、data: 和 blob: 图片均可使用；CDN 图片需要 Access-Control-Allow-Origin，并在标记中设置 crossorigin="anonymous"（图片平面需要 CORS）。无法读取的图片会继续通过 DOM 渲染。
• 仅添加请求的效果。效果常量、着色器数值和擦除方向都是可编辑的默认值；请根据表面进行调整。平面会按照页面布局绘制图片，不会自行添加颜色、字体或布局。
• 标记需要添加平面的图片，例如 img[data-webgl]。依赖祖先裁剪、border-radius、滤镜或 object-position 的图片应排除在 WebGL 之外，或者将这些效果加入替代着色器。

只阅读所需内容

任务	参考
共享渲染器和画布、预算、上下文丢失、暂停、跨路由持久化	WebGL 舞台
跟踪 <img> 的 WebGL 平面；CORS；替换着色器	图像平面
悬停透镜、滚动速度波纹、显现和退出擦除、图像故障效果、溶解、像素化、涟漪	Uniform 效果
不是图像的绘制内容，显示在元素框内，并带有海报回退	带框视图
摄像机穿越图像构成的 3D 螺旋轨迹，并由滚动或时间线控制进度	场景飞行
在文字、徽标、球体和散布形状之间变形的 GPU 粒子	粒子变形
指针拖动时会留下轨迹的液态图像，以及倾注式片头笔画	液态图像
汇聚成文字或形状并滴落的液态金属液滴，或随滚动沿列向下倾泻的液流	变形球
在客户端导航之间保留同一个画布	匹配的已安装框架技能中的 references/transition-archetypes.md，持久化 WebGL 画布
片头依赖的平面；截止时间和恢复	匹配的已安装框架技能中的 references/initialization.md
手机档位和像素预算	匹配的已安装框架技能中的 references/devices.md
验证回退、上下文丢失、暂停和释放	验证，然后检查框架中的相关项目

回退约定

DOM 就是页面。画布绝不是阅读、导航或操作页面的必要条件。

条件	结果
JavaScript 已禁用	不会运行任何内容；图像和海报就是页面。
不支持 WebGL	holdStage 返回 null；不创建画布；平面和视图的 ready 为 false；输入效果不会构建任何内容；擦除、故障效果、溶解、像素化、涟漪、变形和倾注时间线立即结束。
减少动态效果	与不支持 WebGL 时相同。偏好设置变更时，控制器会拆除并重新构建。
图像无法通过 CORS 读取，或加载失败	该图像继续由 DOM 渲染；其他平面不受影响。飞行场景会排除该图像；如果所有图像都未加载，则保留海报。
上下文丢失	所有图像和海报会立即显示；停止绘制。恢复后，会根据保留的源和 uniform 值重建每个平面和视图。
一帧渲染出错	隐藏画布，显示所有图像，记录错误，并且舞台在重新创建之前拒绝添加新平面。
位于屏幕外，或标签页已隐藏	舞台停止逐帧运行；直到图像接近视口或标签页重新显示之前，不会绘制任何内容。

只有当平面或视图已在其位置绘制一帧后，<img> 或海报才会变为透明（opacity: 0，仍保留在无障碍树和布局中）。视图的海报是其静止帧的图像，并带有描述绘制内容的替代文本。

配方约定

框架阶段	效果职责
初始状态	无：<img> 就是初始状态。首屏上方的隐藏擦除效果使用框架的初始状态和截止时间。
引入	挂载后使用 imagePlane(image) 或视图配方；仅当引入效果依赖 ready 时才等待它；擦除或故障效果调用 enter()，变形效果调用 to()，液体效果调用 pour()。
稳定	悬停和波浪效果响应输入；没有活动平面或标签页处于隐藏状态时，舞台进入休眠。
结束	撤销悬停和波浪效果，然后调用擦除或故障效果的 exit()。
结束状态	平面继续绘制；由控制器决定下一步操作。
卸载	撤销效果，然后撤销平面和视图。最后一次释放会移除画布并释放上下文。

• 构建器绝不负责导航、挂载、订阅页面生命周期或决定何时运行。
• 每个构建器都会返回一个幂等的撤销函数。撤销时会释放其创建的所有程序、着色器、缓冲区、顶点数组和纹理，断开观察器，终止补间和触发器，移除监听器，恢复 uniform，并恢复图像的内联 opacity。
• 每个目标只由一个所有者负责：平面负责其图像的 opacity，视图负责其海报的 opacity，每个效果仅负责自己的 uniform。不要在同一图像的 opacity 或 transform 上同时使用平面或视图与 DOM 效果。
• Uniform 是可在上下文恢复后继续存在的普通 { value } 对象。使用 GSAP 和 overwrite 对它们进行补间；绝不要直接对 OGL 对象进行补间。
• 悬停会忽略触摸和触控笔，轻点后不会保持激活；键盘焦点会将镜头居中。飞行效果的倾斜和液体效果的拖尾只响应鼠标，手指则通过 touch 响应。波浪效果和飞行效果的滚动只响应滚动。没有任何效果会自行移动：变形效果的闪烁只在其形状范围内轻微变化几千分之一，拖尾则会逐渐淡出并静止，因此无需暂停控件。循环运行的 uSpin 或 uTravel 属于环境动态效果，需要提供暂停控件。