On this page

Vector engine (elba)

elba is the engine's own 2D vector renderer: paths, fills, strokes, gradients, images, groups, clips and masks, rasterised on the CPU. It stands on its own. elba/elba.h takes no gfx, ui or kit type, and only elba/elba_gfx.h joins it to a gfx device. The Lottie player draws through it, including text it traces from the app font into plain paths when a file ships no glyphs.

Linking

elba is its own static library, elba (also elba::elba), from its own repository. An app that never calls it links none of it. Link it yourself with target_link_libraries(app PRIVATE elba), or let a kit component pull it in with a libs elba line in kit.conf, as lottie does. See the component kit.

The pieces

ObjectWhat it holds
elba_pathMoves, lines, quads, cubics and closes, plus arcs, rects, round rects and ellipses.
elba_sceneA recorded list of fills, strokes, images, nested scenes and pushed groups, clips and masks. It needs no context, so any thread can record its own.
elba_contextThe renderer: worker lanes, scratch memory and the caches. One context renders one scene at a time.
elba_imagePixels a paint or elba_draw_image samples from.
badge.cpp
#include "elba/elba.h"

#include <stdint.h>
#include <stdlib.h>

// record a scene once, then render it into memory the caller owns
static bool badge_png_pixels(uint32_t w, uint32_t h, uint32_t* out)
{
    elba_path* round = elba_path_create();
    elba_add_round_rect(round, 8.0f, 8.0f, float(w) - 16.0f, float(h) - 16.0f, 18.0f, 18.0f);

    elba_path* tick = elba_path_create();
    elba_move_to(tick, 40.0f, 64.0f);
    elba_line_to(tick, 60.0f, 84.0f);
    elba_line_to(tick, 96.0f, 44.0f);

    const elba_stop stops[2] = { { 0.0f, elba_rgba8(0xffe5648au) }, { 1.0f, elba_rgba8(0xffcc986du) } };
    const elba_paint fill = elba_linear(0.0f, 0.0f, float(w), float(h), stops, 2u, elba_spread_pad);
    const elba_paint white = elba_solid(elba_rgba8(0xffffffffu));

    elba_stroke_style line = elba_stroke_default();
    line.width = 10.0f;
    line.cap = elba_cap_round;
    line.join = elba_join_round;

    elba_scene* scene = elba_scene_create();
    elba_fill(scene, round, nullptr, elba_fill_nonzero, &fill);
    elba_stroke(scene, tick, nullptr, &line, &white);

    elba_context* ctx = elba_context_create(nullptr);
    const elba_target target = { out, w, h, w * 4u, elba_format_rgba8_premul };
    const elba_status st = elba_render_cpu(ctx, scene, &target, nullptr);

    elba_context_destroy(ctx);
    elba_scene_destroy(scene);
    elba_path_destroy(tick);
    elba_path_destroy(round);
    return st == elba_ok;
}
  • A null matrix is identity everywhere. Matrices follow SVG order, a b c d e f, and elba_mul(l, r) applies r first.
  • Colours are elba_color floats with straight alpha. elba_rgba8 reads the same 0xAABBGGRR packing as gfx colours.
  • Paths are referenced, not copied, by the scene. Keep them alive and unchanged until the render that uses them is done. The same holds for images and for a scene drawn into another with elba_draw_scene. Gradient stops and dash arrays are copied.
  • Calls report problems through elba_status: elba_invalid, elba_no_memory, elba_unsupported and elba_not_implemented. elba_status_text names each.

Fills and strokes

  • elba_fill takes a fill rule: nonzero, evenodd, or their _inverse forms, which cover everything the path does not, inside the render area.
  • elba_stroke takes an elba_stroke_style: width, butt, round or square caps, miter, round, bevel or miter clip joins, a miter limit, dashes with an offset, and two flags. elba_stroke_hairline is one device pixel wide whatever the width and matrix say, and elba_stroke_non_scaling keeps the width in device pixels while the matrix only moves the centre line. elba_stroke_default is width 1, butt, miter, limit 4.
  • elba_fill_rect and elba_draw_image skip building a path. An image is drawn as the rect from 0, 0 to its size through the matrix.
  • elba_path_bounds, elba_path_contains and elba_path_length measure a path through a matrix.

Paints

elba_solid, elba_linear, elba_radial, elba_sweep and elba_pattern fill an elba_paint. Its geometry is in paint space, and paint.transform maps it into path space before the draw matrix takes it to the device.

  • Radial paints take a focal circle, fx, fy and fr, which covers SVG 2 and the Lottie highlight.
  • Spreads are pad, repeat and reflect, and elba_spread_none for images, which is transparent outside. Images take a separate spread_y.
  • elba_paint_premul_stops interpolates stops premultiplied, and elba_paint_dither dithers the gradient.
  • Image filters are nearest and bilinear. elba_filter_bicubic is accepted but samples as bilinear today.

Images and mipmaps

  • elba_image_create copies the pixels, unless elba_image_borrow is set. A borrowed image keeps pointing at your memory, which must outlive every render that uses it.
  • Formats are RGBA8 and BGRA8, straight or premultiplied, A8, and premultiplied RGBA32F.
  • When an image is drawn at less than half its size with a filter other than nearest, elba builds mipmaps for it once and samples the level that fits. A tiled pattern only uses levels its size divides into evenly.
  • Change pixels through elba_image_write, so the mipmaps are rebuilt from the new pixels.

Groups, clips and masks

card.cpp
#include "elba/elba.h"

// groups, clips and masks are pushed and popped around what they apply to
static void card(elba_scene* s, const elba_path* shape, const elba_path* hole, const elba_path* glow)
{
    elba_group g = elba_group_default();
    g.opacity = 0.9f;
    g.blend = elba_blend_screen;
    g.clip = shape;
    elba_push_group(s, &g);

    const elba_paint violet = elba_solid(elba_rgba8(0xffe5648au));
    elba_fill(s, shape, nullptr, elba_fill_nonzero, &violet);

    // everything outside the hole, inside the render area
    const elba_paint shade = elba_solid(elba_rgba8(0x66000000u));
    elba_fill(s, hole, nullptr, elba_fill_nonzero_inverse, &shade);

    // a luma mask: draw the mask, then the content it masks, then pop
    elba_push_mask(s, elba_mask_luma);
    const elba_paint white = elba_solid(elba_rgba8(0xffffffffu));
    elba_fill(s, glow, nullptr, elba_fill_nonzero, &white);
    elba_mask_content(s);
    const elba_paint gold = elba_solid(elba_rgba8(0xff5aa4e5u));
    elba_fill(s, shape, nullptr, elba_fill_nonzero, &gold);
    elba_pop(s);

    elba_pop(s);
}
  • elba_push_group takes an elba_group: opacity, one of 28 blend modes, an optional clip path with its own matrix and rule, and elba_group_luma_to_alpha, which turns the result into alpha from its luma before it composites. The blends are the 16 separable and non separable modes, an After Effects style clamped add, and the Porter Duff operators.
  • elba_push_clip clips everything drawn until the matching elba_pop.
  • A mask is elba_push_mask, the mask drawing, elba_mask_content, the masked drawing, then elba_pop. Modes are alpha and luma, each with an inverted form.
  • elba_mask_path, between elba_push_mask and elba_mask_content, combines one path into the mask with add, subtract, intersect, difference, lighten or darken and an opacity. It takes the inverse fill rules too. Its feather is recorded but not applied yet.
  • Layers nest up to 15 deep and scenes drawn into scenes 16 deep. Deeper ones are dropped with a warning logged once.

Path booleans

elba_path_boolean(out, a, b, op) writes union, intersect, subtract or xor of two paths into out. The result keeps exact sub curves of both inputs rather than flattening them, so it scales like any other path. The Lottie player builds merge paths on it.

ring.cpp
#include "elba/elba.h"

// a ring with a notch, built once with booleans and kept as a plain path
static elba_path* notched_ring(float cx, float cy, float r)
{
    elba_path* outer = elba_path_create();
    elba_path* inner = elba_path_create();
    elba_path* notch = elba_path_create();
    elba_add_ellipse(outer, cx, cy, r, r);
    elba_add_ellipse(inner, cx, cy, r * 0.6f, r * 0.6f);
    elba_add_rect(notch, cx - r * 0.1f, cy - r, r * 0.2f, r);

    elba_path* ring = elba_path_create();
    elba_path* out = elba_path_create();
    if (elba_path_boolean(ring, outer, inner, elba_bool_subtract) != elba_ok
        || elba_path_boolean(out, ring, notch, elba_bool_subtract) != elba_ok) {
        elba_path_reset(out);
    }

    elba_path_destroy(ring);
    elba_path_destroy(notch);
    elba_path_destroy(inner);
    elba_path_destroy(outer);
    return out;
}

Rendering

elba_render_cpu(ctx, scene, target, render) draws a scene into an elba_target: your pixels, their size, stride and format. A null render means elba_render_default().

FieldDefaultMeaning
qualityexactelba_quality_fast flattens curves more coarsely and uses a smaller gradient table.
spacesRGBBlending happens on the encoded values, like SVG, Lottie and browsers.
flagsclearelba_render_clear fills the area with clear first.
viewidentityA matrix applied after every draw matrix.
areawhole targetx, y, width and height of the only pixels touched. A zero width means the whole target.
  • The raster works in bands of 32 rows. A render with an area gives exactly the same pixels as the matching part of a whole render, because geometry is always cut to the target and only the output is cut to the area.
  • The inner loops use NEON, AVX2 or SSE2, chosen at compile time, with a scalar fallback. Define ELBA_FORCE_SCALAR to build the scalar kernels anywhere. Under strict IEEE math every kernel gives bitwise equal output.
  • elba_stats_get reports frames, the last frame time, draws, edges, bands and the cache bytes, hits and misses.

Contexts, threads and caches

  • elba_desc sets a policy, a job runner and its worker count, up to 32, and a cache budget, 64 MiB by default. A null runner runs every job on the calling thread.
  • elba_policy_retained and elba_policy_auto keep the flattening of a path that has not changed from its second render on. Any matrix within a factor of the square root of 2 in scale reuses it, and any edit to the path starts over. elba_policy_immediate and elba_policy_minimal keep no cache.
  • elba_context_trim frees worker scratch memory and the flatten cache, and elba_context_destroy frees the rest and calls the runner's release.

On a gfx device

elba/elba_gfx.h is the only part of elba that knows gfx, and like every gfx call it runs on the render thread.

  • elba_gfx_desc() is a desc whose runner is the gfx CPU worker pool, so elba shares the lanes the CPU backend uses.
  • elba_gfx_surface_create(ctx, dev, w, h) makes a streamed, no mip gfx image with pixels of its own. elba_gfx_surface_image returns the handle to draw with ui::image or gfx_image_draw, and elba_gfx_surface_resize remakes it at a new size.
  • elba_gfx_render(surface, scene, render) clears and redraws only the union of the last and the current scene bounds, then uploads just that rect with gfx_image_update_rect. A scene with an inverse fill, or a group whose blend reaches past its content (clear, src, src in, dst in, src out, dst atop), redraws the whole surface. A change of clear colour does too.
dial.cpp
#include "isolenui/app/app.h"
#include "elba/elba_gfx.h"
#include "isolenui/ui/ui.h"

// a retained context on the gfx cpu pool renders into a streamed image,
// and only the rows the scene touched go up each frame
struct dial {
    elba_context* ctx;
    elba_gfx_surface* surface;
    elba_scene* scene;
    elba_path* arc;
};

static bool dial_open(dial* d, gfx_device* dev)
{
    elba_desc desc = elba_gfx_desc();
    desc.policy = elba_policy_retained;
    d->ctx = elba_context_create(&desc);
    d->surface = d->ctx ? elba_gfx_surface_create(d->ctx, dev, 256u, 256u) : nullptr;
    d->scene = elba_scene_create();
    d->arc = elba_path_create();
    return d->surface && d->scene && d->arc;
}

static void dial_frame(ui::ctx* u, dial* d, float value)
{
    elba_path_reset(d->arc);
    elba_arc(d->arc, 128.0f, 128.0f, 100.0f, 100.0f, 0.0f, -2.4f, 4.8f * value);

    elba_stroke_style s = elba_stroke_default();
    s.width = 18.0f;
    s.cap = elba_cap_round;
    const elba_paint ink = elba_solid(elba_rgba8(0xffe5648au));

    elba_scene_reset(d->scene);
    elba_stroke(d->scene, d->arc, nullptr, &s, &ink);
    if (elba_gfx_render(d->surface, d->scene, nullptr) == elba_ok) {
        ui::image(u, elba_gfx_surface_image(d->surface), ui::row().width(128.0f).height(128.0f));
    }
}

static void dial_close(dial* d)
{
    elba_path_destroy(d->arc);
    elba_scene_destroy(d->scene);
    elba_gfx_surface_destroy(d->surface);
    elba_context_destroy(d->ctx);
}

Speed

In the engine's own benchmark, with a harness set up to be fair to both sides, single threaded elba ran 1.0 to 2.3 times slower than Blend2D across the test scenes.

Limits today

These parts of the api are declared but not built. They log once and return elba_not_implemented or fall back.
  • elba_path_trim, elba_path_stroke and elba_path_offset return elba_not_implemented, and elba_stroke_contains returns false.
  • elba_space_linear renders in sRGB, and elba_precision_float renders fixed point.
  • There is no GPU renderer. elba_backend_gpu and gpu_threshold are accepted, and every render runs on the CPU.
  • Mask feather is recorded but not drawn.
  • Degenerate curves and cusp loops can cover slightly more than they should near the cusp.

Last updated 6 October 2026