//
|
// ARMediaIO.h
|
// ARtcKit
|
//
|
// Created by 余生丶 on 2020/6/15.
|
// Copyright © 2020 zjq. All rights reserved.
|
//
|
|
#import <Foundation/Foundation.h>
|
#import <AVFoundation/AVFoundation.h>
|
#import "AREnumerates.h"
|
|
/** 视频像素格式
|
|
关于 YVU 图像格式的描述，请参考：
|
FourCC YUV 格式说明
|
Recommended 8-Bit YUV Formats for Video Rendering
|
*/
|
typedef NS_ENUM(NSUInteger, ARVideoPixelFormat) {
|
/** I420 */
|
ARVideoPixelFormatI420 = 1,
|
/** BGRA */
|
ARVideoPixelFormatBGRA = 2,
|
/** NV12 */
|
ARVideoPixelFormatNV12 = 8,
|
};
|
|
/** 视频的顺时针旋转角度
|
|
如果设置为其他数字，系统会自动忽略
|
*/
|
typedef NS_ENUM(NSInteger, ARVideoRotation) {
|
/** 顺时针旋转 0 度 */
|
ARVideoRotationNone = 0,
|
/** 顺时针旋转 90 度*/
|
ARVideoRotation90 = 1,
|
/** 顺时针旋转 180 度 */
|
ARVideoRotation180 = 2,
|
/** 顺时针旋转 270 度 */
|
ARVideoRotation270 = 3,
|
};
|
|
/**
|
ARVideoFrameConsumer 支持接收两种 Buffer 类型的视频帧数据：PixelBuffer 和裸数据。 自定义视频源时，开发者需要通过 bufferType 来指定一种 Buffer 类型，并在自定义视频源中只使用与其对应的方法来传递视频帧数据。
|
*/
|
@protocol ARVideoFrameConsumer <NSObject>
|
|
/** PixelBuffer 类型
|
|
@param pixelBuffer PixelBuffer 类型的视频 Buffer
|
@param timestamp 传入的视频帧的时间戳，开发者必须为每一个视频帧设置一个时间戳。
|
@param rotation 视频的顺时针旋转角度， 详见 ARVideoRotation
|
*/
|
- (void)consumePixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer
|
withTimestamp:(CMTime)timestamp
|
rotation:(ARVideoRotation)rotation;
|
|
/** RawData 类型
|
|
@param rawData RawData 类型的视频 Buffer
|
@param timestamp 传入的视频帧的时间戳，以毫秒为单位。
|
@param format ARVideoPixelFormat
|
@param size 视频裸数据的尺寸
|
@param rotation 视频的顺时针旋转角度， 详见 ARVideoRotation
|
*/
|
- (void)consumeRawData:(void * _Nonnull)rawData
|
withTimestamp:(CMTime)timestamp
|
format:(ARVideoPixelFormat)format
|
size:(CGSize)size
|
rotation:(ARVideoRotation)rotation;
|
|
|
@end
|
|
|
/** ARVideoSourceProtocol 协议
|
|
ARVideoSourceProtocol 定义了一套协议，开发者通过实现该接口，来创建自定义的视频源，并设置给 sdk 底层的 Media Engine
|
|
实时通讯过程中，SDK 通常会启动默认的视频输入设备，即内置的摄像头，进行视频推流。 使用 ARVideoSourceProtocol 接口可以自定义视频源。通过调用 设置视频源 setVideoSource 接口，可以改变并控制默认的视频输入设备，再将自定义的视频源发送给 Media Engine，让 Media Engine 进行其它视频处理，如过滤视频、将视频发布到 RTC 链接等。
|
|
*/
|
@protocol ARVideoSourceProtocol <NSObject>
|
@required
|
/** ARVideoFrameConsumer 协议，详见 ARVideoFrameConsumer */
|
@property (strong) id<ARVideoFrameConsumer> _Nullable consumer;
|
/** 初始化视频源
|
|
Media Engine 在初始化视频源的时候会回调此方法。开发者可以在这个方法中做一些准备工作，例如打开 Camera，或者初始化视频源，并通过返回值告诉 Media Engine，自定义的视频源是否已经准备好。
|
|
**Note**
|
|
初始化视频源过程中，开发者需要在 bufferType 中指定一种 Buffer 类型，并在自定义视频源中只使用与其对应的方法来传递视频帧数据。
|
|
在初始化视频源过程中，Media Engine 会传递给开发者的一个 ARVideoFrameConsumer 对象。开发者需要保存该对象，并在视频源启动后，通过这个对象把视频帧输入给 Media Engine。
|
|
开发者需要手动输入 YES 或 NO，以告诉 Media Engine 自定义视频源是否已准备好。
|
|
@return 初始化状态：
|
* YES: 自定义的视频源已经完成了初始化工作
|
* NO: 自定义的视频源设备没准备好或者初始化失败，Media Engine 会停下来并上报错误
|
*/
|
- (BOOL)shouldInitialize;
|
|
/** 启动视频源
|
|
Media Engine 在启动视频源时会回调这个方法。开发者可以在该方法中启动视频帧捕捉。开发者需要通过返回值告诉告知 Media Engine 自定义的视频源是否开启成功。
|
|
开发者需要手动输入 YES 或 NO，以告诉 Media Engine 自定义视频源是否开启：
|
|
* YES:自定义的视频源已成功开启，接下来会打开 ARVideoFrameConsumer 的开关，接收开发者传输的视频帧
|
* NO：自定义的视频源设备启动失败，Media Engine 会停下来并上报错误
|
*/
|
- (void)shouldStart;
|
|
/** 停止视频源
|
|
Media Engine 在停止视频源的时候会回调这个方法。开发者可以在这个方法中停止视频的采集。Media Engine 通过这个回调通知开发者，ARVideoFrameConsumer 的帧输入开关即将关闭，之后输入的视频帧都会被丢弃。
|
*/
|
- (void)shouldStop;
|
|
/** 释放视频源
|
|
Media Engine 通知开发者视频源即将失效，开发者可以在这个方法中关闭视频源设备。引擎会销毁 ARVideoFrameConsumer 对象，开发者需要确保在此回调之后不再使用它。
|
*/
|
- (void)shouldDispose;
|
|
/** 获取 Buffer 类型
|
|
Media Engine 在初始化的时候，会调用这个方法来查询该视频源所使用的 Buffer 类型。开发者必须指定且只能指定一种 Buffer 类型并通过返回值告诉 Media Engine
|
|
@return ARVideoBufferType
|
*/
|
- (ARVideoBufferType)bufferType;
|
|
@end
|
|
/** ARVideoSinkProtocol 协议
|
|
ARVideoSinkProtocol 定义了一套协议，开发者通过实现该接口，来创建自定义的视频渲染器，并设置给底层的 Media Engine。
|
|
实时通讯过程中，SDK 通常会启动默认的视频渲染器进行视频渲染。 ARVideoSinkProtocol 可以自定义视频渲染器，再通过调用 设置本地视频渲染器 setLocalVideoRenderer 和 设置远端视频渲染器 setRemoteVideoRenderer 接口，改变并控制默认的视频渲染器。
|
|
ARVideoSinkProtocol 由以下方法组成:
|
|
- 初始化渲染器(shouldInitialize)
|
- 启动渲染器 (shouldStart)
|
- 停止渲染器 (shouldStop)
|
- 释放渲染器 (shouldDispose)
|
- 获取 Buffer 类型 (AgoraVideoBufferType)
|
- 获取像素格式 (AgoraVideoPixelFormat)
|
- (可选) 输出视频像素 Buffer (renderPixelBuffer)
|
- (可选) 输出视频裸数据 (renderRawData)
|
Note: ARVideoSinkProtocol 接口中定义的所有方法都是回调方法，Media Engine 内部维护着状态机，并使用这些方法将自定义视频源及渲染器的状态传给 Media Engine。因此请避免直接在 App 中直接调用这些接口。 下面这个例子给出了自定义 video sink 的步骤：
|
|
- 调用 bufferType 和 AgoraVideoPixelFormat 方法设置视频帧的 Buffer 类型和像素格式。
|
- 实现 shouldInitialize、shouldStart、shouldStop 和 shouldDispose 管理自定义的 Video Sink。
|
- 根据 ARVideoFrameConsumer 实现 buffer 类型和像素格式。
|
- 创建 ARVideoFrameConsumer 自定义的 Video Sink 对象。
|
- 调用 setLocalVideoRenderer 和 setRemoteVideoRenderer 方法设置本地和远端视频渲染器。
|
- Media Engine 会根据内部状态调用 ARVideoSinkProtocol 接口中的方法。
|
*/
|
@protocol ARVideoSinkProtocol <NSObject>
|
@required
|
/** 初始化渲染器
|
|
Media Engine 初始化渲染器的时候调用这个方法。开发者可以在这个方法中做渲染器的初始化工作。如果是耗时操作，也可以提前初始化好，然后在这个方法中通过返回值告知 Media Engine 自定义渲染器已初始化好。 该方法需要开发者手动输入 YES 或 NO，告知 Media Engine 自定义渲染器的状态。
|
|
@return - YES: Media Engine 会认为自定义的渲染器已经初始化好
|
- NO: Media Engine 会认为自定义的渲染器初始化失败，不继续往下运行
|
*/
|
- (BOOL)shouldInitialize;
|
|
/** 启动渲染器
|
|
Media Engine 在开启渲染功能的时候会回调这个方法。开发者可以在这个方法中启动渲染器。 该方法需要开发者手动输入 YES 或 NO，Media Engine 会根据输入值做对应的动作：
|
|
- YES: Media Engine 继续进行渲染
|
- NO：Media Engine 认为出错而停止渲染器的功能
|
*/
|
- (void)shouldStart;
|
|
/** 停止渲染器
|
|
Media Engine 在停止渲染功能的时候会回调这个方法。开发者可以在这个方法中停止渲染。
|
*/
|
- (void)shouldStop;
|
|
/** 释放渲染器
|
|
Media Engine 通知开发者渲染器即将被废弃。在 shouldDispose 返回之后，开发者就可以释放掉资源了。
|
*/
|
- (void)shouldDispose;
|
|
/** 获取 Buffer 类型
|
|
用于在自定义渲染器的时候，需要指定 Buffer 类型，通过返回值告知引擎。Media Engine 会调用这个方法并检查返回值类型。
|
|
@return Buffer 类型
|
*/
|
- (ARVideoBufferType)bufferType;
|
|
/** 获取像素格式
|
|
@return 用于自定义渲染器的时候，还需要指定视频数据的像素格式。
|
*/
|
- (ARVideoPixelFormat)pixelFormat;
|
|
@optional
|
/** （可选）输出视频的 PixelBuffer
|
|
@param pixelBuffer 视频的 PixelBuffer
|
@param rotation 视频像素的顺时针旋转角度, ARVideoRotation
|
*/
|
- (void)renderPixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer rotation:(ARVideoRotation)rotation;
|
|
/** 输出视频裸数据
|
|
@param rawData RawData 格式的视频
|
@param size 视频的尺寸
|
@param rotation 视频的顺时针旋转角度, ARVideoRotation
|
*/
|
- (void)renderRawData:(void * _Nonnull)rawData size:(CGSize)size rotation:(ARVideoRotation)rotation;
|
@end
|
