本文档对应 SDK 2.0.0。美妆 / 美型枚举见 参数枚举。
选择正确的帧类型
在processImage: 之前设置 FBImageFrame.type。引擎方法没有独立的处理模式参数。
FBFrameTypeVideo(1):相机预览、直播、通话,延迟更低。FBFrameTypeImage(0):静图 /NSImage,效果更好。
相册大图(预览与导出)
高分辨率静图不要在每次拖动滑条时把原图像素送进processImage:,也不要缩放后丢掉原图。
打开照片时保留完整 NSImage,并另做一份预览帧(长边约 1280–1440,createWithNSImage:)。调参打预览(FBFrameTypeImage);导出对全尺寸帧再处理一次,同一套 setter。输出尺寸等于输入。摄像头预览仍用采集分辨率 + FBFrameTypeVideo。
参数范围
- 美肤 / 美妆 / 滤镜强度:
[0.0, 1.0]。0关闭该项。 - 美型(
setReshape:intensity:):[-1.0, 1.0]。0关闭。正负为相反方向。
一个引擎、一条串行队列
createEngineWithConfig: 返回的是实例,不是进程级单例。每个会话保留一个引擎,并在串行队列上调用(externalContext = YES 时则在 GL 线程)。
内存
- 使用 ARC,用完将
FBImageFrame置nil。 - 相机已是 NV12 / BGRA 时,不要每帧先转成 RGBA。
setFilter:/setSticker:调用一次即可;纹理在下一次processImage:加载。- 用
clearFilter、clearSticker、clearVirtualBackground、clearChromaKey,不要另建引擎。
外部 OpenGL
AppKit 视图已有 桌面 OpenGL 3.2 Core 上下文(NSOpenGLContext / CGL)时:
- 设置
config.externalContext = YES。 - 在该 GL 线程创建引擎(复用调用方当前上下文,不要另建一套)。
- 用
createWithTexture:width:height:stride:包装GL_TEXTURE_2D。 - 输出用
[output texture]。
CVPixelBuffer 混在同一台引擎上。
用 getStats 监控
avgProcessTimeMs 宜低于约 33 ms。桌面 GPU 可跑更高分辨率;界面卡顿时仍应减少效果。
生命周期(AppKit)
引擎放在NSViewController(或会话对象)上。viewWillDisappear 时停止采集。窗口最小化时暂停。在 dealloc / applicationWillTerminate 将引擎置 nil。
FBEngineCallbacks 的 block 里用 __weak。
macOS 采集与显示
- 用
createWithNV12:...、createWithBGRA:...或createWithNSImage:建帧。 - 前置 / 自拍预览:
setMirror:@"horizontal"。 - Retina:按像素尺寸处理(
backingScaleFactor),不要用点尺寸。 - 相机:
NSCameraUsageDescription。沙盒应用的在线授权需要 Outgoing Connections。 - 用户选择的
.fbd/ 背景图:使用 security-scoped URL。
测试
- 绑定 Mac 应用 Bundle ID(命令行工具绑定进程名)。
- 使用真实
appId/appKey或licenseToken。 - 覆盖
FBFrameTypeImage+createWithNSImage:以及FBFrameTypeVideo。 - 断言 setter 返回
FBErrorCode_Success。Universal Binary 请在 Intel 与 Apple Silicon 上都测。

