3 Top-Level Rendering🔗ℹ

This is the small set of functions most programs need: parse an SVG document and get back something you can display or save. Everything else in this document is either a building block these functions use internally (and export for reuse) or a lower-level entry point for working with a piece of the pipeline in isolation.

The two output formats — bitmap% and pict — are not just two ways of returning the same picture:

• bitmap% (svg-string->bitmap, svg-file->bitmap) rasterizes onto a fresh bitmap sized exactly to the SVG’s own width/height, with an opaque white background — the right default for "save this as a standalone image."

• pict (svg-string->pict, svg-file->pict, svg-doc->pict) wraps the same rendering as a self-drawing pict with a transparent background, so it composes correctly with other picts around or behind it. Because render-svg-doc! never assumes bitmap-dc% for the dc<%> it’s handed (only for its own private offscreen buffers — mask, filter, pattern, and marker content, which is unrelated), the resulting pict can be drawn onto any dc<%>: a bitmap via pict->bitmap, but also a pdf-dc% or post-script-dc%, giving vector output for anything that doesn’t need mask/filter rasterization. (Masked or filtered elements still rasterize internally either way, the same as in any renderer, since those effects inherently require pixel buffers — they’d appear as embedded raster images in an otherwise-vector PDF.)

Both families accept either a string of SVG source or a file path; the file-path versions additionally know the SVG’s own directory, which matters for resolving relative <image> references — an <image href="icon.png"> next to diagram.svg only resolves correctly if you render via (svg-file->bitmap "diagram.svg"), not by reading the file yourself and passing its contents to svg-string->bitmap.

If you need to inspect or reuse a parsed document before rendering it (its declared width/height, its id table, or its viewBox matrix), read-svg-document and the svg-doc-* accessors below let you separate parsing from rendering.

(send (svg-string->bitmap

#<<SVG

<svg width="100" height="100">

<circle cx="50" cy="50" r="40" fill="crimson"/>

</svg>

SVG

)

save-file "circle.png" 'png)

(svg-file->bitmap "logo.svg")

(require pict)

(hc-append 10 (svg-string->pict "...") (colorize (disk 20) "orange"))

Constructing the pict costs a second, throwaway render as part of pict’s own contract checking (dc’s precondition renders once with a scratch dc<%> to confirm the draw procedure restores its state correctly) — this is pict’s behavior, not something svg/svg adds on top, and it’s a one-time cost per pict, not per subsequent draw.

(svg-file->pict "logo.svg")

Use this when you’re calling read-svg-document yourself anyway — for instance, to inspect svg-doc-width/svg-doc-height before deciding how to render — and want to avoid parsing the document twice.

Unlike svg-doc->pict, this does not save or restore the dc’s transformation, smoothing mode, pen, brush, font, or other drawing state around the call — it applies the viewBox transform and leaves it applied, and generally assumes it can freely change dc’s state. If you need the dc’s prior state preserved (for instance, because you’re drawing several things onto the same dc in sequence), save and restore it yourself around the call, the way svg-doc->pict does internally.

(define bm (make-object bitmap% 200 200))

(define dc (new bitmap-dc% [bitmap bm]))

(render-svg-doc! (read-svg-document "<svg>...</svg>") dc)

Width and height resolve in the following order: the width/height attributes if present and not given as a percentage; otherwise the viewBox attribute’s width/height, if present; otherwise 300×150 (the CSS replaced-element default).

(define doc (read-svg-document #<<SVG

<svg width="640" height="480">...</svg>

SVG

))

(svg-doc-width doc)   ; 640

(svg-doc-height doc)  ; 480