render
the renderer seam, the blend2d backend and dwrite font resolution
mirrored from
window/cpp/window.core/render/README.md, which is the only copy of this text. edits made here are overwritten the next time the site builds
renderer_t n the blend2d backend behind it, the path caches that survived the ahk port, n font
resolution through dwrite (family plus weight plus style, out to a file path n a face index)
links into window.core, every draw call goes through the pointer plus stride seam, no gdi or dxgi in here ever
| file | what |
|---|---|
renderer.h | the draw api, about thirty calls n the whole drawing vocabulary of the lib |
text_measure.h | P1.42, the two calls that need no frame, carved out so layout can reach them n nothing else |
path.h | the backend neutral built path, n the fill rule that travels with it |
renderer_b2d.{h,cpp} | P1.5, the blend2d backend |
path_b2d.{h,cpp} | P1.5, BLPath behind path_t, native() is how the renderer reaches it |
font_dwrite.{h,cpp} | P1.8, a family name out to a real file n a face index |
prewarm.{h,cpp} | P1.7, the throwaway frame that pays the jit before the first real one |
stroke_rect is a BACKEND call and not a caller side helper, P1.E.9, and the half pixel inset
is the whole reason. every stroke in renderer_b2d.cpp insets by stroke_off(_w) so an odd width
lands down the middle of one row rather than straddling two, and one written outside the backend
would miss that and sit a hair off with nothing on screen to say why. stroke_off is 0 for an
EVEN width, which is worth knowing before checking anything about a stroke, a comparison run only
at width 2 cannot see the inset at all and passes with it deleted
paint_ctx_t is NOT in here, it lives in scene/control.h, P1.E.1. there used to be a
render/paint_ctx.h holding a second struct of the same name in the same namespace, and the only thing
stopping a hard redefinition error was that no translation unit had ever included both. it is deleted,
and window.test/tests/headers.cpp is the check that stops the next one. its list is GENERATED off
the folder every build, P1.E.16, so a new header lands inside the check on the build it lands on,
there is nothing to remember to add it to
the two things to know before editing any of this
the re-point. begin_frame re-points the BLImage at whatever address the surface carries every
frame, unconditionally, with no did-it-change shortcut. that shortcut is the bug, the dcomp presenter
maps WRITE_DISCARD n genuinely hands back a different pointer most frames
no windows header in renderer_b2d.cpp. not gdi, not dxgi, not windows.h itself. the dwrite
resolver is the one file here that does include it, which is exactly why it is its own file with a header
that carries no HRESULT n no wide string, only a utf8 path n a face index. the draw layer stays the one
file in the lib that does not know it is on windows
P1.42, the measure half, n why it is its own interface
measure_text n metrics are the ONLY calls on renderer_t that work with no frame open. both read the
font cache n neither ever touches the render target or can_draw, so both live on text_measure_t n
renderer_t inherits them. the backend needed no change for it, it already overrode both
layout takes that half n never sees the draws, which is the whole reason for the split. a control
measuring outside a frame reaching for a whole renderer_t leaves fill_rect one autocomplete away, n a
draw on a detached blend2d context is an ERROR n not a no-op. two calls make the mistake not compile,
same bargain as the single pop()
so a window hands its OWN renderer over as the measurer, control_t::set_measurer takes a
const text_measure_t* n the tree walks up to the root to find it. no second font cache is built, see
../scene/control.h
P1.8, the four things the resolver exists to get right
- the face index is carried, bc
BLFontFace::create_from_filehardcodes index 0 n that is the ahk libs Cambria Math bug exactly, the.ttcopens n you silently get plain Cambria. so it goes throughBLFontDatancreate_from_data(data, face_index). proven in the runner,CAMBRIA.TTCon face 1 - a per-user font is found, bc one installed for a single user can be absent from the system font
set entirely, which G-window-2 proved. a second set gets built out of
%LOCALAPPDATA%\Microsoft\Windows\FontswithCreateFontSetBuildernAddFontFile - a missing family degrades, along a stated chain, the ask then Segoe UI then Tahoma, so text always draws n a wrong family reads as wrong rather than as a blank control
- an unreachable weight gets a stroke, see the synthetic weight note below
dwrite hands paths back UPPERCASED. it is documented nowhere n any compare against one has to be case insensitive, this cost an hour chasing a resolver that was working the whole time
the synthetic weight, n why it is permanent
blend2d implements no opentype variations in any version, proven from the vendored source, so a
variable fonts named instances are unreachable n its default instance is what draws. the stand in is a
stroke of the glyph colour, min(size * shortfall / 7200, size / 20), i.e. 1/24 em for a full 300 point
jump n capped so a wild ask is not a blob
it is written as a question about the resolved faces real weight rather than as an always, so a face with
its weight baked into the file gets nothing, n if blend2d ever ships the axis this already reads the right
way round. note the ahk lib skips the stroke for variable faces believing the wght axis works, which
is the one place this port deliberately does not match it
two calls that deviate, on purpose
push_alphamultiplies, it does not replace. blend2ds own global alpha is an absolute set, so nesting has to compose here or fading an already faded subtree comes out wrong. the ahk lib replaced,renderer.hdoes not say either wayclip()is tracked by us, blend2d 0.21 has no clip getter on the context. it reads in the space each clip was pushed in, so a transform pushed under a clip leaves it reporting the outer space
P1.6, the six gotchas n where each one is actually answered
most of them are answered by the SHAPE of the interface rather than by code, which is why they went in with P1.5 n P1.6 is mostly the proof plus one assert
| the gotcha | what answers it |
|---|---|
| the fill rule lives on the context, not the path | path_t carries its own, the backend sets it per draw n puts it straight back to non zero |
| blend2d has no implicit begin, a detached draw is an error | drawable(), i.e. can_draw() with an assert in front of it, on every draw |
| clips only ever narrow, the widening comes from a restore | push_clip is save plus clip, pop() is the restore, n end_frame drains whatever is left |
| destroy order, context then image then the pixels | written once in the dtor n in end_frame, both run the same order |
| premultiplied alpha everywhere | BL_FORMAT_PRGB32 in one line, n colour_t::premul is the only conversion into it |
| the dib is top-down | the presenters problem, negative height in the bitmapinfo, checked by P1.3 n P1.4 |
the assert is debug only n the skip stays in release. a draw outside a frame is a caller bug n
silently doing nothing hides it until someone wonders why a panel is blank, but a widget that draws one
frame early should not take a process down in front of a user. the four state pushes n pop() are
deliberately outside the assert, they are a matched pair n unwinding after a frame that never opened is
tidy rather than wrong
the two 0.12 dll bugs were re-measured on 0.21.2, the table is in
../../DEPS.md, comp op CLEAR is still a src_copy, so clear_rect stays the way to punch a hole, n the
set_alpha one was never a bug, one save stack is simply how blend2d works n the single pop() makes
the interleave unwriteable
P1.7, the jit prewarm, n the one thing it cannot reach
blend2d builds its rasteriser pipelines with a jit the first time each one is asked for, so the first frame a process draws pays to compile every pipeline it touches. measured on this box, the throwaway frame costs about 16ms against a warm frame of about 50us, which is the 25x hitch the ahk lib recorded
prewarm() is idempotent, thread safe n free after the first call, n the lib calls it for you at the two
points where a first frame is about to happen, host_t::create n render_scene, so a caller that never
thinks about it still gets it
measured by the runner, first frame against the best of ten warm ones, at 320x240
| frame | first | warm | ratio |
|---|---|---|---|
| geometry only | ~110us | ~48us | 2x, i.e. the criterion |
| with one line of text | ~358us | ~55us | ~6x |
the difference is the font cache n not the jit. m_fonts is a member of the renderer, so every new
renderer, i.e. every new window, opens n parses the face again from scratch. the throwaway frame warms
dwrite n blend2ds glyph machinery process wide, but its own cache dies with it
the fix is a process wide face cache, family plus weight plus style out to a BLFontFace, with the
BLFont at a size staying per renderer bc that part is cheap. it is a threading decision rather than a
tidy up (spawn_ui_thread means two threads really can resolve at once) so it is not done, n the
runner measures n names the cost rather than folding it into the jit number where it would read as a
badly warmed prewarm
P1.32, the extensions, n who is allowed to use them
gradients n shadows are part of renderer_t n anything may use them. the three extensions are
blend2d only n nothing in the control set may depend on them, which is a rule about the controls
rather than about the renderer
push_alpha, a global alpha multiplier, so a whole subtree fades without recolouring every callpush_comp_op, porter-duff plus the blend modesset_text_edge, a hairline stroke of the glyph colour that keeps small text crisp, off at 0 n off is the default, measured at 41px of ink plain against 75px with it on at 9pt
three things about the gradient that are easy to get wrong
- the brush is built in origin space, so a transform moves brush n path together. a brush built in device space leaves the shape sliding out from under its own colours the moment anything is translated, n the runner pins it by drawing one shape twice, once under a translate n once at the translated coords, n comparing the pixels
- the line is stated in full, two points n not a direction, so a diagonal is the same call as a vertical one
- but
_aton a path draw moves the PATH n not the brush, which is the one place the first rule does not reach n it was measured rather than assumed. a path cached at the origin n placed with_atis left behind by its own ramp n pads flat to whichever stop it landed past, so state the gradient in the space the path is DRAWN in, or place it with a transform push, which does move both
P1.E.12, a path with no renderer
gui::make_path() is a free factory in path.h, declared there n defined in path_b2d.cpp, which is
the seam that lets a control build a path in its CONSTRUCTOR without <blend2d.h> anywhere near it
before it, the only way to get a path was renderer_t::create_path, n the only place a control holds a
renderer is inside paint. so a control keeping a path across frames built one lazily on its first paint
n null checked it forever after, two lines n a member in every painting control that draws more than a
rect, n the null check then spreads to every method that reads the path
- the dependency was never real.
renderer_b2d_t::create_pathwas already justmake_unique<path_b2d_t>()n read the renderer not at all, it was a virtual only bc the interface declared it as one create_pathstays n forwards tomake_path, so there is one construction site n not two that could drift, n a caller already holding a renderer need not know the free one exists- the ask was a factory, NOT a change to what a path is. the interface exists so the backend can keep
a real
BLPathbehind it, which is a good reason n is untouched
P1.E.8, the gradient stroke
stroke_path takes a gradient_t beside the flat colour one, n gradient_t::between states a ramp by
its two ENDS rather than by a box, which is what a stroked wire carrying both its port colours needs.
without it the first real app wrote roughly sixty lines of ribbon, a filled polygon rebuilt per
frame to fake a stroke
- the ramp is linear along the gradients own line n never arc length along the curve, so running it with the path is you naming the paths two ends. for a wire the two are indistinguishable, for a path that doubles back they are not
- a variable width stroke is out of scope, the ribbon bought that too n nothing has asked for it
- the runner proves the ramp n the STROKE apart, bc a gradient
fill_pathpasses a red-end blue-end check identically. so three points along an S bend carry the ramp, n the inside of the bend staying hollow is what says it is the outline n not the fill
the shadow is a stand in, not a blur. blend2d has no effects pipeline, so it is stacked translucent
rings that grow n fade, n spread is a ring count rather than a radius in px. going big looks like
rings bc it is rings