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
| file | what it is |
|---|---|
path.h | the d grammar, tokenise n emit, plus the arcs |
xform.h | the transform grammar, the six svg functions |
doc.h | the FILE, tags n attributes n the tree walk, sub-paths with their transform n their paint |
icon.h | one 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
BLPathper 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
BLPathat 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
atan2does the signed angle, where the ahk hand rolled it out ofACosplus 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_charsin general mode would otherwise takeinfnnanoff 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
dstring 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 ad="..."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_tcarries 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 ISrx="5" ry="5" - the endpoint snap checked with a tolerance. the conversion lands within a rounding whisker on its
own, so
roughlypasses with the snap deleted. bit equality is the only compare that can tell put there on purpose from close enough rywas never exercised. every arc check was circular, n a circle passes just as well with the code readingrxtwice. 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-anchorgive 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-baselinegive the top. y is the ALPHABETIC baseline by default, the line letters stand on, so the top is one ascent above it, ncentralshifts it half an em down - the box is then exactly the runs size n the align inside it is
starton 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 > 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