# C API Reference

The C API provides a plain C interface to the Face Verification Library, suitable for integration with C programs and other languages through FFI.

---

## Opaque Types

### FVLFaceVerifier

```c
typedef struct FVLFaceVerifier FVLFaceVerifier;
```

Opaque handle to a FaceVerifier instance.

### FVLFace

```c
typedef struct FVLFace FVLFace;
```

Opaque handle to a Face instance.

---

## FaceVerifier Functions

### fvl_face_verifier_new

```c
FVLFaceVerifier* fvl_face_verifier_new(const char* model_file, int max_concurrency, char** errorMessage);
```

Creates a new FaceVerifier instance. Loads the model file and sets up processing.

| Parameter | Type | Description |
|-----------|------|-------------|
| model_file | `const char*` | Path to the `.realZ` model file |
| max_concurrency | `int` | Maximum allowed concurrency. 0 means automatic (all cores) |
| errorMessage | `char**` | Output: set to error message on failure, `NULL` on success. Caller must `free()`. Pass `NULL` to skip. |

**Returns:** Pointer to the new instance, or `NULL` on failure.

### fvl_face_verifier_free

```c
void fvl_face_verifier_free(FVLFaceVerifier* verifier);
```

Frees a FaceVerifier instance.

| Parameter | Type | Description |
|-----------|------|-------------|
| verifier | [`FVLFaceVerifier`](#fvlfaceverifier)`*` | Instance to free |

### fvl_face_verifier_detect_faces

```c
void fvl_face_verifier_detect_faces(FVLFaceVerifier* verifier, const FVLImageHeader* image_header,
                                     FVLDetectFacesCallback callback, void* user_data);
```

Detects faces on an image asynchronously. The callback is invoked with the result.

| Parameter | Type | Description |
|-----------|------|-------------|
| verifier | [`FVLFaceVerifier`](#fvlfaceverifier)`*` | FaceVerifier instance |
| image_header | `const` [`FVLImageHeader`](#fvlimageheader)`*` | Image descriptor |
| callback | [`FVLDetectFacesCallback`](#fvldetectfacescallback) | Callback invoked with the result |
| user_data | `void*` | User data passed to the callback |

The image data is copied internally — it is safe to free the data after the call. This call is non-blocking.

### fvl_face_verifier_embed_face

```c
void fvl_face_verifier_embed_face(FVLFaceVerifier* verifier, const FVLFace* face,
                                   FVLEmbedFaceCallback callback, void* user_data);
```

Computes the embedding of a detected face asynchronously.

| Parameter | Type | Description |
|-----------|------|-------------|
| verifier | [`FVLFaceVerifier`](#fvlfaceverifier)`*` | FaceVerifier instance |
| face | `const` [`FVLFace`](#fvlface)`*` | The previously detected face |
| callback | [`FVLEmbedFaceCallback`](#fvlembedFacecallback) | Callback invoked with the result |
| user_data | `void*` | User data passed to the callback |

### fvl_face_verifier_compare_faces

```c
FVLMatch fvl_face_verifier_compare_faces(FVLFaceVerifier* verifier,
                                          const float* embedding1, int size1,
                                          const float* embedding2, int size2);
```

Compares two face embeddings.

| Parameter | Type | Description |
|-----------|------|-------------|
| verifier | [`FVLFaceVerifier`](#fvlfaceverifier)`*` | FaceVerifier instance |
| embedding1 | `const float*` | First face embedding |
| size1 | `int` | Size of the first embedding |
| embedding2 | `const float*` | Second face embedding |
| size2 | `int` | Size of the second embedding |

**Returns:** [`FVLMatch`](#fvlmatch) — match result with similarity metric.

### fvl_face_verifier_get_concurrent_calculations

```c
int fvl_face_verifier_get_concurrent_calculations(const FVLFaceVerifier* verifier);
```

Returns the approximate number of calculations currently in-flight.

| Parameter | Type | Description |
|-----------|------|-------------|
| verifier | `const` [`FVLFaceVerifier`](#fvlfaceverifier)`*` | FaceVerifier instance |

**Returns:** `int` — number of concurrent calculations.

### fvl_face_verifier_get_model_name

```c
char* fvl_face_verifier_get_model_name(const FVLFaceVerifier* verifier);
```

Returns the name (version, etc.) of the loaded model.

| Parameter | Type | Description |
|-----------|------|-------------|
| verifier | `const` [`FVLFaceVerifier`](#fvlfaceverifier)`*` | FaceVerifier instance |

**Returns:** `char*` — model name string. **Caller must `free()` the returned string.**

### fvl_face_verifier_get_sdk_version

```c
FVLVersion fvl_face_verifier_get_sdk_version();
```

Returns the SDK version.

**Returns:** [`FVLVersion`](#fvlversion) — SDK version.

### fvl_face_verifier_get_sdk_version_string

```c
char* fvl_face_verifier_get_sdk_version_string();
```

Returns the SDK version as a string.

**Returns:** `char*` — version string. **Caller must `free()` the returned string.**

---

## Face Functions

### fvl_face_new

```c
FVLFace* fvl_face_new(const FVLImageHeader* image_header, const FVLPoint2d* landmarks,
                       int num_landmarks, const FVLBoundingBox* bbox, float confidence,
                       char** errorMessage);
```

Creates a Face object to support 3rd party face detectors.

| Parameter | Type | Description |
|-----------|------|-------------|
| image_header | `const` [`FVLImageHeader`](#fvlimageheader)`*` | Image descriptor |
| landmarks | `const` [`FVLPoint2d`](#fvlpoint2d)`*` | Face landmarks array |
| num_landmarks | `int` | Number of landmarks |
| bbox | `const` [`FVLBoundingBox`](#fvlboundingbox)`*` | Face bounding box |
| confidence | `float` | Detection confidence |
| errorMessage | `char**` | Output: error message on failure. Caller must `free()`. Pass `NULL` to skip. |

**Returns:** Pointer to the new Face instance, or `NULL` on failure.

### fvl_face_copy

```c
FVLFace* fvl_face_copy(const FVLFace* other);
```

Creates a copy of a Face instance.

| Parameter | Type | Description |
|-----------|------|-------------|
| other | `const` [`FVLFace`](#fvlface)`*` | Face to copy |

**Returns:** Pointer to the new Face copy, or `NULL` on failure.

### fvl_face_free

```c
void fvl_face_free(FVLFace* face);
```

Frees a Face instance.

| Parameter | Type | Description |
|-----------|------|-------------|
| face | [`FVLFace`](#fvlface)`*` | Face to free |

### fvl_face_detection_quality

```c
FVLDetectionQuality fvl_face_detection_quality(const FVLFace* face);
```

Returns the detection quality of the face.

| Parameter | Type | Description |
|-----------|------|-------------|
| face | `const` [`FVLFace`](#fvlface)`*` | Face instance |

**Returns:** [`FVLDetectionQuality`](#fvldetectionquality)

### fvl_face_bounding_box

```c
FVLBoundingBox fvl_face_bounding_box(const FVLFace* face);
```

Returns the bounding box of the face.

| Parameter | Type | Description |
|-----------|------|-------------|
| face | `const` [`FVLFace`](#fvlface)`*` | Face instance |

**Returns:** [`FVLBoundingBox`](#fvlboundingbox)

### fvl_face_confidence

```c
float fvl_face_confidence(const FVLFace* face);
```

Returns the confidence value of the face.

| Parameter | Type | Description |
|-----------|------|-------------|
| face | `const` [`FVLFace`](#fvlface)`*` | Face instance |

**Returns:** `float` — detection confidence.

### fvl_face_landmarks

```c
FVLPoint2dArray* fvl_face_landmarks(const FVLFace* face);
```

Returns the landmarks of the face.

| Parameter | Type | Description |
|-----------|------|-------------|
| face | `const` [`FVLFace`](#fvlface)`*` | Face instance |

**Returns:** [`FVLPoint2dArray`](#fvlpoint2darray)`*` — landmark array. **Caller must `free()` the returned array.**

---

## Data Types

### FVLPoint2d

```c
typedef struct FVLPoint2d {
    float x;
    float y;
} FVLPoint2d;
```

| Field | Type | Description |
|-------|------|-------------|
| x | `float` | X coordinate of the point |
| y | `float` | Y coordinate of the point |

### FVLPoint2dArray

```c
typedef struct FVLPoint2dArray {
    int count;
    FVLPoint2d* points;
} FVLPoint2dArray;
```

| Field | Type | Description |
|-------|------|-------------|
| count | `int` | Number of points |
| points | [`FVLPoint2d`](#fvlpoint2d)`*` | Pointer to the array of points |

### FVLBoundingBox

```c
typedef struct FVLBoundingBox {
    int x;
    int y;
    int width;
    int height;
} FVLBoundingBox;
```

| Field | Type | Description |
|-------|------|-------------|
| x | `int` | X coordinate of the top-left corner |
| y | `int` | Y coordinate of the top-left corner |
| width | `int` | Width in pixels |
| height | `int` | Height in pixels |

### FVLImageHeader

```c
typedef struct FVLImageHeader {
    const uint8_t* data;
    int width;
    int height;
    int stride;
    FVLImageFormat format;
} FVLImageHeader;
```

| Field | Type | Description |
|-------|------|-------------|
| data | `const uint8_t*` | Pointer to the byte array of the image |
| width | `int` | Width of the image in pixels |
| height | `int` | Height of the image in pixels |
| stride | `int` | Length of one row of pixels in bytes (e.g., `3*width + padding`) |
| format | [`FVLImageFormat`](#fvlimageformat) | Image pixel format |

### FVLMatch

```c
typedef struct FVLMatch {
    float similarity;
} FVLMatch;
```

| Field | Type | Description |
|-------|------|-------------|
| similarity | `float` | Similarity score between the two faces |

### FVLVersion

```c
typedef struct FVLVersion {
    int major;
    int minor;
    int patch;
} FVLVersion;
```

| Field | Type | Description |
|-------|------|-------------|
| major | `int` | Major version number |
| minor | `int` | Minor version number |
| patch | `int` | Patch version number |

### FVLFaceArray

```c
typedef struct FVLFaceArray {
    int count;
    FVLFace** faces;
} FVLFaceArray;
```

| Field | Type | Description |
|-------|------|-------------|
| count | `int` | Number of faces |
| faces | [`FVLFace`](#fvlface)`**` | Pointer to the array of face pointers |

### FVLFloatArray

```c
typedef struct FVLFloatArray {
    int count;
    float* data;
} FVLFloatArray;
```

| Field | Type | Description |
|-------|------|-------------|
| count | `int` | Number of floats |
| data | `float*` | Pointer to the array of floats |

---

## Enumerations

### FVLImageFormat

```c
typedef enum FVLImageFormat {
    FVLImageFormatGrayscale = 0,
    FVLImageFormatRGB       = 1,
    FVLImageFormatRGBA      = 2,
    FVLImageFormatBGR       = 3,
    FVLImageFormatBGRA      = 4,
} FVLImageFormat;
```

| Value | Description |
|-------|-------------|
| `FVLImageFormatGrayscale` | 8-bit grayscale |
| `FVLImageFormatRGB` | 24-bit RGB |
| `FVLImageFormatRGBA` | 32-bit RGBA or RGB with padding |
| `FVLImageFormatBGR` | 24-bit BGR |
| `FVLImageFormatBGRA` | 32-bit BGRA or BGR with padding |

### FVLDetectionQuality

```c
typedef enum FVLDetectionQuality {
    FVLDetectionQualityGood        = 0,
    FVLDetectionQualityBadQuality  = 1,
    FVLDetectionQualityMaybeRolled = 2,
} FVLDetectionQuality;
```

| Value | Description |
|-------|-------------|
| `FVLDetectionQualityGood` | No issues detected |
| `FVLDetectionQualityBadQuality` | Bad quality detected |
| `FVLDetectionQualityMaybeRolled` | Face may be rolled; embeddings could be incorrect |

---

## Callback Types

### FVLDetectFacesCallback

```c
typedef void (*FVLDetectFacesCallback)(void* user_data, FVLFaceArray* faces, const char* error_msg);
```

Callback for face detection results.

| Parameter | Type | Description |
|-----------|------|-------------|
| user_data | `void*` | User data passed to the detection function |
| faces | [`FVLFaceArray`](#fvlfacearray)`*` | Array of detected faces. Valid only during the callback. |
| error_msg | `const char*` | Error message if failed, `NULL` on success. Valid only during the callback. |

### FVLEmbedFaceCallback

```c
typedef void (*FVLEmbedFaceCallback)(void* user_data, FVLFloatArray* embedding, const char* error_msg);
```

Callback for face embedding results.

| Parameter | Type | Description |
|-----------|------|-------------|
| user_data | `void*` | User data passed to the embedding function |
| embedding | [`FVLFloatArray`](#fvlfloatarray)`*` | Embedding vector. Valid only during the callback. |
| error_msg | `const char*` | Error message if failed, `NULL` on success. Valid only during the callback. |

**Important:** The `faces`/`embedding` and `error_msg` parameters are only valid during the callback execution. Copy any data you need to retain before the callback returns.

---

## Memory Management Summary

| Function Returns | Must Free? | How |
|------------------|------------|-----|
| [`fvl_face_verifier_new()`](#fvl_face_verifier_new) | Yes | [`fvl_face_verifier_free()`](#fvl_face_verifier_free) |
| [`fvl_face_new()`](#fvl_face_new) | Yes | [`fvl_face_free()`](#fvl_face_free) |
| [`fvl_face_copy()`](#fvl_face_copy) | Yes | [`fvl_face_free()`](#fvl_face_free) |
| [`fvl_face_landmarks()`](#fvl_face_landmarks) | Yes | `free()` |
| [`fvl_face_verifier_get_model_name()`](#fvl_face_verifier_get_model_name) | Yes | `free()` |
| [`fvl_face_verifier_get_sdk_version_string()`](#fvl_face_verifier_get_sdk_version_string) | Yes | `free()` |
| `errorMessage` output parameter | Yes | `free()` |
| Callback parameters | No | Valid only during callback |