Functions

This page documents all functions in the Perfectly Clear C API, grouped by purpose.

Main PfC functions

These are the most commonly used functions which will be used in nearly every Perfectly Clear implementation.

PFC_SetProtectionPath

Initializes the SDK license system by specifying the location of license files.

int PFC_SetProtectionPath(const char* utf8FolderPath, const char* licenseCode);

Parameters:

Returns: int status code. See License Status Codes.

PFC_SetParam

Initializes a PFCPARAM structure with parameters from a built-in preset.

void PFC_SetParam(PFCPARAM &param, PFCPRESETID id);

Parameters:

PFC_ReadPresets

Loads image processing settings from a .preset file exported from Perfectly Clear Workbench or Perfectly Clear Complete.

int PFC_ReadPresets(PFCPARAM &param, char* filename);

Parameters:

Returns: int status code. See Preset File Status Codes.

PFC_AutoCorrect

Performs complete image correction in a single call by combining engine creation, calculation, and application.

int PFC_AutoCorrect(
    PFCIMAGE* pImage,
    PFCIMAGE* pImageds,
    PFCPARAM& param,
    int iISO,
    char* pCameraModel,
    BOOL bFastFAE,
    PFC_PROGRESS progfn,
    PFCENGINE* pEngineAI,
    BOOL bUseAutoSDPreset
);

Parameters:

Returns: int. See PFCAPPLYSTATUS. Use decode macros for warnings greater than 0.

PFC_ReleaseProtectionPath

Releases resources allocated by PFC_SetProtectionPath when license validation is no longer needed.

void PFC_ReleaseProtectionPath();

Calc and Apply functions

These functions provide separate calculation and application steps, enabling faster processing when applying different parameters to the same image.

PFC_CreateEngine

Creates a new processing engine instance required for the Calc and Apply workflow.

PFCENGINE* PFC_CreateEngine();

Returns: Pointer to a new PFCENGINE instance.

PFC_Calc

Analyzes an image and calculates correction profiles that can be reused with different parameters.

PFCPROFILE PFC_Calc(
    PFCIMAGE* pImage,
    PFCIMAGE* pImageds,
    PFCENGINE* pEngine,
    unsigned int feature,
    int iISO,
    char* pCameraModel,
    PFCPROFILE pImageProfile,
    PFC_PROGRESS progfn,
    int iRejectOption,
    PFCENGINE* pEngineAI
);

Parameters:

Returns: PFCIMAGEPROFILE containing analysis results.

PFC_Apply

Applies corrections to an image using a previously calculated profile and the specified parameters.

PFCAPPLYSTATUS PFC_Apply(
    PFCIMAGE* pImage,
    PFCENGINE* pEngine,
    PFCPROFILE pImageProfile,
    PFCPARAM& param,
    PFC_PROGRESS progfn,
    int iOpacity,
    void* pBGProfile
);

Parameters:

Returns: PFCAPPLYSTATUS

PFC_ReleaseProfile

Releases memory and resources associated with a calculated image profile.

void PFC_ReleaseProfile(PFCPROFILE pProfile);

PFC_DestroyEngine

Destroys an engine instance and releases all associated resources when processing is complete.

void PFC_DestroyEngine(PFCENGINE* p);

Helper functions

These utility functions provide additional capabilities for face detection, image manipulation, and SDK configuration.

PFC_SetAddonPath

Specifies the directory containing runtime add-on files such as .looks files for Creative LOOKs Filters.

void PFC_SetAddonPath(const char* utf8AddonPath);

PFC_HasFaceBeautification

Checks whether the Face Beautification feature is available in the current engine configuration.

bool PFC_HasFaceBeautification(PFCENGINE* pEngine);

Returns: true if Face Beautification is available.

PFC_FBFaceCount

Returns the number of faces detected during Face Beautification analysis.

int PFC_FBFaceCount(PFCPROFILE pImageProfile);

Returns: Number of faces detected.

PFC_FAEFaceCount

Returns the number of faces detected during Face Aware Exposure analysis.

int PFC_FAEFaceCount(PFCIMAGEPROFILE* pImageProfile);

Returns: Number of faces detected.

PFC_GetFaceInfo

Retrieves detailed geometry information for a specific detected face by index.

bool PFC_GetFaceInfo(PFCIMAGEPROFILE* pImageProfile, PFCFBFACEINFO* pFace, int index);

Parameters:

Returns: true if face info retrieved successfully.

PFC_EnumFAEFaceRect

Iterates through all faces detected during Face Aware Exposure analysis using a linked list pattern.

LPPFCFACERECT PFC_EnumFAEFaceRect(PFCIMAGEPROFILE* pImageProfile, LPPFCFACERECT p);

Parameters:

Returns: Pointer to next PFCFACERECT, or NULL when done.

Example:

PFCFACERECT* face = NULL;
while ((face = PFC_EnumFAEFaceRect(pProfile, face))) {
    // Use face->rect, face->ptEyeL, face->ptEyeR
}

PFC_IsNoiseDetected

Determines whether noise was detected in the image for a specific noise preset configuration.

bool PFC_IsNoiseDetected(PFCIMAGEPROFILE* pImageProfile, int iNoisePreset);

Returns: true if noise is detected.

PFC_AbnormalTintDetected

Determines whether an abnormal color tint was detected in the image.

bool PFC_AbnormalTintDetected(PFCIMAGEPROFILE* pImageProfile, TINTCORRECTION eTintMethod);

Returns: true if abnormal tint detected.

PFC_SetSingleThreadedEngine

Configures an engine to use single-threaded processing instead of the default multi-threaded mode.

void PFC_SetSingleThreadedEngine(PFCENGINE* p, bool bSingleThreaded);

PFC_GetVersion

Retrieves the SDK version string and feature information for diagnostics and compatibility checks.

void PFC_GetVersion(char* buf, int* len, bool bFormatted);

Parameters:

PFC_Resize

Resizes an image from source dimensions to the dimensions specified in the destination structure.

PFCAPPLYSTATUS PFC_Resize(PFCIMAGE* pImageSrc, PFCIMAGE* pImageDst);

PFC_TransposeExif

Rotates and flips an image to match or reverse EXIF orientation metadata.

PFCAPPLYSTATUS PFC_TransposeExif(PFCIMAGE* pImageSrc, int iEXIFOrientation);

Parameters:

PFC_ApplyStrengthToParam

Scales all correction parameters by a global strength multiplier for easy intensity adjustment.

void PFC_ApplyStrengthToParam(PFCPARAM& param, int strength);

Parameters:

PFCImageFile helper class functions

These APIs are methods of the optional C++ PFCImageFile helper class used to read and write JPEG/PNG/WebP data, preserve EXIF metadata, and manage color space conversion.

PFCImageFile::LoadImageFile

Loads JPEG, PNG, or RAW image data from disk.

PFC_FILE_LOAD_STATUS LoadImageFile(const char* filename, bool bConvertToSRGB, const char* iccFolderPath);
PFC_FILE_LOAD_STATUS LoadImageFile(const char* filename, PFC_FILETYPE type, bool bConvertToSRGB, const char* iccFolderPath);

Parameters:

Returns: PFC_FILE_LOAD_STATUS.

PFCImageFile::ExpandImageBuffer

Expands compressed image bytes from memory buffer into image data.

PFC_FILE_LOAD_STATUS ExpandImageBuffer(char* data, long size, PFC_FILETYPE type, bool bConvertToSRGB, const char* iccFolderPath);

PFCImageFile::CompressImageBuffer

Compresses image data to a selected output type and writes to an output buffer.

int CompressImageBuffer(unsigned char** destination, PFC_FILETYPE type, int quality, bool bConvertToOriginalColorSpace, bool bEmbedOriginalMetadata);

PFCImageFile::SaveImageFile

Writes image data to disk using either filename extension or explicit file type.

bool SaveImageFile(const char* filename, int quality, bool bConvertToOriginalColorSpace, bool bEmbedOriginalMetadata);
bool SaveImageFile(const char* filename, PFC_FILETYPE type, int quality, bool bConvertToOriginalColorSpace, bool bEmbedOriginalMetadata);

PFCImageFile::SetOutputIccProfile

Loads an ICC profile from disk for output image saving.

bool SetOutputIccProfile(const char* filename);

PFCImageFile metadata and buffer accessors

void AllocBuffer(int width, int height, int bytes_per_pixel, int stride);
int pfcImageFormat();
int exifOrientation();
int iISO();
const char* cameraModel();
const char* exifSoftware();

These helper methods expose EXIF and image-buffer metadata after loading image content.

AI functions

These functions enable AI-powered features including Scene Detection, AI Corrections, and AI Color for intelligent automatic adjustments.

PFC_LoadAIEngine

Loads AI model files into an engine to enable AI-powered correction features.

int PFC_LoadAIEngine(
    PFCENGINE* pEngineAI,
    unsigned int aifeatures,
    const char* binPath
);

Parameters:

Returns: Bitwise OR of successfully loaded PFCAIFEATURE flags.

Example:

PFCENGINE* pEngineAI = PFC_CreateEngine();
int loaded = PFC_LoadAIEngine(pEngineAI, 
    AI_SCENE_DETECTION | AI_CORRECTIONS | AI_COLOR, 
    "/path/to/models");

PFC_LoadScenePresets

Loads scene-specific preset configurations from a file for use with AI Scene Detection.

int PFC_LoadScenePresets(
    PFCENGINE* pEngine,
    const char* filePath,
    int modelUuid,
    int* presetUuid,
    int arrProfileUUIDLen
);

Returns: Same as PFC_ReadPresets.

PFC_LoadScenePresetsFromStream

Loads AI Scene Detection group presets from an in-memory buffer, and can reload different Scene Detection models as needed by the preset.

int PFC_LoadScenePresetsFromStream(
    PFCENGINE* pEngine,
    const char* buf,
    int lenBuf,
    int modelUuid,
    int* presetUuid,
    int arrProfileUUIDLen
);

Parameters:

Returns: 0 on success, or same error codes as PFC_ReadPresets.

PFC_ReadScenePreset

Populates correction parameters with values optimized for a specific detected scene type.

int PFC_ReadScenePreset(PFCPARAM& param, PFCENGINE* pEngineAI, int scene);

PFC_GetScene

Retrieves the AI-detected scene classification label from a calculated profile.

int PFC_GetScene(PFCPROFILE precalc, int* version);

Returns: Detected scene label, or -1 if none.

PFC_GetSceneDetectionEngineInfo

Retrieves categorization model information loaded with PFC_LoadAIEngine, including group UUID and supported preset UUIDs.

bool PFC_GetSceneDetectionEngineInfo(
    PFCENGINE* pEngine,
    int* groupUUID,
    int* arrProfileUUID,
    int* arrProfileUUIDLen
);

Parameters:

Returns: false when AI engine is not loaded or model does not support categorization.

PFC_GetLastSceneProperties

Returns the last detected scene label and confidence from the AI engine.

void PFC_GetLastSceneProperties(PFCENGINE* pEngine, int* lastSceneLabel, int* lastSceneConfidence);

PFC_GetAutoSkintoneParameters

Returns auto skin tone parameters for a given skin tone type, including LUT GUID and recommended strengths.

const char* PFC_GetAutoSkintoneParameters(int skintoneType, int* strengthLut, int* strengthExposure);

Parameters:

Returns: Zero-terminated LUT GUID string.

PFC_FillAiAutoValues

Fills PFCPARAM with final auto values derived from AI detection results in PFCIMAGEPROFILE.

PFCAPPLYSTATUS PFC_FillAiAutoValues(PFCPARAM& param, PFCIMAGEPROFILE* profile);

Returns: APPLY_SUCCESS on success, or APPLY_ERROR_AI_CORRECTION_MISSING when required AI results are not present.

PFC_ReadPresetsFromStream

Loads image processing settings from a preset stream buffer. This is similar to PFC_ReadPresets but uses in-memory data instead of a file path.

int PFC_ReadPresetsFromStream(PFCPARAM& param, const char* s);

PFC_WasmSetCertificate

Passes certificate data to authorize WASM SDK usage for a specific API key and domain.

int PFC_WasmSetCertificate(PFCENGINE* pEngine, const char* clientAPIKey, const char* certificate);

Returns: Positive value means seconds valid; negative value is PFCAPPLYSTATUS.

PFC_TrackSave

Reports an image save event from the WASM SDK.

void PFC_TrackSave(const char* clientAPIKey);

PFC_DetectCompositeImage

Analyzes an image to determine whether it is a photograph or a composite graphic.

int PFC_DetectCompositeImage(PFCIMAGE* pImage, PFCENGINE* pEngine);

Returns: PFCCOMPOSITE detection result.

PFC_GetSceneDescription

Retrieves human-readable metadata about a scene detection classification by index.

bool PFC_GetSceneDescription(PFCENGINE* pEngine, int index, PFCSCENEDESCRIPTION* sceneDescription);

Returns: true on success.

Callback types

These type definitions specify function signatures for callbacks used during SDK operations.

PFC_PROGRESS

Defines the signature for progress callback functions that receive processing status updates.

typedef BOOL (*PFC_PROGRESS)(int iPercent);

Parameters:

Returns: TRUE to cancel processing, FALSE to continue.