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

# Referência da API

> API C++ do Facebetter SDK 2.0 para Linux

<Note>
  SDK **2.0.0**. Namespace `facebetter`. A mesma API C++ pública de [Windows](/pt-BR/windows/api-reference). Headers: `facebetter/*.h`. Enums: [Enums de parâmetros](/pt-BR/intro/makeup). Autenticação: [Autenticação e licença](/pt-BR/intro/license).
</Note>

## Notas do Linux

* Envie `libfacebetter.so`. Defina `LD_LIBRARY_PATH`, rpath ou `ldconfig`.
* Compile o SDK com `./scripts/build_linux.sh` (saída `build/linux/release`) ou CMake.
* `resource_path` precisa ser o **arquivo `resource.fbd`**.
* `SetRenderView` não está disponível.
* `external_context = true` usa o contexto GL atual do thread chamador (GLFW / EGL / OSMesa).

```cmake theme={null}
target_include_directories(app PRIVATE /path/to/sdk/include)
target_link_libraries(app PRIVATE /path/to/sdk/lib/libfacebetter.so GL)
```

***

## Logs

```cpp theme={null}
enum class LogLevel { Trace = 0, Debug, Info, Warn, Error, Critical };

struct LogConfig {
  bool console_enabled = false;
  bool file_enabled = false;
  LogLevel level = LogLevel::Info;
  std::string file_name = "";
};

static int BeautyEffectEngine::SetLogConfig(const LogConfig& config);
```

Chame `SetLogConfig` **antes** de `Create`.

***

## Mecanismo

### `EngineConfig`

| Campo                | Descrição                                                         |
| -------------------- | ----------------------------------------------------------------- |
| `app_id` / `app_key` | Autenticação online v2 nativa                                     |
| `resource_path`      | Caminho para `resource.fbd` (arquivo, não diretório)              |
| `license_token`      | token / JSON `{token}` / `.lic` — não vazio tem prioridade        |
| `external_context`   | `false`: OpenGL gerenciado pelo SDK; `true`: contexto do chamador |

```cpp theme={null}
struct EngineConfig {
  std::string app_id;
  std::string app_key;
  std::string resource_path;
  std::string license_token;
  bool external_context = false;
};

static std::shared_ptr<BeautyEffectEngine> BeautyEffectEngine::Create(
    const EngineConfig& config);
```

***

### Pele

```cpp theme={null}
int SetSmoothing(float intensity);          // [0, 1]
int SetSmoothingStyle(SmoothingStyle style);
int SetWhitening(float intensity);
int SetWhiteningStyle(WhiteningStyle style);
int SetSharpening(float intensity);
int SetRosiness(float intensity);
int SetBeautySkinOnly(bool enabled);
```

### Remodelagem

```cpp theme={null}
int SetReshape(Reshape param, float intensity);  // [-1, 1]
```

Lista completa de `Reshape`: [Enums de parâmetros](/pt-BR/intro/makeup).

### Remodelagem corporal

```cpp theme={null}
int SetBodyReshape(BodyReshape param, float intensity);  // [0, 1]
```

```cpp theme={null}
```

Lista completa de `BodyReshape`: [Enums de parâmetros](/pt-BR/intro/makeup). Exige `resource_body.fbd`. Veja [Pacotes de recursos opcionais](/pt-BR/intro/resource-packs).

### Maquiagem

```cpp theme={null}
int SetLipstick(float);        int SetLipstickColor(LipstickColor);
int SetBlush(float);           int SetBlushStyle(BlushStyle); int SetBlushColor(BlushColor);
int SetContour(float);         int SetContourStyle(ContourStyle);
int SetEyeShadow(float);       int SetEyeShadowStyle(...); int SetEyeShadowColor(...);
int SetEyeLiner(float);        int SetEyeLinerStyle(...);  int SetEyeLinerColor(...);
int SetEyebrow(float);         int SetEyebrowStyle(...);   int SetEyebrowColor(...);
int SetEyelash(float);         int SetEyelashStyle(...);   int SetEyelashColor(...);
int SetPupil(float);           int SetPupilColor(PupilColor);
```

Batom é só Color; pupila é só Color; contorno é só Style. Valores: [Enums de parâmetros](/pt-BR/intro/makeup).

### Chroma key e fundo virtual

```cpp theme={null}
int SetChromaKey(ChromaKeyColor color);  // Green, Blue, Red
int ClearChromaKey();
int SetChromaKeySimilarity(float);
int SetChromaKeySmoothness(float);
int SetChromaKeyDesaturation(float);

int SetVirtualBackgroundBlur(float level);  // [0, 1]; 0 clears fill
int SetVirtualBackground(const std::string& image_path);
int SetVirtualBackground(const std::vector<uint8_t>& image_data);
int ClearVirtualBackground();
```

### Filtro e adesivo

Caminho ou bytes `.fbd` codificados. Sem API de register / ID. Passa a valer no próximo `ProcessImage`.

```cpp theme={null}
int SetFilter(const std::string& fbd_file_path);
int SetFilter(const std::vector<uint8_t>& fbd_data);
int ClearFilter();
int SetFilterIntensity(float intensity);

int SetSticker(const std::string& fbd_file_path);
int SetSticker(const std::vector<uint8_t>& fbd_data);
int ClearSticker();
int AddResourcePack(const std::string& fbd_file_path);
int AddResourcePack(const std::vector<uint8_t>& fbd_data);
int Set3DSticker(const std::string& resource);
int Set3DSticker(const std::vector<uint8_t>& fbd_data);
int Clear3DSticker();
```

Carregue primeiro os pacotes opcionais (`resource_3d.fbd` para adesivos 3D, `resource_body.fbd` para remodelagem corporal). Veja [Pacotes de recursos opcionais](/pt-BR/intro/resource-packs).

### Estatísticas, callbacks, processamento

```cpp theme={null}
EngineStats GetStats() const;
int SetCallbacks(const EngineCallbacks& callbacks);
const std::shared_ptr<ImageFrame> ProcessImage(
    const std::shared_ptr<ImageFrame> image_frame);
```

Defina `frame->type` como `FrameType::Image` ou `FrameType::Video`.

```cpp theme={null}
struct EngineStats {
  double fps = 0.0;
  double avg_process_time_ms = 0.0;
  double session_time_s = 0.0;
};
```

***

## Eventos

| Código | Significado      |
| ------ | ---------------- |
| `0`    | Licença OK       |
| `1`    | Falha de licença |
| `100`  | Init concluído   |
| `101`  | Falha de init    |

```cpp theme={null}
struct EngineCallbacks {
  std::function<void(const std::vector<FaceDetectionResult>&)> on_face_landmarks;
  std::function<void(int code, const std::string& message)> on_engine_event;
};
```

***

## Imagem

```cpp theme={null}
enum class Format { I420, NV12, NV21, BGRA, RGBA, BGR, RGB, Texture };
enum class Rotation { Rotation_0, Rotation_90, Rotation_180, Rotation_270 };
enum class FrameType { Image = 0, Video = 1 };
```

**Factories:** `CreateWithFile`, `Create`, `CreateWithRGBA/BGRA/RGB/BGR`, `CreateWithI420/NV12/NV21`, `CreateWithTexture`.

**Ops:** `Rotate`, `Mirror("horizontal"|"vertical"|"both")`, `SetMirror`, `Convert`, `ToFile`.

**Acessores:** `Width/Height/Stride/Size/GetFormat/Data`, planos YUV, `Texture()`, `Buffer()`. Campo: `FrameType type`.

```cpp theme={null}
struct FaceDetectionResult {
  Rect rect;
  std::vector<Point2d> key_points;  // 111
  std::vector<float> visibility;
  int face_id = -1;
  float score = 0.0f;
  float pitch, roll, yaw;
};
```

***

## Códigos de erro

| Código | Significado        |
| ------ | ------------------ |
| `0`    | OK                 |
| `-1`   | Argumento inválido |
| `-2`   | Não inicializado   |
| `-3`   | Licença            |
| `-4`   | Não suportado      |
| `-5`   | I/O                |
| `-6`   | Sem slot           |
| `-7`   | Processamento      |
| `-8`   | Sem memória        |

Serialize `ProcessImage` em um thread. Os ponteiros de `Data()` dos pixels são somente leitura.