@ericchen1990/pano-view 3.2.3 → 3.4.0

package/README.md

@@ -702,11 +702,14 @@ a single non-stereo cube panorama.
 
 ## Scenes
 
-`Scenes` switches controlled sphere and cube-tile scenes with GPU-only
-snapshot blending. The target scene loads its sphere or tile preview first;
-once ready, the current framebuffer becomes a temporary GPU texture, its source
-textures are released, and the target scene blends in. This avoids holding two
-high-resolution tile scenes in WebGL memory at once.
+`Scenes` switches controlled sphere, cube-tile, and equirectangular-tile scenes with GPU-only
+snapshot blending. The incoming scene stays hidden while it preloads its preview and base
+tiles. Once that preview can be drawn, the current framebuffer becomes a temporary GPU
+texture and the outgoing source textures are released. The incoming scene then switches to
+full detail immediately: tiles that are already sharp replace the preview during the blend,
+and tiles that are still loading keep the coarser parent tile or the preview. The viewer
+does not keep two high-resolution tile sets resident, and it does not preload tiles outside
+the current view.
 
 ```tsx
 import {
@@ -749,7 +752,25 @@ GPU framebuffer snapshot over the incoming panorama; they do not mix two full
 360 textures. Pass `{ preset: "crossfade", duration: 0.6 }` to override a
 preset duration.
 
-While a transition runs, panorama drag/zoom input is locked and
+`transitionWaitForDetailMs` defaults to `0`. The blend starts as soon as the incoming
+scene can paint, and detail keeps loading during that blend. A positive value such as
+`200` starts only after the outgoing snapshot is stored and the incoming scene is in
+`full`. The blend starts early when the current view is already sharp, and otherwise
+waits at most that many milliseconds. This wait is timed separately from the blend
+duration. During the wait the outgoing snapshot stays fully visible while the incoming
+scene draws and uploads underneath. For a normal `Sphere`, sharp means the full image
+can be drawn. For cube and sphere tiles, sharp means every in-view tile at the level
+chosen from viewport size, device pixel ratio, field of view, and the existing memory
+budget can be drawn. Tiles outside the view are not required. Negative and non-finite
+values are treated as `0`. `transition="none"` uses the same condition and then cuts
+over directly. A new target, an interrupt, unmount, or a lost WebGL context cancels a
+pending wait so a stale readiness report cannot affect the next scene.
+
+`onReady` still means a source can paint for the first time. `onSceneReady` still fires
+for the first paintable scene and when an incoming scene takes over after the outgoing
+snapshot. It does not mean the current view's full detail has finished loading.
+
+While a detail wait or transition runs, panorama drag/zoom input is locked and
 `renderHotspots` is hidden. New `activeSceneId` values supersede a target that
 is still being prepared. `maxTextureMemoryMb` and `maxConcurrentTileLoads`
 apply to the whole `Scenes` viewer rather than to each tile scene.
@@ -1834,8 +1855,43 @@ if the preview failed. `onPreviewError`, `onTileError`, `onLoadProgress`, and
 `onLevelChange` expose failures/progress; levels in callbacks start at 0.
 Unmounting disposes owned textures and ignores late results.
 
-Use `SphereTile` directly as a `PanoViewer` child; `Scenes` currently accepts
-`sphere` and cube `tile` definitions only.
+Use `SphereTile` directly as a `PanoViewer` child, or define a `SphereTileScene`
+with `type: "sphereTile"` inside `Scenes`. All transition presets, including
+`dissolve`, work across `sphere`, cube `tile`, and `sphereTile` scenes:
+
+```tsx
+import { Scenes, type Scene } from "@ericchen1990/pano-view";
+
+const scenes: Scene[] = [
+  {
+    id: "courtyard",
+    type: "sphereTile",
+    baseUrl: "/panoramas/courtyard/",
+    multires: "512,500x250,1000x500,2000x1000",
+    previewUrl: "previews/400.webp",
+    urlTemplate: "tiles/%l/%h_%v.webp",
+    indexBase: 1,
+  },
+  // Add sphere, tile, or other sphereTile scenes here.
+];
+
+<Scenes scenes={scenes} activeSceneId={activeSceneId} transition="dissolve" />;
+```
+
+`onSceneReady(sceneId)` fires when the first scene becomes paintable and when an
+incoming scene takes over after the outgoing snapshot is captured. The transition
+may still be running; use this callback to apply the incoming camera view without
+changing the outgoing snapshot. Full detail loads after that handoff, including during
+the blend. `transitionWaitForDetailMs` can hold the outgoing snapshot until the current
+view is sharp; it does not change when `onSceneReady` fires. `onTransitionEnd` marks
+completion of the blend.
+
+`SphereTileScene` accepts the source options of `SphereTile`, including
+`indexBase`, `resolveTileUrl`, and `yawOffset`. `Scenes` owns visibility,
+preloading, readiness, and transitions. Use `onTransitionEnd` and
+`onTransitionError` on `Scenes`; its shared texture budget and request limit
+apply to both cube and equirectangular tiles. Standalone `SphereTile` retains
+its own cache, callbacks, and loading options.
 
 ## Accessibility matrices and tooltip typography
 

package/README.zh-CN.md

@@ -637,7 +637,7 @@ MAKE PANO (MULTIRES) 文件夹布局常为 `tiles/%s/l%l/%v/l%l_%s_%v_%h.jpg`，
 
 ## Scenes
 
-`Scenes` 在受控的球面与立方体 tile 场景之间切换，采用纯 GPU 快照混合。目标场景先加载其球面或 tile 预览；就绪后，当前帧缓冲成为临时 GPU 纹理，释放其源纹理，目标场景再混合进入。这样避免在 WebGL 内存中同时持有两个高分辨率 tile 场景。
+`Scenes` 在受控的普通球面、立方体瓦片与球面多级瓦片场景之间切换，采用纯 GPU 快照混合。目标场景在隐藏状态下预加载预览和基础层。预览可绘制后，当前帧缓冲成为临时 GPU 纹理，并释放旧场景的源纹理。目标随即进入 `full`：转场期间已经清晰的瓦片立刻盖住预览，尚未就绪的区域继续显示父层瓦片或预览。查看器不会同时保留两套高清瓦片，也不会预加载当前视野之外的瓦片。
 
 ```tsx
 import {
@@ -671,7 +671,11 @@ const scenes: Scene[] = [
 
 可用的 KRpano 风格预设包括 `none`、`crossfade`、`zoom`、`blackout`、`whiteFlash`、`slideRightToLeft`、`slideTopToBottom`、`slideDiagonal`、`circleOpen`、`verticalOpen`、`horizontalOpen`、`ellipticZoomOpen`。网格类预设为 `pixelate`、`gridWipe`、`gridWipeUp`、`gridWipeRight`、`gridWipeDiagonal`、`gridWipeCenter`、`gridWipeChecker`、`hexDissolve`。电影感预设为 `dissolve`、`shatter`、`particles`、`glitch`、`swirl`、`clockWipe`、`ripple`、`zoomBlur`、`filmBurn`。它们均在入画全景之上混合 GPU 帧缓冲快照，不会混合两个完整 360 纹理。传 `{ preset: "crossfade", duration: 0.6 }` 可覆盖预设时长。
 
-过渡进行时，全景拖拽/缩放输入被锁定，`renderHotspots` 被隐藏。新的 `activeSceneId` 会取代仍在准备中的目标。`maxTextureMemoryMb` 与 `maxConcurrentTileLoads` 作用于整个 `Scenes` 查看器，而非每个 tile 场景单独计算。
+`transitionWaitForDetailMs` 默认为 `0`：目标一旦可绘制就开始转场，高清在转场期间继续加载。正数（例如 `200`）从旧画面快照完成、目标进入 `full` 之后开始计时；当前视野已经清晰就提前转场，否则最多再等待指定毫秒。该等待与转场动画时长分开计算。等待期间完整显示旧快照，目标在其下正常绘制并上传纹理。普通球面的“清晰”指完整图片可绘制；立方体和球面瓦片指按视口尺寸、设备像素比、FOV 和现有内存预算选出的当前视野目标层级全部可绘制，不要求视野外瓦片。负值或非有限值按 `0` 处理。`transition="none"` 使用同一条件，满足后直接切换。新的目标、中断、卸载或 WebGL 上下文丢失会取消尚未结束的等待，避免过期的就绪通知影响下一个场景。
+
+`onReady` 仍表示源第一次可绘制。`onSceneReady` 仍在首个场景可绘制，或旧画面快照完成且新场景接管时触发，并不表示当前视野的高清已经到齐。
+
+清晰等待或转场进行时，全景拖拽/缩放输入被锁定，`renderHotspots` 被隐藏。新的 `activeSceneId` 会取代仍在准备中的目标。`maxTextureMemoryMb` 与 `maxConcurrentTileLoads` 作用于整个 `Scenes` 查看器，而非每个 tile 场景单独计算。
 
 ## PanoFilter
 
@@ -1529,8 +1533,40 @@ import { PanoViewer, SphereTile } from "@ericchen1990/pano-view";
 `onLoadProgress`、`onLevelChange` 提供；回调中的层级同样从 0 开始。
 卸载时释放组件纹理，丢弃迟到的加载结果。
 
-将 `SphereTile` 直接放在 `PanoViewer` 下；当前 `Scenes` 仍只接受 `sphere` 和立方体
-`tile` 场景定义。
+可以将 `SphereTile` 直接放在 `PanoViewer` 下，也可以在 `Scenes` 中使用
+`type: "sphereTile"` 的 `SphereTileScene`。所有过渡预设（包括 `dissolve`）均支持
+`sphere`、立方体 `tile` 和球面多级瓦片 `sphereTile` 之间的切换：
+
+```tsx
+import { Scenes, type Scene } from "@ericchen1990/pano-view";
+
+const scenes: Scene[] = [
+  {
+    id: "courtyard",
+    type: "sphereTile",
+    baseUrl: "/panoramas/courtyard/",
+    multires: "512,500x250,1000x500,2000x1000",
+    previewUrl: "previews/400.webp",
+    urlTemplate: "tiles/%l/%h_%v.webp",
+    indexBase: 1,
+  },
+  // 在此添加 sphere、tile 或其他 sphereTile 场景。
+];
+
+<Scenes scenes={scenes} activeSceneId={activeSceneId} transition="dissolve" />;
+```
+
+`onSceneReady(sceneId)` 在首个场景可绘制、或旧画面截图完成且新场景接管时触发。
+此时过渡可能仍在进行，可在该回调中设置新场景视角而不改变旧画面快照。
+高清在这次交接之后加载，转场期间也会继续加载。`transitionWaitForDetailMs`
+可以让旧快照多停留到当前视野清晰，但不会改变 `onSceneReady` 的触发时机。
+`onTransitionEnd` 表示混合效果播放完成。
+
+`SphereTileScene` 保留 `SphereTile` 的资源选项，包括 `indexBase`、`resolveTileUrl`
+和 `yawOffset`。可见性、预加载、就绪判断与过渡由 `Scenes` 管理；通过其
+`onTransitionEnd` 和 `onTransitionError` 接收结果。`Scenes` 的共享纹理预算与请求
+并发上限同时作用于立方体和球面瓦片。独立使用的 `SphereTile` 仍保留原有缓存、
+回调与加载选项。
 
 ## 无障碍颜色矩阵与标签排版