跳转到主要内容
本文档对应 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)时:
  1. 设置 config.externalContext = YES。
  2. 在该 GL 线程创建引擎(复用调用方当前上下文,不要另建一套)。
  3. 用 createWithTexture:width:height:stride: 包装 GL_TEXTURE_2D。
  4. 输出用 [output texture]。
macOS 走桌面 OpenGL,不是 OpenGL ES。不要把外部纹理和 CVPixelBuffer 混在同一台引擎上。

用 getStats 监控

30 fps 时 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 上都测。