window

svg

the path importer and the icon path cache

mirrored from window/cpp/window.core/svg/README.md, which is the only copy of this text. edits made here are overwritten the next time the site builds

the hand written svg subset importer, the <path> grammar n arcs n all, plus groups n transforms, plus the icon path cache, one path built per draw size at the origin n replayed through a transform

links into window.core, it produces geometry n issues no draw call, so it sits under the seam with the rest of the core

four files, n only the last one knows blend2d exists

filewhat it is
path.hthe d grammar, tokenise n emit, plus the arcs
xform.hthe transform grammar, the six svg functions
doc.hthe FILE, tags n attributes n the tree walk, sub-paths with their transform n their paint
icon.hone svg read as ONE ICON, n the BLPath cache per draw size

why the file walk came out of the icon

doc.h used to be the top half of icon.h. it came out bc an icon n a diagram want different things off the same parse, n the split is not at the parse, it is at the BUILD

  • an icon is one shape with one fill n one stroke, so it caches as ONE BLPath per draw size, n the caller picks the colour. that cache is right for an icon n it is the point of the type
  • a diagram is many shapes each painted differently, which cannot be one BLPath at all, so the cache is not something to extend, it is the wrong shape

so they share every line of the walk n diverge at the moment something gets built. doc_t hands back sub-paths carrying geometry, a matrix n a paint_t, n icon_t throws all the paint away bar the roots, bc a file painting its children differently is not an icon n reading it as one is the bug

it was split at the point icon_t had no callers outside the checks, which is the whole reason it was cheap. once P1.27 ports the controls n they start holding icons it would not have been

the importer, P1.26

ported from ../../../gui/svg.ahk, which is the specification n not the source

a d string is walked TWICE. once to tokenise, which is where the arc flag rule lives, n once to emit, which is where relative coords n reflected controls n arcs get worked out. the split is the whole reason a cache is possible at all, one parse feeds every draw size an icon is ever asked for

M L H V C S Q T A Z, absolute n relative both. everything reaches a sink as a move, a line or a CUBIC, so a sink implements four calls n a quadratic n an arc are promoted on the way through

the tokeniser is command aware, n it has to be

an arcs large-arc n sweep flags are single digits n the grammar lets them run into whatever follows with no separator, so a2 2 0 014 0 is laf 0, sf 1, x 4. a plain number walk reads that as ONE number, comes up short on operands n then eats the next command letter as a coordinate

46 of the 1764 lucide icons pack their flags n every one of them threw before the ahk lib grew this rule. it is not a theoretical case n it is checked on both spellings, bc an arity table that listed only the uppercase half parked the operand counter at 0 n the rule never fired on a lowercase a

the sink is the seam

path_sink_t is four virtuals n no state, so a recording sink in a check n a BLPath sink in the lib cost the same to write. that is what lets the whole parse be checked with no renderer n no window anywhere near it, n it keeps blend2d out of path.h entirely

the arc, n why it is the general case

svg says where an arc ENDS plus the two radii n two flags, but drawing one needs the centre n the start n swept angles, so this is the endpoint to centre conversion out of the spec, appendix f.6.5

the sweep is cut into slices of a quarter turn or less n each slice approximated by one cubic, bc a single cubic stops being accurate past ninety degrees. the last slice lands on the commands endpoint exactly rather than wherever the maths got to, so rounding cannot leave a sub pixel gap where the next segment picks up

it handles ROTATED n ELLIPTICAL arcs n not just the circular corners a lucide set uses, bc this is the libs arc support n not a patch for one icon set

the three places the parse goes past the ahk source

  • atan2 does the signed angle, where the ahk hand rolled it out of ACos plus a cross product sign bc v2 has no atan2. same answer n one less clamp to get wrong
  • every operand read is bounds checked, so a truncated d string stops where it ran out. the ahk one indexed past the end n threw, which is a CRASH here n not an exception
  • a number is only parsed where a digit could start one, bc from_chars in general mode would otherwise take inf n nan off a malformed file n hand back a path full of them

the icon, n the two kinds of set

telling the two apart is the whole reason stroke exists. a FILL set (claude, chatgpt) traces around where a stroke would be n gets filled, where a STROKE set (lucide) is open paths with fill="none" n a stroke on the root <svg>, so filling one gives a BLOB n not an icon

the flag rides on the icon n a caller branches on it once. stroke_px(draw) scales the pen with the geometry, else a 16px icon comes out wearing a 24px icons stroke

the shape elements go through the same walk. lucide leans on circle n rect n line n friends as much as it does on <path>, so each one becomes tokens n joins the same list, n a curve comes out as beziers so a shape never leans on the arc support next door

the cache, n why the path sits at the origin

one path per draw size n not one per draw, which is the item saying so. an icon only ever draws at a couple of sizes so replaying the tokens per frame was pure waste

the built path sits at the ORIGIN n the caller moves it with a transform, so ONE 16px path serves every button on screen. building per position would be a path per control per frame n the cache would never hit

a reparse drops the cache with it, bc a path built off the old tokens is the old icon n handing one back after a reload is a bug that only shows up on a hot path

it holds a path_ptr_t n not a BLPath, changed for P1.27. a control draws through renderer_t n that takes a path_t, so a blend2d path was a cache nothing in the lib could actually fill, n the file stopped including blend2d over it, i.e. it came out LESS coupled n not more. the price is that path_at n build want a renderer handed to them, bc a renderer is the thing that MAKES a path

the renderer is handed in PER ASK n never held, an icon outlives any one frame n a renderer pointer kept on one would be the first thing to dangle. create_path needs no frame open, so a check still builds one with no window n no surface anywhere near it

the three places the icon goes past the ahk source

  • a shape element builds TOKENS DIRECTLY where the ahk one synthesised a d string n re-parsed it, bc formatting a double to text n reading it back is a lossy round trip for no gain
  • the tag n attribute walk is hand rolled where the ahk had regex, n the word boundary that stops id="..." matching a d="..." is a check on the preceding char rather than a \b
  • the fill rule is STAMPED on the path rather than left to the caller, changed with the cache for P1.27. path_t carries one where a BLPath left it to whatever the context had last, so an even odd icon can no longer inherit non zero off whoever filled before it n come out a solid block

what the mutation pass changed, n it changed a lot

20 mutations, 20 killed, but the first pass came back 9 killed n 6 survived n every one of those survivors was worth having. they are written up here bc four of them are check shapes that look fine n prove nothing, n the same shapes will look fine next time

  • a reflection checked against a SYMMETRIC curve. the S check used a C whose second control sat at the same x the curve ended on, so the reflected x came out equal to the current point by coincidence n dropping the reflection changed nothing. the C is lopsided now
  • the quadratic promotion had no check at all, so weakening the two thirds to a third sailed through
  • a clamp checked with a BOUNDING BOX. clamping a rect radius to the whole side instead of half leaves a 10 wide rect 10 wide, so the box sees nothing. it compares points against the spelling it is supposed to equal now, rx="40" on a 10 wide rect IS rx="5" ry="5"
  • the endpoint snap checked with a tolerance. the conversion lands within a rounding whisker on its own, so roughly passes with the snap deleted. bit equality is the only compare that can tell put there on purpose from close enough
  • ry was never exercised. every arc check was circular, n a circle passes just as well with the code reading rx twice. the ellipse pair is what makes it a check
  • the circle was checked for SIZE n not for roundness. the four extremes are on-curve so they sit at the radius whatever the control distance is, i.e. any kappa at all measures 12 across. the halfway point of a quarter is the nearest place the constant shows
  • an arc was never repeated implicitly, so the arity could be six. n spelling the repeat out with spaces does not catch it either, both arities land on the same tokens, it is only a second arc with PACKED flags that reads where the group started

two of the six were equivalent mutants n one was a bad mutation, so a survivor is a question n not a verdict. the growth one is the case worth remembering, deleting the radii growth left both endpoint checks passing over an arc that bulged 1 deep instead of 5, bc the endpoint snap was covering for it

the one that hung, n what it really was

one mutation timed out at 300 seconds n graded unusable three runs running. the cause was in the CHECK n not in this module. with the attribute boundary broken the circle reads r as 0 n produces no tokens at all, n the roundness check then subscripted an EMPTY vector. operator[] past the end trips _STL_VERIFY in a debug build, which pops a modal dialog with no console to dismiss it, so a run that should have printed FAIL sat there instead

it cost a whole wrong diagnosis, blend2d n a zero stroke width both got blamed on inference alone. a zero width stroke was then measured at 1124us against 1208us for a real one over 200 passes, i.e. it costs nothing n draws nothing, so none of that theory held

two things came out of it n both are worth keeping. the runner flushes every check line, so a killed process still hands back what it printed, n every check reads its points through pt_at n num_at which hand back a NaN past the end rather than tripping the assert. a NaN fails every comparison, so an absent point fails its check n the run carries on, i.e. a value breaks n never the program

stroke_px() still returns 0 for a FILL set, n that is correct, a fill set has no pen. stroking one draws nothing at all, so a caller branches on is_stroke(), n that is the whole of it

groups n transforms, P1.40

P1.40 settled on extending this parser rather than vendoring one, see the plan, n <g> plus transform is the first half of that bc it is most of a diagram n the cheap end of the work

a walk is placed by a MATRIX now, not by an offset n a scale

emit took ox, oy, scale, which cannot say what a rotated or skewed group does to its children, so it takes a transform_t off core/geom.h. the offset n scale form is still there as an overload bc a uniform scale plus an offset IS an affine, n the caller with no groups in it should not have to spell a matrix out to say the simplest thing there is

the type is the projects existing transform_t n not a double one of our own, bc one affine type per project is the whole point of having one. its coefficients being float costs about 1e-7 relative on the last multiply n every coordinate either side stays double, which lands a long way under a pixel

every coordinate leaves native space through map_x n map_y n nothing else, which is the same argument put_cubic already made for itself, one place to get it wrong instead of nine

the conversion all still runs in NATIVE coords n only the finished segments get mapped. the relative offsets n the S n T reflections would survive being placed early, an affine commutes with both, but an arcs two radii n its rotation are native numbers a matrix cannot be applied to without decomposing it first, so one rule covers all of them rather than three rules nobody can keep straight

the order, which is the half worth reading twice

a * b on a transform_t means a first n then b, so it reads left to right in the order things actually happen. three places depend on that n each one is a different way round

  • a transform list applies RIGHTMOST first, so translate(10 0) scale(2) scales n then moves, n the walk folds each function onto the FRONT of what it has, out = made * out
  • an elements own transform runs inside its group, so it is own * inherited, the same shape a nested <g> takes
  • the draw scale goes on the END, sub.xform * scale, bc a sub-paths transform maps it into ROOT coords n the scale is what takes root coords to device ones. flipping those two leaves a groups translate sat in file units while everything inside it doubled

two translates compose to the same answer whichever way round they went, so every order check in the suite has a scale in it, n the group ones have an identity nowhere near the leaf

the walk is DOCUMENT ORDER now, n it has a stack

the old parse read every <path> n then every circle n then every rect, which loses the file order n cannot see nesting at all. it is one forward scan over the tags now, carrying a stack of transforms with one entry per open <g>, so a sub-path comes out already knowing the matrix that places it

the identity underneath the stack is never popped, so an unbalanced </g> off a hand edited file cannot empty it n take the next back() with it. a self closing <g/> pushes nothing, else the next close pops the group above it instead

three things the old tag walk got quietly wrong n this one does not

  • a comment is skipped to its own terminator, bc a commented out <path> is a normal thing in a hand edited file n drawing one is worse than dropping it, nobody looks for ink they switched off
  • an angle bracket inside a quoted value does not end the tag, where a plain find for the next one loses every attribute behind it without a word
  • what sits inside a <defs> or a <clipPath> is not drawn, bc a marker head or a clip shape rendered as loose ink lands in the middle of the picture looking deliberate

the mutation pass, n the one that survived

21 mutations over this half n the whole set of 45 kills clean, but two of them had to be found first, n they failed in the two different ways a mutation set can

the comment one came back a SURVIVOR, which is the same lesson as the four written up further down, a check shape that looks fine n proves nothing

a one element comment reads the same with the comment rule deleted. with <!-- no longer matched the tag falls through to the declaration branch, which runs tag_end, n that stops at the first angle outside a quote, i.e. exactly past the end of the first commented element. so the wrong branch covered for the missing one n the check never noticed. two elements inside the comment is what tells them apart, the declaration branch ends after the first n the second gets drawn as real geometry

worth reading next to the endpoint snap one below, both are the same shape, a second mechanism quietly landing on the right answer for one input

the other three came back NO ANCHOR, n that grade is the more dangerous of the two. lifting the file walk into doc.h renamed one stack into xforms n paints, so three mutants stopped matching any text at all. a survivor shouts n a stale anchor says nothing, it just quietly stops testing what it was written for while the total still reads fine, so a mutant whose line you edit gets fixed in the same pass n rerun by number

it says what it dropped

dropped() carries every element n transform function that was met n not drawn, one entry per distinct name, bc what a caller prints is what was lost n not how often. that is the honest floor the plan asks for while the subset grows, the converter refuses n NAMES the thing rather than handing back a picture quietly missing half the file

de-duped for a reason, a diagram carrying two hundred <text> elements would otherwise hand back two hundred identical lines

text, n why it needs a renderer

a <text> is not geometry, it is a string that nobody can place until a font has been resolved n the run measured, so it comes off the parse in its OWN list n meets a renderer in render.h

svg places text by a BASELINE POINT n draw_text takes a BOX, so the whole job is turning one into the other

  • the x n the text-anchor give the left edge, the run is measured n the anchor says how much of that width sits left of x
  • the y n the dominant-baseline give the top. y is the ALPHABETIC baseline by default, the line letters stand on, so the top is one ascent above it, n central shifts it half an em down
  • the box is then exactly the runs size n the align inside it is start on both axes, i.e. the box does the placing n the renderer is not asked to align anything, else two things decide one position n they disagree the moment a measure is a pixel out

dominant-baseline is in bc a generated diagram centres a node label with it constantly, n without it every label in one sits half an em low, which reads as a layout bug rather than a missing feature

the entities are expanded n the content is trimmed, bc a file writes &gt; n wraps the tag across lines, n both of those ride into the middle of a label otherwise

the one thing worth knowing, a rotated label lands in the right PLACE n draws upright. draw_text has no transform of its own, so the placing matrix moves the box n scales the em but cannot turn the glyphs. that is wrong n it is not reported, bc nothing distinguishes a matrix that rotates from one that does not until something asks

tspan, i.e. the lines of a wrapped label

a <tspan> is one more run, not a piece of the run above it, so a three line label is three entries in the list n render.h never learns that any of them are related

it inherits everything n overrides what it names, which is why the styling read is one function taking a run to write over rather than a fresh one per element. the pen the tspans inherit from is the <text> itself, n it FOLLOWS each line as it is placed, bc a dy is relative to wherever the line above ended up n a second one only lands right if the first was accounted for

an em on a dy is resolved against the font size n a bare number is user units. that is the one unit that matters in here, dy="1.2em" is how every wrapped label spaces its lines, n reading it as 1.2 user units stacks the whole label on one line, which does not look like a spacing bug on screen, it looks like the text is not there

a carry on is REFUSED n reported. an x is absolute so it restarts the line, where a tspan without one continues from the end of the run before it, n placing that needs the width of what it follows, which nothing in here has measured. the first run of a line is the exception, nothing has moved the pen along yet so it starts at the texts own x. the loose characters behind a </tspan> are the same hole from the other side n land in dropped() as text tail

so a generated multi-line label works, bc every generator writes an x on each line, n a hand written <text>hello <tspan>world</tspan></text> comes back one run short n says so

use, n the flag that makes it work

a <defs> entry with an id is kept as a symbol rather than dropped, n a <use href="#id"> clones it. only an UNNAMED defs entry is a real loss, nothing could ever reach it

a symbol holds its own transform n not the stack it sits under, bc a defs is not drawn where it is written, so every transform between it n the root belongs to somebody else

the use paints the clone, n a def that stated its own colour keeps that one. the symbol carries an explicit own_fill flag for this n a look at the paint kind CANNOT answer it, bc an unpainted def already carries the spec default of black n reads exactly like one that asked for black. every <use fill="..."> in a file came out black until that flag existed, n the render is what showed it

what is still deliberately not in here

no gradients, no css stylesheets n no <textPath>. a run that carries on from the one before it is in the same bucket, it needs a measure the parse cannot do, so it is refused rather than guessed at. everything else an svg carries is lost, n dropped() is why that is a report n not a surprise

On this page