Android API 参考

日志相关

日志级别

日志级别枚举，用于控制日志输出级别。

public enum LogLevel {
  TRACE(0, "TRACE"),
  DEBUG(1, "DEBUG"),
  INFO(2, "INFO"),
  WARN(3, "WARN"),
  ERROR(4, "ERROR"),
  CRITICAL(5, "CRITICAL");
}

日志配置类

日志配置类，用于配置日志输出方式和级别。

字段说明：

• consoleEnabled: 是否启用控制台输出
• fileEnabled: 是否启用文件输出
• level: 日志级别
• fileName: 日志文件路径（仅在 fileEnabled 为 true 时有效）

public static class LogConfig {
  public boolean consoleEnabled;
  public boolean fileEnabled;
  public LogLevel level;
  public String fileName;

  public LogConfig();
  public LogConfig(boolean consoleEnabled, boolean fileEnabled, LogLevel level, String fileName);
}

引擎相关

引擎配置

引擎配置类，用于初始化美颜引擎。

字段说明：

• appId: 应用 ID（可选，如果提供了 licenseJson 则不需要）
• appKey: 应用密钥（可选，如果提供了 licenseJson 则不需要）
• licenseJson: 授权数据 JSON 字符串（可选，如果提供了则优先使用，不需要 appId 和 appKey）
• externalContext: 是否使用外部 OpenGL 上下文（默认 false）
  • true: 使用调用方提供的 GL 上下文，SDK 不再创建/管理内部上下文
  • false: 使用内部默认上下文

方法：

• isValid(): 验证配置是否有效
  • 如果提供了 licenseJson，则使用授权数据验证
  • 否则需要 appId 和 appKey 进行自动联网验证

验证方式优先级：

• 如果 licenseJson 不为空，使用授权数据验证（支持在线响应和离线授权）
• 否则使用 appId 和 appKey 进行自动联网验证

public static class EngineConfig {
  public String appId;
  public String appKey;
  public String licenseJson;  // 授权数据JSON字符串（可选）
  public boolean externalContext = false;  // 是否使用外部 OpenGL 上下文

  public EngineConfig();
  public EngineConfig(String appId, String appKey);
  public boolean isValid();
}

引擎接口

美颜效果引擎主类，提供美颜功能的入口。

静态方法：

• setLogConfig(LogConfig config): 设置日志配置

实例方法：

初始化与释放

• BeautyEffectEngine(Context context, EngineConfig config): 构造函数，创建引擎实例
• void release(): 释放引擎资源

美颜类型控制

• int enableBeautyType(BeautyType type, boolean enabled): 启用或禁用美颜类型
• boolean isBeautyTypeEnabled(BeautyType type): 检查美颜类型是否已启用
• int disableAllBeautyTypes(): 禁用所有美颜类型

参数设置

• int setBeautyParam(BasicParam param, float value): 设置基础美颜参数（范围 0.0 - 1.0）
• int setBeautyParam(ReshapeParam param, float value): 设置面部重塑参数（范围 0.0 - 1.0）
• int setBeautyParam(MakeupParam param, float value): 设置美妆参数（范围 0.0 - 1.0）
• int setVirtualBackground(VirtualBackgroundOptions options): 设置虚拟背景
  • 参数：VirtualBackgroundOptions 对象，包含背景模式和背景图片
  • 返回值：0 表示成功，-1 表示引擎未初始化，-2 表示参数无效（options 为 null 或无效）

回调

• void setEngineEventCallback(OnEngineEventCallback callback): 设置引擎事件回调，用于监听授权验证和引擎初始化状态
  • 回调提供：int code（事件码）、String message（事件描述）
  • 代码 0 表示成功，非零表示失败

图像处理

• ImageFrame processImage(ImageFrame inputFrame): 处理图像帧
  • 帧类型通过 inputFrame.type 字段获取（FrameType.IMAGE 或 FrameType.VIDEO）
  • 处理后的图像帧会保持相同的帧类型

返回值说明：

• 方法返回 int 类型：
  • 0 表示成功
  • -1 表示引擎未初始化
  • -2 表示参数无效（仅 setVirtualBackground 方法）
• processImage 返回 ImageFrame：处理后的图像帧，失败时返回 null

public class BeautyEffectEngine {
  public static void setLogConfig(LogConfig config);
  
  public BeautyEffectEngine(Context context, EngineConfig config);
  public void release();
  
  public int enableBeautyType(BeautyType type, boolean enabled);
  public boolean isBeautyTypeEnabled(BeautyType type);
  public int disableAllBeautyTypes();
  
  public int setBeautyParam(BasicParam param, float value);
  public int setBeautyParam(ReshapeParam param, float value);
  public int setBeautyParam(MakeupParam param, float value);
  public int setVirtualBackground(VirtualBackgroundOptions options);
  
  public void setEngineEventCallback(OnEngineEventCallback callback);
  
  public ImageFrame processImage(ImageFrame inputFrame);
}

美颜参数

美颜参数枚举类，包含所有美颜相关的参数类型定义。

美颜类型

定义可用的美颜功能类型。

public enum BeautyType {
  BASIC(0),        // 基础美颜
  RESHAPE(1),      // 面部重塑
  MAKEUP(2),       // 美妆效果
  VIRTUAL_BACKGROUND(3); // 虚拟背景
}

基础美颜参数

基础美颜效果的参数类型，所有参数值范围均为 0.0 - 1.0。

public enum BasicParam {
  SMOOTHING(0),  // 磨皮
  SHARPENING(1), // 锐化
  WHITENING(2),  // 美白
  ROSINESS(3);   // 红润
}

面部重塑参数

面部重塑效果的参数类型，所有参数值范围均为 0.0 - 1.0。

public enum ReshapeParam {
  FACE_THIN(0),      // 瘦脸
  FACE_V_SHAPE(1),   // V脸
  FACE_NARROW(2),    // 窄脸
  FACE_SHORT(3),     // 短脸
  CHEEKBONE(4),      // 颧骨
  JAWBONE(5),        // 下颌骨
  CHIN(6),           // 下巴
  NOSE_SLIM(7),      // 瘦鼻梁
  EYE_SIZE(8),       // 大眼
  EYE_DISTANCE(9);   // 眼距
}

美妆参数

美妆效果的参数类型，所有参数值范围均为 0.0 - 1.0。

public enum MakeupParam {
  LIPSTICK(0),  // 口红
  BLUSH(1);     // 腮红
}

虚拟背景选项

虚拟背景效果的配置选项。

public static class VirtualBackgroundOptions {
  public BackgroundMode mode = BackgroundMode.NONE;
  public ImageFrame backgroundImage = null;
  
  public VirtualBackgroundOptions() {}
  
  public VirtualBackgroundOptions(BackgroundMode mode) {
    this.mode = mode;
  }
}

图像相关

ImageFrame

图像帧类，用于封装图像数据和处理。

创建方法：

• createWithFile(String filePath): 从文件创建（支持 PNG、JPG）
• createWithRGBA(ByteBuffer data, int width, int height, int stride): 从 RGBA 数据创建
• createWithBGRA(ByteBuffer data, int width, int height, int stride): 从 BGRA 数据创建
• createWithRGB(ByteBuffer data, int width, int height, int stride): 从 RGB 数据创建
• createWithBGR(ByteBuffer data, int width, int height, int stride): 从 BGR 数据创建
• createWithI420(...): 从 I420 YUV 数据创建
• createWithNV12(...): 从 NV12 YUV 数据创建
• createWithNV21(...): 从 NV21 YUV 数据创建
• createWithAndroid420(...): 从 Android Camera2 YUV_420_888 格式创建
• createWithTexture(int texture, int width, int height, int stride): 从 GPU 纹理创建（外部纹理输入）
• createWithBitmap(Bitmap bitmap): 从 Android Bitmap 创建（Android 专用）

图像操作：

• int rotate(Rotation rotation): 旋转图像（返回 0 表示成功）
• ImageFrame convert(Format format): 格式转换方法，返回转换后的 ImageFrame
• int toFile(String path, int quality): 保存图像到文件（指定质量 1-100）
• int toFile(String path): 保存图像到文件（使用默认质量 90）
• boolean isValid(): 检查图像帧是否有效

属性访问：

• int getWidth(), int getHeight(): 获取图像宽高
• int getStride(), int getSize(): 获取图像步长和大小
• Format getFormat(): 获取图像格式
• int getTexture(): 获取纹理句柄（如果是纹理格式）
• FrameType type: 帧类型（FrameType.IMAGE 或 FrameType.VIDEO），默认值为 FrameType.VIDEO

数据访问：

• ByteBuffer getData(): 获取原始数据（单平面格式）
• ByteBuffer getDataY(), getDataU(), getDataV(): 获取 YUV 分量数据
• ByteBuffer getDataUV(): 获取 UV 平面数据（NV12/NV21）
• int getStrideY(), getStrideU(), getStrideV(), getStrideUV(): 获取 YUV 步长
• convert(Format format): 格式转换方法，返回转换后的 ImageFrame

资源管理：

• void release(): 释放 native 资源

public class ImageFrame {
  public static ImageFrame createWithFile(String filePath);
  public static ImageFrame createWithRGBA(ByteBuffer data, int width, int height, int stride);
  public static ImageFrame createWithBGRA(ByteBuffer data, int width, int height, int stride);
  public static ImageFrame createWithRGB(ByteBuffer data, int width, int height, int stride);
  public static ImageFrame createWithBGR(ByteBuffer data, int width, int height, int stride);
  public static ImageFrame createWithI420(int width, int height, ByteBuffer yBuffer, int strideY,
      ByteBuffer uBuffer, int strideU, ByteBuffer vBuffer, int strideV);
  public static ImageFrame createWithNV12(int width, int height, ByteBuffer yBuffer, int strideY,
      ByteBuffer uvBuffer, int strideUV);
  public static ImageFrame createWithNV21(int width, int height, ByteBuffer yBuffer, int strideY,
      ByteBuffer vuBuffer, int strideVU);
  public static ImageFrame createWithAndroid420(int width, int height, ByteBuffer yBuffer,
      int strideY, ByteBuffer uBuffer, int strideU, ByteBuffer vBuffer, int strideV,
      int pixelStrideUV);
  public static ImageFrame createWithTexture(int texture, int width, int height, int stride);
  public static ImageFrame createWithBitmap(Bitmap bitmap);
  
  public int rotate(Rotation rotation);
  public ImageFrame convert(Format format);
  public int toFile(String path, int quality);
  public int toFile(String path);
  public boolean isValid();
  
  // 属性访问方法
  public int getWidth();
  public int getHeight();
  public int getStride();
  public int getSize();
  public ByteBuffer getData();
  public Format getFormat();
  public int getTexture();
  
  public FrameType type;  // 帧类型（FrameType.IMAGE 或 FrameType.VIDEO）
  
  // YUV 相关方法
  public ByteBuffer getDataY();
  public ByteBuffer getDataU();
  public ByteBuffer getDataV();
  public ByteBuffer getDataUV();
  public int getStrideY();
  public int getStrideU();
  public int getStrideV();
  public int getStrideUV();
  
  public void release();
}

枚举类型

Format

图像格式枚举。

public enum Format {
  I420(0),     // YUV 4:2:0 12bpp (3 planes, Y, U, V)
  NV12(1),     // YUV 4:2:0 12bpp (2 planes, Y + UV)
  NV21(2),     // YUV 4:2:0 12bpp (2 planes, Y + VU, Android default)
  BGRA(3),     // BGRA 8:8:8:8 32bpp
  RGBA(4),     // RGBA 8:8:8:8 32bpp
  BGR(5),      // BGR 8:8:8 24bpp
  RGB(6),      // RGB 8:8:8 24bpp
  Texture(7);  // 纹理格式
}

public enum Rotation {
  ROTATION_0(0),    // 0度
  ROTATION_90(1),   // 顺时针旋转90度
  ROTATION_180(2),  // 顺时针旋转180度
  ROTATION_270(3);  // 顺时针旋转270度
}