XLPano 全景引擎
介绍
XLPano 是一个基于 Typescript 的轻量的全景开源库。使用 WebGL1.0 实现，同时支持立方体场景和球体场景。
示例地址
https://breeze-blowing.github.io/xlpano/index.html
安装
本库提供了直接使用 <scrpit> 标签引入方式和 npm 包两种方式
标签引入
<script src="xlpano.min.js"></script>
npm 安装
npm install xl-pano --save 或者 yarn add xl-pano
使用
本库提供了四个关键的类，完成全景的搭建。
- 引入 Pano, CubeScene(立方体场景，六面体贴图), SphereScene(球体场景，长宽2:1贴图), HotSpot
// 全局变量方式引入
const { Pano, CubeScene, SphereScene, HotSpot } = window.XLPano;
// ESM 方式引入
import { Pano, CubeScene, SphereScene, HotSpot } from 'xl-pano';
// CommonJS 方式引入
const { Pano, CubeScene, HotSpot } = require('xl-pano');
- 构建全景
// 创建 pano，containerId 是容器 dom 节点的 id
const pano = new Pano('containerId');
// 创建 CubeScene，立方体贴图按照[前, 右, 上, 左, 下, 后]的顺序添加
const cubeScene = new CubeScene([f, r, u, l, d, b]);
// 创建 hotSpot，传入热点元素，目标场景索引，俯仰角，偏航角
const hotSpot = new HotSpot(HtmlElement, 1, { pitch: -10, yaw: 55 });
// 创建 SphereScene，传入宽高2:1场景贴图
const sphereScene = new SphereScene(image);
// scene 添加 hotSpot
cubeScene.addHotSpots(hotSpot);
// pano 添加 scene
pano.addScene(cubeScene);
pano.addScene(sphereScene);
// 渲染整个 pano
pano.render();
完整示例查看 /example 目录
特别注意
- 本库使用 WebGL1.0 实现，场景贴图的宽高尺寸值必须是2的n次幂
- 本库没有做降级处理，对于不支持 WebGL1.0 的浏览器，无法使用本库
文档
Pano
一个全景能包含多个场景，Pano 作为整个全景的管理者，管理所有的场景，控制着场景的切换。
构造函数
const pano = new Pano('containerId');
| 参数名 | 说明 | 类型 | 必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| id | 容器 id | string | 是 | - | - |
| debug | 是否开启 debug | boolean | 否 | false | WebGL相关方法发生的错误并不会直接抛出来，难以定位问题；开启 debug 会打印这些错误；生产环境请关闭 debug |
实例方法
-
addScene
-
说明：添加场景，场景是承载画面的实例，被添加进 pano 的场景才能显示，具体内容看
Scene文档 -
接口：(scene: Scene) => void
-
参数：
参数名 说明 类型 必填 备注 scene 场景实例 Scene 是 Scene是接口，具体使用CubeScene或者SphereScene -
返回值：无
-
-
render
- 说明：渲染全景，执行该方法发后在页面显示全景。在执行 render 前请先添加好场景。
- 接口：() => void
- 参数：无
- 返回值：无
-
setScene
-
说明：通过该方法，能任意设置当前场景，前提是被设置的场景已经通过
addScene方法被添加到 pano 中了。 -
接口：(scene: scene: Scene | number) => void
-
参数：
参数名 说明 类型 必填 备注 scene 场景实例或者场景索引 Scene 或 number 是 索引是场景被添加到 pano 的顺序值 -
返回值：无
-
-
getCurrentScene
- 说明：获取当前场景实例
- 接口：() => Scene
- 参数：无
- 返回值：当前场景实例
-
addListener
-
说明：添加监听函数
-
接口：(type: ListenerType, callback: ListenerCallback) => void
-
参数：
参数名 说明 类型 必填 备注 type 事件类型 ListenerType 是 sceneChangecallback 回调函数 ListenerCallback 是 SceneChangeCallback -
SceneChangeCallback 方法
-
场景变化回调函数，
type === 'sceneChange'被执行 -
接口：(scene: Scene, index: number) => void
-
回调参数：
参数名 说明 类型 备注 scene 场景实例 Scene 变化后的场景实例 index 场景索引 number 索引是场景被添加到 pano 的顺序值
-
-
-
removeListener
-
说明：移除监听函数
-
接口：(type: ListenerType, callback: ListenerCallback) => void
-
参数：
参数名 说明 类型 必填 可选值 备注 type 事件类型 ListenerType 是 sceneChange目前只有场景变换一种事件类型 callback 回调函数引用 ListenerCallback 是 SceneChangeCallbackaddListener传入方法的引用
-
-
removeAllListeners
- 说明：移除所有监听，一般在销毁的时候调用
- 接口：() => void
- 参数：无
- 返回值：无
Scene
Scene (场景)是真正渲染画面的载体；Scene 本身是一个接口，不能直接实例化使用。
本库提供了 CubeScene (立方体场景) 和 SphereScene (球体场景) 两种场景。
CubeScene 和 SphereScene 相同的实例方法
-
addHotSpots
-
说明：添加热点，热点是附着在场景上的 dom 节点，具体内容看
HotSpot文档 -
接口：(hotSpots: HotSpot | HotSpot[]) => void
-
参数：
参数名 说明 类型 必填 备注 hotSpots 热点实例 HotSpot 或 HotSpot[] 是 可以添加单个热点或热点数组 -
返回值：无
-
-
addListener
-
说明：添加监听函数
-
接口：(type: SceneListenerType, callback: SceneListenerCallback) => void
-
参数：
参数名 说明 类型 必填 可选值 备注 type 事件类型 SceneListenerType 是 angleChange目前只有角度变换一种事件类型 callback 回调函数 SceneListenerCallback 是 SceneAngleChangeCallback方法参数见下面文档 -
SceneAngleChangeCallback 方法
-
场景变化回调函数，
type === 'angleChange'被执行 -
接口：(angle: SceneAngle) => void
-
回调参数：
参数名 说明 类型 备注 angle 场景角度 SceneAngle 变化后的角度，具体看上面 SceneAngle文档
-
-
-
removeListener
-
说明：移除监听函数
-
接口：type: SceneListenerType, callback: SceneListenerCallback) => void
-
参数：
参数名 说明 类型 必填 可选值 备注 type 事件类型 SceneListenerType 是 angleChange目前只有角度变换一种事件类型 callback 回调函数引用 SceneListenerCallback 是 SceneAngleChangeCallbackaddListener传入方法的引用
-
-
removeAllListeners
- 说明：移除所有监听，一般在销毁的时候调用
- 接口：() => void
- 参数：无
- 返回值：无
-
getAngle
- 说明：获取当前角度
- 接口：() => SceneAngle
- 参数：无
- 返回值：场景角度，类型参考下面
SceneAngle文档
-
setAngle
-
说明：设置场景角度
-
接口：(angle: SceneAngle, options?: { animation?: boolean, duration?: number, callback?: VoidFunction}) => void
-
参数：
参数名 说明 类型 必填 默认值 备注 angle 场景角度 SceneAngle 是 - 类型参考下面 SceneAngle文档options 可选参数 参考下面文档 否 { animation: false, duration: 500, callback: () => {} } - -
options 可选参数：
参数名 说明 类型 必填 默认值 备注 animation 切换过程是否需要动画 boolean 否 false - duration 动画执行时间 number 否 500 毫秒 callback 切换完场景后的回调函数 VoidFunction 否 - -
-
-
getFovy
- 说明：获取视角范围
- 接口：() => number
- 参数：无
- 返回值：视角范围
-
setFovy
-
说明：设置视角范围，增大会有离远的视觉效果，减小会有走近的视觉效果
-
接口：(fovy: number, options?: { animation?: boolean, duration?: number, callback?: VoidFunction}) => void
-
参数：
参数名 说明 类型 必填 默认值 备注 fovy 视角范围 number 是 - 小于 180 options 可选参数 参考 setAngle 的 options 参数 否 { animation: false, duration: 500, callback: () => {} } -
-
CubeScene 单独接口
立方体场景，也称天空盒，需要前后左右上下六张贴图构建场景。
构造函数
const cubeScene = new CubeScene([f, r, u, l, d, b], { yaw: 50, pitch: 20 });
| 参数名 | 说明 | 类型 | 必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| textures | 贴图数组 | TextureSource[] | 是 | - | 六个面的贴图，需按照 前-右-上-左-下-后 的顺序；类型详细说明见 TextureSource 文档 |
| defaultAngle | 初始角度 | SceneAngle | 否 | { yaw: 0, pitch: 0 } | 类型详细说明见 SceneAngle 文档 |
- TextureSource 贴图资源：可以是网络资源链接地址，也可以是
TexImageSource对象。通过new Image()可以实例化一个TexImageSource对象；在使用TexImageSource对象实例化CubeScene对象前，请先确保TexImageSource的图片资源已经加载完成。 - SceneAngle 场景角度：有两个属性，pitch(俯仰角) 和 yaw(偏航角)。对于全景而言，俯仰角一般在 [-90, 90] 度范围之间；偏航角理论上可以无限的旋转， 但是为了方便理解，本库会默认将偏航角转换到 [0, 360) 度的范围
实例方法
- replaceTextures
- 说明：替换贴图
- 接口：(textures: TextureSource[]) => void
- 参数：参考构造函数中的 textures 参数
- 返回值：无
SphereScene 单独接口
球体场景，仅需要一张宽高长度比 2:1 的贴图即可构建场景。
构造函数
const scene = new SphereScene(sphereImg, { yaw: 80, pitch: 10 });
| 参数名 | 说明 | 类型 | 必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| texture | 贴图 | TextureSource | 是 | - | 需要宽高比2:1的贴图，TextureSource 具体参考上面文档 |
| defaultAngle | 初始角度 | SceneAngle | 否 | { yaw: 0, pitch: 0 } | 类型详细说明见 SceneAngle 文档 |
实例方法
- replaceTextures
- 说明：替换贴图
- 接口：(texture: TextureSource) => void
- 参数：参考构造函数中的 texture 参数
- 返回值：无
关于 Scene 的 replaceTextures 接口
- CubeScene 和 SphereScene 都有 replaceTextures 方法，参数类型相同；只不过 CubeScene 需要六张图，SphereScene 只需要一张图
- 因为本库没有提供单独的资源加载接口，资源加载是在 render 阶段执行的，加载完资源后才真正绘制场景，因此直接使用高清网络资源图会出现白屏现象。 可以在 Scene 的构造函数中使用低清缩略图来加速首屏显示，然后同时加载高清资源图，加载完成后使用 replaceTextures 替换首屏贴图
- 同时 XLPano 库内部会对非首个场景的网络资源图有预加载机制，所以在切换场景时，一般不会存在白屏问题
HotSpot
热点是附着在场景上的 dom 节点，会跟随场景转动，还内置了被点击切换场景的功能
构造函数
const hotSpot = HotSpot(dom, { pitch: -10, yaw: 10, target: 1 });
| 参数名 | 说明 | 类型 | 必填 | 默认值 | 备注 |
|---|---|---|---|---|---|
| dom | dom对象 | HTMLElement | 是 | - | 热点本质是一个dom对象，需要自己构建后传入构造函数 |
| option | 可选参数 | 参考下面文档 | 否 | { yaw: 0, pitch: 0 } | 参考下面文档 |
- option 参数：有 yaw、pitch 和 target 三个属性，都是可选属性
- yaw 和 pitch 分别为初始偏航角和初始俯仰角，可参考上面 SceneAngle 的定义
- yaw 和 pitch 的初始值是相对于 scene 的偏航角和俯仰角都是 0 的基础的；若添加热点的时候，场景有默认角度，则首次渲染热点的时候会添加场景的默认角度
- target 表示目标场景索引，如果传入了该属性，且目标场景存在，则点击该热点，会切换到目标场景
- 如果不传 target 属性，库不会对热点做任何默认操作，你可以对 dom 做自定义操作