接口说明-特效

特效SDK针对视频或者图片进行特效处理，包括美颜、美形、美体、美妆、滤镜和各种有趣的贴纸，主要应用在短视频、直播、图片修图等场景。

我们的接口支持的输入和输出格式如下表所示：

因为图像特效类算法主要在GPU中完成图像的处理和渲染过程，因此我们建议使用glTexture2D作为输入，从而减少数据在CPU内存和显存中进出导致的时间损耗；如果使用其他格式的数据作为输入，我们在底层使用Shader完成buffer数据向纹理的转换，再执行特效处理,这种方式会增加性能开销。

特效是多个功能的集合， 包括美颜、滤镜、美妆和贴纸等，其相关接口定义在头文件bef_effect_ai_api.h中。特效算法同时支持纹理输入和Buffer数据输入，具体支持的格式参考。

接口说明

1. 创建特效句柄

BEF_SDK_API
bef_effect_result_t bef_effect_ai_create(
bef_effect_handle_t *handle
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

2. 特效句柄授权

#ifdef __ANDROID__  
BEF_SDK_API
bef_effect_result_t bef_effect_ai_check_license(   
JNIEnv* env,  
jobject context,  
bef_effect_handle_t handle,  
const char *license_path   
);  
#else  
BEF_SDK_API
bef_effect_result_t bef_effect_ai_check_license(  
bef_effect_handle_t handle,   
const char *license_path
);  
#endif

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

3. 初始化特效句柄

在对特效句柄进行后续调用前，必须对该句柄进行授权码的验证，否则，后续调用都会失败。

BEF_SDK_API
bef_effect_result_t bef_effect_ai_init(
bef_effect_handle_t handle,
int width,
int height,
const char  *strModelDir,
const char * deviceName
);

初始化特效句柄时，请确保strModelDir是包含我们提供的深度学习模型的

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

如果需要使用叠加特效功能（美颜、美形、美体、美妆等），还需要再进行 composer 初始化或者设置 composer 与贴纸共存，使用方式参考 18. 设置叠加特效是否与贴纸共存 19. 初始化 composer。

4. 设置输入帧宽高

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_width_height(
bef_effect_handle_t handle,
int width,
int height
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

5. 设置手机角度

设置手机的设备旋转角度，在处理图像数据之前必须设置手机当前的旋转角度。

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_orientation(
bef_effect_handle_t handle,
bef_ai_rotate_type orientation
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

6. 设置美颜类型

设置美颜（磨皮、锐化）的资源

BEF_SDK_API 
bef_effect_result_t bef_effect_ai_set_beauty(
bef_effect_handle_t handle,
const char *strBeautyName
);

此接口适用于 2.6 版本及之前设置美颜，在 2.7 版本之后请务必使用 bef_effect_ai_composer_set_nodes 接口设置美颜等

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

7. 设置美妆类型

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_buildin_makeup(
bef_effect_handle_t handle,
const char* strMakeupName
);

此接口适用于 2.6 版本及之前设置美妆，在 2.7 版本之后请务必使用 bef_effect_ai_composer_set_nodes 接口设置美妆等
参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

8. 设置美形类型

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_reshape_face(
bef_effect_handle_t handle,
const char *strPath
);

此接口适用于 2.6 版本及之前设置美形，在 2.7 版本之后请务必使用 bef_effect_ai_composer_set_nodes 接口设置美形等
参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

9. 设置美形强度

BEF_SDK_API
bef_effect_result_t bef_effect_ai_update_reshape_face(
bef_effect_handle_t handle,
const float fIntensity
);

此接口适用于 2.6 版本及之前设置美形强度，在 2.7 版本之后请务必使用 bef_effect_ai_composer_update_node 接口设置美形强度等
参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

BEF_SDK_API
bef_effect_result_t bef_effect_ai_update_reshape_face_intensity(
bef_effect_handle_t handle,
const float eyeIntensity,
const float cheekIntensity
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

10. 设置左右切换效果的滤镜

BEF_SDK_API
bef_effect_result_t bef_effect_ai_switch_color_filter_v2(
bef_effect_handle_t handle,
const char *leftFilterPath,
const char *rightFilterPath,
float position
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

11. 设置滤镜

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_color_filter_v2(
bef_effect_handle_t handle,
const char *strPath
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

12. 设置贴纸

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_effect(
bef_effect_handle_t handle,
const char *strPath
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

13. 执行算法检测

支持纹理输入的接口

BEF_SDK_API
bef_effect_result_t bef_effect_ai_algorithm_texture(
bef_effect_handle_t handle,
unsigned int textureid_src,
double timeStamp
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
支持 buffer 输入接口
该接口无法支持并行渲染，如有需要，直接使用 bef_effect_ai_algorithm_texture_with_buffer

BEF_SDK_API bef_effect_result_t
bef_effect_ai_algorithm_buffer(
        bef_effect_handle_t handle,
        const unsigned char *img_in,
        bef_ai_pixel_format fmt_in,
        int image_width,
        int image_height,
        int image_stride,
        double timestamp
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h
支持纹理和算法同时输入
本接口可同时传入纹理和 buffer，也可单独传入纹理或 buffer，单独传纹理时，效果与 bef_effect_ai_algorithm_texture 一致。

BEF_SDK_API bef_effect_result_t bef_effect_ai_algorithm_texture_with_buffer(bef_effect_handle_t handle,
                                                                            unsigned int texture,
                                                                            const unsigned char *buffer,
                                                                            bef_ai_pixel_format buffer_format,
                                                                            int buffer_width,
                                                                            int buffer_height,
                                                                            int buffer_stride,
                                                                            double timeStamp);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

14. 执行特效处理

支持纹理输入的接口

BEF_SDK_API
bef_effect_result_t bef_effect_ai_process_texture(
bef_effect_handle_t handle,
unsigned int srcTexture,
unsigned int dstTexture,
double timeStamp
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

15. 设置强度

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_intensity(
bef_effect_handle_t handle,
bef_intensity_type intensityType,
float fIntensity
);

此接口适用于 2.6 版本及之前设置美颜强度，在 2.7 版本之后请务必使用 bef_effect_ai_composer_update_node 接口设置美颜强度等
此外，所有版本设置滤镜强度都使用此接口

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

16. 设置叠加特效（美颜、美形、美妆）

BEF_SDK_API
bef_effect_result_t bef_effect_ai_composer_set_nodes(
bef_effect_handle_t handle,
const char *nodePaths[],
int nodeNum
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

17. 设置特效强度（美颜、美形、美妆）

BEF_SDK_API
bef_effect_result_t bef_effect_ai_composer_update_node(
bef_effect_handle_t handle,
const char *nodePath,
const char *nodeTag,
float value
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

18. 设置叠加特效是否与贴纸共存

说明

本函数需要在初始化时设置。

BEF_SDK_API 
bef_effect_result_t bef_effect_ai_composer_set_mode(
bef_effect_handle_t handle, 
int mode, 
int orderType);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

19. 初始化 composer

说明

在 SDK 中存在两种特效，分别是叠加特效（包括美颜、美形、美体、美妆等）和贴纸（包括贴纸、animoji 等），在叠加特效与贴纸不共存的环境中（是否共存需要通过 bef_effect_ai_composer_set_mode 设置，默认不共存），如果需要使用叠加特效的功能，需要先调用此函数初始化 composer ，而在特效与贴纸共存的环境中，无须调用此函数。

BEF_SDK_API
bef_effect_result_t bef_effect_ai_set_composer(
bef_effect_handle_t handle,
const char *strPath
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

20. 获取人脸检测结果

BEF_SDK_API 
bef_effect_result_t bef_effect_ai_get_face_detect_result(
  bef_effect_handle_t handle, 
  bef_ai_face_info* result);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

21. 获取人手检测结果

BEF_SDK_API
bef_effect_result_t bef_effect_ai_get_hand_detect_result(
  bef_effect_handle_t handle, 
  bef_ai_hand_info *result);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

22. 获取人体检测结果

BEF_SDK_API
bef_effect_result_t bef_effect_ai_get_skeleton_detect_result(
  bef_effect_handle_t handle, 
  bef_ai_skeleton_result *result);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

23. 设置触摸事件

有些贴纸会使用到触摸事件，此时调用此函数将上层捕获到的事件传递给 sdk 以保证贴纸效果正常触发。

BEF_SDK_API 
bef_effect_result_t bef_effect_ai_process_touch_event(bef_effect_handle_t handle, 
	float x, float y);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

24. 设置并行渲染

默认关，开启之后 sdk 内部会将算法检测和特效渲染放在不同线程处理，以加速 sdk 处理。

BEF_SDK_API bef_effect_result_t bef_effect_ai_use_pipeline_processor(bef_effect_handle_t handle, bool usePipeline);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

25. 设置并行渲染多输入

并行渲染开启后，由于算法检测和特效渲染非线性，为了支持多线程处理，需要避免处理过程中连续帧的纹理 id/buffer 内存为同一个。
当该开关关闭时，表示上层传进来的连续帧纹理 id/buffer 内存为同一个，sdk 则会对传进来的纹理/buffer进行拷贝，以避免互相影响。
当该开关开启时，表示上层对传进来的纹理/buffer做了处理，sdk 不会再进行拷贝。（如上层维护一个纹理数组，循环传入以避免连续帧纹理相同问题，可参考 demo 实现）
默认关闭。

BEF_SDK_API bef_effect_result_t bef_effect_ai_use_3buffer(bef_effect_handle_t handle, bool use3buffer);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

26. 清空并行渲染数据

并行渲染开启后，由于算法检测和特效渲染非线性，为了支持多线程处理，sdk 内部会保存上一帧的图像。当画面有可能会不连续（如切换相机，暂停等）的时候，可能会出现画面重新开始播放时闪现上一次画面最后一帧的情况，此时可以在画面不连续的时候调用此函数，清空 sdk 内部的缓存。

BEF_SDK_API bef_effect_result_t bef_effect_ai_clean_pipeline_processor_task(bef_effect_handle_t handle)

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

27. 销毁句柄

BEF_SDK_API
void bef_effect_ai_destroy(
bef_effect_handle_t handle
);

参数说明

返回值
成功返回 BEF_RESULT_SUC, 失败返回相应错误码, 具体请参考 bef_effect_ai_public_define.h

特效

特效是多个功能的集合，目前包括美颜、美形、美体、美妆、滤镜、贴纸、Animoj和AR扫一扫。对应的类文件RenderManager.java。

1. 初始化

public int init(
Context context,
String modelDir,
String licensePath
)

参数说明

返回值

成功返回BEF_RESULT_SUC，否则返回对应的错误码

2. 设置美颜素材

public boolean setBeauty(String resourcePath)

此接口适用于 2.6 版本及之前设置美颜，在 2.7 版本之后请务必使用 setComposerNodes 接口设置美颜等
参数说明

返回值

成功返回true，否则返回对应的错误码

3. 设置美形素材

public boolean setReshape(String resourcePath)

此接口适用于 2.6 版本及之前设置美形，在 2.7 版本之后请务必使用 setComposerNodes 接口设置美形等
参数说明

返回值

成功返回true，否则返回对应的错误码

4. 设置滤镜素材

public boolean setFilter(String resourcePath)

参数说明

返回值

成功返回true，否则返回对应的错误码

5. 设置美妆素材

public boolean setMakeUp(String resourcePath)

此接口适用于 2.6 版本及之前设置美妆，在 2.7 版本之后请务必使用 setComposerNodes 接口设置美妆等
参数说明

返回值

成功返回true，否则返回对应的错误码

6. 设置贴纸素材

public boolean setSticker(String resourcePath)

参数说明

返回值

成功返回true，否则返回对应的错误码

7. 处理纹理输入

public boolean processTexture(
int srcTextureId, 
int dstTextureId, 
int width, int height,
BytedEffectConstants.Rotation rotation,
double timestamp)

说明
该接口接收纹输入，经过SDK处理后完成特效的渲染，需要注意如下问题：
1、请确保输入纹理是texure2d格式，并且图像中人脸已经转正，一般Android设备采集到的纹理格式为GL_TEXTURE_EXTERNAL_OES，并且存在一定角度的旋转（前置270度，后置90度）
2、关于前置摄像头加镜像问题，请在输入纹理进入该接口之前进行镜像处理
3、时间戳是从SurfaceTexture对象中获取到的，如果无法获取SurfaceTexture的时间戳，请咨询我们的技术支持同学
参数说明

返回值

成功返回true，否则返回false

8. 处理buffer数据输入

说明
特效SDK不建议使用buffer输入，原因在输入输出格式中有相关说明。

public boolean processBuffer(
ByteBuffer inputdata, 
BytedEffectConstants.Rotation orient, 
int in_pixformat, 
int imagew, 
int imageh, 
int imagestride, 
byte[] outdata, 
int out_pixformat,
double timestamp)

参数说明

返回值
成功返回true，否则返回false

9. 执行算法检测

说明
此方法需要与 10.执行特效渲染 一起使用，并在其之前调用。它们在一起使用的效果与直接使用单一的 7.处理纹理输入 或 8.处理buffer输入 效果一致，只是把上述两个方法进行了拆分，使得算法检测和特效处理可以分别传入不同的数据类型，以及自由决定调用时间。

处理纹理输入
此方法支持对输入的纹理进行算法检测，也可以同时把对应的 buffer 传递进去，进行加速。

public boolean algorithmTextureWithBuffer(int texture,
ByteBuffer buffer, 
BytedEffectConstants.Rotation orient,
int pixelFormat, 
int width, 
int height,
int stride,
long timeStamp)

参数说明

返回值
成功返回true，否则返回false

处理 buffer 输入
此方法支持对输入的 buffer 进行算法检测。

public boolean algorithmBuffer(ByteBuffer buffer,
BytedEffectConstants.Rotation orient, 
int pixelFormat, 
int width, 
int height,
int stride, 
long timeStamp)

参数说明

返回值
成功返回true，否则返回false

10. 执行特效渲染

说明
此方法需要与 9.执行算法检测 一起使用，否则无法正常渲染。

processTextureOnly(int srcTexture, 
int dstTexture,
int width, 
int height, 
BytedEffectConstants.Rotation rotation, 
long timeStamp)

参数说明

返回值
成功返回true，否则返回false

11. 设置强度

public boolean updateIntensity(
int intensitytype, 
float intensity)

此接口适用于 2.6 版本及之前设置美颜强度，在 2.7 版本之后请务必使用 updateComposerNodes 接口设置美颜强度等
此外，所有版本设置滤镜强度都使用此接口
参数说明

返回值
成功返回BEF_RESULT_SUC， 其他返回值查看{@link BytedEffectConstants}

12. 设置美形参数

public boolean updateReshape(
float cheekintensity, 
float eyeintensity)

此接口适用于 2.6 版本及之前设置美形强度，在 2.7 版本之后请务必使用 updateComposerNodes 接口设置美形强度等
参数说明

返回值
成功返回BEF_RESULT_SUC， 其他返回值查看{@link BytedEffectConstants}

13. 设置叠加特效（美颜、美形、美妆、美体）

public int setComposerNodes(String[] composerNodes)

参数说明

返回值
成功返回BEF_RESULT_SUC， 其他返回值查看{@link BytedEffectConstants}

14. 设置特效强度（美颜、美形、美妆、美体）

public int updateComposerNodes(
String path, 
String key, 
float value)

参数说明

返回值
成功返回BEF_RESULT_SUC， 其他返回值查看{@link BytedEffectConstants}

15. 获取人脸检测结果

public BefFaceInfo getFaceDetectResult();

返回值

成功返回 BefFaceInfo 对象，失败返回 null。

16. 获取人手检测结果

public BefHandInfo getHandDetectResult();

返回值

成功返回 BefHandInfo 对象，失败返回 null。

17. 获取人体检测结果

public BefSkeletonInfo getSkeletonDetectResult();

返回值

成功返回 BefSkeletonInfo 对象，失败返回 null。

18. 销毁句柄

public void release()