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
| Object | What it holds |
|---|---|
elba_path | Moves, lines, quads, cubics and closes, plus arcs, rects, round rects and ellipses. |
elba_scene | A 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_context | The renderer: worker lanes, scratch memory and the caches. One context renders one scene at a time. |
elba_image | Pixels a paint or elba_draw_image samples from. |
#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, andelba_mul(l, r)appliesrfirst. - Colours are
elba_colorfloats with straight alpha.elba_rgba8reads the same0xAABBGGRRpacking 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_unsupportedandelba_not_implemented.elba_status_textnames each.
Fills and strokes
elba_filltakes a fill rule:nonzero,evenodd, or their_inverseforms, which cover everything the path does not, inside the render area.elba_stroketakes anelba_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_hairlineis one device pixel wide whatever the width and matrix say, andelba_stroke_non_scalingkeeps the width in device pixels while the matrix only moves the centre line.elba_stroke_defaultis width 1, butt, miter, limit 4.elba_fill_rectandelba_draw_imageskip building a path. An image is drawn as the rect from 0, 0 to its size through the matrix.elba_path_bounds,elba_path_containsandelba_path_lengthmeasure 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,fyandfr, which covers SVG 2 and the Lottie highlight. - Spreads are pad, repeat and reflect, and
elba_spread_nonefor images, which is transparent outside. Images take a separatespread_y. elba_paint_premul_stopsinterpolates stops premultiplied, andelba_paint_ditherdithers the gradient.- Image filters are nearest and bilinear.
elba_filter_bicubicis accepted but samples as bilinear today.
Images and mipmaps
elba_image_createcopies the pixels, unlesselba_image_borrowis 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
#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_grouptakes anelba_group: opacity, one of 28 blend modes, an optional clip path with its own matrix and rule, andelba_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_clipclips everything drawn until the matchingelba_pop.- A mask is
elba_push_mask, the mask drawing,elba_mask_content, the masked drawing, thenelba_pop. Modes are alpha and luma, each with an inverted form. elba_mask_path, betweenelba_push_maskandelba_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. Itsfeatheris 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.
#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().
| Field | Default | Meaning |
|---|---|---|
quality | exact | elba_quality_fast flattens curves more coarsely and uses a smaller gradient table. |
space | sRGB | Blending happens on the encoded values, like SVG, Lottie and browsers. |
flags | clear | elba_render_clear fills the area with clear first. |
view | identity | A matrix applied after every draw matrix. |
area | whole target | x, 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
areagives 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_SCALARto build the scalar kernels anywhere. Under strict IEEE math every kernel gives bitwise equal output. elba_stats_getreports frames, the last frame time, draws, edges, bands and the cache bytes, hits and misses.
Contexts, threads and caches
elba_descsets 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_retainedandelba_policy_autokeep 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_immediateandelba_policy_minimalkeep no cache.elba_context_trimfrees worker scratch memory and the flatten cache, andelba_context_destroyfrees the rest and calls the runner'srelease.
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_imagereturns the handle to draw withui::imageorgfx_image_draw, andelba_gfx_surface_resizeremakes 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 withgfx_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.
#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
elba_not_implemented or fall back.elba_path_trim,elba_path_strokeandelba_path_offsetreturnelba_not_implemented, andelba_stroke_containsreturns false.elba_space_linearrenders in sRGB, andelba_precision_floatrenders fixed point.- There is no GPU renderer.
elba_backend_gpuandgpu_thresholdare 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.