createVideo
创建原生视频视图
当游戏调用 sud.createVideo 创建视频组件时,SDK 通过 createVideo: 将对应的 SUDOPVideo 对象交给 App。App 需要将视频的渲染视图添加到合适的原生容器,并根据对象状态实现布局、层级、控制栏和全屏等交互。
方法声明
objectivec
- (void)createVideo:(SUDOPVideo *)video;参数说明
| 参数名 | 类型 | 必传 | 描述 |
|---|---|---|---|
| video | SUDOPVideo * | 是 | SDK 创建的视频对象,包含渲染视图、布局参数、播放状态和 UI 状态回调。 |
该回调不使用 SUDOPStateHandle。视频的后续操作和状态变化均通过 SUDOPVideo 完成。
SUDOPVideo 常用属性
渲染与布局
| 属性 | 类型 | 描述 |
|---|---|---|
| instanceID | NSInteger | 当前视频实例的唯一 ID。 |
| renderView | UIView * | 需要添加到原生视图层级中的视频渲染视图。 |
| renderLayer | CAEAGLLayer * | SDK 与游戏媒体播放器连接使用的渲染层。通常无需由 App 手动设置。 |
| x / y | CGFloat | 视频左上角坐标,单位为 pt。 |
| width / height | CGFloat | 视频组件宽高,单位为 pt。 |
| frameInPoint | CGRect | 当前期望布局区域,单位为 pt。布局变化时应优先使用该值。 |
| underGameView | BOOL | 是否将视频放在游戏视图下方。 |
视频配置与状态
| 属性 | 类型 | 描述 |
|---|---|---|
| src | NSString * | 视频资源地址。 |
| poster | NSString * | 视频封面地址。 |
| objectFit | NSString * | 视频缩放模式。 |
| controls | BOOL | 是否展示控制栏。 |
| autoplay / loop / muted | BOOL | 是否自动播放、循环播放和静音播放。 |
| playing | BOOL | 当前是否正在播放。 |
| hasStartedPlayback | BOOL | 当前实例是否已经实际开始播放,可用于控制封面显示。仅配置 autoplay 不代表该值立即为 YES。 |
| disabled | BOOL | 当前视频是否不可见。 |
| fullScreen | BOOL | 当前是否处于全屏状态。 |
| currentTime / duration | NSTimeInterval | 当前播放时间和总时长,单位为秒。 |
| bufferedTime | NSTimeInterval | 当前已缓冲到的时间,单位为秒。 |
完整的创建参数可参考游戏侧 sud.createVideo。
UI 状态回调
App 自定义视频 UI 时,应按需设置以下回调:
| 回调 | 触发场景 |
|---|---|
| layoutChangedHandler | frameInPoint 变化,需要更新视频布局。 |
| layerChangedHandler | underGameView 变化,需要调整视频与游戏视图的层级。 |
| styleChangedHandler | 背景色、缩放模式或视频真实尺寸等发生变化。 |
| progressChangedHandler | 播放进度变化,需要刷新进度条和时间。 |
| bufferingProgressChangedHandler | 缓冲进度变化,返回 bufferedTime 和 duration,单位为秒。 |
| endedHandler | 视频播放自然结束。 |
| waitingHandler | 播放进入等待或缓冲状态。 |
| errorHandler | 播放发生错误,返回错误码和错误信息。 |
| visibilityChangedHandler | 视频启用或禁用,需要更新显示状态。 |
| requestFullScreenHandler | 游戏请求进入全屏。完成布局切换后调用 notifyFullScreenChanged:YES。 |
| exitFullScreenHandler | 游戏请求退出全屏。完成布局恢复后调用 notifyFullScreenChanged:NO。 |
| destroyHandler | 视频实例销毁,需要移除原生视频 UI 并清理回调。 |
原生播放、暂停、停止和拖动进度等控件,应分别调用 play、pause、stop 和 seek: 将操作同步给游戏。
代码示例
以下示例只展示最小渲染视图接入。实际项目还应根据产品需求实现控制栏、层级切换、全屏和资源释放。
objectivec
@property (nonatomic, strong) UIView *videoContainerView;
@property (nonatomic, strong) SUDOPVideo *currentVideo;
- (void)createVideo:(SUDOPVideo *)video {
if (!video || !video.renderView) {
return;
}
self.currentVideo = video;
UIView *renderView = video.renderView;
[renderView removeFromSuperview];
renderView.frame = video.frameInPoint;
[self.videoContainerView addSubview:renderView];
__weak typeof(self) weakSelf = self;
video.layoutChangedHandler = ^(SUDOPVideo *changedVideo) {
weakSelf.currentVideo.renderView.frame = changedVideo.frameInPoint;
};
video.visibilityChangedHandler = ^(SUDOPVideo *changedVideo, BOOL visible) {
changedVideo.renderView.hidden = !visible;
};
video.destroyHandler = ^(SUDOPVideo *destroyedVideo) {
[destroyedVideo.renderView removeFromSuperview];
weakSelf.currentVideo = nil;
};
}注意事项
renderView应加入与游戏视图使用同一坐标系的容器,否则frameInPoint无法直接用于布局。underGameView变化后,应重新调整视频相对游戏视图的前后层级。- UIKit 视图更新必须在主线程执行。
play、pause、stop、seek:和destroy会在主线程执行;从后台线程调用时 SDK 会投递到主队列。destroy可重复调用且只触发一次销毁通知;销毁后的布局、样式和播放控制会被忽略。seek:保留小数秒精度,非有限值会被忽略,负数会按 0 处理。- 使用 Block 时避免强引用页面或视频播放器,销毁时应清空回调并移除 UI。
- 如果接入
SUDOPWrappedClientKit,可使用其默认包装客户端和视频播放器实现;自定义代理时才需要自行完成上述 UI 逻辑。
