视频外部滤镜
1 使用场景
当 SDK 自带的美颜无法满足需求，例如需要做挂件、贴纸，或者美颜效果无法达到预期时，建议开发者使用外部滤镜功能。
对于比较复杂的场景，例如想要用摄像头画面做图层混合，建议开发者使用外部采集方案，这样性能优化的空间会更大。
2 功能简介
考虑到滤镜的性能问题和美颜厂商的多样性，SDK 的视频外部滤镜采用面向对象设计，结合线程模型，帮助用户把外部代码封装成可替换的滤镜组件。
主要结构如下：
ZegoVideoFilterFactory 是外部滤镜的入口，定义了创建、销毁 ZegoVideoFilter 接口，向 SDK 提供管理 ZegoVideoFilter 生命周期的能力。需要调用 setVideoFilterFactory 的地方必须实现该接口。
ZegoVideoFilter 定义最基本的组件功能，包括 allocateAndStart、stopAndDeAllocate，方便 SDK 在直播流程中进行交互。
请注意，SDK会在适当的时机创建和销毁 ZegoVideoFilter，开发者无需担心生命周期不一致的问题。
3 选择合适的外部滤镜
为了实现传输不同数据模型，适配不同线程模型，同时避免实现多余接口，SDK 采用伪 COM 的设计方式。
开发者需要在子类中显式指定一种数据传递类型，SDK 目前支持的类型有：
滤镜类型
说明
BUFFER_TYPE_MEM
异步滤镜(异步传递 RGBA32 的图像数据)
BUFFER_TYPE_ASYNC_PIXEL_BUFFER
Android 不支持
BUFFER_TYPE_SYNC_PIXEL_BUFFER
Android 不支持
BUFFER_TYPE_SURFACE_TEXTURE
当开发者使用该种类型滤镜时，SDK 会调用此滤镜的 getSurfaceTexture 获取 SurfaceTexture 对象
BUFFER_TYPE_HYBRID_MEM_GL_TEXTURE_2D
异步 RGBA32 的图像数据
BUFFER_TYPE_SYNC_GL_TEXTURE_2D
当开发者使用该种滤镜时，SDK 会调用此滤镜的 onProcessCallback 方法
BUFFER_TYPE_ASYNC_I420_MEM
异步 I420 滤镜(异步传递 I420 的图像数据)
SDK 会根据数据类型，实例化不同类型的 client，在调用 allocateAndStart 时传给外部滤镜。
下面将以 BUFFER_TYPE_MEM 类型滤镜为例演示外部滤镜的用法。
4 创建外部滤镜
4.1 创建外部滤镜工厂
下述代码演示了如何创建外部滤镜工厂。工厂保存了 ZegoVideoFilter 的实例，不会反复创建。
public class VideoFilterFactoryDemo extends ZegoVideoFilterFactory {
private int mode = 0;
private ZegoVideoFilter mFilter = null;
public VideoFilterFactoryDemo(int mode) {
this.mode = mode;
}
public ZegoVideoFilter create() {
if (mFilter == null) {
switch (mode) {
case 0:
mFilter = new VideoFilterMemDemo();
break;
case 1:
mFilter = new VideoFilterSurfaceTextureDemo();
break;
case 2:
mFilter = new VideoFilterHybridDemo();
break;
case 3:
mFilter = new VideoFilterSurfaceTextureDemo2();
break;
case 4:
mFilter = new VideoFilterI420MemDemo();
break;
case 5:
mFilter = new VideoFilterGlTexture2dDemo();
break;
}
}
return mFilter;
}
public void destroy(ZegoVideoFilter vf) {
mFilter = null;
}
}请注意：
大部分情况下，ZegoVideoFilterFactory 实例会缓存原有 ZegoVideoFilter 实例，开发者需避免创建新的实例。
开发者必须保证 ZegoVideoFilter 在 create 和 destroy 之间是可用的，请勿直接销毁对象。
4.2 设置外部滤镜工厂
开发者需要使用外部滤镜功能时，需在使用前调用 setVideoFilterFactory 设置外部滤镜工厂对象(此例中的对象为步骤 1 中所创建的 VideoFilterFactoryDemo)。
请注意，如果用户释放了工厂对象，不再需要它时，请调用本接口将其设置为空。
if (useVideoFilter) {
// 外部滤镜
if (mFilterFactory == null) {
VideoFilterFactoryDemo videoFilterFactoryDemo = new VideoFilterFactoryDemo(0);
mFilterFactory = videoFilterFactoryDemo;
}
ZegoLiveRoom.setVideoFilterFactory(mFilterFactory);
} else {
ZegoLiveRoom.setVideoFilterFactory(null);
}4.3 创建外部滤镜
下述代码，以创建BUFFER_TYPE_MEM(异步拷贝图像)类型滤镜为例，开发者可根据需求，参考如下实现步骤。
类定义
ZegoVideoFilterDemo 的类定义如下：
/**
* 异步滤镜设备需要实现 ZegoVideoFilter 协议
*/
public class VideoFilterMemDemo extends ZegoVideoFilter {
@Override
protected void allocateAndStart(Client client) {
...
}
@Override
protected void stopAndDeAllocate() {
...
}
@Override
protected int supportBufferType() {
...
}
@Override
protected synchronized int dequeueInputBuffer(int width, int height, int stride) {
...
}
@Override
protected synchronized ByteBuffer getInputBuffer(int index) {
...
}
@Override
protected synchronized void queueInputBuffer(int bufferIndex, final int width, int height, int stride, long timestamp_100n) {
...
}
...
}指定滤镜类型
SDK 需要根据外部滤镜 supportBufferType 返回的类型值创建不同的 client 对象。在本示例中，返回 BUFFER_TYPE_MEM：
@Override
protected int supportBufferType() {
return BUFFER_TYPE_MEM;
}初始化资源
开发者初始化资源在 allocateAndStart 中进行。
开发者在 allocateAndStart 中获取到 client(SDK 内部实现 ZegoVideoFilter.Client 协议的对象)，用于通知 SDK 处理结果。
SDK 会在 App 第一次预览／推流／拉流时调用 allocateAndStart。除非 App 中途调用过 stopAndDeAllocate，否则 SDK 不会再调用 allocateAndStart。
@Override
protected void allocateAndStart(Client client) {
mClient = client;
mThread = new HandlerThread("video-filter");
mThread.start();
mHandler = new Handler(mThread.getLooper());
mIsRunning = true;
mProduceQueue.clear();
mConsumeQueue.clear();
mWriteIndex = 0;
mWriteRemain = 0;
mMaxBufferSize = 0;
}请注意，client 必须保存为强引用对象，在 stopAndDeAllocate 被调用前必须一直被保存。SDK 不负责管理 client 的生命周期。
释放资源
开发者释放资源在 stopAndDeAllocate 中进行。
建议同步停止滤镜任务后再清理 client 对象，保证 SDK 调用 stopAndDeAllocate 后，没有残留的异步任务导致野指针 crash。正常情况下，如果 SDK 是异步调用外部滤镜，外部滤镜完成前处理后，也按照同样的步骤回调 SDK。
@Override
protected void stopAndDeAllocate() {
mIsRunning = false;
final CountDownLatch barrier = new CountDownLatch(1);
mHandler.post(new Runnable() {
@Override
public void run() {
barrier.countDown();
}
});
try {
barrier.await();
} catch (InterruptedException e) {
e.printStackTrace();
}
mHandler = null;
if (Build.VERSION.SDK_INT >= 18) {
mThread.quitSafely();
} else {
mThread.quit();
}
mThread = null;
mClient.destroy();
mClient = null;
}请注意，开发者必须在 stopAndDeAllocate 方法中调用 client 的 destroy 方法，否则会造成内存泄漏。
SDK 通知外部滤镜当前采集图像的宽高并请求内存池下标
SDK 先调用 ZegoVideoFilter 子类的 int dequeueInputBuffer(int, int, int) 方法，通知外部滤镜当前采集图像的宽高，并请求外部滤镜返回内存池的下标。
@Override
protected synchronized int dequeueInputBuffer(int width, int height, int stride) {
if (stride * height > mMaxBufferSize) {
if (mMaxBufferSize != 0) {
mProduceQueue.clear();
}
mMaxBufferSize = stride * height;
createPixelBufferPool(4);
}
if (mWriteRemain == 0) {
return -1;
}
mWriteRemain--;
return (mWriteIndex + 1) % mProduceQueue.size();
}SDK 请求外部滤镜返回 Direct 的 ByteBuffer
当 SDK 获得外部滤镜内存池下标后，会调用 ByteBuffer getInputBuffer(int) 获取 Direct 的 ByteBuffer，在 C++ 底层执行内存拷贝。
@Override
protected synchronized ByteBuffer getInputBuffer(int index) {
if (mProduceQueue.isEmpty()) {
return null;
}
ByteBuffer buffer = mProduceQueue.get(index).buffer;
buffer.position(0);
return buffer;
}外部滤镜处理数据
当 SDK 拷贝完数据后，会调用 void queueInputBuffer(int, int, int, int, long) 方法通知外部滤镜。外部滤镜应当按照约定的数据传递类型，切换线程，异步进行前处理。
此处的演示代码没有做任何操作，只是在另一个线程进行数据拷贝。拷贝流程和 SDK 调用外部滤镜的步骤类似。开发者应该按照各自需求，实现该方法。
@Override
protected synchronized void queueInputBuffer(int bufferIndex, final int width, int height, int stride, long timestamp_100n) {
if (bufferIndex == -1) {
return ;
}
PixelBuffer pixelBuffer = mProduceQueue.get(bufferIndex);
pixelBuffer.width = width;
pixelBuffer.height = height;
pixelBuffer.stride = stride;
pixelBuffer.timestamp_100n = timestamp_100n;
pixelBuffer.buffer.limit(height * stride);
mConsumeQueue.add(pixelBuffer);
mWriteIndex = (mWriteIndex + 1) % mProduceQueue.size();
mHandler.post(new Runnable() {
@Override
public void run() {
if (!mIsRunning) {
Log.e(TAG, "already stopped");
return ;
}
PixelBuffer pixelBuffer = getConsumerPixelBuffer();
int index = mClient.dequeueInputBuffer(pixelBuffer.width, pixelBuffer.height, pixelBuffer.stride);
if (index >= 0) {
ByteBuffer dst = mClient.getInputBuffer(index);
dst.position(0);
pixelBuffer.buffer.position(0);
dst.put(pixelBuffer.buffer);
mClient.queueInputBuffer(index, pixelBuffer.width, pixelBuffer.height, pixelBuffer.stride, pixelBuffer.timestamp_100n);
}
returnProducerPixelBuffer(pixelBuffer);
}
});
}上述步骤的示例代码可以在目录 app/src/main/java/com/zego/livedemo5/videofilter 下的 VideoFilterFactoryDemo.java 与 VideoFilterMemDemo.java 中找到，具体细节不再赘述。
5 同步滤镜
5.1 创建外部滤镜工厂
下述代码演示了如何创建外部滤镜工厂。工厂保存了 ZegoVideoFilter 的实例，不会反复创建。
public class VideoFilterFactoryDemo extends ZegoVideoFilterFactory {
private int mode = 0;
private ZegoVideoFilter mFilter = null;
public VideoFilterFactoryDemo(int mode) {
this.mode = mode;
}
public ZegoVideoFilter create() {
if (mFilter == null) {
switch (mode) {
case 0:
mFilter = new VideoFilterMemDemo();
break;
case 1:
mFilter = new VideoFilterSurfaceTextureDemo();
break;
case 2:
mFilter = new VideoFilterHybridDemo();
break;
case 3:
mFilter = new VideoFilterSurfaceTextureDemo2();
break;
break;
case 4:
mFilter = new VideoFilterI420MemDemo();
break;
case 5:
mFilter = new VideoFilterGlTexture2dDemo();
break;
}
}
return mFilter;
}
public void destroy(ZegoVideoFilter vf) {
mFilter = null;
}
}请注意：
大部分情况下，ZegoVideoFilterFactory 实例会缓存原有 ZegoVideoFilter 实例，开发者需避免创建新的实例。
开发者必须保证 ZegoVideoFilter 在 create 和 destroy 之间是可用的，请勿直接销毁对象。
5.2 设置外部滤镜工厂
开发者需要使用外部滤镜功能时，需在使用前调用 setVideoFilterFactory 设置外部滤镜工厂对象(此例中的对象为步骤 1 中所创建的 VideoFilterFactoryDemo)。
请注意，如果用户释放了工厂对象，不再需要它时，请调用本接口将其设置为空。
if (useVideoFilter) {
// 外部滤镜
if (mFilterFactory == null) {
VideoFilterFactoryDemo videoFilterFactoryDemo = new VideoFilterFactoryDemo(5);
mFilterFactory = videoFilterFactoryDemo;
}
ZegoLiveRoom.setVideoFilterFactory(mFilterFactory);
} else {
ZegoLiveRoom.setVideoFilterFactory(null);
}
5.3创建外部滤镜
下述代码，以创建BUFFER_TYPE_SYNC_GL_TEXTURE_2D(同步拷贝图像)类型滤镜为例，开发者可根据需求，参考如下实现步骤。
类定义
VideoFilterGlTexture2dDemo 的类定义如下：
/**
* 外部滤镜设备需要实现 ZegoVideoFilter 协议
*/
public class VideoFilterMemDemo extends ZegoVideoFilter {
@Override
protected void allocateAndStart(Client client) {
...
}
@Override
protected void stopAndDeAllocate() {
...
}
@Override
protected int supportBufferType() {
...
}
@Override
protected void onProcessCallback(int textureId, int width, int height, long timestamp_100n) {
...
}
...
}指定滤镜类型
SDK 需要根据外部滤镜 supportBufferType 返回的类型值创建不同的 client 对象。在本示例中，返回 BUFFER_TYPE_SYNC_GL_TEXTURE_2D：
@Override
protected int supportBufferType() {
return BUFFER_TYPE_SYNC_GL_TEXTURE_2D;
}初始化资源
开发者初始化资源在 allocateAndStart 中进行。
开发者在 allocateAndStart 中获取到 client(SDK 内部实现 ZegoVideoFilter.Client 协议的对象)，用于通知 SDK 处理结果。
SDK 会在 App 第一次预览／推流／拉流时调用 allocateAndStart。除非 App 中途调用过 stopAndDeAllocate，否则 SDK 不会再调用 allocateAndStart。
@Override
protected void allocateAndStart(Client client) {
mClient = client;
mWidth = mHeight = 0;
if (mDrawer == null) {
mDrawer = new GlRectDrawer();
}
}请注意，client 在 stopAndDeAllocate 被调用前必须一直被保存。
释放资源
开发者释放资源在 stopAndDeAllocate 中进行。
建议同步停止滤镜任务后再清理 client 对象，保证 SDK 调用 stopAndDeAllocate 后，没有残留的异步任务导致野指针 crash。正常情况下，如果 SDK 是异步调用外部滤镜，外部滤镜完成前处理后，也按照同样的步骤回调 SDK。
@Override
protected void stopAndDeAllocate() {
if (mTextureId != 0) {
int[] textures = new int[]{mTextureId};
GLES20.glDeleteTextures(1, textures, 0);
mTextureId = 0;
}
if (mFrameBufferId != 0) {
int[] frameBuffers = new int[]{mFrameBufferId};
GLES20.glDeleteFramebuffers(1, frameBuffers, 0);
mFrameBufferId = 0;
}
if (mDrawer != null) {
mDrawer.release();
mDrawer = null;
}
mClient.destroy();
mClient = null;
}请注意，开发者必须在 stopAndDeAllocate 方法中调用 client 的 destroy 方法，否则会造成内存泄漏。
绘制图像数据
SDK 会通过调用外部滤镜的 void onProcessCallback(int, int, int height, long) 方法通知外部滤镜采集的结果，然后外部滤镜在同一线程进行前处理，再通过调用 client 的 onProgressCallback 通知 SDK 前处理的结果。
@Override
protected void onProcessCallback(int textureId, int width, int height, long timestamp_100n) {
if (mWidth != width || mHeight != height) {
if (mTextureId != 0) {
int[] textures = new int[]{mTextureId};
GLES20.glDeleteTextures(1, textures, 0);
mTextureId = 0;
}
if (mFrameBufferId != 0) {
int[] frameBuffers = new int[]{mFrameBufferId};
GLES20.glDeleteFramebuffers(1, frameBuffers, 0);
mFrameBufferId = 0;
}
mWidth = width;
mHeight = height;
}
if (mTextureId == 0) {
GLES20.glActiveTexture(GLES20.GL_TEXTURE1);
mTextureId = GlUtil.generateTexture(GLES20.GL_TEXTURE_2D);
GLES20.glTexImage2D(GLES20.GL_TEXTURE_2D, 0, GLES20.GL_RGBA, width, height, 0, GLES20.GL_RGBA, GLES20.GL_UNSIGNED_BYTE, null);
mFrameBufferId = GlUtil.generateFrameBuffer(mTextureId);
} else {
GLES20.glBindFramebuffer(GLES20.GL_FRAMEBUFFER, mFrameBufferId);
}
GLES20.glClear(GLES20.GL_COLOR_BUFFER_BIT);
mDrawer.drawRgb(textureId, transformationMatrix,
width, height, 0, 0, width, height);
mClient.onProcessCallback(mTextureId, width, height, timestamp_100n);
}SDK 不推荐使用这种方式实现外部滤镜，因为在同一线程中，OpenGL ES 的上下文、设置、uniform、attribute 是共用的，倘若对 OpenGL ES 不是很熟悉，极易在细节上出现不可预知的 Bug
上述步骤的示例代码可在 app/src/main/java/com/zego/livedemo5/videofilter 目录下的 VideoFilterFactoryDemo.java 和 VideoFilterGlTexture2dDemo.java 中找到。其它类型外部滤镜的示例代码亦可在 app/src/main/java/com/zego/livedemo5/videofilter 下找到，具体细节不再赘述。
6 Q&A
ZegoVideoFilterFactory的子类什么时候释放？
我们推荐把工厂的实例保存为单例，仅作为 SDK 管理外部滤镜生命周期的通道，开发者可以为工厂子类添加 setter 和 getter，一起管理滤镜的生命周期。
如何使用BUFFER_TYPE_ASYNC_I420_MEM方式传递数据？
BUFFER_TYPE_ASYNC_I420_MEM和BUFFER_TYPE_MEM并无本质区别，只是BUFFER_TYPE_ASYNC_I420_MEM颜色空间是I420，而BUFFER_TYPE_MEM是RGBA32，两者同样都是需要异步实现。
如何使用BUFFER_TYPE_SURFACE_TEXTURE方式传递数据？
选择BUFFER_TYPE_SURFACE_TEXTURE方式时，开发者可以通过client获取SurfaceTexture对象，转换成EglSurface，用于OpenGL ES绘制，同时SDK也要求外部滤镜显式实现ZegoVideoFilter的getSurfaceTexture作为滤镜的输入。
如果对于这个机制不太熟悉，开发者可以参考TextureView.getSurfaceTexture或者MediaCode.createInputSurface。SurfaceTexture作为官方推荐的一种传输数据的管道，在许多系统Api中都有使用，包括android.hardware.camera、android.media.MediaCodec等。
因为没有显式传递图像宽高和时间戳的接口，需要借助SurfaceTexture的setDefaultBufferSize方法设置图像宽高，然后SDK可以通过系统Api获取后续的图像宽高。注意这里的宽高必须和后续的glViewport的宽高保持一致，避免图像变形。具体请参考VideoCaptureFromImage.java。
如何使用BUFFER_TYPE_HYBRID_MEM_GL_TEXTURE_2D方式传递数据？
选择BUFFER_TYPE_HYBRID_MEM_GL_TEXTURE_2D方式时，SDK会按顺序依次调用外部滤镜的dequeueInputBuffer、getInputBuffer、queueInputBuffer方法，向外部滤镜传递数据，而外部滤镜调用client的onProcessCallback向SDK传递包含前处理结果的texture。
请注意：
这里的线程模型是异步的，即SDK调用dequeueInputBuffer、getInputBuffer、queueInputBuffer在SDK线程，外部滤镜前处理调用client的onProcessCallback在外部滤镜的工作线程，同时外部滤镜应确保每次执行OpenGL ES绘制时调用makeCurrent及glViewport，否则会产生不可预知的错误。
开发者必须在 stopAndDeAllocate 方法中，切换到对应的工作线程，再调用 client 的 destroy 方法。因为采用这种方式，SDK会共享线程的上下文，销毁时，如果缺少对应的上下文，可能会出现不可预知的情况。
几种外部滤镜类型在实现上的主要区别是什么？
当数据类型为BUFFER_TYPE_MEM、BUFFER_TYPE_HYBRID_MEM_GL_TEXTURE_2D、BUFFER_TYPE_ASYNC_I420_MEM类型的外部滤镜时，SDK会按照dequeueInputBuffer、getInputBuffer、queueInputBuffer的顺序调用外部滤镜的接口。
BUFFER_TYPE_MEM与BUFFER_TYPE_HYBRID_MEM_GL_TEXTURE_2D类型数据均为RGBA32图像数据；BUFFER_TYPE_ASYNC_I420_MEM类型数据为I420图像数据.
当数据类型为BUFFER_TYPE_SURFACE_TEXTURE类型的外部滤镜时，SDK会调用外部滤镜的getSurfaceTexture方法。
当数据类型为BUFFER_TYPE_SYNC_GL_TEXTURE_2D类型的外部滤镜时，SDK会调用外部滤镜的onProcessCallback方法。
为什么BUFFER_TYPE_MEM这么复杂？
BUFFER_TYPE_MEM完全参考MediaCodec的dequeueInputBuffer
、getInputBuffer、queueInputBuffer的流程实现。因为Android平台没有一个类似于iOS的CVPixelBufferRef的结构体，dequeueInputBuffer和getInputBuffer是为了方便开发者保存每一帧数据故意设计成两个接口，SDK只关心核心的内存拷贝，但是外部滤镜还需要保存图像的宽高。
为什么使用ByteBuffer而不使用byte[]访问内存？
ByteBuffer是Java提供的直接访问C++内存的方法，SDK的核心逻辑是跨平台C++实现的，外部滤镜的实际内存是通过C++管理。为了避免C++堆到Java堆上多余的拷贝，所以选择ByteBuffer。ByteBuffer在Java层可以通过ByteBuffer.allocateDirect方法指定分配内存到C++堆上，在C++层可以通过jenv->NewDirectByteBuffer方法包裹成Java对象，使用起来并不会比byte[]麻烦。同时Android api对ByteBuffer的支持也很友好，比如OpenGL ES里面上传贴图glTexImage2D明确指定需要java.nio.Buffer，Bitmap.copyPixelsFromBuffer也支持java.nio.Buffer。
如何创建SurfaceTexture？
首先当前线程需要attach OpenGL ES上下文，即调用eglMakeCurrent，然后生成类型为GLES11Ext.GL_TEXTURE_EXTERNAL_OES的texture，最后通过SurfaceTexture的构造函数实例化。注意这里的attach OpenGL ES上下文，并没有要求必须是TextureView的回调或者是SurfaceView的回调，开发者完全可以自己创建线程，构造EglContext、EglSurface，和系统控件没有任何联系。具体请参考VideoCaptureFromImage.java实现。
RGBA32和I420的内存是如何排布的？
如何获取摄像头的旋转角度？
当开发者使用美颜厂商提供的SDK时，绝大部分需要指定摄像头的旋转角度。考虑到美颜厂商SDK的兼容性问题，SDK对于任何一种方式传递的图像数据都进行了纠正，即正朝向，开发者不需要关心摄像头旋转多少度。
