跑通 Linux 示例程序

本文介绍如何在 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）

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）

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

第一步：获取示例源码

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 下载地址请前往 下载页面 或登录控制台查看。

第三步：构建

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 帧地对该图片应用美颜效果，并在窗口左侧实时显示结果。

第五步：运行

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 环境变量。