共享标注
简介
Pano SDK 支持共享标注,即在屏幕共享窗口上使用常用工具进行标注,以丰富沟通和交互场景。
各端 SDK 相关接口,请查看下列介绍:
Windows (C++)
获取共享标注对象
通过 RtcEngine
实例的 getAnnotationManager
方法获取标注管理器 (AnnotationManager
)。
再通过 AnnotationManager
的 getShareAnnotation(uint64_t userId)
方法获取共享标注对象 (PanoAnnotation
)。
userId
参数指定需要被标注的用户ID,通常发起方指定自己的userId
,也可以根据实际场景指定其他用户以对其视频进行标注。
共享标注事件通知
通过 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
方法将标注内容截图。
macOS/iOS (Objective-C)
获取共享标注对象
通过 PanoRtcEngineKit
实例的 annotationManager
属性获取标注管理器 (PanoRtcAnnotationManager
)。
再通过 PanoRtcAnnotationManager
的 - shareAnnotation:
方法获取共享标注对象 (PanoRtcAnnotation
)。
- (macOS)
userId
参数指定需要被标注的用户ID,通常发起方指定自己的userId
,也可以根据实际场景指定其他用户以对其视频进行标注。- iOS SDK 目前仅支持对其他用户的屏幕共享进行标注,
userId
参数指定需要被标注的用户ID。
共享标注事件通知
通过 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:
方法将标注内容截图。
Android (Java)
获取共享标注对象
通过 RtcEngine
实例的 getAnnotationMgr
方法获取标注管理器 (PanoAnnotationManager
)。
再通过 PanoAnnotationManager
的 getShareAnnotation (long userId)
方法获取共享标注对象 (PanoAnnotation
)。
Android SDK 目前仅支持对其他用户的屏幕共享进行标注,
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
方法将标注内容截图。
Electron (Javascript)
获取共享标注对象
标注对象需要开发者主动创建,发起标注的端,需要创建一个 AnnotationWhiteboard
对象,其他用户会接收到SessionManager 的 shareAnnotationStart 事件,在收到该事件后自行创建对应的 AnnotationWhiteboard
对象,创建 AnnotationWhiteboard
时需要传入对应的 userId
。
userId
参数指定需要被标注的用户ID,通常发起方指定自己的userId
,也可以根据实际场景指定其他用户以对其视频进行标注。
共享标注事件通知
通过 SessionManager 的 on
方法设置标注管理器回调函数。
和共享标注相关的事件通知有:
shareAnnotationStart
: 共享标注开始shareAnnotationStop
: 共享标注结束
AnnotationWhiteboard
和普通白板对象类似,与普通白板对象的方法和事件一致。
设置标注工具和格式
通过 AnnotationWhiteboard
的相关方法设置标注工具和格式,例如:
setToolType
: 设置工具类型lineWidth = 3
: 设置线宽strokeStyle = 'rgba(33, 212, 183, 1)'
: 设置画笔颜色fontSize = 14
: 设置字体大小
开始标注
创建 AnnotationWhiteboard
对象即代表标注开始,如果您是频道中第一个创建该对象的,其他用户会收到标注开始事件。
通过 AnnotationWhiteboard
的 open(dom: HTMLElement)
方法开启标注并设置显示窗口。
- 收到 "共享标注开始" (
onShareAnnotationStart
) 通知时,可以获取被标注的userId
。- 如果
userId
是自己,说明自己被其他用户标注- 如果
userId
是其他用户,说明其他用户被标注
结束标注
- 如果您只是暂时切到别的地方,可以调用
AnnotationWhiteboard
的close
方法关闭展示 - 如果您需要离开标注,可以调用
AnnotationWhiteboard
的leaveSession
方法结束本端的标注 - 如果您需要结束标注,其他所有端也需要一起推出,可以调用
AnnotationWhiteboard
的closeSession
方法结束所有端的标注
注意事项
被标注的的端需要设置正在共享的屏幕或app的分辨率到标注白板对象中,通过setAnnotationViewSize方法设置,开发者需要监听 electron panoRtc
实例的 screenCaptureRegionChanged
事件获取屏幕捕捉区域的大小和位置,当共享区域大小或位置变化时要及时更新到白板中:
rtcEngine.on(
'screenCaptureRegionChanged',
(x, y, width, height) => {
console.log('+++ 捕获屏幕/app共享窗口的位置变化: ', {
x,
y,
width,
height,
});
annotationWhiteboard.setAnnotationViewSize({ width, height });
}
);
屏幕共享标注的原理是在屏幕上叠加全屏透明窗口,由于需要在该透明窗口上进行标注操作,因此 SDK 会截获鼠标事件。
当 Windows 作为屏幕共享发送方的时候,开发者需要传入自己的工具栏窗口,以便 SDK 不捕获该窗口的鼠标事件,从而让用户可以操作工具栏。
electron
设置窗口是否捕获鼠标事件可以使用 setIgnoreMouseEvents
方法。
其他操作
设置权限
通过 AnnotationWhiteboard
的 setRoleType
方法设置权限角色,支持以下角色:
ADMIN
: 管理员 (可以清除全部标注内容,包括其他用户的标注内容)ATTENDEE
: 普通参与者
设置权限角色时,会触发相应回调。
撤销与重做
通过 AnnotationWhiteboard
的 undo
方法撤销上一次操作,redo
方法重做上一次操作。
清除标注内容
通过 AnnotationWhiteboard
的 clearContents
方法清除所有标注内容(需要 ADMIN
权限),clearUserContents
方法清除指定用户标注的内容 (清除其他用户的标注需要 ADMIN
权限)。
设置标注是否可见
通过 AnnotationWhiteboard
的 hideWhiteboard
方法设置标注是否可见。
设置标注白板不捕获鼠标事件
通过 AnnotationWhiteboard
的 setToolType(ShapeType.Click)
方法设置鼠标穿透白板,白板将不再捕获鼠标事件。
截图
通过 PanoRtcAnnotation
的 - snapshot:
方法将标注内容截图。