Handle events

The runtime reports what the player is doing — loaded, started playing, completed a loop — through a queue you drain, rather than through callbacks you register.

Why polling instead of callbacks

Callbacks across an FFI boundary mean handing a function pointer to the library and having it invoked from whatever thread and stack the library happens to be on. That constrains what you can safely do inside the handler and complicates lifetime management on both sides.

Queued events avoid all of it. Events accumulate as playback progresses, and you consume them at a point you choose, on your own thread, where your application state is already accessible.

Draining the queue

dotlottie_poll_event() writes one event into a struct you provide and tells you whether it wrote anything:

Drain it fully with a while loop, since more than one event can be queued per tick:

dotlottieDotLottiePlayerEvent event;

while (dotlottie_poll_event(player, &event) == 1) {
  switch (event.event_type) {
    case Load:
      printf("animation loaded\n");
      break;
    case LoadError:
      fprintf(stderr, "animation failed to load\n");
      break;
    case Loop:
      printf("completed loop %u\n", event.data.loop_count);
      break;
    case Complete:
      printf("playback finished\n");
      break;
    default:
      break;
  }
}

Poll once per iteration of your render loop, after dotlottie_tick(). Events that are never polled stay queued and accumulate, so drain the queue even if you only care about a couple of event types.

Event types

Reading the payload

Two event types carry data, in a union whose active member is determined by the event type:

switch (event.event_type) {
  case Frame:
  case Render:
    printf("frame %.2f\n", event.data.frame_no);   /* float */
    break;
  case Loop:
    printf("loop %u\n", event.data.loop_count);    /* uint32_t */
    break;
  default:
    break;                                         /* no payload */
}

Reading frame_no on a Loop event, or loop_count on a Frame event, reinterprets unrelated bytes and yields nonsense. Always branch on event_type first.

Frame and Render fire every time the animation advances or draws — many times per second. Logging from those handlers will flood your output.

Where events fit in the loop

double last = now_seconds();

for (;;) {
  double current = now_seconds();
  float dt = (float)(current - last);
  last = current;

  bool rendered = false;
  dotlottie_tick(player, dt, &rendered);

  dotlottieDotLottiePlayerEvent event;
  while (dotlottie_poll_event(player, &event) == 1) {
    handle_event(&event);
  }

  if (rendered) {
    present(buffer, width, height);
  }
}

For the common cases you don't need events at all — dotlottie_is_complete(), dotlottie_status(), and dotlottie_get_current_loop_count() answer the same questions by direct query. Events are most useful when you want to act at the exact moment something changes, such as starting a sound on Loop or advancing UI state on Complete.

State machine events

State machines have their own separate queues, polled with dotlottie_state_machine_poll_event() and dotlottie_state_machine_poll_internal_event(). Their events report transitions and input changes rather than playback progress, and unlike player events they contain string pointers with a limited lifetime. See State machines for details.

Learn more

• Control playback — the tick loop events hang off

• Memory and safety rules — event string lifetimes

• C API reference — full signatures