Android Nama Java API 参考文档

1. 简介

本文是相芯人脸跟踪及视频特效开发包（以下简称 Nama SDK）的底层接口文档。该文档中的 Nama API 为底层 native 接口，可以直接用于 PC/iOS/Android NDK/Linux 上的开发。其中，iOS和Android平台上的开发可以利用SDK的应用层接口（Objective-C/Java），相比本文中的底层接口会更贴近平台相关的开发经验。

SDK相关的所有调用要求在同一个线程中顺序执行，不支持多线程。少数接口可以异步调用（如道具加载），会在备注中特别注明。SDK所有渲染线程调用的接口需要保持 OpenGL context 一致，否则会引发纹理数据异常。如果需要用到SDK的绘制功能，则渲染线程的所有调用需要预先初始化OpenGL环境，没有初始化或初始化不正确会导致崩溃。我们对OpenGL的环境要求为 GLES 2.0 以上。具体调用方式，可以参考各平台 demo。

底层接口根据作用逻辑归为六类：初始化、加载道具、主运行接口、销毁、功能接口、P2A相关接口。

2. APIs

2.1 初始化

fuSetup 初始化接口

@Deprecated

public static native int fuSetup(byte[] v3data, byte[] ardata, byte[] authdata);

public static native int fuSetup(byte[] v3data, byte[] authdata);

接口说明：

初始化系统环境，加载系统数据，并进行网络鉴权。必须在调用SDK其他接口前执行，否则会引发崩溃。

第一个接口已废弃，建议采用第二个。

参数说明：

v3data v3.bundle 字节数组。**注意：**SDK 6.6.0 后 v3 不再使用，该参数传 new byte[0] 即可。

ardata 已废弃，传 null 即可

authdata 鉴权数据字节数组

返回值：

返回非0值代表成功，返回0代表失败。如初始化失败，可以通过 fuGetSystemError 获取错误代码。

备注：

App 启动后只需要 setup 一次即可，其中 authpack.A() 鉴权数据声明在 authpack.java 中。必须配置好有效的证书，SDK 才能正常工作。

根据应用需求，鉴权数据也可以运行时提供（如网络下载），不过要注意证书泄露风险，防止证书被滥用。

fuSetupLocal 离线初始化接口

初始化系统环境，加载系统数据，并进行离线鉴权。必须在调用SDK其他接口前执行，否则会引发崩溃。

public static native byte[] fuSetupLocal(byte[] v3data, byte[] authdata, byte[] offlinedata);

接口说明：

初始化系统环境，加载系统数据，并进行离线鉴权。必须在调用SDK其他接口前执行，否则会引发崩溃。

参数说明：

v3data v3.bundle 字节数组。**注意：**SDK 6.6.0 后 v3 不再使用，该参数传 new byte[0] 即可。

authdata 鉴权数据字节数组

offlinedata 离线鉴权数据字节数组，第一次调用传 null，之后调用传该函数返回值。

返回值：

云端返回的鉴权数据，需要保存到本地，用于离线鉴权，使用时作为 offlinedata 参数。

备注：

App 启动后只需要 setup 一次即可，其中 authpack.A() 鉴权数据声明在 authpack.java 中。必须配置好有效的证书，SDK 才能正常工作。

根据应用需求，鉴权数据也可以运行时提供（如网络下载），不过要注意证书泄露风险，防止证书被滥用。

第一次使用需要联网鉴权，鉴权成功后返回离线证书，请妥善保存离线证书数据。之后使用不需要联网。

如果初始化失败，可以通过 fuGetSystemError 获取错误代码。

fuIsLibraryInit 检测接口是否已经初始化

接口说明：

检测接口是否已经初始化。

public static native int fuIsLibraryInit();

返回值:

返回状态0为未初始化，1为已初始化。

fuCreateTexForItem 为特定道具创建纹理

**接口说明：**为特定的道具创建纹理，并将纹理 id 设置给道具参数，供道具使用。

public static native int fuCreateTexForItem(int item, String name, byte[] value, int width, int height);

参数:
item：道具 handle name ：道具参数名 value：图片 RGBA buffer width：图片宽度 height：图片高度 返回值:

返回状态 0 为失败，1 为成功。

fuDeleteTexForItem 释放创建的纹理

**接口说明：**释放由 fuCreateTexForItem 创建纹理。

public static native int fuDeleteTexForItem(int item, String name);

参数:
item：道具 handle name：道具参数名 返回值:

返回状态 0 为失败，1 为成功。

fuSetDefaultRotationMode 设置默认的人脸朝向

**接口说明：**设置默认的人脸朝向。

public static native void fuSetDefaultRotationMode(int rotationMode);

参数:

rotationMode：要设置的人脸朝向，取值范围为 0-3，分别对应人脸相对于图像数据旋转0度、90度、180度、270度。

备注:

Android 平台的原生相机数据为横屏，需要进行该设置加速首次识别。根据经验，Android 前置摄像头一般设置参数 1，后置摄像头一般设置参数 3，部分手机存在例外。取值与设备方向和相机方向有关，自动计算的代码可以参考 FULiveDemo 中 FURenderer 类相关方法。

旧接口 fuSetDefaultOrientation 已废弃，请使用 fuSetDefaultRotationMode 设置。

fuSetFaceProcessorDetectMode 设置人脸识别模式

**接口说明：**SDK人脸识别模式分为图片模式和视频模式。图片模式更为及时，视频模式性能更优。

public static native int fuSetFaceProcessorDetectMode(int mode);

参数:

in]：0为图像模式，1为视频模式。

返回值:

1为成功，0为失败。

fuSetInputCameraMatrix 设置输入纹理的转正方式

**接口说明：**为 fuRenderBundles、fuRenderBundlesWithCamera、fuRenderBundlesSplitView 函数，设置输入纹理的转正方式，转为人像竖屏模式。

public static native void fuSetInputCameraMatrix(int flip_x, int flip_y, int rotate_mode);

参数:

flip_x：水平翻转输入。 flip_y：垂直翻转输入。 rotate_mode：旋转输入，0为0度，1为90度，2为180度，3为270度。

fuRotateImage 函数

旋转或者翻转图像。

public static native int fuRotateImage(RotatedImage outImage, byte[] inputImage, int imageFormat, int inputWidth, int inputHeight, int rotateMode, int flipX, int flipY);

参数:

outImage：输出图像 inputImage：输入图像 imageformat：输入图像的格式。 inputWidth：输入图像的宽。 inputHeight：输入图像的高。 ``rotateMode：旋转输入，0为0度，1为90度，2为180度，3为270度。 flipX：水平翻转输入。 flip_Y`：垂直翻转输入。

返回值：

int 返回 1 代表成功，返回 0 代表失败。

fuLoadAIModelFromPackage 加载 AI 模型接口

接口说明：

SDK6.6.0 新增接口，在fuSetup后，可以预先加载未来可能需要使用到的AI能力。AI模型和SDK一起发布，在Assets目录下。该函数不需要 GL 环境，可以异步调用。

public static native int fuLoadAIModelFromPackage(byte[] data, int type);

参数说明:

data： 内存指针，指向SDK提供的 ai****.bundle 文件内容，为AI能力模型。

type：描述bundle对应的AI能力类型，如下：

typedef enum FUAITYPE{

         FUAITYPE_BACKGROUNDSEGMENTATION=1<<1,//背景分割,7.0.0及以上版本可使用FUAITYPE_HUMAN_PROCESSOR_SEGMENTATION

         FUAITYPE_HAIRSEGMENTATION=1<<2,              //头发分割，7.0.0及以上版本可使用FUAITYPE_FACEPROCESSOR_HAIRSEGMENTATION

         FUAITYPE_HANDGESTURE=1<<3,                   //手势识别

         FUAITYPE_TONGUETRACKING=1<<4,                //暂未使用

         FUAITYPE_FACELANDMARKS75=1<<5,               //废弃

         FUAITYPE_FACELANDMARKS209=1<<6,              //废弃

         FUAITYPE_FACELANDMARKS239=1<<7,              //高级人脸特征点，7.0.0之后实际为241点

         FUAITYPE_HUMANPOSE2D=1<<8,                   //2D身体点位，7.0.0及以上版本可使用FUAITYPE_HUMAN_PROCESSOR_2D_DANCE

         FUAITYPE_BACKGROUNDSEGMENTATION_GREEN=1<<9,//绿幕分割

         FUAITYPE_FACEPROCESSOR=1<<10，                                 //人脸算法模块，默认带低质量高性能表情跟踪

         FUAITYPE_FACEPROCESSOR_FACECAPTURE = 1 << 11, //高质量表情跟踪

         FUAITYPE_FACEPROCESSOR_FACECAPTURE_TONGUETRACKING = 1 << 12,     //高质量表情跟踪模式下额外进行舌头追踪

         FUAITYPE_FACEPROCESSOR_HAIRSEGMENTATION = 1 << 13,     //人脸算法模式下进行头发分割

         FUAITYPE_FACEPROCESSOR_HEADSEGMENTATION = 1 << 14,     //人脸算法模式下进行头部分割

         FUAITYPE_FACEPROCESSOR_EXPRESSION_RECOGNIZER = 1 << 15, //表情识别

         FUAITYPE_HUMAN_PROCESSOR = 1 << 16,                   //人体算法模块

         FUAITYPE_HUMAN_PROCESSOR_DETECT = 1 << 17,    //人体算法模式下进行每帧都进行全图人体检测，性能相对较差

         FUAITYPE_HUMAN_PROCESSOR_2D_SELFIE = 1 << 18,//人体算法模式下进行2D半身点位

         FUAITYPE_HUMAN_PROCESSOR_2D_DANCE = 1 << 19,//人体算法模式下进行2D全身点位

         FUAITYPE_HUMAN_PROCESSOR_2D_SLIM = 1 << 20,//人体算法模式下进行2D全身点位，针对美体场景优化全身关键点检测模式，拥有更快的性能

         FUAITYPE_HUMAN_PROCESSOR_3D_SELFIE = 1 << 21,//人体算法模式下进行3D半身点位

         FUAITYPE_HUMAN_PROCESSOR_3D_DANCE = 1 << 22,//人体算法模式下进行3D全身点位

         FUAITYPE_HUMAN_PROCESSOR_SEGMENTATION = 1 << 23 //人体算法模式下进行人体分割

}FUAITYPE;

返回值:

int 返回1代表成功，返回0代表失败。

可以通过 fuReleaseAIModel 释放模型，以及通过 fuIsAIModelLoaded 查询AI能力模型是否已经加载。

备注:

AI 能力会随 SDK 一起发布，存放在 assets/model目录中。

• ai_bgseg.bundle      为背景分割AI能力模型，对应FUAITYPE_BACKGROUNDSEGMENTATION。7.0.0之后版本，可以统一使用ai_human_processor.bundle对应的全身mask模块。

• ai_hairseg.bundle      为头发分割AI能力模型，对应FUAITYPE_HAIRSEGMENTATION。7.0.0之后版本，可以统一使用ai_face_processor.bundle对应的头发mask模块。

• ai_hand_processor.bundle      ( ai_gesture.bundle 7.2.0 后废弃） 为手势识别AI能力模型，对应FUAITYPE_HANDGESTURE。

• ai_facelandmarks75.bundle      为脸部特征点75点AI能力模型。      //废弃

• ai_facelandmarks209.bundle      为脸部特征点209点AI能力模型。      //废弃

• ai_facelandmarks239.bundle      为脸部特征点239点AI能力模型。      //废弃

• ai_humanpose.bundle      为人体2D点位AI能力模型，对应FUAITYPE_HUMANPOSE2D。7.0.0之后版本，可以统一使用ai_human_processor.bundle对应的人体点位模块。

• ai_bgseg_green.bundle      为绿幕背景分割AI能力模型，对应FUAITYPE_BACKGROUNDSEGMENTATION_GREEN。

• ai_face_processor.bundle      为人脸特征点、表情跟踪以及头发mask、头部mask、表情识别等AI能力模型，需要默认加载，对应FUAITYPE_FACEPROCESSOR。

• ai_human_processor.bundle      为人体算法能力模型，包括人体检测、2D人体关键点（全身、半身）、人体3D骨骼（全身、半身）、人像mask、动作识别等能力，对应FUAITYPE_HUMAN_PROCESSOR。注意: ai_human_processor_mb_fast.bundle为手机背景分割高性能版本。

fuReleaseAIModel 释放 AI 模型接口

接口说明：

当不需要使用特定的AI能力时，可以释放其资源，节省内存空间。

public static native int fuReleaseAIModel(int type);

参数说明:

type：描述bundle对应的AI能力类型，详见上面 fuLoadAIModelFromPackage 参数说明。

返回值:

int 1为已释放，0为未释放。

备注:

AI能力模型内存占用不高，建议长驻内存。

fuIsAIModelLoaded 是否加载 AI 模型接口

接口说明：

获取AI能力是否已经加载的状态。

public static native int fuIsAIModelLoaded(int type);

参数说明:

type：描述bundle对应的AI能力类型，详见上面 fuLoadAIModelFromPackage 参数说明。

返回值:

int 0为未加载，1为加载。

备注:

AI能力模型内存占用不高，建议长驻内存。

fuGetLogLevel 获取当前日志级别

接口说明：

获取当前日志级别。

public static native int fuGetLogLevel();

返回值:

FULOGLEVEL，定义如下：

typedef enum FULOGLEVEL {

  FU_LOG_LEVEL_TRACE = 0, //调试日志，每帧多次

  FU_LOG_LEVEL_DEBUG = 1, //调试日志，每帧一次或多次信息

  FU_LOG_LEVEL_INFO = 2,  //正常信息日志，程序运行过程中出现一次的信息，系统信息等

  FU_LOG_LEVEL_WARN = 3,  //警告级日志

  FU_LOG_LEVEL_ERROR = 4, //错误级日志

  FU_LOG_LEVEL_CRITICAL = 5, //错误且影响程序正常运行日志

  FU_LOG_LEVEL_OFF = 6 //关闭日志输出

} FULOGLEVEL;

 <hr size=1 width="100%" noshade style='color:#A9B7C6'>

fuSetLogLevel 设置当前日志级别

接口说明：

设置当前日志级别，默认INFO级别。设置FU_LOG_LEVEL_OFF时关闭全部日志，设置日志时大于等于当前级别的日志才能正常输出。

public static native int fuSetLogLevel(int level);

参数:

level：设置当前日志级别，详见 FULOGLEVEL 定义。

返回值:

1 表示成功，0 表示失败。

fuOpenFileLog 打开文件日志

接口说明：

打开文件日志，默认 nullptr 使用 console 日志。

public static native int fuOpenFileLog(String file_pullname, int max_file_size, int max_files);

参数:

file_pullname：日志文件名，全路径，由外部决定日志文件位置，如果为 nullptr 表示使用默认的 console 日志。 max_file_size：日志文件最大文件大小，超过将重置。 max_files：轮换日志文件数量，多个日志文件中进行轮转。

返回值:

1 表示成功，0 表示失败。

fuHexagonInitWithPath 初始化Hexagon dsp加速功能

接口说明：

初始化Hexagon dsp加速功能，启用dsp加速后，可以降低部分算法的计算耗时，提升性能。

支持dsp加速的算法有：人体检测算法、人体骨骼关键点算法。

dsp运行时需要动态加载如下四个动态库：libhexagon_interface.so,libHexagon_nn_skel.so,libHexagon_nn_skel_v65.so,libHexagon_nn_skel_v66.so，本接口在初始化时需要传入这四个动态库的路径

public static native void fuHexagonInitWithPath(String var0);

参数:

var0：dsp依赖的动态库的路径。

备注:
Android设备集成了较新的高通cpu才支持dsp加速，目前支持的cpu有：骁龙835、骁龙660/820/821、骁龙710/845、骁龙855、骁龙865。

目前dsp加速功能还处于内部试用阶段，可能存在兼容问题，不建议客户大规模集成使用。

LoadConfig.loadLibrary 自定义动态库加载的路径

接口说明：

用于加载外部的动态库。如果您要使用该功能，确保在使用 faceunity 静态方法和静态内部类之前调用，一般在 fuSetup 之前即可。

public static void loadLibrary(String soDir);

参数：

soDir: so 文件路径，例如 /data/data/com.faceunity.fulivedemo/app_libs/arm64-v8a/，该路径下需包含 libCNamaSDK.so 和 libfuai.so 两个库，建议将 so 文件放在应用程序私有目录，避免对外暴露的风险。

备注：

在部分支持 64 位动态库的Android 5.0 机型上，动态加载 64 位的 so 会出现异常，是系统底层 bug 所致，建议使用 32 位的库。

2.2 加载道具包

fuCreateItemFromPackage 通过道具二进制文件创建道具接口

public static native int fuCreateItemFromPackage(byte[] data);

接口说明：

加载道具包，使其可以在主运行接口中被执行。一个道具包可能是一个功能模块或者多个功能模块的集合，加载道具包可以在流水线中激活对应的功能模块，在同一套SDK调用逻辑中实现即插即用。

参数说明：

data 道具二进制文件

返回值：

int 创建的道具句柄

备注：

该接口可以和渲染异步执行，不需要 GL 环境，为了避免加载道具阻塞渲染线程，建议异步调用。

fuItemSetParam 为道具设置参数接口（三个重载接口）

public static native int fuItemSetParam(int item, String name, double value);

public static native int fuItemSetParam(int item, String name, double[] value);

public static native int fuItemSetParam(int item, String name, String value);

接口说明：

修改或设定道具包中变量的值。可以支持的道具包的变量名、含义、及取值范围需要参考道具的文档。

参数说明：

item 道具句柄

name 参数名

value 参数值，只支持 double 、 double[] 、String

返回值：

int 执行结果：返回 0 代表设置失败，大于 0 表示设置成功

fuItemGetParam 从道具中获取 double 型参数值接口

public static native double fuItemGetParam(int item,String name);

接口说明：

获取道具中 double 变量的值。可以支持的道具包的变量名、含义、及取值范围需要参考道具的文档。

参数说明：

item 道具句柄

name 参数名

返回值：

double 参数值

备注：

该接口可以和渲染线程异步执行。

fuItemGetParamString 从道具中获取 String 型参数值接口

public static native String fuItemGetParamString(int item,String name);

接口说明：

获取道具中 String 变量的值。可以支持的道具包的变量名、含义、及取值范围需要参考道具的文档。

参数说明：

item 道具句柄

name 参数名

返回值：

String 参数值

备注：

该接口可以和渲染线程异步执行。

2.3 主运行接口

fuDualInputToTexture 视频处理双输入接口

public static native int fuDualInputToTexture(byte[] img, int tex_in, int flags, int w, int h, int frame_id, int[] h);

接口说明：

将输入的图像数据，送入SDK流水线进行处理，并输出处理之后的图像数据。该接口会执行所有道具要求、且证书许可的功能模块，包括人脸检测与跟踪、美颜、贴纸或avatar绘制等。

参数说明：

img 图像数据byte[]，支持的格式为：NV21（默认）、I420、RGBA

tex_in 图像数据纹理ID

flags flags，可以指定数据img数据格式，返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明

w 图像数据的宽

h 图像数据的高

frame_id 当前处理的视频帧序数

items 包含多个道具句柄的int数组

返回值：

int 被处理过的的图像数据纹理ID。返回值小于等于0为异常，具体信息通过fuGetSystemError获取。纹理返回的数据为 2D。

备注：

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

美颜处理后的图像数据默认不会写回 img，参数 flags 设置为 FU_ADM_FLAG_ENABLE_READBACK 就会以相同宽高写回 img。如果需要自定义输出数据，请调用带有 readback 参数的 fuDualInputToTexture 接口。

该输入模式可以减少一次 CPU-GPU 间数据传输，在 Android 平台上可以显著优化性能，因此推荐尽可能使用该接口。

fuRenderDualInput 视频处理双输入接口，自定义 byte[] 数据回写

public static native int fuRenderDualInput(int w, int h, int frame_id, int[] items, int tex_in, int flags, byte[] img, int imgType, int readback_w, int readback_h, byte[] readback_img);

接口说明：

将输入的图像数据，送入SDK流水线进行处理，并输出处理之后的图像数据。该接口会执行所有道具要求、且证书许可的功能模块，包括人脸检测与跟踪、美颜、贴纸或avatar绘制等。

参数说明： w 图像数据的宽

h 图像数据的高

frame_id 当前处理的视频帧序数

items 包含多个道具句柄的int数组

tex_in 图像数据纹理ID

flags flags，可以指定数据img数据格式，返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明

img 图像数据byte[]，支持的格式为：NV21（默认）、I420、RGBA

imgType 图像数据类型，faceunity.FU_FORMAT_NV21_BUFFER faceunity.FU_FORMAT_RGBA_BUFFER faceunity.FU_FORMAT_I420_BUFFER YUV：0

readback_w 需要回写的图像数据的宽

readback_h 需要回写的图像数据的高

readback_img 需要回写的图像数据byte[]

返回值：

int 被处理过的的图像数据纹理ID。返回值小于等于0为异常，具体信息通过fuGetSystemError获取。纹理返回的数据为 2D。

备注：

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

美颜处理后的图像数据默认不会写回 img，参数 flags 设置为 FU_ADM_FLAG_ENABLE_READBACK 就会以相同宽高写回 img。

fuRenderTexture 视频处理单纹理输入接口

 public static native int fuRenderTexture(int w, int h, int frame_id, int[] items, int tex_in, int flags);

接口说明：

将输入的图像数据，送入SDK流水线进行处理。该接口会执行所有道具要求、且证书许可的功能模块，包括人脸检测与跟踪、美颜、贴纸或avatar绘制等。

参数说明：

w 图像数据的宽

h 图像数据的高

frame_id 当前处理的视频帧序数

items 包含多个道具句柄的int数组

tex_in 图像纹理 ID

flags flags，可以指定返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明

返回值：

int 被处理过的的图像数据纹理ID。返回值小于等于0为异常，具体信息通过fuGetSystemError获取。纹理返回的数据为 2D。

备注：

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

如果需要自定义输出数据，请调用带有 readback 参数的 fuRenderToTexture 接口。

fuRenderImg 视频处理单图象输入接口

public static native int fuRenderImg(int w, int h, int frame_id, int[] items, int flags, byte[] img, int imgType, int readback_w, int readback_h, byte[] readback_img);

接口说明：

将输入的图像数据，送入SDK流水线进行处理，并输出处理之后的图像数据。该接口会执行所有道具要求、且证书许可的功能模块，包括人脸检测与跟踪、美颜、贴纸或avatar绘制等。

参数说明：

w 图像数据的宽

h 图像数据的高

frame_id 当前处理的视频帧序数

items 包含多个道具句柄的int数组

flags flags，可以指定返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明

img 图像数据byte[]，被处理过的的图像数据会回写到该byte[]中

imgType 图像数据类型，faceunity.FU_FORMAT_NV21_BUFFER faceunity.FU_FORMAT_RGBA_BUFFER faceunity.FU_FORMAT_I420_BUFFER YUV：0

readback_w 需要回写的图像数据的宽

readback_h 需要回写的图像数据的高

readback_img 需要回写的图像数据byte[]

返回值：

int 被处理过的的图像数据纹理ID。返回值小于等于0为异常，具体信息通过fuGetSystemError获取。纹理返回的数据为 2D。

备注：

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

美颜处理后的图像数据默认会以相同宽高写回 img。如果需要自定义输出数据，请调用带有 readback 参数的 fuRenderToNV21Image 接口。

fuRenderYUV 视频处理单输入接口，YUV数据格式

 public static native int fuRenderYUV(int w, int h, int frame_id, int[] items, int flags, byte[] y_buffer, byte[] u_buffer, byte[] v_buffer, int y_stride, int u_stride, int v_stride, boolean read_back);

接口说明：

将输入的图像数据，送入SDK流水线进行处理，并输出处理之后的图像数据。该接口会执行所有道具要求、且证书许可的功能模块，包括人脸检测与跟踪、美颜、贴纸或avatar绘制等。

将 items 中的道具绘制到 YUV 三通道的图像中。

参数说明：

w 图像宽度

h 图像高度

frame_id 当前处理的视频帧序数，每次处理完对其进行加 1 操作，不加 1 将无法驱动道具中的特效动画

items 包含多个道具句柄的 int 数组，包括普通道具、美颜道具、手势道具等

flags flags，可以指定返回纹理ID的道具镜像等

y_buffer Y帧图像数据byte[]

u_buffer U帧图像数据byte[]

v_buffer V帧图像数据byte[]

y_stride Y帧stride

u_stride U帧stride

v_stride V帧stride

read_back 是否需要回写

返回值：

int 被处理过的的图像数据纹理ID。返回值小于等于0为异常，具体信息通过fuGetSystemError获取。纹理返回的数据为 2D。

备注：

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

fuBeautifyImage 视频处理接口，只美颜不进行人脸识别

public static native int fuBeautifyImage(int tex_in, int flags, int w, int h, int frame_id, int[] items);

接口说明：

将输入的图像数据，送入SDK流水线进行全图美化，并输出处理之后的图像数据。该接口只执行图像层面的美化处理（包括滤镜、美肤），不执行人脸跟踪以及所有人脸相关的操作（如美型）。由于功能集中，相比fuRenderItemsEx 接口执行美颜道具，该接口所需计算更少，执行效率更高。

参数说明：

tex_in 图像数据纹理ID

flags flags，可以指定返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明

w 图像宽度

h 图像高度

frame_id 当前处理的视频帧序数，每次处理完对其进行加 1 操作，不加 1 将无法驱动道具中的特效动画

items 包含多个道具句柄的 int 数组，包括普通道具、美颜道具、手势道具等

返回值：

int 被处理过的的图像数据纹理ID。返回值小于等于0为异常，具体信息通过fuGetSystemError获取。纹理返回的数据为 2D。

备注：

该接口正常生效需要传入的道具中必须包含美颜道具（随SDK分发，文件名通常为face_beautification.bundle）。

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

fuRenderBundles 函数

将输入的图像数据，送入SDK流水线进行处理，并输出处理之后的图像数据。该接口会执行Controller、FXAA、CartoonFilter等道具要求、且证书许可的功能模块，包括人脸检测与跟踪、身体追踪、Avatar绘制、FXAA抗锯齿、卡通滤镜后处理等。

public static native int fuRenderBundles(AvatarInfo avatar_info, int flags, int w, int h, int frame_id, int[] items);

参数:

avatar_info Avatar 模型信息，传入默认构造的实例。

flags 可以指定返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明。

w 输入的图像宽度

h 输入的图像高度

frame_id：当前处理的帧序列号，用于控制道具中的动画逻辑。

items 包含多个道具句柄的 int 数组，其中每个标识符应为调用 fuCreateItemFromPackage 函数的返回值，并且道具内容没有被销毁。

返回值:

处理之后的输出图像的纹理ID。

备注:

即使在非纹理模式下，函数仍会返回输出图像的纹理ID。虽然输出的图像可能是多种可选格式，但是绘制工作总是通过GPU完成，因此输出图像的纹理ID始终存在。输出的OpenGL纹理为SDK运行时在当前OpenGL context中创建的纹理，其ID应与输入ID不同。输出后使用该纹理时需要确保OpenGL context保持一致。

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

fuRenderBundlesWithCamera 函数

将输入的图像数据，送入SDK流水线进行处理，并输出处理之后的图像数据，同时绘制相机原始画面。该接口会执行Controller、FXAA、CartoonFilter等道具要求、且证书许可的功能模块，包括人脸检测与跟踪、身体追踪、Avatar绘制、FXAA抗锯齿、卡通滤镜后处理等。

public static native int fuRenderBundlesWithCamera(byte[] img, int tex_in, int flags, int w, int h, int frame_id, int[] items);

参数:

img 图像数据 byte[]，支持的格式为：NV21（默认）、I420、RGBA

tex_in 输入图像纹理 ID

flags 可以指定返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明。

w 输入的图像宽度

h 输入的图像高度

frame_id：当前处理的帧序列号，用于控制道具中的动画逻辑。

items 包含多个道具句柄的 int 数组，其中每个标识符应为调用 fuCreateItemFromPackage 函数的返回值，并且道具内容没有被销毁。

返回值:

处理之后的输出图像的纹理ID。

备注:

即使在非纹理模式下，函数仍会返回输出图像的纹理ID。虽然输出的图像可能是多种可选格式，但是绘制工作总是通过GPU完成，因此输出图像的纹理ID始终存在。输出的OpenGL纹理为SDK运行时在当前OpenGL context中创建的纹理，其ID应与输入ID不同。输出后使用该纹理时需要确保OpenGL context保持一致。

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

fuRenderBundlesSplitView 函数

将输入的图像数据，送入SDK流水线进行处理，并输出处理之后的图像数据。该接口会执行Controller、FXAA、CartoonFilter等道具要求、且证书许可的功能模块，包括人脸检测与跟踪、身体追踪、Avatar绘制、FXAA抗锯齿、卡通滤镜后处理等。

相比 fuRenderBundlesEx 该接口使用分屏绘制，输入图像和虚拟Avatar将绘制在两个视口。

public static native int fuRenderBundlesSplitView(AvatarInfo avatar_info, int flags, int w, int h, int frame_id, int[] items, SplitViewInfo split_view_info);

参数:

avatar_info Avatar 模型信息，传入默认构造的实例。

flags 可以指定返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明。

w 输入的图像宽度

h 输入的图像高度

frame_id：当前处理的帧序列号，用于控制道具中的动画逻辑。

items 包含多个道具句柄的 int 数组，其中每个标识符应为调用 fuCreateItemFromPackage 函数的返回值，并且道具内容没有被销毁。

split_view_info：分屏接口参数，详细的格式列表参加后续章节 输入输出格式列表 。

返回值:

处理之后的输出图像的纹理ID。

备注:

即使在非纹理模式下，函数仍会返回输出图像的纹理ID。虽然输出的图像可能是多种可选格式，但是绘制工作总是通过GPU完成，因此输出图像的纹理ID始终存在。输出的OpenGL纹理为SDK运行时在当前OpenGL context中创建的纹理，其ID应与输入ID不同。输出后使用该纹理时需要确保OpenGL context保持一致。

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

fuAvatarToTexture 视频处理接口，依据fuTrackFace获取到的人脸信息来绘制画面

public static native int fuAvatarToTexture(float[] pupilPos, float[] expression, float[] rotation, float[] rmode, int flags, int w, int h, int frame_id, int[] items, int isTracking);

接口说明：

依据fuTrackFace获取到的人脸信息来绘制画面。

参数说明：

pupilPos 眼球方向，长度2

expression 表情系数，长度46

rotation 人脸三维旋转，返回值为旋转四元数，长度4

rmode 人脸朝向，0-3分别对应手机四种朝向，长度1

flags flags，可以指定返回纹理ID的道具镜像等，详见后文”Android 双输入“部分说明

w 图像宽度

h 图像高度

frame_id 当前处理的视频帧序数，每次处理完对其进行加 1 操作，不加 1 将无法驱动道具中的特效动画

items 包含多个道具句柄的 int 数组，包括普通道具、美颜道具、手势道具等

isTracking 是否识别到人脸，可直接传入fuIsTracking方法获取到的值

返回值：

int 被处理过的的图像数据纹理ID。返回值小于等于0为异常，具体信息通过fuGetSystemError获取。纹理返回的数据为 2D。

备注：

该绘制接口需要OpenGL环境，环境异常会导致崩溃。

fuTrackFace 人脸信息跟踪接口

public static native void fuTrackFace(byte[] img, int format, int w, int h);

接口说明：

对于输入的图像数据仅执行人脸跟踪操作，其他所有图像和绘制相关操作均不执行，因此该函数没有图像输出。由于该函数不执行绘制相关操作，仅包含CPU计算，可以在没有OpenGL环境的情况下正常运行。该函数执行人脸跟踪操作后，结果产生的人脸信息通过 fuGetFaceInfo 接口进行获取。

参数说明：

img 图像数据byte[]

format 输入图像格式：FU_FORMAT_RGBA_BUFFER 、 FU_FORMAT_NV21_BUFFER 、 FU_FORMAT_NV12_BUFFER 、 FU_FORMAT_I420_BUFFER

w 图像数据的宽度

h 图像数据的高度

返回值：

int 检测到的人脸个数，返回 0 代表没有检测到人脸。

备注：

该接口不需要 OpenGL 环境，可以在渲染线程之外调用。

fuTrackFaceWithTongue 在跟踪人脸表情的同时，跟踪舌头blendshape系数

public static native void fuTrackFaceWithTongue(byte[] img, int format, int w, int h);

接口说明：

同 fuTrackFace ，在跟踪人脸表情的同时，跟踪舌头blendshape系数。 对于输入的图像数据仅执行人脸跟踪操作，其他所有图像和绘制相关操作均不执行，因此该函数没有图像输出。由于该函数不执行绘制相关操作，仅包含CPU计算，可以在没有OpenGL环境的情况下正常运行。该函数执行人脸跟踪操作后，结果产生的人脸信息通过 fuGetFaceInfo 接口进行获取。

参数说明：

img 图像数据byte[]

format 输入图像格式：FU_FORMAT_RGBA_BUFFER 、 FU_FORMAT_NV21_BUFFER 、 FU_FORMAT_NV12_BUFFER 、 FU_FORMAT_I420_BUFFER

w 图像数据的宽度

h 图像数据的高度

返回值：

int 检测到的人脸个数，返回 0 代表没有检测到人脸。

备注：

需要调用 fuLoadTongueModel 加载 tongue.bundle，才能开启舌头跟踪。

不需要 OpenGL 环境，可以在渲染线程之外调用。

2.4 销毁道具包

fuDestroyItem 销毁单个道具接口

public static native void fuDestroyItem(int item);

接口说明：

通过道具句柄销毁道具，并释放相关资源，销毁道具后请将道具句柄设为 0 ，以避免 SDK 使用无效的句柄而导致程序出错。

参数说明：

item 道具句柄

备注:

该函数调用后，会即刻释放道具标识符，道具占用的内存无法瞬时释放，需要等 SDK 后续执行主处理接口时通过 GC 机制回收。

fuDestroyAllItems 销毁所有道具接口

public static native void fuDestroyAllItems();

接口说明：

销毁全部道具，并释放相关资源，销毁道具后请将道具句柄数组中的句柄设为 0 ，以避免 SDK 使用无效的句柄而导致程序出错。

备注:

该函数必须在有context的情况下调用,该函数会即刻释放系统所占用的资源。但不会破坏 fuSetup 的系统初始化信息，应用临时挂起到后台时可以调用该函数释放资源，再次激活时无需重新初始化系统。

fuOnDeviceLost 释放内存资源

接口说明：

特殊函数，当程序退出或OpenGL context准备销毁时，调用该函数，会进行资源清理和回收，所有系统占用的内存资源会被释放，包括GL的GPU资源以及内存。

public static native void fuOnDeviceLost();

备注:

该函数必须在有context的情况下调用，且context必须和在fuRender开头的系列渲染函数的context保持一致，否则可能由于context 发生变化，OpenGL 资源相关的内存可能会发生泄露。

fuOnDeviceLostSafe 释放 CPU 资源

特殊函数，当客户端调用代码存在逻辑BUG时，可能会导致OpenGL Context状态异常，此时fuOnDeviceLost无法成功释放GPU资源进而导致应用崩溃，若无法有效定位客户端BUG，可以使用本函数替代。本函数只负责释放CPU资源，对GPU资源不进行销毁操作，借由外部context的销毁统一维护。

public static native void fuOnDeviceLostSafe();

备注:

1.    请优先使用fuOndeviceLost函数，仅当OpenGL环境异常时使用本函数；

2.    不恰当的调用会造成OpenGL 资源相关的内存发生泄露，不恰当调用包括：在同一个OpenGL Context下，重复调用本函数；

fuDestroyLibData 释放初始化相关资源

接口说明：

特殊函数，当不再需要Nama SDK时，可以释放由fuSetup初始化所分配的相关资源。调用后，人脸跟踪以及道具绘制功能将失效，fuRender 相关接口、fuTrackFace等函数将失败。如需使用，需要重新调用 fuSetup进行初始化。

public static native void fuDestroyLibData();

fuHexagonTearDown 关闭dsp加速功能

接口说明：

关闭dsp加速功能，释放资源

public static native void fuHexagonTearDown();

typedef enum TRANSFORM_MATRIX {

  /*

   * 8 base orientation cases, first do counter-clockwise rotation in degree,

   * then do flip

   */

  DEFAULT = 0,             // no rotation, no flip

  CCROT0 = DEFAULT,        // no rotation, no flip

  CCROT90,                 // counter-clockwise rotate 90 degree

  CCROT180,                // counter-clockwise rotate 180 degree

  CCROT270,                // counter-clockwise rotate 270 degree

  CCROT0_FLIPVERTICAL,     // vertical flip

  CCROT0_FLIPHORIZONTAL,   // horizontal flip

  CCROT90_FLIPVERTICAL,    // first counter-clockwise rotate 90 degree，then

                           // vertical flip

  CCROT90_FLIPHORIZONTAL,  // first counter-clockwise rotate 90 degree，then

                           // horizontal flip

  /*

   * enums below is alias to above enums, there are only 8 orientation cases

   */

  CCROT0_FLIPVERTICAL_FLIPHORIZONTAL = CCROT180,

  CCROT90_FLIPVERTICAL_FLIPHORIZONTAL = CCROT270,

  CCROT180_FLIPVERTICAL = CCROT0_FLIPHORIZONTAL,

  CCROT180_FLIPHORIZONTAL = CCROT0_FLIPVERTICAL,

  CCROT180_FLIPVERTICAL_FLIPHORIZONTAL = DEFAULT,

  CCROT270_FLIPVERTICAL = CCROT90_FLIPHORIZONTAL,

  CCROT270_FLIPHORIZONTAL = CCROT90_FLIPVERTICAL,

  CCROT270_FLIPVERTICAL_FLIPHORIZONTAL = CCROT90,

} TRANSFORM_MATRIX;

/**

 \brief input description for fuRender api, use to transform the input gpu

 texture to portrait mode(head-up). then the final output will portrait mode.

 the outter user present render pass should use identity matrix to present the

 result.

 \param tex_trans_mat, the transform matrix use to transform the input

 texture to portrait mode.

 \note when your input is cpu buffer only don't use

 this api, fuSetInputCameraBufferMatrix will handle all case.

 */

public static native void fuSetInputTextureMatrix(int tMat);

public static native void fuSetInputCameraTextureMatrixState(int enable);

/**

 \brief input description for fuRender api, use to transform the input cpu

 buffer to portrait mode(head-up). then the final output will portrait mode. the

 outter user present render pass should use identity matrix to present the

 result.

 \param buf_trans_mat, the transform matrix use to transform the input

 cpu buffer to portrait mode.

 \note when your input is gpu texture only don't

 use this api, fuSetInputCameraTextureMatrix will handle all case.

 */

public static native void fuSetInputBufferMatrix(int tMat);

public static native void fuSetInputCameraTextureMatrixState(int enable);

/**

 \brief add optional transform for final result, when use

 fuSetInputCameraTextureMatrix/fuSetInputCameraBufferMatrix, we means the output

 is in portrait mode(head-up), and the outter user present render pass should

 use identity matrix to present the result. but in some rare case, user would

 like to use a diffent orientation output. in this case,use

 fuSetInputCameraTextureMatrix/fuSetInputCameraBufferMatrix(portrait mode), then

 use the additional fuSetOutputMatrix to transform the final result to perfer

 orientation.

 \note Don't use this api unless you have to!

 */

public static native void fuSetOutputMatrix(int bMat);

/**

 \brief set additional transform matrix state, turn on or turn off

 */

public static native void fuSetOutputMatrixState(int enable);

/**

 * \brief set use async ai inference.

 * \param use_async,

 * ture or false.

 */

public static native int fuSetUseAsyncAIInference(int use);

public static native int fuBindItems(int item_src, int[] items)

public static native int fuUnBindItems(int item_src, int[] items);

public static native void fuOnCameraChange();

public static native int fuSetTongueTracking(int enable);

public static native int fuIsTracking();

public static native int fuSetMultiSamples(int samples);

public static native int fuSetMaxFaces(int n);

public static native void fuSetHandGestrueListener(faceunity.OnHandGestureListener listener);

public static native int fuGetFaceInfo(int face_id, String name, float[] value);

typedef enum FUAITONGUETYPE {

  FUAITONGUE_UNKNOWN = 0,

  FUAITONGUE_UP = 1 << 1,

  FUAITONGUE_DOWN = 1 << 2,

  FUAITONGUE_LEFT = 1 << 3,

  FUAITONGUE_RIGHT = 1 << 4,

  FUAITONGUE_LEFT_UP = 1 << 5,

  FUAITONGUE_LEFT_DOWN = 1 << 6,

  FUAITONGUE_RIGHT_UP = 1 << 7,

  FUAITONGUE_RIGHT_DOWN = 1 << 8,

} FUAITONGUETYPE;

typedef enum FUAIEXPRESSIONTYPE {

  FUAIEXPRESSION_UNKNOWN = 0,

  FUAIEXPRESSION_BROW_UP = 1 << 1, //抬眉毛

  FUAIEXPRESSION_BROW_FROWN = 1 << 2,//皱眉

  FUAIEXPRESSION_LEFT_EYE_CLOSE = 1 << 3,//闭左眼

  FUAIEXPRESSION_RIGHT_EYE_CLOSE = 1 << 4,//闭右眼

  FUAIEXPRESSION_EYE_WIDE = 1 << 5,//睁大眼睛

  FUAIEXPRESSION_MOUTH_SMILE_LEFT = 1 << 6,//抬左边嘴角

  FUAIEXPRESSION_MOUTH_SMILE_RIGHT = 1 << 7,//抬右边嘴角

  FUAIEXPRESSION_MOUTH_FUNNEL = 1 << 8,//嘴型O

  FUAIEXPRESSION_MOUTH_OPEN = 1 << 9,//嘴型'啊'

  FUAIEXPRESSION_MOUTH_PUCKER = 1 << 10,//嘟嘴

  FUAIEXPRESSION_MOUTH_ROLL = 1 << 11,//抿嘴

  FUAIEXPRESSION_MOUTH_PUFF = 1 << 12,//鼓脸

  FUAIEXPRESSION_MOUTH_SMILE = 1 << 13,//微笑

  FUAIEXPRESSION_MOUTH_FROWN = 1 << 14,//撇嘴

  FUAIEXPRESSION_HEAD_LEFT = 1 << 15,//左转头

  FUAIEXPRESSION_HEAD_RIGHT = 1 << 16,//右转头

  FUAIEXPRESSION_HEAD_NOD = 1 << 17,//点头

} FUAIEXPRESSIONTYPE;

public static native int fuGetFaceIdentifier(int face_id);

public stativ native int fuGetOpenGLSupported();

public static native String fuGetVersion();

public static native int fuGetModuleCode(int i);

public static native int fuGetSystemError();

public static native String fuGetSystemErrorString(int code);

public static native int fuCheckDebugItem(byte[] data);

public static native int fuSetCropState(int state);

public static native int fuSetCropFreePixel(int x0, int y0, int x1, int y1);

public static native void fuSetFocalLengthScale(float scale);

public static native void fuFaceProcessorSetMinFaceRatio(float ratio);

public static native void fuSetTrackFaceAIType(int ai_type);

public static native int fuSetFaceProcessorFov(float fov);

public static native void fuHumanProcessorReset();

public static native void fuHumanProcessorSetMaxHumans(int max_humans);

public static native int fuHumanProcessorGetNumResults();

public static native int fuHumanProcessorGetResultTrackId(int index);

public static native int fuHumanProcessorGetResultRect(int index, float[] rect);

public static native int fuHumanProcessorGetResultJoint2ds(int index, float[] joint2ds);

/**

 \brief get ai model HumanProcessor's tracking fov, use to 3d joint projection.

 */

public static native float fuHumanProcessorGetFov();

/**

 \brief set ai model HumanProcessor's tracking fov, use to 3d joint projection.

 */

public static native void fuHumanProcessorSetFov(float fov);

public static native int fuHumanProcessorGetResultJoint3ds(int index, float[] joint3ds);

public static native void fuHumanProcessorSetBonemap(byte[] data);

public static native void fuHumanProcessorGetResultTransformArray(int index, float[]data);

public static native void fuHumanProcessorGetResultModelMatrix(int index, float[]matrix);

public static native int fuHumanProcessorGetResultHumanMask(int index,float[] mask);

public static native int fuFaceProcessorGetResultHairMask(int index,float[] mask);

public static native int fuFaceProcessorGetResultHeadMask(int index,float[] mask);

public static native int fuHumanProcessorGetResultActionType(int index);

public static native float fuHumanProcessorGetResultActionScore(int index);

public static native int fuHandDetectorGetResultNumHands();

public static native int fuHandDetectorGetResultHandRect(int index, float[] rect);

public static native int fuHandDetectorGetResultGestureType(int index);

typedef enum FUAIGESTURETYPE {

  FUAIGESTURE_NO_HAND = -1,

  FUAIGESTURE_UNKNOWN = 0,

  FUAIGESTURE_THUMB = 1,

  FUAIGESTURE_KORHEART = 2,

  FUAIGESTURE_SIX = 3,

  FUAIGESTURE_FIST = 4,

  FUAIGESTURE_PALM = 5,

  FUAIGESTURE_ONE = 6,

  FUAIGESTURE_TWO = 7,

  FUAIGESTURE_OK = 8,

  FUAIGESTURE_ROCK = 9,

  FUAIGESTURE_CROSS = 10,

  FUAIGESTURE_HOLD = 11,

  FUAIGESTURE_GREET = 12,

  FUAIGESTURE_PHOTO = 13,

  FUAIGESTURE_HEART = 14,

  FUAIGESTURE_MERGE = 15,

  FUAIGESTURE_EIGHT = 16,

  FUAIGESTURE_HALFFIST = 17,

  FUAIGESTURE_GUN = 18,

} FUAIGESTURETYPE;

public static native float fuHandDetectorGetResultHandScore(int index);

public static native int fuAvatarBindItems(int avatar_item, int[] items, int[] contracts);

public static native int fuAvatarUnbindItems(int avatar_item, int[] items);

public static native int fuBindItems(int item_src, int[] items);

public static native int fuUnbindAllItems(int item_src);

public static native int fuLoadExtendedARData(byte[] ardata);

public static native void fuSetQualityTradeoff(float quality);

public static native void fuSetStrictTracking(int mode);

public static native int fuSetFaceDetParam(String name, float value);

public static native int fuSetAsyncTrackFace(int enable);

public static native int fuSetFaceTrackParam(String name, float value);

public static native void fuSetDefaultOrientation(int rmode);

public static native void fuSetExpressionCalibration(int mode);

public static native int fuLoadAnimModel(byte[] data);

typedef struct{

         void* p_Y;

         void* p_CbCr;

         int stride_Y;

         int stride_CbCr;

}TNV12Buffer;

typedef struct{

         void* p_NV21;

         int tex;

         int flags;

}TAndroidDualMode;

typedef struct{

         int fbo;

         int tex;

}TSPECFBO;

typedef struct{

         float* p_translation;

         float* p_rotation;

         float* p_expression;

         float* rotation_mode;

         float* pupil_pos;

         int is_valid;

}TAvatarInfo;

typedef struct{

         float* p_translation;

         float* p_rotation;

         float* p_expression;

         float* rotation_mode;

         float* pupil_pos;

         int is_valid;

}TAvatarInfo;

typedef struct {

  void* in_ptr;

  int in_type;

  int out_w;

  int out_h;

  float view_0_ratio;

  int margin_in_pixel;

  int is_vertical;

  int is_image_first;

  int rotation_mode_before_crop;

  float crop_ratio_top;

  int use_black_edge;

} TSplitViewInfo;