Render routes

bibui separates recording a frame from drawing it. The runtime turns your build into a DrawList. The list holds fills, borders, shadows, paths, textures and glyphs. A window provides a target, and a renderer draws the list onto it. There are three renderers and two windows. You choose the combination in code. Nothing is discovered at run time.

Steps 1 to 3 are identical on every route. That is why a frame is a pure function of tree, theme, surface size and scale factor. Changing route changes only steps 4 and 5.

#The renderers

Every renderer has the same calls: Draw, CreateTexture, UpdateTexture and ReleaseTexture. Build code never sees the renderer. An app names its renderer in one place:

global using Renderer = Bibui.Raster.Skia.SkiaGlRenderer;   // or Bibui.Raster.Managed.Backend.ManagedRenderer

#Window × renderer

Which renderer can draw into which window, and how the pixels get to the screen.

#The two complete routes

#Choosing a route

The easy way is a Bibui.App package. It names the window and the renderer for you. Swap the package to swap the route, with no change to your code. To choose in code, open the window. Then construct the renderer, bound to one of the window's targets:

using var window = SilkWindow.Open(runtime, new("My app", 960, 640));
using var skia = new SkiaGlRenderer(window.Gl);
// in the loop, between BeginDraw and EndDraw:
skia.Draw(runtime.DrawList);

using var window = SilkWindow.Open(runtime, new("My app", 960, 640));
using var shown = new GlCpuFramebuffer(window.Gl);     // memory shown on the GL framebuffer
using var skia = new SkiaCpuRenderer(shown.Cpu);       // or new ManagedRenderer(shown.Cpu)
// in the loop, between SilkWindow.BeginDraw and SilkWindow.EndDraw:
shown.BeginDraw();
skia.Draw(runtime.DrawList);
shown.EndDraw();                                       // upload, then blit onto the framebuffer

using var window = WaylandWindow.Open(runtime, new("My app", 960, 640),
    new WaylandHostOptions { AppId = "dev.example.app" });
using var managed = new ManagedRenderer(window.Cpu) { DamageTracking = true };
// in the loop, between BeginDraw and EndDraw:
managed.Draw(runtime.DrawList);

#Falling back from the GPU

Nothing falls back on its own. SkiaGlRenderer.ForGl returns null where Skia cannot drive the window's GL context. The app then decides what to do instead. Usually that means the CPU through GlCpuFramebuffer, as in the second tab above. Textures belong to the renderer that made them. If the app swaps renderer while it runs, the textures are made again.

#Text

bibui holds, measures and draws text as UTF-16. Skia shapes and draws text on the Skia routes. On the managed route, FreeType rasterises the glyphs and HarfBuzz shapes them. Text from FreeType and HarfBuzz measures exactly as Skia's does. Its pixels match Skia's too, at SSIM 1.0. So a layout does not move when you change route.

#Damage tracking

The managed rasterizer can repaint only what changed. Turn it on with new ManagedRenderer { DamageTracking = true } or BIBUI_DAMAGE=1. It then compares each DrawList with the previous one, draw by draw. It rasterises only the rectangles that differ. It draws them onto a surface that still holds an earlier frame.

• The result is byte-identical to a full repaint.
• If the changes cover more than half the surface, the whole frame is drawn.
• Nothing above the rasterizer changes. Every frame is still built, laid out and recorded in full.
• A typical frame changes only a hover colour or a caret. That is how a CPU-only stack holds 60 Hz.
• BIBUI_DAMAGE_DEBUG=1 tints what each frame repainted, so you can see it.

Skia always draws whole frames.

#Pixel parity

Each component has one reference picture, rendered by Skia. Every route is compared with it by SSIM. The managed rasterizer matches it except in gradients and wide strokes. Within one build of bibui, the same tree, theme, surface size and scale factor give the same image, byte for byte, every time.

#Environment variables

These are diagnostics. They are not part of the API promise (see Versions).

#Custom drawing and textures

A box can paint itself. Set Box.Draw to a callback. Whatever it draws is recorded into the same DrawList as the built-in nodes. So every renderer draws it, and damage tracking sees it. Images and video frames are textures, made on the renderer the app chose. The formats are RGBA8, BGRA8, R8, RG8 and A8. R8 suits a camera's NIR frame, for example. A Stream texture is updated in place each frame. Concepts covers both.