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

使用

本库提供了四个关键的类，完成全景的搭建。

1. 引入 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');

2. 构建全景

// 创建 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 | 是 | sceneChange | 目前只有场景变换一种事件类型 | | callback | 回调函数 | 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 | 是 | SceneChangeCallback | addListener 传入方法的引用 |

• 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 | 是 | SceneAngleChangeCallback | addListener 传入方法的引用 |

• 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 做自定义操作