Core API

Plugin API Surface

Core C ABI contract between VLiva host, PluginManager, and plugins based on plugin_api.h.

5 sections

3 source files

Core API

Overview

What this page covers

  1. 01API Versioning
  2. 02Host Callbacks (VlivaHostApi)
  3. 03Tracking Snapshot (VlivaTrackingFrame)
  4. 04Plugin Surface (VlivaPluginApi)
  5. 05Factory Symbol (create_plugin)
Source files referenced by this page
  • include/vliva/plugins/plugin_api.h
  • include/vliva/plugins/plugin_manager.hpp
  • plugins/example_plugin.cpp

Full source: github.com/TamKungZ/VLiva

Section 1

API Versioning

Every plugin should advertise and validate API version compatibility before use.

  • Host and plugin must agree on VLIVA_PLUGIN_API_VERSION.
  • Tracking payload schema is versioned by VLIVA_TRACKING_FRAME_VERSION.
  • Model and tracking_mode capacities are fixed by compile-time constants.
  • Mismatch should be rejected by host safely.

c

#define VLIVA_PLUGIN_API_VERSION 1u
#define VLIVA_TRACKING_FRAME_VERSION 1u
#define VLIVA_TRACKING_MODEL_NAME_CAPACITY 128u
#define VLIVA_TRACKING_MODE_NAME_CAPACITY 64u

Section 2

Host Callbacks (VlivaHostApi)

The host exposes logging, tracking snapshot access, and UDP bridge callbacks.

  • The pointer is received in on_load(host).
  • get_tracking_frame() provides latest resolved parameters for plugin-side protocols.
  • udp_configure() and udp_send() allow plugins to reuse host UDP networking.
  • Always guard callback pointers before calling optional services.

c

typedef struct VlivaHostApi {
    void (*log)(const char* message);
    int (*get_tracking_frame)(VlivaTrackingFrame* out_frame);
    int (*udp_configure)(const char* host, int port, int enabled);
    int (*udp_send)(const char* payload);
} VlivaHostApi;

Section 3

Tracking Snapshot (VlivaTrackingFrame)

Plugins receive a typed frame snapshot that contains face/body/eye/mouth values plus model metadata.

  • struct_size enables forward compatibility when fields are extended.
  • has_valid_parameters helps plugins skip incomplete frames safely.
  • model_name and tracking_mode expose host context for protocol mapping.

c

typedef struct VlivaTrackingFrame {
    uint32_t struct_size;
    uint32_t frame_version;
    double time_seconds;
    int32_t has_face;
    int32_t has_valid_parameters;
    float angle_x;
    float angle_y;
    float angle_z;
    float body_angle_x;
    float body_angle_y;
    float body_angle_z;
    float eye_x;
    float eye_y;
    float eye_l_open;
    float eye_r_open;
    float mouth_open_y;
    float mouth_form;
    float jaw_open;
    char model_name[VLIVA_TRACKING_MODEL_NAME_CAPACITY];
    char tracking_mode[VLIVA_TRACKING_MODE_NAME_CAPACITY];
} VlivaTrackingFrame;

Section 4

Plugin Surface (VlivaPluginApi)

Plugin returns a function table that host can call during lifecycle events.

  • name() returns plugin display name.
  • on_load() runs once when plugin is initialized.
  • on_frame() is called every frame with timing values.
  • on_unload() runs once before plugin is removed.

c

typedef struct VlivaPluginApi {
    uint32_t api_version;
    const char* (*name)(void);
    void (*on_load)(const VlivaHostApi* host);
    void (*on_unload)(void);
    void (*on_frame)(double time_seconds, float delta_seconds);
} VlivaPluginApi;

Section 5

Factory Symbol (create_plugin)

Shared library must export a factory function returning VlivaPluginApi.

  • Host resolves symbol with C ABI naming.
  • Function returns a stable pointer to plugin API table.
  • Returned table should stay valid for plugin lifetime.

c

typedef const VlivaPluginApi* (*VlivaCreatePluginFn)(void);