58.3 Bitmap and SVG Visuals
Choose image for a bitmap, svg-image for a static SVG rendered by the SVG backend, or svg->visual when individual supported SVG elements must become addressable scene children. The first two defer file reading until rendering; semantic SVG import reads the file during construction.
See also Visual Protocols and Groups, Shapes and Path Visuals.
58.3.1 Bitmap Images
procedure
(image source #:id id [ #:center center #:rotation rotation #:scale scale #:opacity opacity] #:width width #:height height) → image-visual? source : path-string? id : symbol? center : vec2? = origin rotation : finite-real? = 0 scale : scale-factor? = 1 opacity : opacity? = 1 width : (and/c finite-real? positive?) height : (and/c finite-real? positive?)
The built-in renderer loads the source lazily, scales it to the requested world size at the current camera scale, then applies the normal Visual scale and rotation. A missing or unreadable source therefore raises a renderer-time error. Its renderer-local bitmap cache is bounded and does not affect scene semantics. Image Visuals implement affine and opacity protocols, so standard movement, scaling, rotation, fading, grouping, layout, camera placement, and frame rendering work without a special timeline request.
procedure
(image-visual? value) → boolean?
value : any/c
procedure
(image-visual-source visual) → immutable-string?
visual : image-visual?
procedure
(image-visual-width visual) → (and/c finite-real? positive?)
visual : image-visual?
A bitmap model can be inspected before its source is read.
> (define photo (image "diagram.png" #:id 'photo #:width 2 #:height 1)) > (image-visual-width photo) 2
procedure
(image-visual-height visual) → (and/c finite-real? positive?)
visual : image-visual?
58.3.2 Full-Fidelity SVG Images
procedure
(svg-image source #:id id [ #:center center #:rotation rotation #:scale scale #:opacity opacity] #:width width #:height height) → svg-image-visual? source : path-string? id : symbol? center : vec2? = origin rotation : finite-real? = 0 scale : scale-factor? = 1 opacity : opacity? = 1 width : (and/c finite-real? positive?) height : (and/c finite-real? positive?)
width and height specify unscaled local world dimensions, independently of the SVG document’s viewport. The Visual otherwise behaves like image: standard movement, scaling, rotation, opacity animation, groups, layout, camera placement, and frame rendering work normally. The renderer has a bounded local source-Pict cache. Use svg->visual rather than this constructor when individual SVG elements must be directly addressed or animated.
procedure
(svg-image-visual? value) → boolean?
value : any/c
procedure
(svg-image-visual-source visual) → immutable-string?
visual : svg-image-visual?
procedure
(svg-image-visual-width visual)
→ (and/c finite-real? positive?) visual : svg-image-visual?
procedure
(svg-image-visual-height visual)
→ (and/c finite-real? positive?) visual : svg-image-visual?
58.3.3 Semantic SVG Import
procedure
(svg->visual source #:id id [ #:center center #:rotation rotation #:scale scale #:opacity opacity]) → group-visual? source : path-string? id : symbol? center : vec2? = origin rotation : finite-real? = 0 scale : scale-factor? = 1 opacity : opacity? = 1
The root takes id. An SVG element’s nonempty id becomes its stable child identity; missing IDs receive deterministic generated symbols. Nested g elements become nested built-in groups, so imported IDs participate in scene-ref, scene-visual-at, derived-context lookup, and all nested style and transform requests. The constructor rejects duplicate IDs using the existing built-in group-tree invariant.
SVG’s screen-down y coordinate is converted to the semantic world-up y coordinate. Unitless translate(x[, y]) transforms are supported. Other SVG transforms must be flattened before import. Inherited fill, stroke, stroke-width, and opacity attributes (including simple inline style declarations) are preserved. CSS stylesheets, clipping, text, use elements, arcs, and paint servers are outside this deliberately semantic subset.