cve-connector/docs/player.md

UE Web 开发套件

rPlayer 是用于 UE5 像素流播放的插件。

# 安装

- npm

```cmd
npm install cve-connector@latest
```

- yarn

```cmd
yarn add cve-connector@latest
```

# 集成到 Web 页面

- *在 HTML 模板内使用之前，必须先引入！*
- *`<cve-player>` 的高度不能为 0！*
- 基于模板渲染设置事件回调函数时(以 Vue2 为例):

```html
<cve-player
  application-name="HdecUnrealHaining"
  url="http://localhost:1234"
  @error="onError"
  @start="onStart"
>
</cve-player>

<script type="module">
import { defineContainer } from 'cve-connector'

defineContainer()

export default {
  methods: {
    onStart(evt) {
      console.warn('start ===> ', evt.detail)
    },
    onError(evt) {
      console.error('error ===> ', evt.message)
    },
  }
}
</script>
```

- 不基于前端框架的集成示例

```html
<!-- HTML Template -->
<cve-player
  application-name="HdecUnrealHaining"
  url="http://localhost:1234"
>
</cve-player>

<script type="module">
import { defineContainer } from 'cve-connector'

defineContainer((player) => {
  player.addEventListener('start', (evt) => {
    console.warn('start ===> ', evt.detail)
  })
  player.addEventListener('error', (evt) => {
    console.error('error ===> ', evt.message)
  })
})
</script>
```

# 属性

```html
<cve-player
  aspect-ratio="auto"
  signaling-url="http://39.170.3.124:80/"
  volume="0.3"
>
</cve-player>
```

## application-name

- 必要属性
- UE 应用名称，联系 UE 研发人员确认
- 无默认值

## aspect-ratio

- 可选属性
- 云渲染视口纵横比例
- 示例: 'auto', '16 / 9', '4 / 3'
- 默认值: 'auto'

## height

- 可选属性
- UE 渲染分辨率高度
- 无默认值

## matchmaker-url

- 可选属性
- 云渲染源地址，协议://主机:端口/路径
- 无默认值

## signaling-url

- 可选属性
- 信令服务地址，协议://主机:端口/路径
- 无默认值

## volume

- 可选属性
- UE 音量
- 默认值: 0.3

## width

- 可选属性
- UE 渲染分辨率宽度
- 无默认值

# 事件

CvePlayer 扩展了 HTMLELment，有更多的事件回调。

| Event         | Description                   |
| ------------- | ----------------------------- |
| command       | Web 发送指令到 UE            |
| error         | 云渲染异常                    |
| featurehover  | 鼠标悬浮/离开在点、线、面之上 |
| featureselect | 点、线、面被选中/取消选中     |
| message       | UE 传递消息到 Web            |
| mouseclick    | UE 鼠标点击                   |
| roam          | 路径漫游时                    |
| sequencepause | 过场动画暂停播放              |
| sequenceplay  | 过场动画开始播放              |
| sequencestop  | 过场动画停止播放              |
| start         | 云渲染开始                    |
| stop          | 云渲染结束                    |
| timechange    | 时间变化                      |
| yaw           | 以正北方为起点的方位角旋转    |

- 全局环境下，有且仅有一个 player 元素，请导入后使用；
- player 可能为空(尚未初始化)，请注意校验；

```ts
export class CvePlayer extends HTMLELment {
  oncommand?: (evt: CustomEvent<UIDescriptor>) => void
  onerror?: (evt: ErrorEvent) => void
  onfeaturehover?: (evt: CustomEvent<UIDescriptor>) => void
  onfeatureselect?: (evt: CustomEvent<UIDescriptor>) => void
  onmessage?: (evt: CustomEvent<UIDescriptor>) => void
  onmouseclick?: (evt: CustomEvent<UIDescriptor>) => void
  onroam?: (evt: CustomEvent<string>) => void
  onsequencepause?: (evt: CustomEvent<string>) => void
  onsequenceplay?: (evt: CustomEvent<string>) => void
  onsequencestop?: (evt: CustomEvent<string>) => void
  onstart?: (evt: CustomEvent<number>) => void
  onstop?: (evt: CustomEvent<string>) => void
  ontimechange?: (evt: CustomEvent<string>) => void
  onyaw?: (evt: CustomEvent<number>) => void
}
export let player: CvePlayer | undefined
```

# 云渲染控制

## connect2Matchmaker

```ts
import { connect2Matchmaker } from 'cve-connector'
// 运行云渲染程序，使用绑定的源地址和应用名称
connect2Matchmaker()
```

## connect2Signaling

```ts
import { connect2Signaling } from 'cve-connector'
// 输入像素流实例地址，重新渲染
connect2Signaling('http://localhost:8081')
```

## defineContainer

```ts
import { defineContainer } from 'cve-connector'
// 云渲染插件初始化后，立即执行回调函数
defineContainer(async () => {
  if (!player) {
    return
  }

  player.onstart = () => {
    const reference: CVE.GeoReference = {
      IsOriginLocationInProjectedCRS: true,
      OriginCenter: [116, 39, 100],
    }
    GisController.config(reference)
  }
})
```

## disconnect

```ts
import { disconnect } from 'cve-connector'
// 停止渲染
disconnect()
```

## listen

```ts
import { listen } from 'cve-connector'
// 监听鼠标点击事件
listen('mouseclick', function(e) {
  console.log(e)
})
```

## requestInstance

```ts
import { requestInstance } from 'cve-connector'
// 获取云渲染实例
requestInstance('http://127.0.0.1:8080', 'HdecUnrealDemo')
```

## setDegradationPreference

```ts
import { setDegradationPreference } from 'cve-connector'
// 停止渲染设置云渲染实例流送质量偏好
// 'BALANCED' | 'MAINTAIN_FRAMERATE' | 'MAINTAIN_RESOLUTION'
setDegradationPreference('BALANCED')
```

## setResolution

```ts
import { setResolution } from 'cve-connector'
// 设置云渲染实例分辨率
setResolution(1920, 1080)
```

## unlisten

```ts
import { unlisten } from 'cve-connector'
// 取消监听鼠标点击事件
unlisten('mouseclick', function(e) {
  console.log(e)
})
```

## useWebBrowser

```ts
import { useWebBrowser } from 'cve-connector'
// 基于新版本 CVE 套件，Web 卡片的通讯方案
useWebBrowser()
```

## useWebSocket

```ts
import { useWebSocket } from 'cve-connector'
// 基于 WebSocket 的 Web 与 UE 通讯
useWebSocket('ws://127.0.0.1:1000')
```

## useWebUI

```ts
import { useWebUI } from 'cve-connector'
// 基于旧版 CVE 套件中 WebBrowser 的 Web 与 UE 的通讯方案
useWebUI()
```

## useWebView2

```ts
import { useWebView2 } from 'cve-connector'
// 基于新版本 CVE 套件，使用 UE 内嵌入 Web 开发模式的通讯方案
useWebView2()
```

# 自定义指令

```ts
import { sendCommand } from 'cve-connector'
// 指令请跟 UE 开发协定
const command = 'Highlight'
// 参数根据实际需求，与 UE 开发协定
const params = {
  Tags: ['tag-1', 'tag-2']
}
sendCommand(command, params)
```