> ## 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 上构建并运行 Facebetter C++ 桌面示例（GLFW + ImGui）

本文介绍如何在 Linux 上构建并运行 Facebetter C++ 桌面 Demo。Demo 使用 **GLFW + Dear ImGui + OpenGL 3** 渲染，左侧实时预览美颜效果，右侧通过滑块控制各项参数。

## 环境要求

| 工具                | 版本要求                                                              |
| ----------------- | ----------------------------------------------------------------- |
| GCC 或 Clang       | 支持 C++17（GCC 7+ / Clang 5+）                                       |
| CMake             | 3.16+                                                             |
| Ninja             | 任意版本（`apt install ninja-build` / `dnf install ninja-build`）       |
| OpenGL 开发库        | `libgl1-mesa-dev`（Ubuntu/Debian）或 `mesa-libGL-devel`（Fedora/RHEL） |
| X11 / Wayland 开发库 | GLFW 依赖（见下方安装命令）                                                  |

### 安装依赖（Ubuntu / Debian）

```bash theme={null}
sudo apt update
sudo apt install -y build-essential cmake ninja-build \
    libgl1-mesa-dev libglu1-mesa-dev \
    libx11-dev libxrandr-dev libxinerama-dev \
    libxcursor-dev libxi-dev
```

### 安装依赖（Fedora / RHEL）

```bash theme={null}
sudo dnf install -y gcc-c++ cmake ninja-build \
    mesa-libGL-devel mesa-libGLU-devel \
    libX11-devel libXrandr-devel libXinerama-devel \
    libXcursor-devel libXi-devel
```

## 第一步：获取示例源码

```bash theme={null}
git clone https://github.com/pixpark/facebetter-sdk.git
cd facebetter-sdk
```

## 第二步：放置 SDK 文件

将 Linux SDK 文件放入 `demo/cpp/sdk/` 目录：

```
demo/cpp/sdk/
├── include/
│   └── facebetter/
│       ├── beauty_effect_engine.h
│       ├── beauty_params.h
│       ├── image_frame.h
│       └── type_defines.h
├── lib/
│   └── libfacebetter.so    ← 动态库
└── resource/
    └── resource.fbd        ← 模型与资源包
```

<Tip>
  SDK 下载地址请前往 [下载页面](https://facebetter.net/zh/download) 或登录控制台查看。
</Tip>

## 第三步：构建

```bash theme={null}
cd demo/cpp
cmake -B build -G "Ninja" -DCMAKE_BUILD_TYPE=Release
cmake --build build
```

CMake 在构建完成后会自动将 `resource/resource.fbd` 和 `demo.png`（如果存在）复制到 `build/resource/` 目录。

## 第四步：准备预览图（可选）

将任意一张人脸图片命名为 `demo.png`，放到 `demo/cpp/` 目录下：

```
demo/cpp/demo.png
```

引擎会每秒约 30 帧地对该图片应用美颜效果，并在窗口左侧实时显示结果。

## 第五步：运行

```bash theme={null}
cd demo/cpp/build

# 方式一：将 libfacebetter.so 所在目录加入运行时搜索路径
LD_LIBRARY_PATH=../sdk/lib ./facebetter_demo

# 方式二：将 libfacebetter.so 复制到可执行文件目录
cp ../sdk/lib/libfacebetter.so .
./facebetter_demo
```

程序运行后，窗口左侧为预览区，右侧为美颜控制面板：

* **Basic Beauty**：磨皮 / 美白 / 红润 / 锐化
* **Face Reshape**：瘦脸 / V脸 / 窄脸 / 短脸 / 颧骨 / 下颌 / 下巴 / 鼻梁 / 大眼 / 眼距
* **Makeup**：口红 / 腮红
* **Sticker**：贴纸选择（Off / rabbit）

点击 **Reset All** 可一键恢复所有参数为默认值。

## 常见问题

**Q：`libfacebetter.so: cannot open shared object file`**\
A：用 `LD_LIBRARY_PATH=../sdk/lib ./facebetter_demo` 运行，或将库文件复制到可执行文件同目录，或使用 `ldconfig` 将路径加入系统库路径。

**Q：CMake 报告找不到 OpenGL**\
A：安装 `libgl1-mesa-dev`（Ubuntu）或 `mesa-libGL-devel`（Fedora）后重新配置。

**Q：窗口显示 "Put demo.png …"**\
A：在 `demo/cpp/` 目录下放置名为 `demo.png` 的人脸图片，然后重新运行。

**Q：显示器无法打开 / `GLFW: X11: Display variable not set`**\
A：确认当前 shell 在图形会话中运行，或设置 `DISPLAY` 环境变量。