123 3D: Retained renderer backends

9.3

Racket

123 3D: Retained renderer backends🔗ℹ

The animate/3d API is pure; effectful backend selection belongs to animate/3d/render. A compiled view includes ordered, renderer-neutral centreline strokes and screen markers. A backend receives an immutable render3d-request containing a camera-independent compiled view, a frame specification, and a canonical attachment demand. It returns one immutable renderer3d-frame-artifact which owns every delivered attachment. Thus changing a backend, releasing its cache, or recovering from a failed optional native renderer cannot mutate a view3d, any of its spatial children, or a completed frame.

(require animate/3d/render)

package: animate

value
geometry-key3d : procedure?

The immutable renderer geometry identity for an indexed mesh. It excludes semantic part IDs and material state.

value
geometry-key3d? : procedure?

Recognizes a geometry-key3d value.

procedure
(renderer3d? value) → boolean?
value : any/c

Recognizes a renderer-backend instance.

procedure
(renderer3d-id renderer) → symbol?
renderer : renderer3d?

Returns a stable backend identity, such as 'software-reference.

value
prop:renderer3d-cache-identity : any/c

A structure-type property whose immutable primitive datum declares a backend’s pixel-affecting configuration for an enclosing persistent cache. A backend without a stable declaration omits the property.

procedure
(renderer3d-cache-identity renderer) → any/c
renderer : renderer3d?

Returns the declared backend appearance identity or #f. An opaque view3d Pict adapter treats #f conservatively: section-output caching is disabled rather than reusing pixels rendered with an ambient custom backend. The built-in OpenGL backend identifies a live driver/profile and its compiled shader-source digests; when configured to fall back, it delegates this identity to the software renderer that actually produced the pixels.

procedure
(renderer3d-capabilities-of renderer)
→ renderer3d-capabilities?
renderer : renderer3d?

Returns the backend’s immutable declared feature set, limits, and diagnostics.

procedure
(renderer3d-fingerprint renderer request) → any/c
renderer : renderer3d?
request : render3d-request?

Returns an implementation-owned cache key for this immutable request. It is diagnostic and cache data, never a scene identity.

procedure
(renderer3d-prepare renderer request) → any/c
renderer : renderer3d?
request : render3d-request?

Builds or retrieves backend-owned preparation data.

procedure
(renderer3d-render renderer
preparation
request) → renderer3d-render-result?
  renderer : renderer3d?
  preparation : any/c
  request : render3d-request?

Rasterizes a fresh frame from a preparation and request.

procedure
(renderer3d-release renderer) → void?
renderer : renderer3d?

Releases every resource retained by renderer. It does not change an existing Scene or an already returned render result.

struct
(struct renderer3d-capabilities (features limits diagnostics)
    #:transparent)
  features : set?
  limits : immutable-hash?
  diagnostics : immutable-hash?

The immutable declaration returned by renderer3d-capabilities-of. features is an immutable set of symbols; limits maps a symbol to an exact number (or a transparent future resource value), and diagnostics records immutable backend details. Feature membership and named limits describe the backend without relying on positional Boolean fields.

value
renderer3d-known-features : set?

The vocabulary currently includes 'wireframe, 'opaque-triangles, 'perspective, 'orthographic, 'depth-buffer, 'flat-shading, 'smooth-shading, 'transparency, 'clipping-planes, 'screen-strokes, 'linear-depth, 'object-id, 'ambient-light, 'directional-light, 'point-light, 'spot-light, 'specular, 'emission, 'directional-shadow, and 'spot-shadow. A vocabulary symbol is not an implied implementation claim: use renderer3d-supports?.

value
renderer3d-known-limits : set?

The current limit vocabulary includes 'maximum-directional-lights, 'maximum-point-lights, 'maximum-spot-lights, 'maximum-shadow-lights, 'maximum-clip-planes, 'maximum-shadow-map-size, and 'maximum-samples.

procedure
(renderer3d-supports? capabilities
features) → boolean?
capabilities : renderer3d-capabilities?
features : (or/c symbol? (listof symbol?) set?)

Returns true exactly when every requested feature is in the immutable report.

procedure
(renderer3d-capability-limit capabilities
limit
[ default]) → any/c
  capabilities : renderer3d-capabilities?
  limit : symbol?
  default : any/c = #f

Returns the declared limit, or default when the backend did not declare it. A zero limit is distinct from an absent limit.

procedure
(renderer3d-missing-capabilities capabilities
features)
→ (listof symbol?)
capabilities : renderer3d-capabilities?
features : (or/c symbol? (listof symbol?) set?)

Returns missing requested features in request order.

procedure
(renderer3d-require-capabilities capabilities
features) → void?
capabilities : renderer3d-capabilities?
features : (or/c symbol? (listof symbol?) set?)

Raises a diagnostic exception when one or more requested features are missing.

procedure
(renderer3d-request-required-features request) → set?
request : render3d-request?

Infers the immutable set of features needed by one compiled request, including projection, material shading, present light kinds, clipping, screen marks, transparency, and requested frame attachments.

procedure
(renderer3d-request-required-limits request) → immutable-hash?
request : render3d-request?

Returns exact per-frame resource demands, including directional-light and clip-plane counts.

procedure
(renderer3d-require-request-capabilities renderer
request) → void?
renderer : renderer3d?
request : render3d-request?

Checks the same inferred feature and limit demand before a built-in backend prepares resources. check-project! performs this comparison across every selected project frame before rendering begins.

Current capability limitation: The software backend has no practical fixed directional, point, spot, or clipping bound. The optional OpenGL shaders explicitly support at most four directional lights, eight point lights, four spot lights, and eight clip planes; an over-limit request raises an error rather than silently dropping lights. Its maximum sample count is the live GL limit, although a one-sample framebuffer remains available. The software backend supports directional and spot shadow maps. The OpenGL backend supports the same descriptor kinds with at most eight cached depth maps.

I	Concepts
II	Cookbook
III	Guide
IV	Complete Example Programs
V	Reference

52	Find a task or a name
53	Modules to require
54	Scenes and sampling
55	Scene states
56	Animation requests
57	Native model details
58	Visuals
59	Geometry
60	Number Lines and Coordinate Decorations
61	Point Markers, Scatter Plots, and Filled Areas
62	Probability and Statistical Diagrams
63	Calculus lessons
64	Colors
65	Slides
66	Slide command-line tools
67	Source Programs and Authored Timelines
68	Interactive Preview and Inspection
69	Preview controls and diagnostics
70	Projects and Final Rendering
71	Project execution and cache details
72	Pict Renderer Protocol
73	3D reference map
74	3D: Objects, groups, and paths
75	3D: Cameras and projection
76	3D: Views inside a Scene
77	3D: Animating 3D objects
78	3D: Animating the 3D camera
79	3D: Cuts, caps, and section measurements
80	3D: Supplementary surface, section, and annotation bindings
81	3D: Cuts, sections, and numerical volume
82	3D: Vectors
83	3D: Linear maps and rotations
84	3D: Affine transforms
85	3D: Bounds, rays, and planes
86	3D: Spatial maps and homotopies
87	3D: Materials and lights
88	3D: Lighting inspection
89	3D: Shadow descriptors and stable bounds
90	3D: Finite-light animation
91	3D: Software finite-light evaluation
92	3D: Colour space and final output
93	3D: Relations and geometric annotations
94	3D: Projected labels
95	3D: Textured billboards
96	3D: Spatial curves and vector diagrams
97	3D: Spatial anchors and label layout
98	3D: Anchors and projected labels
99	3D: Parametric surfaces and calculus
100	3D: Adaptive, trimmed, and implicit surfaces
101	3D: Constructive solids
102	3D: Surface constructors and queries
103	3D: Meshes
104	3D: Triangle topology
105	3D: Polygonal faces
106	3D: Deterministic convex hulls
107	3D: Polyhedral duals
108	3D: Schlegel diagrams and polyhedral nets
109	3D: Conservative mesh correspondence
110	3D: Topology-safe mesh matching
111	3D: Checking and repairing mesh orientation
112	3D: Clipping, sections, and transparency
113	3D: Prepared spatial ODE trajectories and vector fields
114	3D: Seeds and streamline sets
115	3D: Poincare sections and return maps
116	3D: Equilibria and local linearization
117	3D: Flow maps and volume change
118	3D: Drawing and inspecting trajectories
119	3D: Reading prepared trajectories
120	3D: Drawing vector fields and particles
121	3D: Trajectory display
122	3D: Spatial inspection and exact picking
123	3D: Retained renderer backends
124	3D: Compiled geometry and instances
125	3D: Frame requests and results
126	3D: Software rendering and statistics
127	3D: Optional Racket/ Open GL backend
128	Experimental Derived Visuals
129	Source Package Hygiene