填充图案

用共同图片资源和图片表达式绘制二维重复纹理

共同二维 fill 图层支持统一或逐要素 RGBA / SDF fill-pattern，分别用 commonFillPatternsUniform 和 commonFillPatternsPerFeature 判断。字符串直接选图；image 返回当前可用图片值，缺失返回实际 null，因此可以用 coalesce 回退。支持 case、match、词法 let/var，图片名称可由整数缩放级别或 global-state 选择。未使用的分支和回退不产生缺图通知。

import { map } from 'sqsmap';
const data = [];
for (let y = 0; y < 16; y++) for (let x = 0; x < 16; x++) {
  data.push(...(((x >> 3) ^ (y >> 3)) ? [0, 0, 255, 255] : [255, 0, 0, 255]));
}
map.addImage('checker', { width: 16, height: 16, data: new Uint8Array(data) }, { pixelRatio: 2 });
map.addSource('area', { type: 'geojson', data: {
  type: 'Feature', properties: {}, geometry: { type: 'Polygon', coordinates: [
    [[116.38, 39.88], [116.42, 39.88], [116.42, 39.92], [116.38, 39.92], [116.38, 39.88]]
  ] }
} });
map.addLayer({ id: 'pattern', type: 'fill', source: 'area', paint: {
  'fill-pattern': ['coalesce', ['image', 'primary'], ['image', 'checker']],
  'fill-opacity': 0.8
} });
map.jumpTo({ center: [116.4, 39.9], zoom: 13 });
await map.sqs.flush();

RGBA图案保持原始图片颜色，透明度乘 fill-opacity，不使用 fill-color 或轮廓颜色。周期为图片像素宽高除以 pixelRatio，以世界位置锚定并随地图旋转；上例的 16×16 图片形成 8×8 CSS 像素周期。更新、移除、补入图片、全局状态以及要素属性/状态变化会重新选择图案。同一图层中的不同面可选择不同图片，保持原始要素绘制顺序；缺图只隐藏使用它的要素，不隐藏其它可用要素。实际可见面尝试的缺失名称通过 styleimagemissing 通知；全部缺失时不绘制且没有对应渲染查询命中。

将 fill-pattern 设为 null 删除该属性，恢复原纯色和轮廓。查询按面及洞几何，不按纹理每个透明像素筛选。图片、数据源、图层变更在原生和 WASM 入口都先验证候选，失败保留旧状态和身份。

当前选中图片每边须为 2 至 512 的二次幂；本实现对所有选中图案严格检查此预算；MapLibre 规范也将这一尺寸范围用于无缝图案。图案过渡、线图案及三维/球面组合尚不支持，会明确报错。已有资源预算和表达式预算仍适用。移动应用、设备和正式发行保持独立待验收。

复制共同脚本 portable-fill-pattern.js，或运行完整网页。同一脚本在原生持续会话、网页主线程和普通地图 Worker 检查 16 项行为，并核对最终红蓝纹理及面洞。另见样式 API和缺失图片。

逐要素选择使用实际属性和 feature-state。未设置状态时，先在图片名称中回退，再调用 image；image(null) 不会被当作合法名称。

map.setPaintProperty('pattern', 'fill-pattern',
  ['image', ['coalesce', ['feature-state', 'tile'], ['get', 'tile']]]);
// 源中的每个面 properties.tile 为已经注册的图片名，并有稳定 id。
map.setFeatureState({ source: 'area', id: 7 }, { tile: 'checker' });
await map.sqs.flush();

属性、状态和图片候选在提交前逐要素预检；名称类型非法、SDF前景色非法或不符合当前尺寸预算时拒绝，保留旧源/状态/图案和身份。图案就绪要素按面与洞几何参与查询，缺图要素不命中。图片材质与图集代次随实际几何提交保持一致。

25条逐要素共同脚本与完整网页提供同层双面、洞/相交、属性/状态选择、图片生命周期和失败恢复的可运行代码。原始16条统一图案脚本仍保留；原先逐要素不可用的历史拒绝检查已改为非法图片参数检查。

图案候选的共同预算为累计10万显示要素，以及表达式结构节点数乘显示要素数的累计200万估算（包含选中SDF的前景色/opacity表达式）；超出以 RESOURCE_LIMIT 拒绝，不部分提交。每要素求值继续使用既有表达式预算。

SDF图案通过 addImage(name, image, {sdf: true}) 登记，以图片alpha通道表示距离：0.5为边界，较大值为前景，使用图块内部循环插值与屏幕导数抗锯齿。commonFillPatternsSdf 表示此能力。图片RGB不参与SDF着色，fill-color 是前景色（默认黑色），前景alpha与 fill-opacity 相乘；按属性和要素状态动态着色与既有表达式一致。RGBA图案仍忽略 fill-color。透明SDF前景/零opacity不进入渲染查询，查询仍不逐纹理透明像素拾取。

map.addImage('mask', {width:8, height:8,
  data:new Uint8Array(Array.from({length:64},()=>[0,0,0,255]).flat())}, {sdf:true});
map.setPaintProperty('pattern', 'fill-pattern', 'mask');
map.setPaintProperty('pattern', 'fill-color',
  ['coalesce', ['feature-state','tone'], ['get','tone']]);
await map.sqs.flush({render:true});

这是SqsMap自研实现，语义参考 MapLibre fill-color规范。该规范当前的GL JS与Native支持表仍将SDF图案着色列为未支持，因此这里不宣称与MapLibre渲染结果逐像素兼容。

24条SDF共同脚本与完整网页展示同一mask双色、透明与opacity、RGBA切换、图片更新及严格失败恢复。