window

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

filewhat
renderer.hthe draw api, about thirty calls n the whole drawing vocabulary of the lib
text_measure.hP1.42, the two calls that need no frame, carved out so layout can reach them n nothing else
path.hthe 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_file hardcodes index 0 n that is the ahk libs Cambria Math bug exactly, the .ttc opens n you silently get plain Cambria. so it goes through BLFontData n create_from_data(data, face_index). proven in the runner, CAMBRIA.TTC on 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\Fonts with CreateFontSetBuilder n AddFontFile
  • 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_alpha multiplies, 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.h does not say either way
  • clip() 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 gotchawhat answers it
the fill rule lives on the context, not the pathpath_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 errordrawable(), i.e. can_draw() with an assert in front of it, on every draw
clips only ever narrow, the widening comes from a restorepush_clip is save plus clip, pop() is the restore, n end_frame drains whatever is left
destroy order, context then image then the pixelswritten once in the dtor n in end_frame, both run the same order
premultiplied alpha everywhereBL_FORMAT_PRGB32 in one line, n colour_t::premul is the only conversion into it
the dib is top-downthe 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

framefirstwarmratio
geometry only~110us~48us2x, 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 call
  • push_comp_op, porter-duff plus the blend modes
  • set_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 _at on 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 _at is 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_path was already just make_unique<path_b2d_t>() n read the renderer not at all, it was a virtual only bc the interface declared it as one
  • create_path stays n forwards to make_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 BLPath behind 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_path passes 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

On this page