English

简体中文

English

简体中文

Appearance

Facebetter Beauty Engine API 参考 ​

目录 ​

  1. BeautyEffectEngine
  2. ImageFrame
  3. ImageBuffer
  4. 配置结构体
  5. 枚举类型
  6. 错误码说明

BeautyEffectEngine ​

美颜效果引擎的核心类，提供美颜处理的主要功能。

静态方法 ​

SetLogConfig ​

cpp
static int SetLogConfig(const LogConfig& config);

功能：设置日志配置
参数：

  • config：日志配置结构体

返回值：

  • 0：成功
  • 非 0：失败

使用示例：

cpp
facebetter::LogConfig log_config;
log_config.console_enabled = true;
log_config.level = facebetter::LogLevel::Info;
int result = facebetter::BeautyEffectEngine::SetLogConfig(log_config);

Create ​

cpp
static std::shared_ptr<BeautyEffectEngine> Create(const EngineConfig& config);

功能：创建引擎实例
参数：

  • config：引擎配置结构体

返回值：

  • 成功：返回引擎实例的智能指针
  • 失败：返回 nullptr

使用示例：

cpp
facebetter::EngineConfig config;
config.app_id = "your_app_id";
config.app_key = "your_app_key";
config.resource_path = "path/to/resource.bundle";
auto engine = facebetter::BeautyEffectEngine::Create(config);

实例方法 ​

SetBeautyTypeEnabled ​

cpp
virtual int SetBeautyTypeEnabled(BeautyType type, bool enabled) = 0;

功能：启用或禁用美颜类型
参数：

  • type：美颜类型（Basic、Reshape、Makeup、VirtualBackground）
  • enabled：是否启用

返回值：

  • 0：成功
  • 非 0：失败

使用示例：

cpp
engine->SetBeautyTypeEnabled(facebetter::BeautyType::Basic, true);

IsBeautyTypeEnabled ​

cpp
virtual bool IsBeautyTypeEnabled(BeautyType type) const = 0;

功能：检查美颜类型是否启用
参数：

  • type：美颜类型

返回值：

  • true：已启用
  • false：未启用

DisableAllBeautyTypes ​

cpp
virtual int DisableAllBeautyTypes() = 0;

功能：禁用所有美颜类型
返回值：

  • 0：成功
  • 非 0：失败

SetBeautyParam (基础美颜) ​

cpp
virtual int SetBeautyParam(beauty_params::Basic param, float value) = 0;

功能：设置基础美颜参数
参数：

  • param：基础美颜参数类型
  • value：参数值（0.0 - 1.0）

支持参数：

  • Smoothing：磨皮
  • Sharpening：锐化
  • Whitening：美白
  • Rosiness：红润

使用示例：

cpp
engine->SetBeautyParam(facebetter::beauty_params::Basic::Smoothing, 0.5f);

SetBeautyParam (面部重塑) ​

cpp
virtual int SetBeautyParam(beauty_params::Reshape param, float value) = 0;

功能：设置面部重塑参数
参数：

  • param：面部重塑参数类型
  • value：参数值（0.0 - 1.0）

支持参数：

  • FaceThin：瘦脸
  • FaceVShape：V脸
  • FaceNarrow：窄脸
  • FaceShort：短脸
  • Cheekbone：颧骨
  • Jawbone：下颌骨
  • Chin：下巴
  • NoseSlim：瘦鼻梁
  • EyeSize：大眼
  • EyeDistance：眼距

SetBeautyParam (美妆) ​

cpp
virtual int SetBeautyParam(beauty_params::Makeup param, float value) = 0;

功能：设置美妆参数
参数：

  • param：美妆参数类型
  • value：参数值（0.0 - 1.0）

支持参数：

  • Lipstick：口红
  • Blush：腮红

SetVirtualBackground ​

cpp
virtual int SetVirtualBackground(const beauty_params::VirtualBackgroundOptions& options) = 0;

功能：设置虚拟背景
参数：

  • options：虚拟背景选项，包含背景模式和背景图片

使用示例：

cpp
// Set blur background
facebetter::beauty_params::VirtualBackgroundOptions options;
options.mode = facebetter::beauty_params::BackgroundMode::Blur;
engine->SetVirtualBackground(options);

// Set background image
facebetter::beauty_params::VirtualBackgroundOptions imageOptions;
imageOptions.mode = facebetter::beauty_params::BackgroundMode::Image;
imageOptions.background_image = backgroundImageFrame;
engine->SetVirtualBackground(imageOptions);

SetRenderView ​

cpp
virtual int SetRenderView(void* view) = 0;

功能：设置渲染视图（仅 iOS/macOS 平台支持）
参数：

  • view：视图句柄（iOS: UIView*, macOS: NSView*）

返回值：

  • 0：成功
  • 非 0：失败

平台限制：仅在 iOS 和 macOS 平台可用

ProcessMode ​

cpp
virtual facebetter::ProcessMode ProcessMode() const = 0;

功能：获取当前处理模式
返回值：当前处理模式（Image 或 Video）

SetProcessMode ​

cpp
virtual int SetProcessMode(facebetter::ProcessMode mode) = 0;

功能：设置处理模式
参数：

  • mode：处理模式（Image 或 Video）

返回值：

  • 0：成功
  • 非 0：失败

ProcessImage ​

cpp
virtual const std::shared_ptr<ImageFrame> ProcessImage(
    const std::shared_ptr<ImageFrame> image_frame) = 0;

功能：处理图像
参数：

  • image_frame：输入图像帧

返回值：

  • 成功：返回处理后的图像帧
  • 失败：返回 nullptr

ImageFrame ​

图像帧类，提供图像数据的创建、转换和操作功能。

静态创建方法 ​

CreateWithAndroid420 ​

cpp
static std::shared_ptr<ImageFrame> CreateWithAndroid420(
    int width,
    int height,
    uint8_t* yBuffer,
    int strideY,
    uint8_t* uBuffer,
    int strideU,
    uint8_t* vBuffer,
    int strideV,
    int pixelStrideUV);

功能：从 Android Camera2 YUV420 数据创建图像帧
参数：

  • width：图像宽度
  • height：图像高度
  • yBuffer：Y 平面数据
  • strideY：Y 平面步长
  • uBuffer：U 平面数据
  • strideU：U 平面步长
  • vBuffer：V 平面数据
  • strideV：V 平面步长
  • pixelStrideUV：UV 像素步长

Create (通用方法) ​

cpp
static std::shared_ptr<ImageFrame> Create(const uint8_t* data,
                                          int width,
                                          int height,
                                          ImageBuffer::Format format);

功能：通用创建方法（推荐使用）
参数：

  • data：图像数据指针
  • width：图像宽度
  • height：图像高度
  • format：图像格式

CreateWithRGBA ​

cpp
static std::shared_ptr<ImageFrame> CreateWithRGBA(const uint8_t* data,
                                                  int width,
                                                  int height,
                                                  int stride);

功能：从 RGBA 数据创建图像帧
参数：

  • data：RGBA 数据指针
  • width：图像宽度
  • height：图像高度
  • stride：数据步长

CreateWithBGRA ​

cpp
static std::shared_ptr<ImageFrame> CreateWithBGRA(const uint8_t* data,
                                                  int width,
                                                  int height,
                                                  int stride);

功能：从 BGRA 数据创建图像帧

CreateWithRGB ​

cpp
static std::shared_ptr<ImageFrame> CreateWithRGB(const uint8_t* data,
                                                 int width,
                                                 int height,
                                                 int stride);

功能：从 RGB 数据创建图像帧

CreateWithBGR ​

cpp
static std::shared_ptr<ImageFrame> CreateWithBGR(const uint8_t* data,
                                                 int width,
                                                 int height,
                                                 int stride);

功能：从 BGR 数据创建图像帧

CreateWithI420 ​

cpp
static std::shared_ptr<ImageFrame> CreateWithI420(int width,
                                                  int height,
                                                  const uint8_t* dataY,
                                                  int strideY,
                                                  const uint8_t* dataU,
                                                  int strideU,
                                                  const uint8_t* dataV,
                                                  int strideV);

功能：从 I420 YUV 数据创建图像帧

CreateWithNV12 ​

cpp
static std::shared_ptr<ImageFrame> CreateWithNV12(int width,
                                                  int height,
                                                  const uint8_t* dataY,
                                                  int strideY,
                                                  const uint8_t* dataUV,
                                                  int strideUV);

功能：从 NV12 YUV 数据创建图像帧

CreateWithNV21 ​

cpp
static std::shared_ptr<ImageFrame> CreateWithNV21(int width,
                                                  int height,
                                                  const uint8_t* dataY,
                                                  int strideY,
                                                  const uint8_t* dataUV,
                                                  int strideUV);

功能：从 NV21 YUV 数据创建图像帧

CreateWithFile ​

cpp
static std::shared_ptr<ImageFrame> CreateWithFile(const std::string& file_path);

功能：从文件创建图像帧
参数：

  • file_path：文件路径

返回值：

  • 成功：返回图像帧实例
  • 失败：返回 nullptr

实例方法 ​

Rotate ​

cpp
int Rotate(ImageBuffer::Rotation rotation);

功能：旋转图像
参数：

  • rotation：旋转角度

返回值：

  • 0：成功
  • 非 0：失败

ToRGBA ​

cpp
std::shared_ptr<ImageBuffer> ToRGBA() const;

功能：转换为 RGBA 格式
返回值：RGBA 格式的 ImageBuffer

ToBGRA ​

cpp
std::shared_ptr<ImageBuffer> ToBGRA() const;

功能：转换为 BGRA 格式

ToRGB ​

cpp
std::shared_ptr<ImageBuffer> ToRGB() const;

功能：转换为 RGB 格式

ToBGR ​

cpp
std::shared_ptr<ImageBuffer> ToBGR() const;

功能：转换为 BGR 格式

ToI420 ​

cpp
std::shared_ptr<ImageBuffer> ToI420() const;

功能：转换为 I420 YUV 格式

ToNV12 ​

cpp
std::shared_ptr<ImageBuffer> ToNV12() const;

功能：转换为 NV12 YUV 格式

ToNV21 ​

cpp
std::shared_ptr<ImageBuffer> ToNV21() const;

功能：转换为 NV21 YUV 格式

ImageBuffer ​

图像缓冲区抽象基类，提供统一的图像数据访问接口。

枚举类型 ​

Format ​

cpp
enum class Format {
  I420,    // YUV 4:2:0 12bpp (3 planes: Y, U, V)
  NV12,    // YUV 4:2:0 12bpp (2 planes: Y + UV)
  NV21,    // YUV 4:2:0 12bpp (2 planes: Y + VU, Android 默认)
  BGRA,    // BGRA 8:8:8:8 32bpp (4 channels)
  RGBA,    // RGBA 8:8:8:8 32bpp (4 channels)
  BGR,     // BGR 8:8:8 24bpp (3 channels)
  RGB,     // RGB 8:8:8 24bpp (3 channels)
  Texture, // 纹理格式（用于 GPU 纹理）
};

Rotation ​

cpp
enum class Rotation {
  Rotation_0,   // 0度
  Rotation_90,  // 顺时针旋转90度
  Rotation_180, // 顺时针旋转180度
  Rotation_270, // 顺时针旋转270度
};

虚函数接口 ​

Width ​

cpp
virtual int32_t Width() const = 0;

功能：获取图像宽度
返回值：图像宽度（像素）

Height ​

cpp
virtual int32_t Height() const = 0;

功能：获取图像高度
返回值：图像高度（像素）

Stride ​

cpp
virtual int32_t Stride() const = 0;

功能：获取图像步长
返回值：图像步长（字节）

Size ​

cpp
virtual int32_t Size() const = 0;

功能：获取图像数据大小
返回值：图像数据大小（字节）

Data ​

cpp
virtual const uint8_t* Data() const = 0;

功能：获取图像数据指针
返回值：图像数据指针

DataY / DataU / DataV ​

cpp
virtual const uint8_t* DataY() const = 0;
virtual const uint8_t* DataU() const = 0;
virtual const uint8_t* DataV() const = 0;

功能：获取 YUV 格式各平面数据指针
适用格式：I420
返回值：对应平面的数据指针

StrideY / StrideU / StrideV ​

cpp
virtual int32_t StrideY() const = 0;
virtual int32_t StrideU() const = 0;
virtual int32_t StrideV() const = 0;

功能：获取 YUV 格式各平面步长
适用格式：I420

DataUV / StrideUV ​

cpp
virtual const uint8_t* DataUV() const = 0;
virtual int32_t StrideUV() const = 0;

功能：获取 UV 平面数据指针和步长
适用格式：NV12、NV21

GetFormat ​

cpp
virtual Format GetFormat() const = 0;

功能：获取图像格式
返回值：图像格式枚举值

配置结构体 ​

LogConfig ​

cpp
struct LogConfig {
  bool console_enabled = false;
  bool file_enabled = false;
  LogLevel level = LogLevel::Info;
  std::string file_name = "";
};

功能：日志配置结构体
成员：

  • console_enabled：是否输出到控制台
  • file_enabled：是否输出到文件
  • level：日志级别
  • file_name：日志文件名

EngineConfig ​

cpp
struct EngineConfig {
  std::string app_id;
  std::string app_key;
  std::string resource_path;
  ProcessMode process_mode = ProcessMode::Video;
};

功能：引擎配置结构体
成员：

  • app_id：应用ID
  • app_key：应用密钥
  • resource_path：资源文件路径
  • process_mode：处理模式

枚举类型 ​

LogLevel ​

cpp
enum class LogLevel {
  Trace = 0,    // 跟踪级别
  Debug,        // 调试级别
  Info,         // 信息级别
  Warn,         // 警告级别
  Error,        // 错误级别
  Critical      // 严重错误级别
};

ProcessMode ​

cpp
enum class ProcessMode {
  Image = 0,    // 图像模式
  Video = 1     // 视频模式
};

BeautyType ​

cpp
enum class BeautyType {
  Basic = 0,        // 基础美颜
  Reshape,          // 面部重塑
  Makeup,           // 美妆效果
  VirtualBackground,     // Virtual background
};

beauty_params::Basic ​

cpp
enum class Basic {
  Smoothing = 0,    // 磨皮
  Sharpening,       // 锐化
  Whitening,        // 美白
  Rosiness,         // 红润
};

beauty_params::Reshape ​

cpp
enum class Reshape {
  FaceThin = 0,     // 瘦脸
  FaceVShape,       // V脸
  FaceNarrow,       // 窄脸
  FaceShort,        // 短脸
  Cheekbone,        // 颧骨
  Jawbone,          // 下颌骨
  Chin,             // 下巴
  NoseSlim,         // 瘦鼻梁
  EyeSize,          // 大眼
  EyeDistance,      // 眼距
};

beauty_params::Makeup ​

cpp
enum class Makeup {
  Lipstick,         // 口红
  Blush,            // 腮红
};

beauty_params::VirtualBackgroundOptions ​

cpp
struct VirtualBackgroundOptions {
  BackgroundMode mode = BackgroundMode::None;
  std::shared_ptr<const ImageFrame> background_image = nullptr;
  
  VirtualBackgroundOptions() = default;
  explicit VirtualBackgroundOptions(BackgroundMode m) : mode(m) {}
};

beauty_params::BackgroundMode ​

cpp
enum class BackgroundMode {
  None = 0,  // No background processing
  Blur,      // Blur background
  Image,     // Background image replacement
};

错误码说明 ​

返回值约定 ​

大部分方法返回 int 类型，表示操作结果：

  • 0：操作成功
  • 非 0：操作失败，具体错误码请参考错误码定义

常见错误码 ​

  • -1：引擎未初始化
  • -2：无效参数
  • -3：资源文件未找到
  • -4：处理失败

错误处理建议 ​

cpp
auto engine = facebetter::BeautyEffectEngine::Create(config);
if (!engine) {
    // 引擎创建失败
    std::cerr << "Failed to create engine" << std::endl;
    return -1;
}

int result = engine->SetBeautyParam(facebetter::beauty_params::Basic::Smoothing, 0.5f);
if (result != 0) {
    // 参数设置失败
    std::cerr << "Failed to set beauty param, error code: " << result << std::endl;
}

使用注意事项 ​

1. 内存管理 ​

  • 所有返回的智能指针会自动管理内存
  • ImageBuffer 是只读的，不能直接修改数据
  • 避免频繁创建和销毁对象

2. 线程安全 ​

  • BeautyEffectEngine 不是线程安全的
  • 多线程环境下需要适当的同步机制

3. 平台兼容性 ​

  • SetRenderView 仅在 iOS/macOS 平台可用
  • 其他接口在所有支持的平台上都可用

4. 性能优化 ​

  • 根据应用场景选择合适的处理模式
  • 避免频繁的格式转换
  • 重用 ImageBuffer 对象以提高性能