9.3
68 Interactive Preview and Inspection
animate/preview provides the optional GUI and its headless controller API. Requiring it does not initialize a GUI; opening a window does. It uses the same scene sampling and rendering semantics as final output.
procedure
(animation-inspection? value) → boolean?
value : any/c
Recognizes an
immutable active-animation inspection record re-exported by the preview API.
procedure
(animation-inspection-kind inspection) → any/c
inspection : animation-inspection?
Returns
the animation request-family symbol retained by inspection.
procedure
(animation-inspection-data inspection) → any/c
inspection : animation-inspection?
Returns
the immutable semantic explanation data retained by inspection.
procedure
(preview-session? value) → boolean?
value : any/c
Recognizes a live preview controller session.
procedure
(preview-status? value) → boolean?
value : any/c
Recognizes the immutable status snapshot returned by preview configuration and
transport operations.
procedure
(open-scene-preview source [ #:fps fps #:theme theme #:typography typography #:pixel-scale pixel-scale #:cache-megabytes cache-megabytes #:prefetch prefetch #:render-workers render-workers #:title title]) → preview-session? source : (or/c scene? authored-timeline?) fps : exact-positive-integer? = 30 theme : (or/c false/c color-theme?) = #f typography : (or/c false/c typography-theme?) = #f pixel-scale : positive? = 1 cache-megabytes : exact-positive-integer? = 512 prefetch : exact-nonnegative-integer? = 3 render-workers : exact-positive-integer? = 1 title : string? = "Animate"
Opens an interactive preview with immutable color and typography snapshots.
They affect rendered scene pixels only: canvas handles, inspector text, and
operating-system widgets retain their editor UI appearance. The bitmap cache
uses 512 MiB by default. #:render-workers normally remains 1: it is
for producers that explicitly provide isolated render processes, not for an
ordinary in-process scene or an OpenGL context.
procedure
(inspector-subject? value) → boolean?
value : any/c
Recognizes an immutable semantic inspection subject.
procedure
(inspector-document? value) → boolean?
value : any/c
Recognizes an immutable GUI-independent inspector snapshot.
procedure
(open-program-preview module-path binding [ #:auto-reload? auto-reload? #:fps fps #:start start #:start-block start-block #:section section #:pixel-scale pixel-scale #:repl? repl? #:title title]) → preview-session? module-path : path-string? binding : symbol? auto-reload? : boolean? = #t fps : exact-positive-integer? = 30 start : (or/c #f real?) = #f start-block : (or/c #f symbol?) = #f section : (or/c #f symbol?) = #f pixel-scale : positive? = 1 repl? : boolean? = #f title : string? = "Animate"
Loads a module binding containing a scene-program?, compiles it, and
opens a hot-reloading preview. At most one of #:start and
#:start-block may be supplied. Run the containing program with
GRacket (or raco animate preview) rather than a headless Racket process.
procedure
(open-project-preview project [ #:target target #:directory directory #:title title]) → preview-session? project : animate-project? target : project-target? = (project-target-all) directory : path-string? = (current-directory) title : (or/c #f string?) = #f
Prepares and opens an immutable project declaration. A module-binding source
uses ten restartable software-renderer subprocesses, so queued independent
frames can use up to ten CPU cores. The software workers preview menu
selects how many of those lanes receive new work. Direct Scene or timeline sources use
cooperative in-process cancellation. An OpenGL project keeps one serialized
graphics context.
procedure
(preview-color-theme session) → color-theme?
session : preview-session?
Returns the immutable theme snapshot selected for this session’s video content.
procedure
(preview-set-color-theme! session theme) → preview-status?
session : preview-session? theme : color-theme?
Changes only the preview content theme. The session keeps its semantic time,
selection, audio position, and inspection-camera overrides, but advances its
render generation and uses separately keyed frame-cache entries. A bitmap from
the previous theme can never be installed as a result for the new theme.
procedure
(preview-typography-theme session) → typography-theme?
session : preview-session?
Returns the typography snapshot selected for this session’s semantic text.
procedure
(preview-set-typography-theme! session typography) → preview-status? session : preview-session? typography : typography-theme?
Changes only the preview typography snapshot. The preview keeps its semantic
time and selection. If the new snapshot has a different typography appearance,
the preview advances its render generation and never reuses a bitmap from the
earlier appearance. If only metadata such as the theme name or provenance
changes, the current bitmap and render generation are retained while inspector
metadata is updated.
procedure
(preview-scrub! session time) → void?
session : preview-session? time : real?
Seeks during a drag. Older pending scrub work is superseded and the current
time first uses the preview’s draft quality.
procedure
(preview-render-worker-count session) → exact-positive-integer?
session : preview-session?
Returns the number of renderer lanes that may receive new work concurrently.
procedure
(preview-set-render-worker-count! session count) → preview-status? session : preview-session? count : exact-positive-integer?
Sets the renderer-lane limit, up to the session’s pre-created worker pool.
Existing jobs finish; the new limit applies when the scheduler chooses its next
jobs. Module-backed project previews expose this as the software workers
menu.
procedure
(preview-play! session) → void?
session : preview-session?
Starts playback.
procedure
(preview-set-loop-range! session start end) → void?
session : preview-session? start : real? end : real?
Stores a half-open loop range. It applies to both visual playback and an
available project audio monitor.
procedure
(preview-jump-to-section! session name) → void?
session : preview-session? name : symbol?
Jumps to the named authored section.
procedure
(preview-jump-to-cue! session name) → void?
session : preview-session? name : symbol?
Jumps to the named authored cue.
procedure
(preview-session-diagnostics session) → immutable-hash?
session : preview-session?
Returns one immutable production-monitor snapshot: requested and displayed
sample times, quality, cache state, cancellation count, worker information,
recent rendering measurements, and the color/typography appearance
fingerprints plus resolver versions used by the current frame-cache namespace.
procedure
(scene-inspector-subject-at-path state path) → inspector-subject? state : scene-state? path : visual-path?
Builds a stable inspector subject for a sampled Visual path. It promotes a
uniquely mapped formula leaf to its precise source-map unit and never guesses
between repeated or shared source occurrences.
procedure
(scene-inspector-document scene time [ #:subject subject #:theme theme #:typography typography]) → inspector-document? scene : scene? time : real? subject : (or/c #f inspector-subject?) = #f theme : color-theme? = animate-light-theme typography : typography-theme? = animate-typography-theme
Creates the immutable, GUI-independent inspector model for a scene sample.
Formula maps, active string-match plans, relation dependency reports, camera,
and preview-only overlays all live in this value; inspecting does not invalidate
the bitmap cache. When the selected object is semantic text, its Typography
section distinguishes the authored role and overrides from the base style and
resolved appearance. It also reports the resolved color and measured rendered
box under the selected theme and typography snapshots.
Limitations: hard cancellation is available only for a module-backed project worker. An arbitrary direct Scene can contain an opaque Racket procedure, so it is cancelable only at cooperative rendering boundaries. Audio monitoring is optional and requires a usable ffplay installation.