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.


In the galleryGIFgif
Playing a GIF
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 meansanim_auto.gif(u, label, src, play, style)declares the box and returns the frame shown. The label keys its clock.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.
#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.
| Call | Does |
|---|---|
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
GIF87aorGIF89a. 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
gifnow needsspinnerinkit.conf.
#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.
| Field | Meaning |
|---|---|
speed | A multiple of the file's own timing. Zero or less stops the clock. |
repeat | How 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. |
restart | A new value starts it over from from. |
paused | Holds the frame shown. |
from, to | A range of frames to loop, clamped to the file and swapped if backwards. |
seek | 0 to 1 across the range. Not below zero, it picks the frame by time and the clock stops. |
f | The 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.
#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.
| Mode | What it keeps |
|---|---|
anim_stream | One texture and a canvas on the CPU. Each new frame decodes into the canvas and only the rectangle it touched is uploaded. |
anim_prerender | Every 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_minimal | CPU 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_auto | Minimal 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:
| Mode | Where the next frame is decoded |
|---|---|
anim_decode_auto | The 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_inline | Always on the UI thread. |
anim_decode_ahead | A 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.
#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 afileor null with astatus: not a GIF, truncated, too big, out of memory or bad data.status_textnames it.limits_default()allows a canvas of up to 2 to the 26 pixels and 65536 frames.leankeeps a line buffer instead of a frame of indices, at about half the speed.infogives 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, andtruncatedwhen the data ended early but every listed frame still plays.frame_atgives 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.forgetmakes the next render start on a canvas it clears, andshownis the last frame drawn.render_allhands every frame in order to a sink, with the decompression of a batch spread over therunworkers you pass.
#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.
--gif-url URL starts it on another URL, and a capture always uses the local one so it never touches the network.