> ## Documentation Index
> Fetch the complete documentation index at: https://docs.facebetter.net/llms.txt
> Use this file to discover all available pages before exploring further.

# API 参考

> Android API 参考

## 日志相关

### 日志级别

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

```java theme={null}
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` 时有效）

```java theme={null}
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` 进行自动联网验证

```java theme={null}
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 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 setLipstickStyle(LipstickStyle style)`: 设置口红样式（Rouge / Coral / Pink）
* `int setBlushStyle(BlushStyle style)`: 设置腮红样式（Classic / Peach / Rose）
* `int setSkinOnlyBeauty(boolean enabled)`: 设置美颜是否仅作用于皮肤区域
  * 参数：`enabled` 为 `true` 时启用皮肤区域美颜，为 `false` 时美颜作用于整张图像
  * 返回值：`0` 表示成功，`-1` 表示引擎未初始化
* `int setVirtualBackground(VirtualBackgroundOptions options)`: 设置虚拟背景
  * 参数：`VirtualBackgroundOptions` 对象，包含背景模式和背景图片
  * 返回值：`0` 表示成功，`-1` 表示引擎未初始化，`-2` 表示参数无效（options 为 null 或无效）

#### 滤镜与贴纸管理

* `int setFilter(String filterId)`: 设置滤镜
  * 参数：`filterId` 滤镜唯一标识符
* `int setFilterIntensity(float intensity)`: 设置滤镜强度
  * 参数：`intensity` 强度值（范围 0.0 - 1.0）
* `int setSticker(String stickerId)`: 设置贴纸
  * 参数：`stickerId` 贴纸唯一标识符，传入空字符串可清除贴纸
* `int registerFilter(String filterId, String fbdFilePath)`: 从文件注册滤镜
* `int registerFilter(String filterId, byte[] fbdData)`: 从内存注册滤镜
* `int registerSticker(String stickerId, String fbdFilePath)`: 从文件注册贴纸
* `int registerSticker(String stickerId, byte[] fbdData)`: 从内存注册贴纸
* `int unregisterFilter(String filterId)`: 卸载滤镜
* `int unregisterAllFilters()`: 卸载所有滤镜
* `int unregisterSticker(String stickerId)`: 卸载贴纸
* `int unregisterAllStickers()`: 卸载所有贴纸
* `String[] getRegisteredFilters()`: 获取已注册滤镜列表
* `String[] getRegisteredStickers()`: 获取已注册贴纸列表

#### 回调

* `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`

```java theme={null}
public class BeautyEffectEngine {
  public static void setLogConfig(LogConfig config);
  
  public BeautyEffectEngine(Context context, EngineConfig config);
  public void release();
  
  public int setBeautyParam(BasicParam param, float value);
  public int setBeautyParam(ReshapeParam param, float value);
  public int setBeautyParam(MakeupParam param, float value);
  public int setLipstickStyle(LipstickStyle style);
  public int setBlushStyle(BlushStyle style);
  public int setSkinOnlyBeauty(boolean enabled);
  public int setVirtualBackground(VirtualBackgroundOptions options);
  
  public int setFilter(String filterId);
  public int setFilterIntensity(float intensity);
  public int setSticker(String stickerId);
  public int registerFilter(String filterId, String fbdFilePath);
  public int registerFilter(String filterId, byte[] fbdData);
  public int registerSticker(String stickerId, String fbdFilePath);
  public int registerSticker(String stickerId, byte[] fbdData);
  public int unregisterFilter(String filterId);
  public int unregisterAllFilters();
  public int unregisterSticker(String stickerId);
  public int unregisterAllStickers();
  public String[] getRegisteredFilters();
  public String[] getRegisteredStickers();
  
  public void setEngineEventCallback(OnEngineEventCallback callback);
  
  public ImageFrame processImage(ImageFrame inputFrame);

  // Deprecated APIs
  public int enableBeautyType(BeautyType type, boolean enabled);
  public boolean isBeautyTypeEnabled(BeautyType type);
  public int disableAllBeautyTypes();
}
```

## 美颜参数

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

### 美颜类型

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

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

### 基础美颜参数

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

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

### 面部重塑参数

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

```java theme={null}
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`。

```java theme={null}
public enum MakeupParam {
  LIPSTICK(0),  // 口红
  BLUSH(1);     // 腮红
}
```

### 口红样式

```java theme={null}
public enum LipstickStyle {
  ROUGE(0),  // 玫瑰红
  CORAL(1),  // 珊瑚橙
  PINK(2);   // 粉色（默认）
}
```

### 腮红样式

```java theme={null}
public enum BlushStyle {
  CLASSIC(0),  // 经典（默认）
  PEACH(1),    // 蜜桃
  ROSE(2);     // 玫瑰
}
```

### 虚拟背景选项

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

```java theme={null}
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 表示成功）
* `int mirror(String mode)`: 镜像图像（返回 0 表示成功）
  * 参数：`mode` 镜像模式，可以是 "horizontal"（水平）、"vertical"（垂直）或 "both"（两者）（不区分大小写）
* `void setMirror(String mode)`: 设置引擎处理时的镜像模式（避免额外的格式转换）
  * 参数：`mode` 镜像模式，可以是 "horizontal"（水平）、"vertical"（垂直）或 "both"（两者）（不区分大小写）
  * 注意：这仅设置镜像标志，实际的镜像发生在引擎处理期间
* `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 资源

```java theme={null}
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 int mirror(String mode);
  public void setMirror(String mode);
  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

图像格式枚举。

```java theme={null}
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);  // 纹理格式
}
```

#### Rotation

图像旋转角度枚举。

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

## 已废弃接口 (Deprecated APIs)

<Warning>
  **已弃用**

  以下接口已弃用。请使用参数驱动接口（如 `setBeautyParam`）替代。
</Warning>

### 美颜类型控制

* `int enableBeautyType(BeautyType type, boolean enabled)`
  * **说明**: \[已弃用] 启用或禁用美颜类型（参数驱动模式下无效果）
  * **返回值**: `0` 表示成功

* `boolean isBeautyTypeEnabled(BeautyType type)`
  * **说明**: \[已弃用] 检查美颜类型是否已启用（始终返回 false）
  * **返回值**: `false`

* `int disableAllBeautyTypes()`
  * **说明**: \[已弃用] 禁用所有美颜类型（请通过置零参数重置效果）
  * **返回值**: `0` 表示成功