On this page

GIF and animations

ui::gif plays an animated GIF from isolenui/kit/charts.h. It runs on the kit's animation runtime, the anim_* calls, which opens a file, keeps its frames on the GPU the way you choose and runs the clock. The decoder is doga, the engine's own, in doga/src/doga.h.

GIF, an animated gif, drawn by isolenGIF, an animated gif, drawn by isolen

Playing a GIF

  1. anim_open(dev, bytes, n, &desc) finds a decoder for the bytes, opens the file and makes its textures. It returns null and logs why when no decoder claims the bytes or the file does not open. A null desc means anim_auto.
  2. gif(u, label, src, play, style) declares the box and returns the frame shown. The label keys its clock.
  3. anim_close(dev, src) frees the textures and the decoder.

The bytes stay yours and must outlive the source. Nothing is copied at open, and a streamed frame or a backend switch decodes from them again. anim_info_of(src) gives the width, height, frames, loops (zero loops forever), duration in seconds and vector, false for a GIF.

loader.cpp
#include "isolenui/app/app.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// the file bytes are yours and must outlive the source, a backend switch or a
// streamed frame decodes from them again
struct loader_gif {
    const uint8_t* bytes;
    size_t size;
    ui::anim_src* src;
    bool paused;
};

static bool loader_open(isolen_app* a, loader_gif* g)
{
    ui::anim_desc d = {};
    d.cache = ui::anim_auto;
    g->src = ui::anim_open(isolen_device(a), g->bytes, g->size, &d);
    return g->src != nullptr;
}

static void loader_show(ui::ctx* u, loader_gif* g)
{
    ui::anim_play p = ui::anim_play_of();
    p.paused = g->paused;
    ui::gif(u, "loading", g->src, p, ui::row().width(96.0f).height(96.0f));
    if (ui::button(u, g->paused ? "play" : "pause")) {
        g->paused = !g->paused;
    }
}

static void loader_close(isolen_app* a, loader_gif* g)
{
    ui::anim_close(isolen_device(a), g->src);
    g->src = nullptr;
}

From a URL

A ui::gif_url fetches a GIF over HTTPS with the engine's network service and opens it once it lands. Hand it to the gif overload that takes a gif_url* and the box shows a spinner while it loads, the GIF once it is ready, and the reason as could not load, WHY if it failed.

CallDoes
gif_url* gif_url_open(gfx_device* dev, const char* url, const anim_desc* d, void (*wake)(void* user), void* user)Starts the fetch with the default net options: HTTPS only, 32 MB, 30 seconds. wake runs on the fetch thread when the bytes land, so pass one that calls isolen_wake. A null desc means anim_auto. It returns null only without memory.
void gif_url_close(gif_url* g)Cancels a fetch still in flight, closes the source and frees it.
gif_load gif_url_poll(gif_url* g)gif_loading, gif_ready or gif_failed. The gif overload polls it for you, and a poll is what opens the source once the bytes are in.
anim_src* gif_url_src(const gif_url* g)The source once ready, null before, for anim_info_of and the other anim_* calls.
const char* gif_url_why(const gif_url* g)Why it failed, such as http 404 or not a gif, the server sent text/html.
size_t gif_url_bytes(const gif_url* g)The size of the file once it is in.
uint32_t gif(ctx* u, const char* label, gif_url* src, const anim_play& p, const style& s)Declares the box and returns the frame shown, 0 while it loads or after it failed.
  • Only GIFs open. The bytes must start with GIF87a or GIF89a. Anything else fails with the type the server sent, so an HTML error page never reaches the decoder.
  • Session cache. The fetched bytes stay in memory for the session, so a URL opened again, by another box or after a close, opens from memory with no fetch. Up to 96 MB is kept, and past that the least recently used files that no open source still reads are let go.
  • The spinner is sized to a fifth of the box's shorter side, between 16 and 48 units. That is why gif now needs spinner in kit.conf.
badge.cpp
#include "isolenui/app/app.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

struct badge {
    ui::gif_url* web;
};

// runs on the fetch thread once the bytes land
static void badge_wake(void* user)
{
    isolen_wake(static_cast<isolen_app*>(user));
}

static void badge_open(isolen_app* a, badge* b)
{
    ui::anim_desc d = {};
    d.cache = ui::anim_auto;
    b->web = ui::gif_url_open(isolen_device(a), "https://example.com/party.gif", &d, badge_wake, a);
}

// a spinner while it loads, the gif once it is ready, the reason if it failed
static void badge_view(ui::ctx* u, badge* b)
{
    ui::gif(u, "party", b->web, ui::anim_play_of(), ui::row().width(120.0f).height(120.0f));
    if (ui::gif_url_poll(b->web) == ui::gif_ready) {
        const ui::anim_info* i = ui::anim_info_of(ui::gif_url_src(b->web));
        ui::textf(u, ui::caption(u), "%ux%u, %zu bytes", i->width, i->height,
                  ui::gif_url_bytes(b->web));
    }
}

static void badge_close(badge* b)
{
    ui::gif_url_close(b->web);
    b->web = nullptr;
}

Play options

anim_play_of() returns speed 1, the whole file, no seek and fit_contain.

FieldMeaning
speedA multiple of the file's own timing. Zero or less stops the clock.
repeatHow many times the range plays before it holds the last frame. anim_repeat_file, zero and the default, plays as many times as the file asks. anim_repeat_forever loops for good whatever the file says. Any other value is a play count.
restartA new value starts it over from from.
pausedHolds the frame shown.
from, toA range of frames to loop, clamped to the file and swapped if backwards.
seek0 to 1 across the range. Not below zero, it picks the frame by time and the clock stops.
fThe fit in the box: contain, cover or stretch.

Under anim_repeat_file a GIF with no loop block plays once, and a loop count of n plays n more times, as browsers do. Changing repeat while it plays keeps the plays so far, so a finished GIF starts again when the new count is higher or is forever. A frame delay of 10 ms or less plays at 100 ms, which is also what browsers do.

The clock follows the same rules as animimg. It only runs while the box is painted, so a GIF off screen, paused or finished asks for no frames, and each paint asks for the next frame with redraw_after, timed to that frame's delay. A stall counts as a quarter of a second at most.

wave.cpp
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// frames 12 to 23 twice at half speed, then it holds on 23
static uint32_t wave(ui::ctx* u, ui::anim_src* src, uint32_t replay)
{
    ui::anim_play p = ui::anim_play_of();
    p.from = 12u;
    p.to = 23u;
    p.repeat = 2u;
    p.speed = 0.5f;
    p.restart = replay;
    p.f = ui::fit_cover;
    return ui::gif(u, "wave", src, p, ui::row().width(lay_grow(1.0f)).height(160.0f));
}

// a scrubber drives seek, the clock stops while it is set
static void scrub(ui::ctx* u, ui::anim_src* src, float* at)
{
    ui::slider(u, "time", at, 0.0f, 1.0f, "%.2f");
    ui::anim_play p = ui::anim_play_of();
    p.seek = *at;
    ui::gif(u, "scrubbed", src, p, ui::row().width(240.0f).height(180.0f));
}

Cache modes

anim_desc sets the cache, a GPU budget in bytes, zero for 64 MiB, a size that only vector formats use, the decode mode below, and a font for vector text that brings no glyphs, which Lottie describes.

ModeWhat it keeps
anim_streamOne texture and a canvas on the CPU. Each new frame decodes into the canvas and only the rectangle it touched is uploaded.
anim_prerenderEvery frame decoded once at open into its own image, so playing costs no decoding. Identical frames share one image: a hash finds the candidate and a byte compare of the whole picture confirms it, so two frames that only share a hash keep their own images and the open logs it. Past the budget or 64 images it falls back to streaming and logs it. The decode spreads across the CPU worker pool when it is free.
anim_minimalCPU backend only. The decoder keeps a line buffer instead of a frame of indices, and frames decode straight into the canvas the backend draws, with nothing copied. On a GPU backend it logs a warning and streams.
anim_autoMinimal on the CPU backend and prerender everywhere else.

The open logs the mode it chose, the image count and the GPU and CPU bytes. On a backend switch a prerendered or streamed source replays its frames through the new backend, and a minimal source wraps its canvas again on the CPU or streams on a GPU.

Decoding ahead

A streamed source decodes each new frame when it is due, on the UI thread. anim_desc::decode can move that work off it:

ModeWhere the next frame is decoded
anim_decode_autoThe default. Ahead when the canvas is 512 by 512 pixels or more, about where a frame costs a tenth of a millisecond, and on the UI thread below that.
anim_decode_inlineAlways on the UI thread.
anim_decode_aheadA worker decodes the next frame into a second canvas while the current one shows, and the swap uploads only what changed.
  • Stream only. Ahead applies to a streamed canvas. A prerendered source has nothing left to decode, and a minimal one decodes in place, so there it logs that ahead waits for a switch to streaming.
  • One worker. Every source that decodes ahead shares one thread, started by the first and logged as anim decode ahead worker up. It costs one more canvas of CPU memory per source.
  • Quiet first. Before the UI thread touches a decoder for anything else, such as a seek, a backend switch or lending a font, it waits for the worker to finish and drops a frame it drew ahead, so the two never touch a decoder at once.
  • Fallback. With no thread or no memory for the second canvas it logs a warning and decodes on the UI thread.

The open log line adds ahead after the mode when it is on.

banner.cpp
#include "isolenui/app/app.h"
#include "isolenui/ui/ui.h"
#include "isolenui/kit/kit.h"

// a big banner decodes its next frame on the shared worker and loops for
// good, a small sticker plays as many times as the file asks
struct banner_gifs {
    const uint8_t* banner;
    size_t banner_size;
    const uint8_t* sticker;
    size_t sticker_size;
    ui::anim_src* big;
    ui::anim_src* small;
};

static bool banner_open(isolen_app* a, banner_gifs* g)
{
    ui::anim_desc d = {};
    d.cache = ui::anim_stream;
    d.decode = ui::anim_decode_ahead;
    g->big = ui::anim_open(isolen_device(a), g->banner, g->banner_size, &d);

    ui::anim_desc s = {};
    s.cache = ui::anim_prerender;
    g->small = ui::anim_open(isolen_device(a), g->sticker, g->sticker_size, &s);
    return g->big && g->small;
}

static void banner_show(ui::ctx* u, banner_gifs* g)
{
    ui::anim_play p = ui::anim_play_of();
    p.repeat = ui::anim_repeat_forever;
    ui::gif(u, "banner", g->big, p, ui::row().grow().height(160.0f));

    ui::anim_play once = ui::anim_play_of();
    once.repeat = ui::anim_repeat_file;
    ui::gif(u, "sticker", g->small, once, ui::row().width(64.0f).height(64.0f));
}

More formats

A format is an anim_decoder table: probe, open, frame and close, plus optional delay, open_lean for the minimal mode and all, which hands every finished frame to a sink in order, and lend, which a vector format with text uses to take a font. anim_register adds one, up to 8. The GIF decoder registers itself from a static initializer in gif.cpp, and since gif is named in kit.conf it is linked into every app, so anim_open knows GIF bytes before main runs even when the app never calls gif. gif off strips it. Lottie files play through the same runtime. See Lottie.

The doga decoder

doga/src/doga.h can be used on its own, with no device. It holds the caller's bytes until close and allocates nothing after open except in render_all.

  • open(bytes, n, &limits, &info, &why) returns a file or null with a status: not a GIF, truncated, too big, out of memory or bad data. status_text names it.
  • limits_default() allows a canvas of up to 2 to the 26 pixels and 65536 frames. lean keeps a line buffer instead of a frame of indices, at about half the speed.
  • info gives the size, frames, loops (below zero plays once, zero loops forever, n repeats n more times), the duration in ms, a background hint, whether any pixel can be clear, and truncated when the data ended early but every listed frame still plays.
  • frame_at gives a frame's rectangle, delay, disposal and whether it is a key frame that covers the canvas.
  • render(f, index, rgba, stride, &dirty) draws a frame into a canvas that holds what the last render left. Any index works: it walks on from the frame shown or starts again from the nearest key frame. The pixels are straight and premultiplied at once, since GIF alpha is only 0 or 255.
  • forget makes the next render start on a canvas it clears, and shown is the last frame drawn.
  • render_all hands every frame in order to a sink, with the decompression of a batch spread over the run workers you pass.
gif_length.cpp
#include "doga/doga.h"

#include <stdlib.h>

// every frame of a gif into one canvas, straight rgba, no engine needed
static uint32_t total_ms(const uint8_t* bytes, size_t n)
{
    doga::limits l = doga::limits_default();
    doga::info inf;
    doga::status why;
    doga::file* f = doga::open(bytes, n, &l, &inf, &why);
    if (!f) {
        return 0u;
    }
    const uint32_t stride = inf.width * 4u;
    uint8_t* canvas = static_cast<uint8_t*>(calloc(size_t(stride) * inf.height, 1u));
    uint32_t ms = 0u;
    for (uint32_t i = 0; canvas && i < inf.frames; ++i) {
        doga::rect dirty;
        if (doga::render(f, i, canvas, stride, &dirty)) {
            ms += doga::frame_at(f, i)->delay_ms;
        }
    }
    free(canvas);
    doga::close(f);
    return ms;
}

kit.conf

gif named needs animimg spinner libs doga. The libs key links the doga library from its own repository, and named links gif.cpp into every app so the decoder registers at startup. See the component kit.

The gallery has a GIF page with every play option, cache mode, decode mode and repeat mode as props. Its source prop picks a GIF from a URL, the default, with a URL field and a reload button, or a local one generated in code, so the repository carries no binary for it. --gif-url URL starts it on another URL, and a capture always uses the local one so it never touches the network.

Last updated 6 October 2026