okage is a pure Go port of tiny-skia and of resvg.
- tiny-skia is a small 2D renderer in Rust, and it is a subset of
Skia, the renderer of Chrome. It fills and strokes paths with a
solid color, a gradient or a pattern. It dashes strokes, clips with a mask
and blends images. It renders on the CPU only. okage ports it into the root
package and the package
path. - resvg renders SVG files with tiny-skia. okage ports it into the package
svg. - velato renders Lottie animations. okage ports it into the package
lottie, which draws with okage (D41). - tinyhtml5, tinycss2 and cssselect2
parse HTML, parse CSS and match CSS selectors in Python, for WeasyPrint.
okage ports them into the packages
html,tinycss2andcssselect2(D49, D50).
Today xo/resvg wraps resvg through cgo and a static archive for
each platform. A program that imports okage needs the Go toolchain and nothing
else.
okage uses SIMD where Go can, and its scalar code is the fallback. SIMD (single instruction, multiple data) means one instruction that works on several values at once. A build with TinyGo, most of all for WebAssembly, is a goal that the port keeps in mind.
The port of tiny-skia is done, in the root package and in path. It gives
the same bytes as tiny-skia in the scalar build, in the SIMD build and with
TinyGo, and the 157 integration tests of tiny-skia pass. It is about 1.2 to
3 times slower than the scalar code of tiny-skia, and work that makes it
faster stays open (D35). The package svg is the port of usvg and
resvg. It parses and renders each test file of resvg: without text and
without a raster image, with the same pixels as resvg, and with text or an
image, within the tolerance of D31. The package lottie is the port of
velato. It gives the same calls to its sink as velato for each of the 879
Noto animated emoji, and each sampled frame of them is within the tolerance of
D43 of ThorVG. docs/PLAN.md holds the plan, the phases and the
open questions.
The port starts from resvg v0.49.0 and from the versions of the crates that
it uses, such as tiny-skia v0.12.0. After each base port, okage follows each
upstream commit. On 2026-11-20 okage follows resvg up to its commit 433d0213
of 2026-11-17. docs/upstream/upstreams.tsv lists the upstream
repositories, and one ledger for each records what okage did with each commit.
Install okage with this command:
go get github.com/xo/okageThe renderer imports only the Go standard library. The package svg also
uses typesetting for text, and golang.org/x/image/webp for WebP files.
typesetting is a public copy of go-text/typesetting in
okage (D52). okage does not use cgo, so a program that imports it builds with
CGO_ENABLED=0 for every platform that Go supports.
Go 1.27 has SIMD only as an experiment, so okage has two builds:
- The scalar build is the default.
- The SIMD build uses the package
simd/archsimdof Go on amd64, arm64 and WebAssembly. A program gets it when it builds withGOEXPERIMENT=simd.
GOEXPERIMENT=simd go build ./...Both builds give the same bytes for every image. On an amd64 CPU without AVX2, the SIMD build uses the scalar code. TinyGo always uses the scalar code. When Go makes SIMD a standard feature, the SIMD build becomes the default. docs/SIMD.md holds the details.
| Document | What it holds |
|---|---|
| docs/PLAN.md | the plan, the testing plan, the phases and the open questions |
| docs/UPSTREAM.md | the rules for porting each upstream repository and each change that it makes |
| docs/SIMD.md | the rules for the vector code, the two builds and the SIMD packages of Go |
| docs/BACKLOG.md | the work that is known and not done |
| docs/FORMATS.md | a survey of the work to support other vector formats, such as PDF, EPS and DWG |
| docs/decisions/ | every decision, one file each, with an index |
| CONTRIBUTING.md | how to change okage |
| AGENTS.md | the rules for a coding agent, which also hold for a person |
okage differs from upstream only where a decision says so:
-
The SIMD build computes a reciprocal exactly. The SIMD backends of tiny-skia approximate it in the blend modes color dodge and color burn, and its scalar backend computes it exactly (D16).
-
svgdecodes PNG, JPEG and GIF files with the standard library, and WebP files withgolang.org/x/image/webp, in place of the decoders of resvg (D7). -
svgfinds fonts and shapes text withtypesetting, the copy ofgo-text/typesettingin okage, in place of the crates of resvg. Its text can differ from the text of resvg (D9, D52). -
Each package logs to a
*slog.Loggerthat the caller gives (D20). -
An elliptical arc makes at most 4,096 cubic curves. kurbo has no limit, so an arc with a radius of about 4.23e20 or more does not end in upstream (D30).
-
The gamma stages give one result for every NaN. Upstream reads the bits of a NaN there, and they differ between x86 and ARM (D34).
-
The fallback of text skips a character that no font draws, and goes on with the characters after it. Upstream stops at that character, so the characters after it get no fallback (D39). The fallback also replaces whole clusters, where upstream copies glyphs one by one, so an emoji sequence such as a flag falls back with the text around it (D39).
-
The fallback of text also goes on for an emoji that the font does not draw as an emoji: a character with U+FE0F without a color glyph, such as "©️" in a text font, and an emoji sequence that the font draws as several glyphs. Upstream falls back only for a missing glyph (D40).
-
lottiedraws as ThorVG where velato differs: the opacity, the opacity stops, the radius and the highlight of gradients, solid layers, time remap, easing, spatial positions, the closing of animated shapes, the opacity and the blend mode of layers, masks and stroke dashes (D43).Renderer.MergePathsdraws merge paths by compositing, which velato and ThorVG do not, and it is off by default (D42). -
htmlbuilds a tree with a node for each run of text, where tinyhtml5 builds an ElementTree of Python. It goes on where upstream raises an error, and options bound the depth, the nodes and the issues of a parse (D49). -
tinycss2nests at most 256 blocks andcssselect2at most 32 selectors, where upstream has no limit. Where upstream raises an exception for a selector or a color, the port returns aSelectorErroror no color (D50). -
A fill clamps each side of the bounds of a path to 2^26 pixels from the origin before it rounds them. Upstream panics or leaves out rows for an antialiased fill with a point past about 2^29 pixels, and draws nothing for a fill without antialiasing of a path wider or taller than 2^31 pixels.
DrawPixmapof an image that is aligned to the pixels skips the stages of the pipeline, with the same bytes (D53). -
A hairline on a pixmap of 1 or 2 rows or columns draws its pixels. Upstream draws nothing there (D54).
-
The subsetter of fonts of
internal/subsetterruns at most 1,000,000 operators for one glyph of a CFF font, and makes at most 1,000,000 instructions. Past either limit, it returns an error. Upstream has no such limit, so a small font can make it run for a very long time. It also returnsokage.ErrSubsetTooLargewhen a subset grows larger than 8 times the font data plus 1 MiB (D74). Where subsetter panics on a font, the port returns an error. The package comment ofinternal/subsetterlists the other differences (D62). -
pdfwrites no XMP metadata, where krilla writes it by default, and it has no validators of PDF/A and PDF/UA. It compresses withcompress/zlib, so the bytes of a compressed stream differ from krilla, and its data does not. It returns an error where krilla panics, such as for a box of a page that does not fit the coordinates of PDF, for a pop of a surface without a push, for a gradient with a transform that cannot be inverted, or for the stops of a gradient in two color spaces. It also returns an error for a path to stroke with a point that is NaN or a coordinate above 2^60, where krilla can panic or not end.Document.StartPageandDocument.Finishfinish the page that is open, andPage.Finishfinishes the surface of the page, which Rust does not let a program leave open (D62, D66). It also returns an error for a destination to a page that does not exist, and for a link with no target, where krilla panics. -
The stroker of
pathtreats a quadratic curve as a line where the products offindQuadMaxCurvatureoverflow to NaN. tiny-skia panics there (D66). -
The images of
pdfdecode withimage/png,image/jpeg,image/gifandgolang.org/x/image/webp, where krilla uses the crates png, zune-jpeg, gif and image-webp.pdfreads the headers of the files as those crates do, so it writes the same objects. The decoded samples of an image hold at most 256 MiB, and above that a function that makes an image returns an error. krilla has no such limit.ImageFromImagetakes animage.Imageof Go in place of the traitCustomImageof krilla (D62). -
The text of
pdfreads the fonts withtypesetting, by the rules of skrifa, and shapes a text withtypesetting/harfbuzzin place of harfrust. It shapes a text with no language, as harfrust does, wheretypesettingtakes the language of the locale. It returns an error for a glyph whose range is not a range of its text, where krilla panics. The package comment ofpdflists the other differences of the text (D62, D65). -
NewLinearGradienttakes the stops of a degenerate gradient with the spread mode repeat or reflect in the order ofnewGradient, and clamps the average color to 0..=1. tiny-skia panics there for stops that are not in order. Stops in order give the bytes of tiny-skia (D68). -
pdfsvgdraws the tree ofsvg, which follows a later usvg than krilla-svg. A group without a layer bounding box draws no filter. A group with the blend modePlusLighter, which PDF does not have, is drawn into an image withsvg, with the groups that it blends with.svgdraws the filters into images, where krilla-svg uses resvg.DrawandRenderGlyphreturn false where krilla-svg panics. The package comment ofpdfsvglists the changes (D62). -
pdfwrites a stitching function of more than 256 functions as a tree of stitching functions. Each one holds at most 256 functions, because MuPDF 1.28 reads no more. krilla writes one stitching function. The tree draws the same gradient (D69). -
Path.StrokeandPathStroker.Strokeofpathreturn no path, andfalse, for a path with a point that is NaN or infinite. tiny-skia does not end for some of these paths. A path whose points are finite gives the bytes of tiny-skia (D74).
When upstream changes the code of a difference, okage removes its own code and ports the change of upstream. D40 gives the steps for items 7 and 8, and D42 and D43 give them for item 9.
okage also adds APIs that upstream does not have:
- A
Pixmapgives an*image.RGBAthat shares its bytes, and it implementsimage.Imageanddraw.Image(D19). svg.Newmakes aRenderer, which renders SVG data into an*image.RGBAin one call, asxo/resvgdoes. It loads the fonts of the system on its first call, and sets each generic family to the first of a list of common fonts that is installed. The package registers the formatsvgwithimage.RegisterFormat, soimage.Decodereads SVG data (D36).FontDatabase.LoadOSFontsloads the same fonts into a database of the program (D46).svg.ShapeTextlays out a run of text with the fonts, the fallback and the shaping ofsvg, and gives its advance width and the outlines of its glyphs as a path, so that a program can draw text without SVG data (D37).TextRun.RenderColorGlyphsdraws its color glyphs, such as color emoji (D39).html.Parseparses an HTML-like label of Graphviz,label=<...>in DOT, andLabel.Layoutlays it out asdotdoes: the boxes of the tables and the cells, the rules, the runs of text and the ports (D38).lottie.Parsereads a Lottie file, andlottie.RenderFramedraws a frame of it onto an okage pixmap throughPixmapSink, the sink oflottiethat draws with okage (D41). The sink draws the image assets in PNG, JPEG, GIF and WebP, as velato leaves them to the sink. It decodes an image that the file embeds as adata:URL, and it reads an image file from thefs.FSof the optionlottie.WithFS(D75).lottie.Detectfinds a Lottie document from the start of a file, andlottie.OpenDotLottiereads a dotLottie archive.lottie.Loadparses either one.Composition.Imagedraws a frame into an*image.RGBAof a given size, andFrameCountandDurationcount and time the frames (D44). A composition of a dotLottie archive draws the image files of the archive (D75).FontDatabase.LoadFontDataloads a font in WOFF, WOFF2 or EOT, as well as TrueType and OpenType data.svg.ConvertFontDataconverts such a font to TrueType or OpenType data.FontDatabase.FaceNamereturns a string of the name table of a face, such as the version or the sample text (D45). The packagewebfontgives the same conversion to a program that does not usesvg(D51).Paint.Coveragefills a path with 8 by 8 samples in each pixel, in place of the 4 by 4 of tiny-skia, andPaint.StrokeAdjustmoves a thin stroke onto the pixel grid, as stroke adjustment does in PDF (D54).MeshGradient, whichNewMeshGradientmakes, fills a mesh of triangles with a color at each corner, for the shadings of the types 4 to 7 of PDF and PostScript.SpreadModeDecalmakes a gradient transparent before its start and after its end, as the decal tile mode of Skia does (D55).MaskFromLuminanceandMask.ApplyTransfermake the soft masks of PDF with a backdrop color and a transfer function.Pixmap.RemoveBackdropandPixmap.Knockoutcomposite the groups of PDF that are not isolated and the knockout groups (D56).TextStylealso takes the stretch, the variations, the features, the language and the spacing of a run, andTextRun.Clustersgives the bytes, the advance and the glyphs of each cluster.FontDatabasegives the parsed faces, the cmaps and the metrics that it keeps, andAutoFontVariationsmaps a CSS weight, stretch and style to the axes of a variable font.FontDatabase.ColorGlyphgives a glyph of COLR or of the table SVG as a tree (D57).svg.ReadDimensionsreads the size and the viewBox of an SVG image before the parse.svg.FromXMLTreeandsvg.FromXMLNodemake a tree from a document of roxmltree, androxmltree.Buildermakes such a document without XML text.svg.WithZeroSizeaccepts an image of size zero (D58).- The package
typesetting/font/cffexports the predefined charsets of CFF, and draws the accented glyphs ofseacand the FontMatrix of each font dictionary (D59). internal/subsetterreturns an error where subsetter panics, such as on the glyph after 65,535 glyphs. Its closure of composite glyphs reads each glyph once, where upstream can take time and memory that grow with the square of the number of components, and it gives the same order. It normalizes the coordinates of a variable font in float32 with avar version 1, astypesettingdoes, where skrifa uses fixed point and avar version 2. It hashes the glyphs in little-endian order on every machine (D62).NewRadialGradientExtendmakes a radial gradient with the rule of the radial shadings of PDF and PostScript. A point takes the color of the largest t in 0..=1 whose circle has a radius of at least 0. Two flags let t go below 0 or above 1, as the keyExtendof PDF does (D64).typesettingapplies five commits of go-text out of order, for the variable fonts ofinternal/subsetter. It maps a coordinate with the table avar as skrifa does, with a rounded division. A malformed font gives an empty glyph, an advance of 0 or an error where go-text panics (D65). It also applies the 23 commits of go-text that fix a panic, a loop or a missing bound on malformed input, out of order, and fixes two more panics of the feature indexes of GSUB and GPOS and of the table cmap (D67).internal/subsettermakes the instances of variable fonts withtypesetting, and an instance can differ from the instance of subsetter by 1 unit in a point (D62, D65).pdfadds what the PDF device of ivy needs and krilla does not have:Surface.PushGroupfor the transparency groups with the flagsIandK,Mask.WithBackdropandMask.WithTransferfor the entriesBCandTRof a soft mask, the fieldExtendof a linear and a radial gradient, the paintMeshGradientas a shading of type 4,Surface.FillStencilfor a stencil of 8 bits,Surface.PushStrokeAdjustmentfor the entrySA,Surface.PaintFromShader, which converts a shader of okage, andSurface.DrawRaster, which draws a part of a page with okage as an image. The shaders of okage give their parameters with the methodParametersfor that conversion (D68).StrokeDashgives its dash array and its dash offset with the methodsArrayandOffset. A writer of PDF writes the dashes of a stroke with them (D69).
The output of svg is compared with resvg and with libvips within a
tolerance, not byte for byte (D23). The renderer gives the same bytes as
tiny-skia.
The root package and path are under the BSD-3-Clause license of tiny-skia.
See LICENSE, which keeps the copyright lines of upstream. The
package svg and the packages that it uses take the MIT license of resvg and
of its crates, in a LICENSE file in each folder (D13). The package html
takes the MIT license of tinyhtml5, in html/LICENSE. That
license also covers the parser of the labels of Graphviz (D49). The packages
tinycss2 and cssselect2 keep the BSD-3-Clause licenses of their upstreams,
in tinycss2/LICENSE and
cssselect2/LICENSE (D50).
The brotli decoder in internal/brotli is a copy of the one of
github.com/dsnet/compress, and keeps its BSD-3-Clause license, in
internal/brotli/LICENSE (D45). The packages
under typesetting are a copy of go-text, and keep its license, the
Unlicense or the BSD-3-Clause license, in
typesetting/LICENSE. The package harfbuzz keeps the
MIT license of HarfBuzz in
typesetting/harfbuzz/LICENSE (D52). The
package lottie takes the MIT license of velato, in
lottie/LICENSE. Its test files are Noto animated emoji
under CC BY 4.0, as lottie/testdata/NOTICE says.