88 3D: Lighting inspection

9.3

Racket

88 3D: Lighting inspection🔗ℹ

struct
(struct material-inspection3d (material fields)
    #:transparent)
  material : material3d?
  fields : immutable-hash?

An immutable, presentation-neutral report of every material parameter relevant to the current lighting contract. fields names the base colour, normal mode, lighting model, ambient/diffuse/specular coefficients, specular colour, roughness, derived exponent, emission, double-sided policy, and cast/receive-shadow policies.

procedure
(material3d-inspection material) → material-inspection3d?
material : material3d?

Returns the immutable material report without rendering or changing material.

struct
(struct light-inspection3d (light fields)
    #:transparent)
  light : light3d?
  fields : immutable-hash?

An immutable description of one light. Its fields include the stable ID, kind, colour, intensity, position or direction where applicable, attenuation/range, spot angles, and its shadow descriptor.

procedure
(light3d-inspection light) → light-inspection3d?
light : light3d?

Returns the immutable light report without allocating renderer resources.

struct
(struct fragment-light-sample3d ( id
kind
direction
distance
attenuation
cone
facing
shadow-factor
shadow-state
diffuse-energy
specular-energy
diffuse-linear
specular-linear)
    #:transparent)
  id : symbol?
  kind : symbol?
  direction : any/c
  distance : any/c
  attenuation : any/c
  cone : any/c
  facing : any/c
  shadow-factor : real?
  shadow-state : symbol?
  diffuse-energy : real?
  specular-energy : real?
  diffuse-linear : any/c
  specular-linear : any/c

One per-light term in a lighting probe. Ambient samples deliberately use #f for geometric values that have no ambient meaning.

struct
(struct fragment-lighting-report3d ( world-point
normal
view-direction
material
light-samples
pre-tone-map
final-srgb
diagnostics
authored-lights
theme-id
appearance-fingerprint
resolved-material
resolved-lights)
    #:transparent)
  world-point : vec3?
  normal : vec3?
  view-direction : vec3?
  material : material3d?
  light-samples : list?
  pre-tone-map : any/c
  final-srgb : rgba-color?
  diagnostics : list?
  authored-lights : list?
  theme-id : symbol?
  appearance-fingerprint : bytes?
  resolved-material : material3d?
  resolved-lights : list?

The complete pure fragment-lighting explanation: normalized geometry, each light’s diffuse/specular/shadow term, the accumulated linear colour before tone mapping, final sRGB output, and any honest unavailable-data diagnostic. The material and lights fields retain authored specifications; the separate resolved fields record the concrete colours used for arithmetic.

procedure
(fragment-lighting-inspection3d
material
lights
world-point
normal
camera-position
[ #:tone-map tone-map
#:shadow-factors shadow-factors
#:theme theme])
→ fragment-lighting-report3d?
  material : material3d?
  lights : (listof light3d?)
  world-point : vec3?
  normal : vec3?
  camera-position : vec3?
  tone-map : tone-map3d? = default-tone-map3d
  shadow-factors : immutable-hash? = #hasheq()
  theme : color-theme? = animate-light-theme

Recomputes the documented lighting equation from immutable authoring values under the selected immutable theme. Tokenized material and light colours are resolved once before numerical color-space calculations begin. shadow-factors may supply a sampled fraction in [0,1] for each named shadowed light. The preview’s Material, Lights, and Fragment probe inspector sections use the same query after a mesh click.

Current limitation. A pure probe does not read a private software or OpenGL depth map: when a light declares a shadow but its factor has not been explicitly supplied, the report uses a numerically unshadowed factor of one, marks it 'not-sampled, and returns a diagnostic. This prevents the inspector from guessing hidden renderer state or changing the rendered Scene. It is not a per-pixel GPU debugger; the preview probe reports the exact CPU pick and authored equations, while actual shadow-map sampling remains backend owned.

procedure
(ambient-light3d [ #:id id
#:intensity intensity
#:color color
#:shadow shadow]) → ambient-light3d?
  id : symbol? = 'ambient
  intensity : nonnegative-real? = 1
  color : color-spec? = "white"
  shadow : #f = #f

Creates uniform ambient illumination with a stable authored identifier. The colour specification must resolve to opaque under the frame’s theme. Shadow descriptors are not supported for ambient lights; the only accepted value is #f.

procedure
(directional-light3d direction
[ #:id id
#:intensity intensity
#:color color
#:shadow shadow])
→ directional-light3d?
  direction : vec3?
  id : symbol? = 'key
  intensity : nonnegative-real? = 1
  color : color-spec? = "white"
  shadow : (or/c #f directional-shadow3d?) = #f

Creates a directional light whose colour must resolve to opaque under the frame’s theme. Its direction is the direction in which illumination travels, so a normal facing its negation receives diffuse light. The direction is normalized. A directional-shadow3d makes both built-in opaque renderers produce and sample one depth map.

procedure
(point-light3d position
[ #:id id
#:intensity intensity
#:color color
#:attenuation attenuation
#:range range
#:shadow shadow]) → point-light3d?
  position : vec3?
  id : symbol? = 'point
  intensity : nonnegative-real? = 1
  color : color-spec? = "white"
   attenuation : light-attenuation3d?
= (inverse-square-attenuation3d)
  range : (or/c #f positive-real?) = #f
  shadow : #f = #f

Creates a finite-position light value.

procedure
(spot-light3d position
direction
[ #:id id
#:intensity intensity
#:color color
#:inner-angle inner-angle
#:outer-angle outer-angle
#:attenuation attenuation
#:range range
#:shadow shadow]) → spot-light3d?
  position : vec3?
  direction : vec3?
  id : symbol? = 'spot
  intensity : nonnegative-real? = 1
  color : color-spec? = "white"
  inner-angle : nonnegative-real? = 0
  outer-angle : positive-real? = (math "pi/4")
   attenuation : light-attenuation3d?
= (inverse-square-attenuation3d)
  range : (or/c #f positive-real?) = #f
  shadow : (or/c #f spot-shadow3d?) = #f

Creates a finite-position cone light. Its normalized direction points outward; inside inner-angle illumination is full, outside outer-angle it is zero, and the interval between uses the fixed smoothstep falloff. Angles are radians. A spot-shadow3d is sampled by both built-in opaque renderers. Point-light cube shadows are not supported, so a point light accepts only #f.

procedure
(ambient-light3d? value) → boolean?
value : any/c

Recognizes ambient light.

procedure
(ambient-light3d-id light) → symbol?
light : ambient-light3d?

Returns its stable ID.

procedure
(ambient-light3d-intensity light) → nonnegative-real?
light : ambient-light3d?

Returns ambient intensity.

procedure
(ambient-light3d-color light) → color-spec?
light : ambient-light3d?

Returns the retained ambient colour specification.

procedure
(ambient-light3d-shadow light) → #f
light : ambient-light3d?

Returns reserved shadow policy.

procedure
(directional-light3d? value) → boolean?
value : any/c

Recognizes directional light.

procedure
(directional-light3d-id light) → symbol?
light : directional-light3d?

Returns its stable ID.

procedure
(directional-light3d-direction light) → vec3?
light : directional-light3d?

Returns normalized travel direction.

procedure
(directional-light3d-intensity light) → nonnegative-real?
light : directional-light3d?

Returns directional intensity.

procedure
(directional-light3d-color light) → color-spec?
light : directional-light3d?

Returns the retained directional colour specification.

procedure
(directional-light3d-shadow light)
→ (or/c #f directional-shadow3d?)
light : directional-light3d?

Returns attached shadow intent.

procedure
(point-light3d? value) → boolean?
value : any/c

Recognizes a point light.

procedure
(point-light3d-id light) → symbol?
light : point-light3d?

Returns its stable ID.

procedure
(point-light3d-position light) → vec3?
light : point-light3d?

Returns position.

procedure
(point-light3d-intensity light) → nonnegative-real?
light : point-light3d?

Returns intensity.

procedure
(point-light3d-color light) → color-spec?
light : point-light3d?

Returns the retained colour specification.

procedure
(point-light3d-attenuation light) → light-attenuation3d?
light : point-light3d?

Returns attenuation policy.

procedure
(point-light3d-range light) → (or/c #f positive-real?)
light : point-light3d?

Returns optional cutoff range.

procedure
(point-light3d-shadow light) → #f
light : point-light3d?

Returns reserved shadow policy.

procedure
(spot-light3d? value) → boolean?
value : any/c

Recognizes a spot light.

procedure
(spot-light3d-id light) → symbol?
light : spot-light3d?

Returns its stable ID.

procedure
(spot-light3d-position light) → vec3?
light : spot-light3d?

Returns position.

procedure
(spot-light3d-direction light) → vec3?
light : spot-light3d?

Returns normalized outward direction.

procedure
(spot-light3d-intensity light) → nonnegative-real?
light : spot-light3d?

Returns intensity.

procedure
(spot-light3d-color light) → color-spec?
light : spot-light3d?

Returns the retained colour specification.

procedure
(spot-light3d-inner-angle light) → nonnegative-real?
light : spot-light3d?

Returns full-cone angle in radians.

procedure
(spot-light3d-outer-angle light) → positive-real?
light : spot-light3d?

Returns cutoff-cone angle in radians.

procedure
(spot-light3d-attenuation light) → light-attenuation3d?
light : spot-light3d?

Returns attenuation policy.

procedure
(spot-light3d-range light) → (or/c #f positive-real?)
light : spot-light3d?

Returns optional cutoff range.

procedure
(spot-light3d-shadow light) → (or/c #f spot-shadow3d?)
light : spot-light3d?

Returns attached shadow intent.

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

Recognizes any authored light.

procedure
(light3d-id light) → symbol?
light : light3d?

Returns its stable ID.

procedure
(light3d-kind light)
→ (or/c 'ambient 'directional 'point 'spot)
light : light3d?

Returns its kind.

procedure
(light3d-color light) → color-spec?
light : light3d?

Returns the retained light colour specification, which must resolve to opaque for rendering.

procedure
(light3d-intensity light) → nonnegative-real?
light : light3d?

Returns intensity.

procedure
(light3d-shadow light) → (or/c #f shadow3d?)
light : light3d?

Returns attached shadow intent, if any.

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