# C API Documentation

## Structs

### DELPoint2d

Point2d class for landmarks

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

**Members:**
- `float x` - x coordinate of the point
- `float y` - y coordinate of the point

### DELPoint2dArray

Array of Point2d

```c
typedef struct DELPoint2dArray {
    int count;
    DELPoint2d* points;
} DELPoint2dArray;
```

**Members:**
- `int count` - number of points
- `DELPoint2d* points` - pointer to the array of points

### DELBoundingBox

Bounding Box class for the faces

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

**Members:**
- `int x` - x coordinate of the top-left corner
- `int y` - y coordinate of the top-left corner
- `int width` - width of the bounding box in pixels
- `int height` - height of the bounding box in pixels

### DELImageHeader

Descriptor class for image data (non-owning)

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

**Members:**
- `const uint8_t* data` - pointer to the byte array of the image
- `int width` - width of the image in pixels
- `int height` - height of the image in pixels
- `int stride` - length of one row of pixels in bytes (e.g: 3*width + padding)
- `DELImageFormat format` - image format

### DELOutput

Output struct for various estimated outputs

```c
typedef struct DELOutput {
    DELOutputType type;
    union {
        DELGender gender;
        float float_value;
    };
    const char* name;
} DELOutput;
```

**Members:**
- `DELOutputType type` - type of the output
- `DELGender gender` - gender value (when type is DELOutputTypeGender)
- `float float_value` - float value (when type is DELOutputTypeAge or DELOutputTypeAgeUncertainty)
- `const char* name` - name of the output (valid only during callback)

### DELOutputArray

Array of Outputs

```c
typedef struct DELOutputArray {
    int count;
    DELOutput* outputs;
} DELOutputArray;
```

**Members:**
- `int count` - number of outputs
- `DELOutput* outputs` - pointer to the array of outputs

### DELVersion

Semantic version number for the SDK

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

### DELFaceArray

Array of Faces

```c
typedef struct DELFaceArray {
    int count;
    DELFace** faces;
} DELFaceArray;
```

**Members:**
- `int count` - number of faces
- `DELFace** faces` - pointer to the array of face pointers

## Enums

### DELImageFormat

Image format enum

**Values:**
- `DELImageFormatGrayscale = 0` - 8-bit grayscale
- `DELImageFormatRGB = 1` - 24-bit RGB
- `DELImageFormatRGBA = 2` - 32-bit RGBA or 32-bit RGB_
- `DELImageFormatBGR = 3` - 24-bit BGR
- `DELImageFormatBGRA = 4` - 32-bit BGRA or 32-bit BGR_

### DELOutputType

Type of the output in Output struct

**Values:**
- `DELOutputTypeAge = 0` - Age estimation
- `DELOutputTypeGender = 1` - Gender classification
- `DELOutputTypeAgeUncertainty = 2` - Age uncertainty estimation

### DELGender

Gender enum

**Values:**
- `DELGenderFemale = 0` - Female
- `DELGenderMale = 1` - Male

## Callbacks

### DELDetectFacesCallback

```c
typedef void (*DELDetectFacesCallback)(void* user_data, DELFaceArray* faces, const char* error_msg);
```

Callback for face detection

**Parameters:**
- `user_data` - user data passed to the function
- `faces` - array of detected faces. The array and its contents are owned by the library and are valid only during the callback.
- `error_msg` - error message if any, otherwise NULL

### DELEstimateCallback

```c
typedef void (*DELEstimateCallback)(void* user_data, DELOutputArray* outputs, const char* error_msg);
```

Callback for demographic estimation

**Parameters:**
- `user_data` - user data passed to the function
- `outputs` - array of estimation outputs. The array and its contents are owned by the library and are valid only during the callback.
- `error_msg` - error message if any, otherwise NULL

## DemographicEstimator Functions

### del_demographic_estimator_new

```c
DELDemographicEstimator* del_demographic_estimator_new(const char* model_file,
                                                       int max_concurrency,
                                                       char** errorMessage);
```

Constructor: loads model file, sets up the processing.

**Parameters:**
- `model_file` - path for the used model
- `max_concurrency` - maximum allowed concurrency, 0 means automatic (using all cores), default: 0
- `errorMessage` - pointer to a char* that will be set to an error message string on failure, or NULL on success. The caller is responsible for freeing the string using free(). If errorMessage is a NULL pointer, no error message will be returned.

**Returns:** pointer to the new DemographicEstimator instance, or NULL on failure

### del_demographic_estimator_free

```c
void del_demographic_estimator_free(DELDemographicEstimator* estimator);
```

Destructor

**Parameters:**
- `estimator` - pointer to the DemographicEstimator instance to free

### del_demographic_estimator_detect_faces

```c
void del_demographic_estimator_detect_faces(DELDemographicEstimator* estimator,
                                           const DELImageHeader* image_header,
                                           DELDetectFacesCallback callback,
                                           void* user_data);
```

Detects the faces on an image with a callback API.

**Note:** The given ImageHeader doesn't own the image data, and it is safe to delete the data after the call, a copy is happening internally. See DELImageHeader for details.

**Note:** Calling this function is non-blocking, so calling it again with the next frame without waiting for the result is possible. Also see del_demographic_estimator_get_concurrent_calculations().

**Parameters:**
- `estimator` - pointer to the DemographicEstimator instance
- `image_header` - image descriptor
- `callback` - callback to call with the result
- `user_data` - user data to pass to the callback

### del_demographic_estimator_estimate

```c
void del_demographic_estimator_estimate(DELDemographicEstimator* estimator,
                                       const DELFace* face,
                                       DELEstimateCallback callback,
                                       void* user_data);
```

Returns the demographic estimation of the detected face.

**Note:** Calling this function is non-blocking, so calling it again with the next frame without waiting for the result is possible. Also see del_demographic_estimator_get_concurrent_calculations().

**Parameters:**
- `estimator` - pointer to the DemographicEstimator instance
- `face` - the previously detected face to estimate
- `callback` - callback to call with the result
- `user_data` - user data to pass to the callback

### del_demographic_estimator_get_concurrent_calculations

```c
int del_demographic_estimator_get_concurrent_calculations(const DELDemographicEstimator* estimator);
```

Returns the value of the atomic counter for the number of calculations currently running concurrently. You can use this to limit the number of concurrent calculations.

**Parameters:**
- `estimator` - pointer to the DemographicEstimator instance

**Returns:** The (approximate) number of calculations currently in-flight.

### del_demographic_estimator_get_model_name

```c
char* del_demographic_estimator_get_model_name(const DELDemographicEstimator* estimator);
```

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

**Parameters:**
- `estimator` - pointer to the DemographicEstimator instance

**Returns:** name of the model. The caller is responsible for freeing the returned string using free().

### del_demographic_estimator_get_sdk_version

```c
DELVersion del_demographic_estimator_get_sdk_version();
```

Returns the version of the SDK (and not the model)

**Returns:** version of the SDK

### del_demographic_estimator_get_sdk_version_string

```c
char* del_demographic_estimator_get_sdk_version_string();
```

Returns the version string of the SDK (and not the model)

**Returns:** version string of the SDK. The caller is responsible for freeing the returned string using free().

## Face Functions

### del_face_new

```c
DELFace* del_face_new(const DELImageHeader* image_header,
                      const DELPoint2d* landmarks,
                      int num_landmarks,
                      const DELBoundingBox* bbox,
                      float confidence,
                      char** errorMessage);
```

Constructor for the Face object to support 3rd party face detectors

**Parameters:**
- `image_header` - image descriptor
- `landmarks` - face landmarks
- `num_landmarks` - number of landmarks
- `bbox` - face bounding box
- `confidence` - face detection confidence
- `errorMessage` - pointer to a char* that will be set to an error message string on failure, or NULL on success. The caller is responsible for freeing the string using free(). If errorMessage is a NULL pointer, no error message will be returned.

**Returns:** pointer to the new Face instance, or NULL on failure

### del_face_copy

```c
DELFace* del_face_copy(const DELFace* other);
```

Copy constructor

**Parameters:**
- `other` - pointer to the Face instance to copy

**Returns:** pointer to the new Face instance, or NULL on failure

### del_face_free

```c
void del_face_free(DELFace* face);
```

Destructor

**Parameters:**
- `face` - pointer to the Face instance to free

### del_face_bounding_box

```c
DELBoundingBox del_face_bounding_box(const DELFace* face);
```

Returns the bounding box of the detected face

**Parameters:**
- `face` - pointer to the Face instance

**Returns:** DELBoundingBox

### del_face_confidence

```c
float del_face_confidence(const DELFace* face);
```

Returns the confidence value of the detected face

**Parameters:**
- `face` - pointer to the Face instance

**Returns:** float

### del_face_landmarks

```c
DELPoint2dArray* del_face_landmarks(const DELFace* face);
```

Returns the landmarks of the face

**Parameters:**
- `face` - pointer to the Face instance

**Returns:** pointer to DELPoint2dArray. The caller is responsible for freeing the returned array using free().