21.1 Built-in Rendering🔗ℹ

The built-in circle renderer multiplies the local diameter by the Visual’s x and y scale factors. Non-uniform scale therefore produces an ellipse. Rotation is applied when that ellipse is not rotationally symmetric.

The built-in rectangle renderer multiplies local width and height by the scale factors and then rotates the resulting Pict.

The built-in arrow renderer derives one open shaft and zero, one, or two closed triangular tip subpaths from the semantic arrow. The built-in axes renderer derives the two open shafts, ordered open ticks, and optional closed maximum-end tips. Both then use the ordinary path renderer. Tip dimensions and tick sizes are transformed as local geometry. Stroke width remains cosmetic.

Closed tips use the same odd-even fill, miter join, and butt-cap policy as other closed path geometry. Open shafts and ticks use round endpoint caps and miter joins. The adapter uses the stored stroke style for shaft and tick lines and for tip fill and outline.

The built-in plain-text renderer converts the semantic font size from world units to camera pixels and constructs a platform font from the requested face, family, style, and weight. It renders the one-line string with Pict, applies the stored color, places the chosen anchor at the center of a symmetric local Pict, and then applies semantic scale and rotation around that anchor. Direct font sizes are kept within the drawing backend’s supported range; a final Pict scale preserves the requested world-space size outside that range.

Since version 0.50.1, the completed nonempty local text appearance is rasterized to an alpha bitmap before scene placement. Moving the Visual or panning the camera therefore translates an already-rasterized glyph run instead of asking the platform font backend to rerasterize it at changing device-space origins. This prevents subtle apparent inter-letter spacing changes during smooth motion. The default renderer keeps a bounded renderer-local cache for common immutable text appearances. The cache key excludes position, Visual identity, opacity, and camera center, but includes text/font/color/alignment data, semantic scale and rotation, and camera pixel scale. Camera zoom and appearance transforms therefore rerasterize at their sampled resolution. Unknown adapter-native color objects bypass the cache while retaining stable local-origin rasterization. The same bounded renderer-resource mechanism caches complete formula appearances. Formula position, identity, opacity, and camera center do not invalidate an appearance, while formula source/options, semantic scale/rotation, and camera pixel scale do.

An empty text string produces a transparent one-pixel Pict. Left and right anchors reserve symmetric space on the opposite side of the anchor, and top and bottom anchors do the same vertically. Baseline alignment uses the Pict’s font ascent and descent. These symmetric boxes keep the semantic anchor at the local Pict center, which is the placement convention used by groups and scene states.

The built-in formula renderer chooses one of tex-math, tex-display-math, and tex-real-display-math from the semantic mode. It passes the immutable source, preamble, document-class options, and Preview options to latex-pict with that package’s extra scale set to one. It then maps the selected 10pt, 11pt, or 12pt document base to the formula’s semantic world-unit font size.

Formula anchoring, non-uniform semantic scale, rotation, and opacity follow the same order as plain text. Empty formula source produces a transparent one-pixel Pict without loading latex-pict or running TeX. Nonempty formula rendering can perform external process and native-library work. latex-pict is loaded at that adapter boundary instead of from the pure formula model. That package caches repeated complete TeX documents; source, preamble, or option changes produce a different document.

A formula assembly is composed from its parts in significant back-to-front order. Each part is rendered as an ordinary formula Visual at its stored local position. The same explicit renderer list is passed to every part. An empty assembly produces a transparent one-pixel Pict and does not invoke TeX. The assembly’s uniform scale and rotation are inherited through its part model transforms before rendering, and its global opacity is applied after the parts have been composed.

The built-in path renderer transforms every stored local point by scale and rotation, converts world units to pixels, and draws the result through dc-path%. Sampled function graphs reach this renderer as ordinary path Visuals; no separate graph renderer is used. Line segments become drawing-path line operations. Cubic segments become drawing-path curve operations and remain true cubic curves. Closed subpaths are filled together with the odd-even rule. Open subpaths are stroked without implicit filling. A false fill or stroke selects a transparent brush or pen.

Closed outlines use miter joins and butt caps, which keeps polygon corners sharp. Open paths use round endpoint caps and miter joins between segments.

A partial piece returned by path-geometry-partial is open unless it contains a complete original closed subpath. During create, a closed shape is therefore stroked as it grows and becomes filled when its subpath is complete. In a compound path, one completed closed subpath can be filled while a later subpath is still partial. uncreate performs the same sequence in reverse.

For all built-in Visuals, stroke width is cosmetic: semantic scale does not multiply it. A group is composed recursively from its ordered children. Its uniform scale and rotation are inherited by child model transforms before each child is rendered, so cosmetic stroke widths are not enlarged by scaling a finished composite Pict. The same explicit renderer list is passed to every descendant. Group translation places the complete composite in its containing coordinate system.

The built-in compositor uses a symmetric Pict box around the group anchor. Its half-width and half-height are the largest absolute child extents on each axis. This keeps the anchor at the center even when all children lie on one side. An empty group produces a transparent one-pixel Pict.

Global opacity is applied to the complete local Pict after renderer selection or group composition. It affects fill and stroke together and does not change Pict bounds. World translation is applied later by scene-state->pict. Path reveal is measured in untransformed local arc length. Cubic reveal uses the deterministic approximation described by path-subpath-length. A non-uniform Visual scale can therefore change displayed speed along differently oriented or curved portions.

21.2 Defining a Custom Renderer🔗ℹ

Here is a complete custom Visual and renderer:

(require pict

animate)

(struct cross-visual (id position)

#:transparent

#:methods gen:visual

[(define (visual-id value)

(cross-visual-id value))

(define (visual-position value)

(cross-visual-position value))

(define (visual-with-position value position)

(struct-copy cross-visual value [position position]))])

(struct cross-renderer ()

#:transparent

#:methods gen:pict-renderer

[(define (pict-renderer-supports? renderer visual)

(cross-visual? visual))

(define (pict-renderer-render renderer visual camera)

(define arm

(camera-length->pixels camera 1))

(cc-superimpose

(filled-rectangle arm (/ arm 5))

(filled-rectangle (/ arm 5) arm)))])

(define renderers

(cons (cross-renderer) default-pict-renderers))

The example’s renderer uses Pict operations, so its module must also require pict.

21.3 Relative Layout🔗ℹ

Relative layout measures the Pict that a Visual would produce and converts its pixel dimensions back into world units. Arrow tips, axis ticks, tip outlines, and cosmetic stroke padding are therefore included in the measured box. It then returns new Visual values with updated reference positions. The source Visuals are not mutated.

Layout is renderer-aware. Text, formulas, custom Visuals, and composites can have dimensions that are known only after renderer selection. Every measurement and placement procedure therefore accepts the same #:camera and #:renderers arguments as the Pict adapter. Use the same values for layout and final rendering.

A layout box is the complete symmetric render box of the local Pict. It is not a tight ink box. Transparent padding, text anchor padding, formula anchor padding, group composition extents, and any padding returned by a custom renderer are included. Semantic opacity does not change the box because opacity does not change Pict dimensions.

Measuring a nonempty LaTeX formula with the built-in formula renderer can invoke LaTeX and Poppler. A custom formula renderer can provide deterministic metrics without launching TeX.

The fields have these meanings:

• left is the smallest horizontal coordinate.

• bottom is the smallest vertical coordinate.

• right is the largest horizontal coordinate.

• top is the largest vertical coordinate.

All four fields must be finite real numbers. left must not exceed right, and bottom must not exceed top. Zero-width and zero-height boxes are valid.

The structure is immutable and transparent. Its public bindings include layout-box, layout-box?, the four field accessors, and struct:layout-box.

'left

'center

'right

These symbols select a horizontal coordinate of a layout box.

'bottom

'center

'top

These symbols select a vertical coordinate of a layout box. Baseline alignment is not part of this layout protocol. A text or formula Visual may still use a baseline as its own semantic anchor before its complete render box is measured.

'bottom-left  'bottom  'bottom-right

'left         'center  'right

'top-left     'top     'top-right

These names select both coordinates at once. They are distinct from the one-axis alignment predicates and intentionally do not infer a baseline from a renderer.

If the local Pict has pixel width w, pixel height h, camera scale s, and Visual position (x,y), the result is:

layout-box(x - w/(2s), y - h/(2s), x + w/(2s), y + h/(2s))

The selected renderer must follow the Pict-renderer protocol and return centered local geometry. The procedure checks that the Visual position is a vec2, that its identity is a symbol, and that the Pict dimensions are finite and nonnegative.

This procedure can perform adapter effects. In particular, measuring a nonempty formula through the built-in formula renderer can run TeX.

The camera and renderer list are validated even for an empty list. Every nonempty Visual is measured with visual-layout-box using the supplied context.

Only the x component of the Visual position changes. Its y component, identity, geometry, style, transform components other than translation, opacity, and children remain as supplied by its visual-with-position implementation. reference is unchanged.

Only the y component of the Visual position changes. The x component and the reference Visual remain unchanged.

The selected horizontal coordinates are aligned. The default aligns box centers; 'left and 'right align the corresponding edges.

Returns an empty list when visuals is empty. The camera, renderer list, and center are still validated.

When center is a vec2, the complete arranged list is translated as one unit so that its union layout box has that center. #f leaves the first Visual fixed. An empty input list returns an empty list.

The procedure returns a new list and does not reorder identities. Arrangement uses adjacent measured boxes; it is not a constraint solver and does not recompute automatically after later content, renderer, camera, or transform changes.

When center is a vec2, the complete arranged list is translated as one unit so that its union layout box has that center. #f leaves the first Visual fixed. An empty input list returns an empty list.

The returned list preserves order and identities. Layout is a one-time immutable calculation. It does not maintain a live relationship between the arranged Visuals.

21.4 Temporary Attention Effects🔗ℹ

The outline does not mutate the target and is absent at both structural clip endpoints. It measures a renderer box rather than visible glyph contours, and does not respond to camera or renderer changes within the same clip.

21.5 Pict, Bitmap, and Frame Conversion🔗ℹ

The dispatcher does not apply translation in the Visual’s containing coordinate system. It also does not interpret an affine transform on behalf of a custom renderer. The built-in circle, rectangle, path, plain-text, and formula renderers apply their Visuals’ scale and rotation themselves. The built-in group compositor inherits the group’s uniform scale and rotation through its children before rendering. A formula assembly delegates the same composition rule to its ordered formula parts.

When visual implements gen:opacity-visual, its visual-opacity result must satisfy opacity?. Opacity one returns the rendered or composed Pict unchanged. Lower values use Pict alpha without changing the Pict’s width, height, or reference placement. A custom renderer therefore receives opacity behavior without handling it itself. Group opacity is applied after its children have been composed.

A derived-visual? cannot be rendered by visual->pict directly because no scene-state scalar context is available. Resolve it first with scene-state-resolved-ref, or render through scene-state->pict or scene->pict.

If no renderer supports the concrete Visual, an exception is raised. Invalid custom support, render, or opacity-protocol results also raise exceptions.

When camera is #f, the Visual state and scene camera are sampled together using one easing evaluation. Supplying a camera is a static override: the supplied camera is used instead of the scene-camera timeline for this conversion.

When camera is #f, the camera is sampled from the scene at the frame time. A supplied camera is used as one fixed override for the frame.

21.6 PNG and MP4 Output🔗ℹ

The procedures in this section perform external effects. Their names end in ! according to the project house style.

When camera is #f, each frame samples the camera stored in the scene timeline. Supplying a camera uses that one static view for every frame and ignores camera pan or zoom requests during rendering. Pixel dimensions remain fixed either way.

When a sampled scene contains a nonempty formula, including a nonempty part of a formula assembly, and the built-in formula renderer is selected, frame rendering can invoke LaTeX and Poppler through latex-pict. A custom renderer placed before the defaults can replace that behavior for a formula leaf or for the complete assembly.

Names use at least six decimal digits:

• "frame-000000.png"

• "frame-000001.png"

• "frame-000002.png"

When clean? is true, the procedure first deletes files in the output directory whose names match frame- followed by at least six digits and .png. Other files are preserved. When clean? is false, no cleanup is performed.

workers is a bounded worker-pool size. Its default, one, retains sequential output. On Racket 8.18 or later with parallelism enabled, more than one worker builds independent frame bitmaps through a parallel thread pool; one ordinary thread then encodes their PNG files, because Racket’s PNG encoder uses callbacks that cannot run in a parallel thread. On the package’s Racket 8.12 baseline, the same argument uses the compatible coroutine-thread implementation. In every case, returned paths remain in frame-index order and each frame keeps its deterministic filename. The built-in renderers synchronize their shared resources. A custom renderer used with more than one worker must itself be safe for concurrent calls.