fx-presets

本文回答：fx 的 12 点预设 + 5 线预设 —— 各自效果、适合场景、选型指南。

一、12 点预设

所有点预设签名：fx.addPoint(name, opts) → handle。

二、通用字段

fx.addPoint('halo', {
  cad: [100, 200],         // 或 lngLat / mercator
  size: 80,                // 尺寸（默认 'map' 单位）
  sizeUnits: 'map',        // 'map' 跟随缩放 / 'pixels' 屏幕恒定
  color: [1, 0.5, 0, 1],   // RGBA 0~1
  params: [0, 1, 1, 0.5],  // [kind, p1, p2, p3]：槽 0 会被强制覆盖为预设 kind，只需关心 1..3
  bucket: 'above',         // 'below' / 'above' / 'topmost'
  visible: true,
  triggerOnce: false,      // 一次性
  ttl: 2000                // 一次性的生命周期（ms）
});

params[0] 是预设 kind——实现里会被强制覆盖为所选预设的 kind 值，传什么都被忽略；params[1..3] 才是可调参数（含义随预设变化）。注意 params 若传必须恰好是长度 4 的 vec4（SymbolFxImage.setParams/preset 校验长度，不对直接 throw）。

三、5 线预设

签名：fx.addLine(name, opts) → handle。

fx.addLine('flowLine', {
  path: { cad: [[x1, y1], [x2, y2], [x3, y3]] },  // FxPathInput：cad / lngLat / mercator 三选一
  width: 4,          // 线宽（widthUnits 默认 'pixels'）
  color: [0, 1, 1, 1],
  bucket: 'above'
});

四、Shadertoy 入口

3 个自定义入口：

// 三者都是单参数 opts 对象
fx.addShadertoy({ cad: [x, y], fragmentShader: 'void mainImage(...)...', size: 120 });
fx.addShadertoyLine({ path: { cad: [[x1,y1],[x2,y2]] }, fragmentShader: '...', width: 6 });
fx.addShadertoyFullscreen({ fragmentShader: '...' });   // 全屏 NDC 覆盖，不绑坐标

支持 5 种 alphaMode：premul / opaque / additive / luma / colorKey，用于和底图混合。

详见 vjmapext 的 fx shadertoy 文档（MCP mapext/docs/fx/shadertoy.md，入口 https://vjmap.com/server/aimcp/mcp?products=mapext）。

五、一次性触发

fx.addPoint('lightning', {
  cad: [x, y], size: 60,
  triggerOnce: true,
  ttl: 800          // 800ms 后自动移除
});

内建 lightning 和 firework 是"瞬发即灭"型；triggerOnce: true 跑完自动清理。

六、选型指南

数量

场景

七、CAD 实体绑定 FX

const circle = new vjmapext.CircleEnt([100, 200], 50);
mapcadLayer.addEntity(circle);

fx.bindToEntity(circle, 'pulseRing', {
  color: [1, 0, 0, 1],
  size: 60
});

// 实体动 → FX 跟随；实体删 → FX 自动清理

八、关掉不用的预设省 GPU

// 清空某预设在默认 'above' 桶的全部实例（replaceAllPoints 传空数组）
fx.replaceAllPoints('fire', []);
// 或整个 FX 层清空（所有预设所有 bucket）：fx.removeAll()

预设首次使用时编译 shader / 创建 buffer；不再用时可清零回收。没有 removeAllOfPreset——按预设清空用 replaceAllPoints(preset, [])，按句柄删单个用 fx.remove(handle)。

⚠️ replaceAllPoints 的限制（1.0.1）：

• 只动默认 above 桶：below/topmost 里的同预设实例不清；新列表里每项的 bucket 也被忽略，一律加进 above。
• 不走 addPoint 的语法糖：triggerOnce/ttl 自动移除、lightning 的 strikeEvery 都不生效。
• 它会重置该预设的槽位分配器——之前拿到的该预设句柄（含 bindToEntity 绑定的）全部失效，甚至可能与新点串号；有实体绑定的预设别用它整批替换。

九、色彩搭配建议

alpha 0.8~0.9 对光晕类效果自然；完全不透明会掩盖底图。

十、常见坑

1. params[0] 传了自定义值：无害但无效——实现会强制覆盖为预设 kind；要调效果改 p1/p2/p3（各预设含义不同）。
2. 颜色传 0~255：FX 要 0~1；传错没错误但色很淡。
3. sizeUnits 用 pixels 但 size 太大：屏占比大 → GPU 贵；用 map 跟随缩放。
4. 所有预设都 cinematic：卡；按重要度选档。
5. triggerOnce 但没 ttl：内建 lightning/firework 有默认 ttl；自定义没有 ttl 永不清理。
6. addLine 的坐标要包在 opts.path 里：addLine('flowLine', { cad: [[x1,y1],[x2,y2]] })（把 cad 写在 opts 顶层）会抛 Cannot read properties of undefined (reading 'lngLat')——校验器读的是 opts.path.cad。正确形态 addLine('flowLine', { path: { cad: [[...]] } })。
7. 校验报错是无条件的，并非只在 dev 抛出：fx.addPoint('not-a-preset', {cad}) 抛 [FX] unknown point preset，缺坐标（cad/lngLat/mercator 三选一都不给）、size<=0、非法 bucket、params 非 vec4 同样总是抛错——addPoint/addLine/addPoints 的 validatePointOptions/validateLineOptions 在调用链上不被环境门控。真正被 if(ht)（typeof process==="undefined" || NODE_ENV!=="production"）包裹的只是 addShadertoy/addShadertoyLine/addShadertoyFullscreen/setShadertoyUniforms 里的 mainImage 正则、resolution 等额外校验——而浏览器里 process 未定义使 ht 恒为 true，这些校验在 vite 产物中实际也总是执行。

相关

• FX 总览 → fx-overview
• 运行时调优 → fx-quality
• 大量点 → large-markers