RichSurface

RichSurface 是 3D 场景中的一个可交互部件，可在上面设置多媒体资源，SDK 内置的功能包括视频源、静态贴图、呼吸点、文本板。也是继承自 actor

Richsurface 由两个部分组成，一个是模型(Mesh)，一个是媒体资源(mediaSource)。通过特定接口，可以给模型设定任意符合规范的媒体资源。

模型部分

实例化 RichSurface 和其他 Actor 一致。

import { RichSurface } from '@xverse/core'
const surface = world.spawn(RichSurface)

模型和媒体资源初始化

可以通过 create 方法，初始化一个任意媒体类型的 RichSurface ，指定模型类型和配置参数之后，create 方法内部会生成对应类型的媒体资源，并设置到一个新建的 richsurface 模型上。

媒体资源全部继承自基类XMediaSource，目前实现的媒体资源包括

媒体资源	说明
XVideoSource	视频类媒体资源
XStaticTextureSource	静态图资源
XTextSource	文本资源
XSpriteImgSource	精灵图资源

下面代码描述了生成一个静态图资源，并设置到一个 richsurface 模型上的过程

//EMediaSourceType 包括上述四种资源类型
import { RichSurface, EMediaSourceType } from '@xverse/core'

const surface = world.spawn(RichSurface)

//richsurface需要挂载的模型
const addMeshOption = {
  defaultMeshOption: {
    type: EDefaultMeshType.Plane,
    position: point?.point.position,
    rotation: point?.point.rotation,
    width: 2 * 100,
    height: 2 * 100,
  },
}

//richsurface挂载的富媒体资源
const media = 'https://static.xverse.cn/playground/demo.jpg'

//媒体参数
const mediaOptions = {
  fps: fps,
  lifeTime: lifeTime,
  spriteWidthNumber: spriteWidthNumber,
  spriteHeightNumber: spriteHeightNumber,
}

surface.create({
  type: EMediaSourceType.XStaticTextureSource,
  mediaData: media,
  addMeshOption,
  mediaOptions,
  billboardMode: EBillboardMode.All,
})

改变 richsurface 绑定的媒体资源及其内容

import { RichSurface,EMediaSourceType} from '@xverse/core'

const surface = world.spawn(RichSurface)
surface.create(...)

//richsurface挂载的富媒体资源
const media = 'https://static.xverse.cn/playground/demo.jpg'
//媒体资源参数
const options = {
    mediaOptions: {
        fps: fps,
        lifeTime: lifeTime,
        spriteWidthNumber: spriteWidthNumber,
        spriteHeightNumber: spriteHeightNumber
      }
}

interface IChangeOptions {
  /**
   * mediaSource类型
   */
  changeType?: EMediaSourceType
  /**
   * mediaSource的选项
   */
  mediaOptions?: IRichsurfaceTextureOption | ISpriteImgOptions | ITextSourceOption | IVideoOptions
  /**
   * 文本canvas的选项
   * 当type为ITextSourceOption时需要设置
   */
  textCanvasOptions?: ITextCanvasOption
}

/**
 * 切换mediaSource和media
 * 如果只传入mediaData则只切换media
 * 传入options则判定类型有无改变，有改变就创建新的mediaSource并设置其media
 * @param mediaData mediaData，IRichsurfaceTextureOption/ISpriteImgOptions对应url， ITextSourceOption对应文本，IVideoOptions对应videoElement
 * @param options 选项，IChangeOptions类型
 */
surface.changeMediaSource(media, options)

事件监听

目前支持方法有 beginLoading, beginOverlap, beginPlay, click, doubleClick,endLoading, endOverlap, endPlay, longPress, mouseEnter, mouseLeave, pointerDown, pointerOut, pointerUp

/**
 * surface事件监听方法
 */
surface.on('click', (e) => {
  // do something
})

静态贴图

在 new XStaticTextureSource之后，使用setMedia(data: string)设置静态图资源，此处的 data 可以是 base64、url、blob 等。静态图没有什么控制器，因此getController()拿到的是 null

视频流

在 new XVideoSource之后，使用setMedia(data: HTMLVideoElement)设置 tv 资源。通过getController()拿到控制器，做play、pause、stop、seek操作。

精灵图

在 new XSpriteImgSource之后，使用setMedia(data: string, options: ISpriteImgOptions)来设置精灵图资源，通过getController()拿到精灵图控制器，主要为控制精灵图的播放play()与暂停pause()

"每循环播放完一次"后会抛出onLoop事件

在下面的代码中，创建一份精灵图媒体资源，并指定声明周期为 1s，闪烁频率 15fps，精灵图中的水平精灵数量与垂直精灵数量分别为 4 和 5。当设置声明周期为-1 时，会永久显示。 XSpriteImgSource 中每次播放完成所有序列帧之后，会触发回调, 参考下面的代码

//创建surface
const surface = world.spawn(RichSurface)
surface.create(.....)

// 添加回调,每次循环一次之后，就会触发
surface.getMediaSource().on('onLoop',()=>{
  console.log('===> loop')
})

文字

在 new XTextSource之后，首先需要使用init(option: ITextCanvasOption)来做本文资源的初始化，此处主要设置文本绘制画面的大小、画面区域划分等信息。然后通过setMedia(data: string, options: ITextSourceOption)来填写实际的文本内容。初始化只要做一次即可，之后的setMedia可以执行多次，来完成文本更新等内容。文本的 demo 在 playground/src/simpleLevelDemo/test/demo_richsurface.ts 中 DemoCreateWordSource() 函数部分。

ITextCanvasOption

类型	说明
width	用于承载文字绘制区域的画布的宽(像素)
height	用于承载文字绘制区域的画布的高(像素)
widthSlotNum	画布区域水平均匀划分数量
heightSlotNum	画布区域垂直均匀划分数量

之所以需要设置画布水平、垂直区域划分，是为了在同一块画布中，可以同时指定不同区域，绘制不同文字。

一些情况说明：

当设置背景图的大小，小于画布的宽高时，可能出现背景图只展示了一部分的问题；
当文字比较模糊时，需要增大画布的宽高，同时需要增大文字字体大小
当只增大画布宽高，不改变文字大小时，会发现文字相对于画布缩小了，原因是文字绘制是按照像素绘制，而不是比例绘制

ITextSourceOption

类型	说明
currentSlot	当前需要绘制文字的区域编号，从 0 开始，最大为 (widthSlotNum*heightSlotNum-1), 按照从左到右、从上到下一次排列。
clearArea	true: 清理当前指定区域；false：不清理，直接在现有区域中继续绘制
fontSize	字体大小
font	字体类型
color	字体颜色
fontWeight	字体粗细
backgroundUrl	背景图片

通过 ITextSourceOption 中的 currentSlot 来指定当前绘制作用于哪个区域。背景图片会直接在整张画布中展示，而文字本身会在指定区域中绘制。

Billboard 模式

目前提供了 5 种模式，具体见文档中关于 EBillboardMode 的描述；

export enum EBillboardMode {
  /**
   * 只有X轴朝向相机
   */
  X = "x",
  /**
   * 只有Y轴朝向相机
   */
  Y = "y",
  /**
   * 只有Z轴朝向相机
   */
  Z = "z",
  /**
   * 所有轴都朝向相机
   */
  All = "all",
  /**
   * 关闭billboard
   */
  None = "none",
}

下面表示在各个方向上，都开启 billboard

surface.rootComponent.billboardMode = EBillboardMode.All

通过create()方法创建的 richsurface,可以自行设置 EBillboardMode 参数

AttachToActor

开发者可以选择将创建好的 RichSurface 附着到其他的 Actor 之上，比如 Avatar，实现一些自定义的组合。

可视距离

RichSurface 实例的 maxVisibleValue 属性可以获取和设置最大可视距离 RichSurface 实例的 minVisibleValue 属性可以获取和设置最小可视距离

可通过 world 实例上统一设置可视距离,使用方式如下

world.setVisibilityCullingDistance(min:number, max:number)

事件

参考事件处理章节

RichSurface

模型部分​

模型和媒体资源初始化​

改变 richsurface 绑定的媒体资源及其内容​

事件监听​

静态贴图​

视频流​

精灵图​

文字​

ITextCanvasOption​

ITextSourceOption​

Billboard 模式​

AttachToActor​

可视距离​

事件​