Persistent globe padding
map.setPadding(value), map.jumpTo({padding: value}), and await map.getPadding() use logical pixels. A number applies to all edges; an object accepts top/right/bottom/left, with omitted edges defaulting to0. Each edge must be finite and nonnegative; horizontal/vertical sums must remain below viewport width/height. Invalid writes or viewport reductions preserve the previous state.
import {map} from 'sqsmap';
map.setProjection({type: 'globe'});
map.jumpTo({center: [116.4, 39.9], zoom: 5, pitch: 25, roll: 15});
map.setPadding({left: 300, top: 40});
await map.sqs.flush();
console.log(await map.getPadding());
const end = map.once('moveend');
map.easeTo({padding: {left: 0, top: 40}, duration: 600});
await map.sqs.flush();
await end;
Padding projects the geographic center to the viewport midpoint plus [(left-right)/2, (top-bottom)/2]. Immediate changes preserve center, zoom, bearing, pitch, roll, eye position, and orthogonal lighting axes. Surface projection/inverse rays, original line/fill geometry, circles, bounds, scale, tile coverage, scene rendering and queries share this principal point. The browser SDK's synchronous screenToLngLat follows the same calculation.
easeTo/flyTo interpolate the four edges; around anchors continue to use actual spherical rays. Padding changes emit the move lifecycle and historical snapshots, without a separate padding event. Planar/globe transitions preserve padding. cameraForBounds/fitBounds use current persistent padding when omitted; explicit option padding constrains that target only and leaves the persistent value unchanged. Use setPadding for persistent changes.
globePadding: true reports connected calculations. Native calls use existing sqsm_map_camera_json; ABI version1 and exports are unchanged. Explicit Rust constructors must include GlobeCamera.padding: Default::default() and SceneCamera.screen_offset: [0.; 2]. Desktop scripts use the common facade. Linux software GPU and browser main thread/Worker verify the same10 script checks and actual blue fill pixels at DPR1/2; native also checks4 rejected writes/viewport changes without mutation. The direct scene shader is checked at both densities. Windows/macOS and mobile devices need separate acceptance.