> ## 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.

# 实现美颜

> 在 Linux 平台使用 C++ 接口集成 Facebetter SDK 实现美颜效果

Linux 桌面平台通过 C++ 接口调用 Facebetter SDK。Linux 与 Windows 平台共用同一套 C++ API，本文以 [C++ Demo](https://github.com/pixpark/facebetter-sdk) 为参考，介绍完整的集成流程。

## 引入头文件

```cpp theme={null}
#include <facebetter/beauty_effect_engine.h>
#include <facebetter/beauty_params.h>
#include <facebetter/image_frame.h>
#include <facebetter/type_defines.h>

using namespace facebetter;
using namespace facebetter::beauty_params;
```

## 集成流程概览

```
配置日志 → 创建引擎 → 启用美颜类型 → 设置参数 → 逐帧处理 → 渲染结果
```

***

## 1. 配置日志（可选）

日志配置须在创建引擎前调用。

```cpp theme={null}
LogConfig log_cfg;
log_cfg.console_enabled = true;
log_cfg.file_enabled    = false;
log_cfg.level           = LogLevel::Info;
BeautyEffectEngine::SetLogConfig(log_cfg);
```

日志级别（从低到高）：`Trace` / `Debug` / `Info` / `Warn` / `Error` / `Critical`。

***

## 2. 创建引擎

```cpp theme={null}
EngineConfig eng_cfg;
eng_cfg.app_id        = "your_app_id";
eng_cfg.app_key       = "your_app_key";
eng_cfg.resource_path = "resource/resource.fbd";
eng_cfg.external_context = false;

std::shared_ptr<BeautyEffectEngine> engine = BeautyEffectEngine::Create(eng_cfg);
if (!engine) {
    return -1;
}
```

> 运行时需确保 `libfacebetter.so` 可被找到：将其放在可执行文件同目录，或通过 `LD_LIBRARY_PATH` 指定路径。

***

## 3. 启用美颜类型

SDK 默认所有美颜类型均为**关闭**状态，需显式启用：

```cpp theme={null}
engine->SetBeautyTypeEnabled(BeautyType::Basic,   true);
engine->SetBeautyTypeEnabled(BeautyType::Reshape, true);
engine->SetBeautyTypeEnabled(BeautyType::Makeup,  true);
engine->SetBeautyTypeEnabled(BeautyType::Sticker, true);
```

***

## 4. 设置美颜参数

所有参数值范围均为 `[0.0, 1.0]`，`0` 表示关闭。

### 基础美颜

```cpp theme={null}
engine->SetBeautyParam(Basic::Smoothing,  0.5f);
engine->SetBeautyParam(Basic::Whitening,  0.3f);
engine->SetBeautyParam(Basic::Rosiness,   0.2f);
engine->SetBeautyParam(Basic::Sharpening, 0.4f);
```

### 美颜仅作用于皮肤区域

通过 `SetSkinOnlyBeauty` 接口，设置美颜是否仅作用于皮肤区域。当启用时，美颜效果（磨皮、美白等）仅会应用于检测到的皮肤区域，非皮肤区域保持不变。

```cpp theme={null}
// 启用美颜仅作用于皮肤区域
engine->SetSkinOnlyBeauty(true);

// 禁用美颜仅作用于皮肤区域（美颜作用于整张图像）
engine->SetSkinOnlyBeauty(false);
```

<Tip>
  启用皮肤区域美颜后，即使美颜参数值较高，非皮肤区域（如背景、衣物等）也不会受到影响。
</Tip>

### 美型

```cpp theme={null}
engine->SetBeautyParam(Reshape::FaceThin,    0.4f);
engine->SetBeautyParam(Reshape::FaceVShape,  0.3f);
engine->SetBeautyParam(Reshape::FaceNarrow,  0.2f);
engine->SetBeautyParam(Reshape::FaceShort,   0.2f);
engine->SetBeautyParam(Reshape::Cheekbone,   0.3f);
engine->SetBeautyParam(Reshape::Jawbone,     0.2f);
engine->SetBeautyParam(Reshape::Chin,        0.2f);
engine->SetBeautyParam(Reshape::NoseSlim,    0.3f);
engine->SetBeautyParam(Reshape::EyeSize,     0.4f);
engine->SetBeautyParam(Reshape::EyeDistance, 0.1f);
```

### 美妆

```cpp theme={null}
engine->SetBeautyParam(Makeup::Lipstick, 0.6f);
engine->SetBeautyParam(Makeup::Blush,    0.4f);
```

### 贴纸

```cpp theme={null}
engine->SetSticker("rabbit");  // 启用贴纸
engine->SetSticker("");        // 关闭贴纸
```

### 滤镜

```cpp theme={null}
engine->SetFilter("chuxin");
engine->SetFilterIntensity(0.8f);
engine->SetFilter("");  // 关闭滤镜
```

***

## 5. 处理帧

```cpp theme={null}
// 从内存 RGBA 数据创建输入帧
auto input_frame = ImageFrame::CreateWithRGBA(
    rgba_data, width, height, stride);
input_frame->type = FrameType::Video;  // 实时视频流

auto output_frame = engine->ProcessImage(input_frame);

if (output_frame && output_frame->Data()) {
    const uint8_t* data = output_frame->Data();
    int w = output_frame->Width();
    int h = output_frame->Height();
}
```

**单帧图片处理：**

```cpp theme={null}
auto input_frame  = ImageFrame::CreateWithFile("input.jpg");
input_frame->type = FrameType::Image;
auto output_frame = engine->ProcessImage(input_frame);
```

**格式转换：**

```cpp theme={null}
auto bgra_frame = output_frame->Convert(Format::BGRA);
auto i420_frame = output_frame->Convert(Format::I420);
```

***

## 6. 与 OpenGL 集成（渲染预览）

```cpp theme={null}
// 创建纹理（一次性）
GLuint tex;
glGenTextures(1, &tex);
glBindTexture(GL_TEXTURE_2D, tex);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);

// 每帧上传数据
glBindTexture(GL_TEXTURE_2D, tex);
glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA,
             output_frame->Width(), output_frame->Height(),
             0, GL_RGBA, GL_UNSIGNED_BYTE, output_frame->Data());

// ImGui 显示
ImGui::Image(
    static_cast<ImTextureID>(static_cast<intptr_t>(tex)),
    ImVec2(img_w, img_h));
```

***

## 7. 完整示例（实时处理循环）

```cpp theme={null}
#include <facebetter/beauty_effect_engine.h>
#include <facebetter/beauty_params.h>
#include <facebetter/image_frame.h>
#include <glad/glad.h>
#include <GLFW/glfw3.h>

using namespace facebetter;
using namespace facebetter::beauty_params;

// 初始化
LogConfig log_cfg;
log_cfg.console_enabled = true;
log_cfg.level = LogLevel::Info;
BeautyEffectEngine::SetLogConfig(log_cfg);

EngineConfig eng_cfg;
eng_cfg.app_id           = "your_app_id";
eng_cfg.app_key          = "your_app_key";
eng_cfg.resource_path    = "resource/resource.fbd";
eng_cfg.external_context = false;

auto engine = BeautyEffectEngine::Create(eng_cfg);
engine->SetBeautyTypeEnabled(BeautyType::Basic,   true);
engine->SetBeautyTypeEnabled(BeautyType::Reshape, true);
engine->SetBeautyTypeEnabled(BeautyType::Makeup,  true);
engine->SetBeautyTypeEnabled(BeautyType::Sticker, true);

engine->SetBeautyParam(Basic::Smoothing,  0.5f);
engine->SetBeautyParam(Reshape::FaceThin, 0.4f);
engine->SetBeautyParam(Makeup::Lipstick,  0.6f);

// 处理循环（~30fps）
double last_time = 0.0;
const double kInterval = 1.0 / 30.0;
GLuint preview_tex = 0;

while (!glfwWindowShouldClose(window)) {
    glfwPollEvents();
    double now = glfwGetTime();
    if (now - last_time >= kInterval) {
        auto input = ImageFrame::CreateWithRGBA(
            rgba_buffer, width, height, stride);
        input->type = FrameType::Video;

        auto output = engine->ProcessImage(input);
        if (output && output->Data()) {
            if (preview_tex == 0) {
                glGenTextures(1, &preview_tex);
                glBindTexture(GL_TEXTURE_2D, preview_tex);
                glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MIN_FILTER, GL_LINEAR);
                glTexParameteri(GL_TEXTURE_2D, GL_TEXTURE_MAG_FILTER, GL_LINEAR);
            }
            glBindTexture(GL_TEXTURE_2D, preview_tex);
            glTexImage2D(GL_TEXTURE_2D, 0, GL_RGBA,
                         output->Width(), output->Height(),
                         0, GL_RGBA, GL_UNSIGNED_BYTE, output->Data());
        }
        last_time = now;
    }
    // ... ImGui render ...
}

// 释放
if (preview_tex) glDeleteTextures(1, &preview_tex);
engine.reset();
```

***

## 参数速查表

与 Windows 平台完全一致，请参考 [Windows 美颜参数速查表](../windows/implement-beauty#参数速查表)。

## 使用滤镜和贴纸

### 滤镜

```cpp theme={null}
engine->SetFilter("chuxin");
engine->SetFilterIntensity(0.8f);
engine->SetFilter("");
```

### 贴纸

```cpp theme={null}
engine->SetSticker("rabbit");
engine->SetSticker("");
```