gmod-tinysvg

What it is

tinysvg is a pure-Lua SVG reader and renderer designed for Garry's Mod. It parses SVG documents and renders them as true vector graphics, allowing icons and images to scale without losing resolution. It ships as a single client-side file (cl_tinysvg.lua) with no dependencies and works in HUD hooks, VGUI Paint, and 3D2D.

How it works

The library parses SVGs and renders them as vector geometry that is flattened and tessellated to triangles. Rendering can be done via a cached render target per size bucket or via immediate vector drawing. It maintains per-size render targets and re-rasterizes when the requested size leaves its bucket. Key features include a pooled render target system, size-bucket caching, and a Draw/Render API to control rasterization behavior. Supported SVG features include paths, basic shapes, transforms, gradients, and CSS, with unsupported features skipped and recorded as warnings.

Getting started

-- Parse from a string, or load (and cache) from a file:
local doc = tinysvg.Parse(svgText)                 -- returns doc, or nil + errString
local doc = tinysvg.Load("materials/hq/icon.svg")  -- "GAME" mount by default

-- In a HUD / panel Paint hook:
function PANEL:Paint(w, h)
    doc:Draw(0, 0, w, h)   -- recommended: cached render-target, crisp per size bucket
end

The primary usage is doc:Draw for typical rendering, with doc:Render available for absolute sharpness when caching isn't suitable.

Getting started (API usage)

• doc:Draw(x, y, w, h, opts) — rasterizes once per size bucket and reuses the cached material.
• doc:Render(x, y, w, h, opts) — immediate vector draw using stencils; higher per-frame cost.
• doc:GetMaterial(w, h, opts) → IMaterial — returns a rasterized material, with caveats about blending.
• tinysvg.DrawMaterial(mat, x, y, w, h, alpha) — draws a premultiplied-alpha material.
• doc:GetSize() → w, h — intrinsic size of the document.

Options

Options are passed to Draw/Render/GetMaterial and include:

• supersample (default 1) — Raster antialiasing factor (1–4).
• tint (default –) — Color multiplication for all paints.
• alpha (default 1) — Opacity multiplier at draw time.
• exact (default false) — Draw only: rasterize at the exact requested size.

Options for Parse/Load:

• currentColor — used as the value for SVG currentColor.

Performance & caching

• Per-frame Draw path avoids allocations; size buckets and cache keys are integers.
• Render targets are pooled by pixel size to bound GPU memory.
• tinysvg.Load(path, mount, opts) caches by path and re-reads on mtime changes.
• doc:Invalidate() clears document caches; automatic on OnScreenSizeChanged.
• tinysvg.ClearCache() clears the Load path cache.
• tinysvg.TessTolerance default 0.25 for device-pixel curve flattening.

Prewarming helps avoid blank caches during fades by rasterizing up-front when panel opens.

SVG support

Supported: SVG root and groups, gradients, transforms, shapes (paths, rects, circles, ellipses, lines, polylines, polygons), CSS/inline styles, gradients, colors, and units. Not supported: <text>, <image>, <pattern>, masks/filters/clip paths, animation/scripting. Group opacity is approximated.

Notes: Rasterized materials are premultiplied-alpha; doc:Draw handles blending.

IconSet

Provides a thin wrapper for named inline SVGs with caching and fade-in behavior. Example usage includes NewIconSet, Draw, and Prewarm.

Installation

Drop cl_tinysvg.lua client-side, and ensure it defines the global tinysvg table. Place it under a gamemode/.../libraries/ path so it is loaded by the client.