dotLottie C API Reference

Every declaration here comes from the generated dotlottie_player.h. Functions are grouped by area, with the build feature noted wherever one is required.

Two naming rules apply throughout. Function names are unprefixed beyond dotlottie_; type names carry a dotlottie prefix, so the Rust DotLottieResult becomes dotlottieDotLottieResult. The header also defines the aliases DotLottiePlayer and DOTLOTTIE_SUCCESS for the two you use most.

Enum constants are emitted without a prefix

Values such as Success, Error, None, Loop, Stop, Play, Frame, Idle, and Surface enter the global namespace unqualified. Watch for collisions with your own macros, and ignore the prefixed spellings that appear in a few of the header's doc comments — identifiers like DotLottiePlayerEventType_Load do not exist.

Types

dotlottieDotLottieResult

The return type of every fallible function. DOTLOTTIE_SUCCESS is defined as 0.

Constant	Value	Meaning
`Success`	0	The call succeeded
`Error`	1	A general failure
`InvalidParameter`	2	Null or out-of-range argument, or an invalid handle
`ManifestNotAvailable`	3	The loaded file has no manifest
`AnimationNotLoaded`	4	The call requires a loaded animation
`InsufficientCondition`	5	The player is not in a valid state for the call
`FeatureNotEnabled`	6	The library was built without the required feature

dotlottieStatus

Constant	Value	Meaning
`Idle`	0	Created, nothing loaded
`Playing`	1	Advancing on each tick
`Paused`	2	Holding the current frame
`Stopped`	3	Reset to the start
`Tweening`	4	Interpolating between two frames

dotlottieMode

Constant	Value	Playback direction
`Forward`	0	Start to end
`Reverse`	1	End to start
`Bounce`	2	Forward then back, repeating
`ReverseBounce`	3	Back then forward, repeating

dotlottieFit

Constant	Value	Behavior
`Contain`	0	Fit entirely inside the target, preserving aspect ratio
`Fill`	1	Stretch to the target, ignoring aspect ratio
`Cover`	2	Fill the target, preserving aspect ratio and cropping
`FitWidth`	3	Match the target width
`FitHeight`	4	Match the target height
`None`	5	Draw at intrinsic size, unscaled

dotlottieLayout

typedef struct dotlottieLayout {
  dotlottieFit fit;
  float align[2];
} dotlottieLayout;

align[0] is horizontal and align[1] vertical, each from 0.0 to 1.0. The default is Contain with {0.5, 0.5}.

dotlottieColorSpace

How eight-bit channels pack into each 32-bit pixel, most significant byte first.

Constant	Value	Layout	Alpha
`ABGR8888`	0	`0xAABBGGRR`	Premultiplied
`ABGR8888S`	1	`0xAABBGGRR`	Not premultiplied
`ARGB8888`	2	`0xAARRGGBB`	Premultiplied
`ARGB8888S`	3	`0xAARRGGBB`	Not premultiplied

dotlottieDotLottieWgpuTargetType

Constant	Value	`target` points to
`Surface`	0	A `WGPUSurface`
`Texture`	1	A `WGPUTexture`

dotlottieDotLottiePlayerEvent

typedef union dotlottieDotLottiePlayerEventData {
  float frame_no;        /* Frame and Render events */
  uint32_t loop_count;   /* Loop events */
} dotlottieDotLottiePlayerEventData;

typedef struct dotlottieDotLottiePlayerEvent {
  dotlottieDotLottiePlayerEventType event_type;
  dotlottieDotLottiePlayerEventData data;
} dotlottieDotLottiePlayerEvent;

Event type	Value	Fires when	Payload
`Load`	0	An animation finished loading	—
`LoadError`	1	An animation failed to load	—
`Play`	2	Playback started	—
`Pause`	3	Playback paused	—
`Stop`	4	Playback stopped and reset	—
`Frame`	5	The current frame advanced	`frame_no`
`Render`	6	A frame was drawn	`frame_no`
`Loop`	7	A loop iteration completed	`loop_count`
`Complete`	8	Playback finished	—

Read only the union member matching event_type.

dotlottieStateMachineEvent

typedef struct dotlottieStateMachineEvent {
  dotlottieStateMachineEventType event_type;
  dotlottieStateMachineEventData data;
} dotlottieStateMachineEvent;

Event type	Value	Payload member
`StateMachineStart`	0	—
`StateMachineStop`	1	—
`StateMachineTransition`	2	`transition`
`StateMachineStateEntered`	3	`state`
`StateMachineStateExit`	4	`state`
`StateMachineCustomEvent`	5	`message`
`StateMachineError`	6	`message`
`StateMachineStringInputChange`	7	`string_input`
`StateMachineNumericInputChange`	8	`numeric_input`
`StateMachineBooleanInputChange`	9	`boolean_input`
`StateMachineInputFired`	10	`input_fired`

The payload members are:

Member	Fields
`transition`	`previous_state`, `new_state` — `const char *`
`state`	`state` — `const char *`
`message`	`message` — `const char *`
`string_input`	`name`, `old_value`, `new_value` — `const char *`
`numeric_input`	`name` — `const char *`; `old_value`, `new_value` — `float`
`boolean_input`	`name` — `const char *`; `old_value`, `new_value` — `bool`
`input_fired`	`name` — `const char *`

dotlottieStateMachineInternalEvent contains a single message field.

Event strings are only valid until the next poll

Every const char * in a state machine event points into memory the library reuses on the following poll call. Copy anything you need to retain.

Opaque handles

Type	Created by	Released by
`dotlottiePlayer`, aliased `DotLottiePlayer`	`dotlottie_new_player()`	`dotlottie_destroy()`
`dotlottieDotLottieStateMachine`	`dotlottie_state_machine_load()`, `..._load_data()`	`dotlottie_state_machine_release()`

DotLottieConfig also appears in the header as a typedef to an undefined struct. It is unused — ignore it.

Interaction bitmask

Returned by dotlottie_state_machine_get_framework_setup() as a uint16_t. The type itself is internal and not emitted into the header, so these values are the reference.

Bit	Value	Interaction
`1 << 0`	1	Pointer up
`1 << 1`	2	Pointer down
`1 << 2`	4	Pointer enter
`1 << 3`	8	Pointer exit
`1 << 4`	16	Pointer move
`1 << 5`	32	Click
`1 << 6`	64	On complete
`1 << 7`	128	On loop complete

Lifecycle

Function	Returns	Description
`dotlottie_new_player(uint32_t threads)`	`DotLottiePlayer *`	Creates a player. `threads` sizes the renderer's worker pool; `0` uses the calling thread. Returns `NULL` on failure
`dotlottie_destroy(DotLottiePlayer *player)`	`dotlottieDotLottieResult`	Destroys the player. Release any state machine first

The thread count is fixed process-wide by the first player created; later values are ignored. Threading also needs the tvg-threads feature.

Fonts

Fonts live in a process-wide registry, so these take no player handle. Requires tvg-ttf or tvg-otf.

Function	Description
`dotlottie_load_font(const char name, const uint8_t data, size_t size)`	Registers a font under `name`. The data is copied
`dotlottie_unload_font(const char *name)`	Removes a registered font

Loading

Function	Feature	Description
`dotlottie_load_animation_path(DotLottiePlayer , const char path)`	—	Loads a `.json` or `.lottie` file from disk
`dotlottie_load_animation_data(DotLottiePlayer , const char json)`	—	Loads Lottie JSON from a null-terminated string
`dotlottie_load_dotlottie_data(DotLottiePlayer , const char data, size_t size)`	`dotlottie`	Loads a `.lottie` file from memory
`dotlottie_load_animation(DotLottiePlayer , const char animation_id)`	`dotlottie`	Switches to another animation inside the loaded `.lottie` file
`dotlottie_get_manifest(DotLottiePlayer , char buffer, size_t *size_out)`	`dotlottie`	Reads the manifest as JSON. Returns `ManifestNotAvailable` if absent
`dotlottie_get_animation_id(DotLottiePlayer , char buffer, size_t *size_out)`	`dotlottie`	Reads the active animation's ID

Functions taking a buffer and size_out pair use the two-call pattern: pass NULL for buffer to learn the required size, then call again with an allocated buffer. The reported size includes the null terminator.

Configuration

Setters

Function	Description
`dotlottie_set_mode(DotLottiePlayer *, dotlottieMode mode)`	Sets the playback direction
`dotlottie_set_speed(DotLottiePlayer *, float speed)`	Sets the speed multiplier. `1.0` is normal
`dotlottie_set_loop(DotLottiePlayer *, bool loop)`	Enables or disables looping
`dotlottie_set_loop_count(DotLottiePlayer *, uint32_t count)`	Sets the loop repetition count. `0` means infinite
`dotlottie_set_autoplay(DotLottiePlayer *, bool autoplay)`	Starts playback automatically on load
`dotlottie_set_use_frame_interpolation(DotLottiePlayer *, bool enabled)`	Enables sub-frame rendering
`dotlottie_set_background(DotLottiePlayer *, uint8_t r, uint8_t g, uint8_t b, uint8_t a)`	Sets the background color, channels `0`–`255`
`dotlottie_set_segment(DotLottiePlayer , const float (segment)[2])`	Restricts playback to `[start, end]`. `NULL` clears it
`dotlottie_set_marker(DotLottiePlayer , const char marker)`	Plays a named marker's range. `NULL` clears it
`dotlottie_set_layout(DotLottiePlayer *, dotlottieLayout layout)`	Sets fit mode and alignment
`dotlottie_set_viewport(DotLottiePlayer *, int32_t x, int32_t y, int32_t w, int32_t h)`	Restricts drawing to a rectangle of the target

Getters

These return dotlottieDotLottieResult and write through an output pointer.

Function	Writes
`dotlottie_get_background(DotLottiePlayer , uint8_t r, uint8_t g, uint8_t b, uint8_t *a)`	The background color
`dotlottie_get_segment(DotLottiePlayer , float (result)[2])`	The active segment
`dotlottie_get_layout(DotLottiePlayer , dotlottieLayout result)`	The current layout
`dotlottie_get_active_marker(DotLottiePlayer , char buffer, size_t *size_out)`	The active marker name
`dotlottie_get_total_frames(DotLottiePlayer , float result)`	The total frame count
`dotlottie_get_duration(DotLottiePlayer , float result)`	The duration in seconds
`dotlottie_get_current_frame(DotLottiePlayer , float result)`	The current frame number
`dotlottie_get_current_loop_count(DotLottiePlayer , uint32_t result)`	Completed loop iterations
`dotlottie_get_animation_size(DotLottiePlayer , float width, float *height)`	The animation's intrinsic size

These return the value directly and substitute a default when the handle is invalid — they cannot report an error.

Function	Returns	Default if invalid
`dotlottie_get_mode(DotLottiePlayer *)`	`dotlottieMode`	`Forward`
`dotlottie_get_speed(DotLottiePlayer *)`	`float`	`1.0`
`dotlottie_get_loop(DotLottiePlayer *)`	`bool`	`false`
`dotlottie_get_loop_count(DotLottiePlayer *)`	`uint32_t`	`0`
`dotlottie_get_autoplay(DotLottiePlayer *)`	`bool`	`false`
`dotlottie_get_use_frame_interpolation(DotLottiePlayer *)`	`bool`	`false`
`dotlottie_status(DotLottiePlayer *)`	`dotlottieStatus`	`Idle`
`dotlottie_is_complete(DotLottiePlayer *)`	`bool`	`false`

Playback

Function	Feature	Description
`dotlottie_play(DotLottiePlayer *)`	—	Starts or resumes playback
`dotlottie_pause(DotLottiePlayer *)`	—	Pauses at the current frame
`dotlottie_stop(DotLottiePlayer *)`	—	Stops and resets to the start
`dotlottie_set_frame(DotLottiePlayer *, float frame)`	—	Jumps to a frame. Fractional values are allowed
`dotlottie_render(DotLottiePlayer *)`	—	Draws the current frame without advancing time
`dotlottie_tick(DotLottiePlayer , float dt, bool rendered)`	—	Advances by `dt` seconds and draws if the frame changed. `rendered` may be `NULL`
`dotlottie_set_audio_volume(DotLottiePlayer *, float volume)`	`audio`	Sets volume from `0.0` to `1.0`
`dotlottie_get_audio_volume(DotLottiePlayer , float result)`	`audio`	Reads the current volume

dt is in seconds, not milliseconds

A 60 fps step is 0.0167. The example in the header's dotlottie_tick doc comment derives dt from a millisecond clock without converting, which advances the animation 1000× too fast.

Render targets

Exactly one target is attached per player.

Function	Feature	Description
`dotlottie_set_sw_target(DotLottiePlayer , uint32_t buffer, uint32_t width, uint32_t height, dotlottieColorSpace cs)`	`tvg-cpu`	Renders into a caller-owned buffer of `width × height` pixels
`dotlottie_set_gl_target(DotLottiePlayer , void display, void surface, void context, int32_t id, uint32_t width, uint32_t height)`	`tvg-gl`	Renders into GL framebuffer `id`. `display` and `surface` may be `NULL`
`dotlottie_set_wg_target(DotLottiePlayer , void device, void instance, void target, uint32_t width, uint32_t height, dotlottieDotLottieWgpuTargetType type)`	`tvg-wg`	Renders into a WebGPU surface or texture

The software buffer belongs to you and must outlive the player.

Theming

All require the theming feature.

Function	Description
`dotlottie_set_theme(DotLottiePlayer , const char theme_id)`	Applies a theme packaged in the loaded file
`dotlottie_set_theme_data(DotLottiePlayer , const char theme_json)`	Applies a theme from JSON you supply
`dotlottie_reset_theme(DotLottiePlayer *)`	Removes the active theme
`dotlottie_get_theme_id(DotLottiePlayer , char buffer, size_t *size_out)`	Reads the active theme's ID

Slots

Function	Description
`dotlottie_get_slot_ids_count(DotLottiePlayer , uint32_t count)`	Counts the slots the animation defines
`dotlottie_get_slot_id(DotLottiePlayer , uint32_t index, char buffer, size_t *size_out)`	Reads a slot ID by index
`dotlottie_get_slot_type(DotLottiePlayer , const char slot_id, char buffer, size_t size_out)`	Reads a slot's type name, such as `color` or `text`
`dotlottie_set_color_slot(DotLottiePlayer , const char slot_id, float r, float g, float b)`	Sets a color slot. Channels are `0.0`–`1.0`
`dotlottie_set_scalar_slot(DotLottiePlayer , const char slot_id, float value)`	Sets a scalar slot
`dotlottie_set_text_slot(DotLottiePlayer , const char slot_id, const char *text)`	Sets a text slot
`dotlottie_set_vector_slot(DotLottiePlayer , const char slot_id, float x, float y)`	Sets a 2D vector slot
`dotlottie_set_position_slot(DotLottiePlayer , const char slot_id, float x, float y)`	Sets a 2D position slot
`dotlottie_set_image_slot_src(DotLottiePlayer , const char slot_id, const char *src)`	Sets an image slot from a `data:` URI, an `http(s)://` URL, or a filename in the package's `i/` folder
`dotlottie_set_slots_str(DotLottiePlayer , const char slots_json)`	Sets many slots from JSON, including gradients and keyframes
`dotlottie_set_slot_str(DotLottiePlayer , const char slot_id, const char *json)`	Sets one slot from JSON
`dotlottie_get_slot_str(DotLottiePlayer , const char slot_id, char buffer, size_t size_out)`	Reads one slot's value as JSON
`dotlottie_get_slots_str(DotLottiePlayer , char buffer, size_t *size_out)`	Reads all slot values as JSON
`dotlottie_reset_slot(DotLottiePlayer , const char slot_id)`	Restores a slot to the animation's original value
`dotlottie_reset_slots(DotLottiePlayer *)`	Restores every slot to its original value
`dotlottie_clear_slot(DotLottiePlayer , const char slot_id)`	Removes the override for a slot
`dotlottie_clear_slots(DotLottiePlayer *)`	Removes all slot overrides

Slot colors are floats from 0.0 to 1.0, unlike dotlottie_set_background(), which takes bytes.

Markers

Function	Description
`dotlottie_get_markers_count(DotLottiePlayer , uint32_t count)`	Counts the markers the animation defines
`dotlottie_get_marker(DotLottiePlayer , uint32_t idx, const char name, float start, float *end)`	Reads a marker by index. `name` is library-owned — do not free. `start` and `end` may be `NULL`

Events

Function	Returns	Description
`dotlottie_poll_event(DotLottiePlayer , dotlottieDotLottiePlayerEvent event)`	`int32_t` — `1` wrote an event, `0` queue empty, `-1` null argument	Removes one event from the queue

Drain the queue with a while loop each frame; unpolled events accumulate.

State machines

All require the state-machines feature. The load functions return NULL without it, so you never hold a valid handle in a build that lacks it.

Lifecycle

Function	Description
`dotlottie_state_machine_load(DotLottiePlayer , const char state_machine_id)`	Loads a machine packaged in the file. Returns a handle or `NULL`
`dotlottie_state_machine_load_data(DotLottiePlayer , const char definition)`	Loads a machine from a JSON definition
`dotlottie_state_machine_start(dotlottieDotLottieStateMachine , const char whitelist, bool require_user_interaction)`	Starts the machine. `whitelist` is a comma-separated list of permitted URL prefixes; `NULL` permits none
`dotlottie_state_machine_stop(dotlottieDotLottieStateMachine *)`	Stops the machine, keeping the handle valid
`dotlottie_state_machine_release(dotlottieDotLottieStateMachine *)`	Destroys the machine. Must be called before `dotlottie_destroy()`
`dotlottie_state_machine_tick(dotlottieDotLottieStateMachine , float dt, bool rendered)`	Advances by `dt` seconds, evaluates transitions, and draws if the frame changed
`dotlottie_get_state_machine(DotLottiePlayer , const char id, char buffer, size_t size_out)`	Reads a machine's JSON definition without loading it

Starting a machine resets playback to frame zero, forward mode, speed 1.0, no looping, and no autoplay.

Input

Function	Description
`dotlottie_state_machine_post_click(sm, float x, float y)`	Posts a click
`dotlottie_state_machine_post_pointer_down(sm, float x, float y)`	Posts a pointer-down
`dotlottie_state_machine_post_pointer_up(sm, float x, float y)`	Posts a pointer-up
`dotlottie_state_machine_post_pointer_move(sm, float x, float y)`	Posts a pointer-move
`dotlottie_state_machine_post_pointer_enter(sm, float x, float y)`	Posts a pointer-enter
`dotlottie_state_machine_post_pointer_exit(sm, float x, float y)`	Posts a pointer-exit
`dotlottie_state_machine_post_event(sm, const dotlottiePlayerEvent *event)`	Posts a pre-built input event
`dotlottie_state_machine_fire_event(sm, const char *event_name)`	Fires a named custom event

Coordinates are in pixels relative to the render target's top-left corner.

Inputs and state

Function	Description
`dotlottie_state_machine_set_numeric_input(sm, const char *key, float value)`	Sets a numeric input
`dotlottie_state_machine_set_string_input(sm, const char key, const char value)`	Sets a string input
`dotlottie_state_machine_set_boolean_input(sm, const char *key, bool value)`	Sets a boolean input
`dotlottie_state_machine_get_numeric_input(sm, const char key, float result)`	Reads a numeric input
`dotlottie_state_machine_get_string_input(sm, const char key, char buffer, size_t *size_out)`	Reads a string input
`dotlottie_state_machine_get_boolean_input(sm, const char key, bool result)`	Reads a boolean input
`dotlottie_state_machine_get_current_state(sm, char buffer, size_t size_out)`	Reads the current state's name
`dotlottie_state_machine_get_status(sm, char buffer, size_t size_out)`	Reads the engine's status
`dotlottie_state_machine_get_framework_setup(sm, uint16_t *result)`	Reads the interaction bitmask
`dotlottie_state_machine_set_seed(sm, uint64_t seed)`	Fixes the random seed for reproducibility

Events

Function	Returns	Description
`dotlottie_state_machine_poll_event(sm, dotlottieStateMachineEvent *event)`	`int32_t` — `1`, `0`, or `-1`	Polls transition and input-change events
`dotlottie_state_machine_poll_internal_event(sm, dotlottieStateMachineInternalEvent *event)`	`int32_t` — `1`, `0`, or `-1`	Polls messages meant for platform integrations

Platform

Function	Description
`dotlottie_init_android(void vm, void ctx)`	Supplies the `JavaVM` and Android context needed for audio output. Call once before loading an animation with audio

Learn more

How the C API works — the design behind these signatures
Memory and safety rules — ownership and lifetimes
Build for your target architecture — enabling the features listed above