共享标注
简介
Pano SDK 支持共享标注,即在屏幕共享窗口上使用常用工具进行标注,以丰富沟通和交互场景。
注意:目前仅支持对 Windows, maOS, Electron 客户端发起的屏幕共享进行标注。
各端 SDK 相关接口,请查看下列介绍:
Windows (C++)
获取共享标注对象
注意:标注功能底层依赖于白板能力,要使用标注功能,在加入频道时,
serviceFlags
需要包含kChannelServiceWhiteboard
。
通过 RtcEngine
实例的 getAnnotationManager
方法获取标注管理器 (AnnotationManager
)。
再通过 AnnotationManager
的 getShareAnnotation(uint64_t userId)
方法获取共享标注对象 (PanoAnnotation
)。
userId
参数指定需要被标注的用户ID,可以是自己,也可以是其他用户。
共享标注事件通知
通过 AnnotationManager
的 setCallback
方法设置标注管理器回调函数。
和共享标注相关的事件通知有:
onShareAnnotationStart(uint64_t userId)
: 共享标注开始onShareAnnotationStop(uint64_t userId)
: 共享标注结束
通过 PanoAnnotation
的 setCallback
方法设置标注回调函数。
相应的事件通知例如:
onAnnoRoleChanged
: 标注角色类型变化通知onSnapshotComplete
: 标注截图完成通知
设置标注工具和格式
通过 PanoAnnotation
的相关方法设置标注工具和格式,例如:
setToolType
: 设置工具类型 (注意:标注图形不支持填充)setLineWidth
: 设置线宽setColor
: 设置颜色setFontStyle
: 设置字体样式setFontSize
: 设置字体大小
开始标注
通过 PanoAnnotation
的 startAnnotation(void *window)
方法开启标注并设置显示窗口。
- 如果有使用共享标注的场景:
订阅其他用户的屏幕共享时,建议使用RtcEngine
的subscribeScreen(uint64_t userId, void *window)
方法,以设置视频渲染窗口,而不是视频数据接收槽。- 如果对自己的屏幕共享进行标注,
window
参数应传入NULL
。- 如果对其他用户的屏幕共享进行标注,
window
参数应与上述subscribeScreen
方法传入的window
一致。- 收到 "共享标注开始" (
onShareAnnotationStart
) 通知时,可以获取被标注的userId
。
- 如果
userId
是自己,说明自己被其他用户标注,window
参数应传入NULL
。- 如果
userId
是其他用户,说明其他用户被标注,window
参数应与上述subscribeScreen
方法传入的window
一致。
结束标注
通过 PanoAnnotation
的 stopAnnotation
方法结束标注。
注意事项
屏幕共享标注的原理是在屏幕上叠加全屏透明窗口,由于需要在该透明窗口上进行标注操作,因此 SDK 会截获鼠标事件。
当 Windows 作为屏幕共享发送方的时候,开发者需要传入自己的工具栏窗口,以便 SDK 不捕获该窗口的鼠标事件,从而让用户可以操作工具栏。
通过 PanoAnnotation
的 addToolboxView (void *window)
方法增加工具栏窗口,通过 removeToolboxView (void *window)
移除工具栏窗口。
其他操作
设置权限
通过 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, ¶m1, sizeof(param1));
bool param2 = true;
panoAnnotation->setOption(AnnoOption::ENABLE_SHOW_REMOTE_CURSOR, ¶m2, sizeof(param2));
macOS/iOS (Objective-C)
获取共享标注对象
注意:标注功能底层依赖于白板能力,要使用标注功能,在加入频道时,
serviceFlags
需要包含kPanoChannelServiceWhiteboard
。
通过 PanoRtcEngineKit
实例的 annotationManager
属性获取标注管理器 (PanoRtcAnnotationManager
)。
再通过 PanoRtcAnnotationManager
的 - shareAnnotation:
方法获取共享标注对象 (PanoRtcAnnotation
)。
userId
参数指定需要被标注的用户ID,可以是自己,也可以是其他用户。- 注意: 不支持对 iOS 用户发起的屏幕共享进行标注。
共享标注事件通知
通过 PanoRtcAnnotationManager
的 - setDelegate:
方法设置标注管理器回调对象。
和共享标注相关的事件通知有:
- onShareAnnotationStart:
共享标注开始- onShareAnnotationStop:
共享标注结束
通过 PanoRtcAnnotation
的 - setDelegate:
方法设置标注回调对象。
相应的事件通知例如:
- onAnnoRoleChanged:
标注角色类型变化通知- onSnapshotComplete:name:
标注截图完成通知
设置标注工具和格式
通过 PanoRtcAnnotation
的相关方法设置标注工具和格式,例如:
- setToolType:
设置工具类型 (注意:标注图形不支持填充)- setLineWidth:
设置线宽- setColor:
设置颜色- setFontStyle:
设置字体样式- setFontSize:
设置字体大小
开始标注
通过 PanoRtcAnnotation
的 - startAnnotation:
方法开启标注并设置显示窗口。
- 如果有使用共享标注的场景:
订阅其他用户的视频时,建议使用PanoRtcEngineKit
的- subscribeScreen:withView:
方法,以设置视频渲染视图,而不是外置渲染器。- (macOS) 如果对自己的视频进行标注,
view
参数应传入nil
。- (iOS/macOS) 如果对其他用户的视频进行标注,
view
参数应与上述- subscribeScreen:withView:
方法传入的view
一致。- 收到 "共享标注开始" (
- onShareAnnotationStart:
) 通知时,可以获取被标注的userId
。
- (macOS) 如果
userId
是自己,说明自己被其他用户标注,view
参数应传入nil
。- (iOS/macOS) 如果
userId
是其他用户,说明其他用户被标注,view
参数应与上述- subscribeScreen:withView:
方法传入的view
一致。
结束标注
通过 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
的 getShareAnnotation (long userId)
方法获取共享标注对象 (PanoAnnotation
)。
userId
参数指定需要被标注的用户ID,可以是自己,也可以是其他用户。
共享标注事件通知
通过 PanoAnnotationManager
的 setCallback
方法设置标注管理器回调函数。
和共享标注相关的事件通知有:
onShareAnnotationStart(long userId)
: 共享标注开始onShareAnnotationStop(long userId)
: 共享标注结束
通过 PanoAnnotation
的 setCallback
方法设置标注回调函数。
相应的事件通知例如:
onAnnoRoleChanged
: 标注角色类型变化通知onSnapshotComplete
: 标注截图完成通知
设置标注工具和格式
通过 PanoAnnotation
的相关方法设置标注工具和格式,例如:
setToolType
: 设置工具类型 (注意:标注图形不支持填充)setLineWidth
: 设置线宽setColor
: 设置颜色setFontStyle
: 设置字体样式setFontSize
: 设置字体大小
开始标注
通过 PanoAnnotation
的 startAnnotation(RtcWbView view)
方法开启标注并设置显示窗口。
- Android SDK 目前仅支持对其他用户的屏幕共享进行标注,
view
参数应与调用RtcEngine
的setRemoteScreenRender
方法传入的render
一致。- 收到 "共享标注开始" (
onShareAnnotationStart
) 通知时,可以获取被标注的userId
,view
参数应与上述setRemoteScreenRender
方法传入的render
一致。
结束标注
通过 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 用户发起的屏幕共享进行标注)。sourceType
参数配置为"share"
表示屏幕共享标注。videoSourceIndex
参数不填。
共享标注事件通知
通过 RtsService
实例的 on
方法注册标注回调通知。
和共享标注相关的事件通知有:
shareAnnotationStart
: 共享标注开始shareAnnotationStop
: 共享标注结束
Annotation
和普通白板对象类似,与普通白板对象的方法和事件一致。
设置标注工具和格式
通过 Annotation
的相关方法设置标注工具和格式,例如:
setToolType
: 设置工具类型lineWidth = 3
: 设置线宽strokeStyle = 'rgba(33, 212, 183, 1)'
: 设置画笔颜色fontSize = 14
: 设置字体大小
开始标注
创建 Annotation
对象即代表标注开始,如果您是频道中第一个创建该对象的,其他用户会收到标注开始事件。
通过 Annotation
的 open(dom: HTMLElement)
方法开启标注并设置显示窗口。
- 收到 "共享标注开始" (
shareAnnotationStart
) 通知时,可以获取被标注的userId
。- 如果
userId
是自己,说明自己被其他用户标注。- 如果
userId
是其他用户,说明其他用户被标注。
结束标注
- 如果您只是暂时切到别的地方,可以调用
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'; // 仅在鼠标按下做绘制动作时同步光标位置