外部标注

简介

Pano SDK 支持外部标注，可以在开发者自定义的窗口上使用常用工具进行标注，以丰富沟通和交互场景。

各端 SDK 相关接口，请查看下列介绍：

• Windows (C++)
• macOS/iOS (Objective-C)
• Android (Java)
• Electron/Web (Javascript)

---

Windows (C++)

获取外部标注对象

注意：标注功能底层依赖于白板能力，要使用标注功能，在加入频道时，serviceFlags 需要包含 kChannelServiceWhiteboard。

通过 RtcEngine 实例的 getAnnotationManager 方法获取标注管理器 (AnnotationManager)。
再通过 AnnotationManager 的 getExternalAnnotation(const char *annotationId) 方法获取外部标注对象 (PanoAnnotation)。

• annotationId 由开发者自定义，必须以 "pano-annotation-ext-" 作为前缀。

通过 PanoAnnotation 的 setAspectSize(int32_t w, int32_t h) 方法设置标注区域大小。

外部标注事件通知

通过 AnnotationManager 的 setCallback 方法设置标注管理器回调函数。
和外部注相关的事件通知有：

• onExternalAnnotationStart(const char *annotationId): 外部标注开始
• onExternalAnnotationStop(const char *annotationId): 外部标注结束

注意：

• 第一位用户调用"开始标注"方法时(具体见后文介绍)，频道内的其他用户会收到"外部标注开始"的通知(第一位用户自己不会收到此通知)；
• 后续加入频道的其他用户也会收到"外部标注开始"的通知；
• 任一用户调用"结束标注"方法时，频道内的其他用户会收到"外部标注结束的"通知。

通过 PanoAnnotation 的 setCallback 方法设置标注回调函数。
相应的事件通知例如：

• onAnnoRoleChanged: 标注角色类型变化通知
• onSnapshotComplete: 标注截图完成通知

设置标注工具和格式

通过 PanoAnnotation 的相关方法设置标注工具和格式，例如：

• setToolType: 设置工具类型 (注意：标注图形不支持填充)
• setLineWidth: 设置线宽
• setColor: 设置颜色
• setFontStyle: 设置字体样式
• setFontSize: 设置字体大小

开始标注

通过 PanoAnnotation 的 startAnnotation(void *window) 方法开启标注并设置显示窗口。

结束标注

通过 PanoAnnotation 的 stopAnnotation 方法结束标注。

其他操作

设置权限

通过 PanoAnnotation 的 setRoleType 方法设置权限角色，支持以下角色：

• ADMIN: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
• ATTENDEE: 普通参与者
• VIEWER: 观看者 (仅可观看，不可标注)

设置权限角色时，会触发相应回调。

撤销与重做

通过 PanoAnnotation 的 undo 方法撤销上一次操作，redo 方法重做上一次操作。

清除标注内容

通过 PanoAnnotation 的 clearContents 方法清除所有标注内容 (需要 ADMIN 权限)，clearUserContents(uint64_t userId) 方法清除指定用户标注的内容 (清除其他用户的标注需要 ADMIN 权限)。

设置标注是否可见

通过 PanoAnnotation 的 setVisible(bool visible) 方法设置标注是否可见。

截图

通过 PanoAnnotation 的 snapshot 方法将标注内容截图。

同步光标位置

通过 PanoAnnotation 的 setOption 方法：

• option 参数设置为 ENABLE_CURSORPOS_SYNC，param 参数设置为布尔值来设置是否同步光标位置给其他用户。
• option 参数设置为 ENABLE_SHOW_REMOTE_CURSOR，param 参数设置为布尔值来设置是否显示其他用户的光标位置。
• 这两个参数默认都是关闭的。

bool param1 = true;
panoAnnotation->setOption(AnnoOption::ENABLE_CURSORPOS_SYNC, &param1, sizeof(param1));
bool param2 = true;
panoAnnotation->setOption(AnnoOption::ENABLE_SHOW_REMOTE_CURSOR, &param2, sizeof(param2));

---

macOS/iOS (Objective-C)

获取外部标注对象

注意：标注功能底层依赖于白板能力，要使用标注功能，在加入频道时，serviceFlags 需要包含 kPanoChannelServiceWhiteboard。

通过 PanoRtcEngineKit 实例的 annotationManager 属性获取标注管理器 (PanoRtcAnnotationManager)。
再通过 PanoRtcAnnotationManager 的 - externalAnnotation: 方法获取外部标注对象 (PanoRtcAnnotation)。

• annotationId 由开发者自定义，必须以 "pano-annotation-ext-" 作为前缀。

通过 PanoRtcAnnotation 的 - setAspectWidth:height: 方法设置标注区域大小。

外部标注事件通知

通过 PanoRtcAnnotationManager 的 - setDelegate: 方法设置标注管理器回调对象。
和外部标注相关的事件通知有：

• - onExternalAnnotationStart: 外部标注开始
• - onExternalAnnotationStop: 外部标注结束

注意：

• 第一位用户调用"开始标注"方法时(具体见后文介绍)，频道内的其他用户会收到"外部标注开始"的通知(第一位用户自己不会收到此通知)；
• 后续加入频道的其他用户也会收到"外部标注开始"的通知；
• 任一用户调用"结束标注"方法时，频道内的其他用户会收到"外部标注结束的"通知。

通过 PanoRtcAnnotation 的 - setDelegate: 方法设置标注回调对象。
相应的事件通知例如：

• - onAnnoRoleChanged: 标注角色类型变化通知
• - onSnapshotComplete:name: 标注截图完成通知

设置标注工具和格式

通过 PanoRtcAnnotation 的相关方法设置标注工具和格式，例如：

• - setToolType: 设置工具类型 (注意：标注图形不支持填充)
• - setLineWidth: 设置线宽
• - setColor: 设置颜色
• - setFontStyle: 设置字体样式
• - setFontSize: 设置字体大小

开始标注

通过 PanoRtcAnnotation 的 - startAnnotation: 方法开启标注并设置显示窗口。

结束标注

通过 PanoRtcAnnotation 的 - stopAnnotation 方法结束标注。

其他操作

设置权限

通过 PanoRtcAnnotation 的 - setRoleType: 方法设置权限角色，支持以下角色：

• kPanoWBRoleAdmin: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
• kPanoWBRoleAttendee: 普通参与者
• kPanoWBRoleViewer: 观看者 (仅可观看，不可标注)

设置权限角色时，会触发相应回调。

撤销与重做

通过 PanoRtcAnnotation 的 - undo 方法撤销上一次操作，- redo 方法重做上一次操作。

清除标注内容

通过 PanoRtcAnnotation 的 - clearContents 方法清除所有标注内容 (需要 kPanoWBRoleAdmin 权限)，- clearUserContents: 方法清除指定用户标注的内容 (清除其他用户的标注需要 kPanoWBRoleAdmin 权限)。

设置标注是否可见

通过 PanoRtcAnnotation 的 - setVisible: 方法设置标注是否可见。

截图

通过 PanoRtcAnnotation 的 - snapshot: 方法将标注内容截图。

同步光标位置

通过 PanoRtcAnnotation 的 - setOption:forType: 方法：

• type 参数设置为 kPanoAnnoOptionCursorPosSync，option 参数设置为带 BOOL 值的 NSNumber 来设置是否同步光标位置给其他用户。
• type 参数设置为 kPanoAnnoOptionShowRemoteCursor，option 参数设置为带 BOOL 值的 NSNumber 来设置是否显示其他用户的光标位置。
• 这两个参数默认都是关闭的。

[self.panoAnnotation setOption:@YES forType:kPanoAnnoOptionCursorPosSync]; // 同步光标位置给其他用户
[self.panoAnnotation setOption:@YES forType:kPanoAnnoOptionShowRemoteCursor]; // 显示其他用户的光标位置

---

Android (Java)

获取外部标注对象

注意：标注功能底层依赖于白板能力，要使用标注功能，在加入频道时，serviceFlags 需要包含 kChannelServiceWhiteboard。

通过 RtcEngine 实例的 getAnnotationMgr 方法获取标注管理器 (PanoAnnotationManager)。
再通过 PanoAnnotationManager 的 getExternalAnnotation(String annotationId) 方法获取外部标注对象 (PanoAnnotation)。

• annotationId 由开发者自定义，必须以 "pano-annotation-ext-" 作为前缀。

通过 PanoAnnotation 的 setAspectSize(int w, int h) 方法设置标注区域大小。

外部标注事件通知

通过 PanoAnnotationManager 的 setCallback 方法设置标注管理器回调函数。
和外部标注相关的事件通知有：

• onExternalAnnotationStart(String annotationId): 外部标注开始
• onExternalAnnotationStop(String annotationId): 外部标注结束

注意：

• 第一位用户调用"开始标注"方法时(具体见后文介绍)，频道内的其他用户会收到"外部标注开始"的通知(第一位用户自己不会收到此通知)；
• 后续加入频道的其他用户也会收到"外部标注开始"的通知；
• 任一用户调用"结束标注"方法时，频道内的其他用户会收到"外部标注结束的"通知。

通过 PanoAnnotation 的 setCallback 方法设置标注回调函数。
相应的事件通知例如：

• onAnnoRoleChanged: 标注角色类型变化通知
• onSnapshotComplete: 标注截图完成通知

设置标注工具和格式

通过 PanoAnnotation 的相关方法设置标注工具和格式，例如：

• setToolType: 设置工具类型 (注意：标注图形不支持填充)
• setLineWidth: 设置线宽
• setColor: 设置颜色
• setFontStyle: 设置字体样式
• setFontSize: 设置字体大小

开始标注

通过 PanoAnnotation 的 startAnnotation(RtcWbView view) 方法开启标注并设置显示窗口。

结束标注

通过 PanoAnnotation 的 stopAnnotation 方法结束标注。

其他操作

设置权限

通过 PanoAnnotation 的 setRoleType 方法设置权限角色，支持以下角色：

• Admin: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
• Attendee: 普通参与者
• Viewer: 观看者 (仅可观看，不可标注)

设置权限角色时，会触发相应回调。

撤销与重做

通过 PanoAnnotation 的 undo 方法撤销上一次操作，redo 方法重做上一次操作。

清除标注内容

通过 PanoAnnotation 的 clearContents 方法清除所有标注内容 (需要 Admin 权限)，clearUserContents (long userId) 方法清除指定用户标注的内容 (清除其他用户的标注需要 Admin 权限)。

设置标注是否可见

通过 PanoAnnotation 的 setVisible(boolean visible) 方法设置标注是否可见。

截图

通过 PanoAnnotation 的 snapshot 方法将标注内容截图。

同步光标位置

通过 PanoAnnotation 的：

• enableCursorPosSync 方法设置是否同步光标位置给其他用户
• enableShowRemoteCursor 方法设置是否显示其他用户的光标位置，当启用时，需要传入一个 PanoLabelView 用于显示远端光标位置

---

Electron/Web (Javascript)

如需在 Electron 中使用标注功能，请集成 Web SDK。

获取外部标注对象

通过 RtsService 实例的 getAnnotation 方法获取外部标注对象(Annotation)：

• annotationId 参数由开发者自定义，表示标注ID。

  注意：当 Web 端和其他端协同开发时，其他端的外部标注ID必须以 "pano-annotation-ext-" 作为前缀，而 Web 端不需要该前缀。例如，Windows 端传入的 annotationId 为 "pano-annotation-ext-test"，那么 Web 端应传入的 annotationId 为 "test"。

• sourceType 参数配置为 "external" 表示外部标注。
• videoSourceIndex 参数不填。

外部标注事件通知

通过 RtsService 实例的 on 方法注册标注回调通知。

和外部标注相关的事件通知有：

• externalAnnotationStart: 外部标注开始
• externalAnnotationStop: 外部标注结束

注意：

• 第一位用户调用 open 方法"开始标注"时(具体见后文介绍)，频道内的其他用户会收到"外部标注开始"的通知(第一位用户自己不会收到此通知)；
• 后续加入频道的其他用户也会收到"外部标注开始"的通知；
• 任一用户调用"结束标注"方法时，频道内的其他用户会收到"外部标注结束的"通知。

设置标注工具和格式

Annotation 和普通白板对象类似，与普通白板对象的方法和事件一致。

通过 Annotation 的相关方法设置标注工具和格式，例如：

• setToolType: 设置工具类型
• lineWidth = 3: 设置线宽
• strokeStyle = 'rgba(33, 212, 183, 1)': 设置画笔颜色
• fontSize = 14: 设置字体大小

开始标注

通过 Annotation 的 open(dom: HTMLElement) 方法开启标注并设置显示窗口。

收到 "外部标注开始" (externalAnnotationStart) 通知时，可以获取被标注的 annotationId。

结束标注

• 如果您只是暂时切到别的地方，可以调用 Annotation 的 close 方法关闭展示
• 如果您需要离开标注，可以调用 Annotation 的 leave 方法结束本端的标注
• 如果您需要结束标注，并且将其他所有端一起退出，可以调用 Annotation 的 stop 方法结束所有端的标注

注意事项

需要设置标注内容的真实分辨率到标注对象中，用以计算标注显示的位置，通过setAnnotationViewSize方法设置。

如果对视频进行标注，可以使用以下工具方法获取视频分辨率：

// 此方法可以查询视频分辨率，兼容 Electron 和 Web
// 需要传入包含视频元素的 DOM（Electron 是 Canvas，Web 是 video 标签）
function getVideoResolution(domRef: HTMLElement) {
  const videoDom: any =
    domRef.getElementsByTagName('video')[0] ||
    domRef.getElementsByTagName('canvas')[0];
  if (videoDom) {
    return {
      width:
        videoDom instanceof HTMLVideoElement
          ? videoDom.videoWidth
          : videoDom.width,
      height:
        videoDom instanceof HTMLVideoElement
          ? videoDom.videoHeight
          : videoDom.height,
    };
  }
  return undefined;
}

// 设置标注分辨率
annotation.setAnnotationViewSize(getVideoResolution(domRef));

其他操作

设置权限

通过 Annotation 的 setRoleType 方法设置权限角色，支持以下角色：

• ADMIN: 管理员 (可以清除全部标注内容，包括其他用户的标注内容)
• ATTENDEE: 普通参与者

设置权限角色时，会触发相应回调。

撤销与重做

通过 Annotation 的 undo 方法撤销上一次操作，redo 方法重做上一次操作。

清除标注内容

通过 Annotation 的 clearContents 方法清除所有标注内容（需要 ADMIN 权限)，clearUserContents 方法清除指定用户标注的内容 (清除其他用户的标注需要 ADMIN 权限)。

设置标注是否可见

通过 Annotation 的 hideWhiteboard 方法设置标注是否可见。

截图

通过 Annotation 的 snapshot 方法将标注内容截图。

同步光标位置

通过 Annotation 的 cursorSyncType 属性设置光标同步类型。

rtcWhiteboard.cursorSyncType = 'write'; // 仅在鼠标按下做绘制动作时同步光标位置

---