平面相机 API

动态库、WASM 和浏览器 SDK 共用的实时相机接口与当前支持边界。

开发原生会话现已支持共同非零平面 pitch，完整脚本、能力范围及真实像素验收见原生倾斜地图。匹配 WASM/主线程/严格 Worker 也已接通，见网页倾斜地图；桌面共同适配已接通，见桌面倾斜地图。

本页对应 SQSAPI-06.2/06.3 的开发源码。共享计算已接入真实地图会话、C ABI、WASM 和浏览器 SDK；不是旧 npm 包已经升级的声明。桌面调试板与本地网页工作台的 sqsmap 门面已接入共同二维调用。应用脚本仍须保留 project.read / map.write 权限头；下列调用写法一致。

接口名称和参数写法参考 MapLibre Map API。计算、默认值和错误由共享核心实现，不使用 MapLibre 代码。与 MapLibre 的必要区别：独立原生库及 SDK 的权威查询返回 Promise，使用 await；写方法返回地图，可链式调用，flush 用于确认。浏览器主线程与 Worker 使用同一写法。

方法与单位

方法	参数或返回	当前范围
`getCenter()`	`{ lng, lat }`	WGS84，经度可明确选择世界副本
`getZoom()`	数值	512 个逻辑像素的世界缩放约定
`getBearing()`	数值	顺时针角度，归一化到 [-180, 180)
`getPitch()`	角度	原生/WASM/主线程/严格Worker墨卡托与球面为0–65度；geographic暂限0；桌面墨卡托也支持0–65度，见地球仪 API
`getPadding()`	`{ top, right, bottom, left }`	非负逻辑像素
`getBounds()`	`[[west,south],[east,north]]`	包含旋转后全部视口角点
`getProjection()`	`{ type }`	共同接口支持 geographic、mercator、globe，见地球仪 API
`project(position)`	`{ x, y }`	接受 `[lng,lat]` 或 `{lng,lat}`，返回逻辑屏幕像素
`unproject(point)`	`{ lng, lat }`	接受 `[x,y]` 或 `{x,y}`；超出地面纬度明确报错
`jumpTo(options)`	地图	可设置 center、zoom、bearing、pitch、roll、padding；未知参数拒绝
`fitBounds(bounds, options?)`	地图	可用四数范围或两端点；跨日期变更线 east < west
`cameraForBounds(bounds, options?)`	相机姿态	只计算，不修改地图，也不提交写命令
`setCenter/setZoom/setBearing/setPitch/setPadding`	地图	单项设置复用同一完整校验与应用路径
`resetNorth/zoomIn/zoomOut`	地图	回正、缩放一级；保持有边距的相机中心

padding 可为统一数值或只包含部分边的对象，未提供的边为零。没有设置 padding 时保留当前值；宽高必须大于边距总和。缩小视口导致现有边距无效时清除边距，保留已经显示的原始视图，并通过视图/resize 通知可观察。

fitBounds 的选项为 padding、offset、bearing、minZoom、maxZoom、animate、duration、linear。默认计算缩放范围为 0～24；同名选项由共享实现校验。当前已接通相机动画：默认平滑移动 300 毫秒，animate:false 或 duration:0 立即定位；linear:true 使用线性进度。flush 确认应用或下一帧，不表示动画已经结束。

所有输入在修改前完成校验。几何计算使用双精度；渲染器 scale 和着色器仍有单精度边界，因此不得把数学误差指标等同于任意设备的像素精度。原生相机查询输出当前物理视口；本阶段原生离屏图使用 DPR=1，WASM 边界按实际 DPR 换算。旧直接 WASM setView/view 仍为 canvas 像素兼容入口；新 SDK 的 setView/getView 已使用共享逻辑像素约定。详见相机计算。

浏览器 SDK

使用同一提交生成的 JS、Worker、WASM 和声明。/example 的已发布 npm 依赖不会因开发源码更新而获得本页接口。

// view 为 MapView.create(...) 创建的同版本地图。
view.jumpTo({ center: [116.4, 39.9], zoom: 8, bearing: 30,
  padding: { left: 240 } }).setZoom(9);
await view.flush({ render: true });
const center = await view.getCenter();
const pixel = await view.project(center);
const position = await view.unproject(pixel);
view.fitBounds([[170, -10], [-170, 10]], { padding: 40, animate: false });
await view.flush();
console.log(await view.cameraState(), position);

新相机写入口经过主线程/Worker 的同一命令日志；权威查询不会绕过写命令预算去偷偷修改视图。查询请求按实际接收顺序执行，flush 水位用于明确确认。帧和回执可附带 publicCamera，原始相机数据继续保留；比例尺和视图状态读取有边距的中心。

原生动态库与脚本

高层 ABI 保持版本 1，通过 sqsm_map_runtime_flags() & SQSM_MAP_PLANAR_CAMERA 判断新增能力（位值 16）。独立纯地图库也提供相机 C 入口，QuickJS 仍是可选 feature。

sqsm_map_bytes_t out = { NULL, 0, 0 };
const char *request = "{\"method\":\"jumpTo\",\"args\":[{\"center\":[116.4,39.9],\"zoom\":8}]}";
int32_t status = sqsm_map_camera_json(map,
  (const uint8_t *)request, strlen(request), &out);
if (status == SQSM_MAP_OK) sqsm_map_bytes_free(out.allocation);

请求包含且只包含 method 字符串与 args 数组，上限 64 KiB。读返回 JSON 数据；写返回 JSON null，写操作进入共享确认日志。沿用创建线程、失效句柄、错误和输出缓冲区规则；失败会清空输出，不承诺回滚先前已确认修改。调用方仍须检查每个状态并释放每个成功输出。

完整 C 主机、完整原生脚本、原生类型声明。完整脚本在同一原生库的一次性和持续会话中运行。原生权威相机组合快照用 map.sqs.cameraState()；浏览器 SDK 使用 view.cameraState()。

已验证与待验证

Linux NVIDIA GeForce RTX 4060 / Vulkan 的真实 C、QuickJS 一次性/持续入口验证了坐标往返、有边距的中心、原子参数拒绝、日期变更线、失败日志与恢复、新渲染回执和真实多边形像素。C11 主机、C++17 头文件、共享数学、依赖边界、两套匹配 WASM、SDK 类型和官网文档检查记录在任务清单。

球面即时相机、投影切换、软件 GPU 与网页主线程/Worker 已在14.1单独验证，见地球仪 API。球面动画与锚点已接通；Windows/macOS 外机和移动宿主仍需后续验收或实现。

06.3 的桌面空白底图暂不能将带边距的原始焦点移出墨卡托南北界限；GIS 专用坐标系与平面三维视图有专有接口；球面使用共同球面模型，不以二维计算冒充。相机查询等候此前共同相机写入，可使用真正的 Promise 方法。写入失败不会因省略 flush 而被隐藏；需要恢复时捕获失败水位并显式使用 flush({since})。完整应用示例见共同地图门面。

原生样式与资源宿主：动态库新增 set_style_json、请求轮询与响应回传；可选原生脚本支持链式 map.setStyle(url, {diff:false}) 和 sqs.resourceschange。样式开启时显示投影为墨卡托，清空后为 geographic；共同样式门面已见样式脚本；共同 setProjection({type}) 已接通，支持边界见地球仪 API。

独立 SDK 同步快照与旧接口：缓存相机、倾角与 CSS 地面比例，以及兼容状态读取。

原生 Rust 显示密度：逻辑输入、真实物理纹理与共同相机绑定。