89 3D: Shadow descriptors and stable bounds

9.3

Racket

89 3D: Shadow descriptors and stable bounds🔗ℹ

procedure
(shadow-bias3d [ #:world-normal-offset world-normal-offset
#:slope-scale slope-scale
#:constant-depth-offset constant-depth-offset
#:pcf-radius-texels pcf-radius-texels])
→ shadow-bias3d?
  world-normal-offset : nonnegative-real? = 0
  slope-scale : nonnegative-real? = 0
  constant-depth-offset : nonnegative-real? = 0
  pcf-radius-texels : exact-nonnegative-integer? = 1

Creates renderer-neutral shadow bias. The three distances are world-space distances: world-normal-offset moves a receiver along its normal, slope-scale is multiplied by the derived world length of one shadow texel and the grazing-angle factor, and constant-depth-offset moves it toward the light. The PCF radius is a texel count. Both the software and OpenGL renderers project this same adjusted receiver position before comparing the shadow map.

procedure
(shadow-bias3d? value) → boolean?
value : any/c

Recognizes semantic shadow bias.

procedure
(shadow-bias3d-world-normal-offset bias) → nonnegative-real?
bias : shadow-bias3d?

Returns the world-normal offset.

procedure
(shadow-bias3d-slope-scale bias) → nonnegative-real?
bias : shadow-bias3d?

Returns the dimensionless grazing-angle scale.

procedure
(shadow-bias3d-constant-depth-offset bias) → nonnegative-real?
bias : shadow-bias3d?

Returns the world-space offset toward the light.

procedure
(shadow-bias3d-pcf-radius-texels bias)
→ exact-nonnegative-integer?
bias : shadow-bias3d?

Returns the PCF radius in texels.

procedure
(shadow-settings3d [ #:map-size map-size
#:bias bias
#:depth-bias depth-bias
#:normal-bias normal-bias
#:pcf-radius pcf-radius
#:bounds bounds
#:near near
#:far far
#:prepared-bounds-key prepared-bounds-key])
→ shadow-settings3d?
  map-size : exact-positive-integer? = 1024
  bias : (or/c #f shadow-bias3d?) = #f
  depth-bias : (or/c #f nonnegative-real?) = #f
  normal-bias : (or/c #f nonnegative-real?) = #f
  pcf-radius : (or/c #f exact-nonnegative-integer?) = #f
  bounds : (or/c #f aabb3?) = #f
  near : (or/c #f positive-real?) = #f
  far : (or/c #f positive-real?) = #f
  prepared-bounds-key : (or/c #f symbol?) = #f

Creates immutable shadow-map settings. An explicit bounds is a nonempty world-space shadow region. Without it, both renderers fit the current opaque caster bounds; this direct-frame fit can shimmer as casters move. prepared-bounds-key is retained for stable retained-renderer map identity and enables directional texel-centre snapping when named. New code should pass #:bias and a shadow-bias3d value. The depth/normal/PCF keywords are retained only for image-compatible legacy scenes and cannot be combined with #:bias; their normalized depth units remain backend-specific.

procedure
(shadow-settings3d? value) → boolean?
value : any/c

Recognizes shadow settings.

procedure
(shadow-settings3d-map-size settings) → exact-positive-integer?
settings : shadow-settings3d?

Returns map size.

procedure
(shadow-settings3d-bias settings) → (or/c #f shadow-bias3d?)
settings : shadow-settings3d?

Returns the semantic bias, or #f for a legacy descriptor.

procedure
(shadow-settings3d-depth-bias settings) → nonnegative-real?
settings : shadow-settings3d?

Returns the legacy constant receiver-depth bias. New code should use shadow-settings3d-bias.

procedure
(shadow-settings3d-normal-bias settings) → nonnegative-real?
settings : shadow-settings3d?

Returns the legacy slope-dependent receiver bias. New code should use shadow-settings3d-bias.

procedure
(shadow-settings3d-pcf-radius settings)
→ exact-nonnegative-integer?
settings : shadow-settings3d?

Returns the legacy square PCF radius. New code should use shadow-settings3d-bias.

procedure
(shadow-settings3d-bounds settings) → (or/c #f aabb3?)
settings : shadow-settings3d?

Returns explicit world-space shadow-region bounds, if any.

procedure
(shadow-settings3d-near settings) → (or/c #f positive-real?)
settings : shadow-settings3d?

Returns optional light near plane.

procedure
(shadow-settings3d-far settings) → (or/c #f positive-real?)
settings : shadow-settings3d?

Returns optional light far plane.

procedure
(shadow-settings3d-prepared-bounds-key settings)
→ (or/c #f symbol?)
settings : shadow-settings3d?

Returns the optional prepared-bound name.

procedure
(directional-shadow3d [#:settings settings])
→ directional-shadow3d?
settings : shadow-settings3d? = (shadow-settings3d)

Attaches the settings to a directional light.

procedure
(spot-shadow3d [#:settings settings]) → spot-shadow3d?
settings : shadow-settings3d? = (shadow-settings3d)

Attaches the settings to a spot light.

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

Recognizes a directional shadow descriptor.

procedure
(directional-shadow3d-settings shadow) → shadow-settings3d?
shadow : directional-shadow3d?

Returns directional settings.

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

Recognizes a spot shadow descriptor.

procedure
(spot-shadow3d-settings shadow) → shadow-settings3d?
shadow : spot-shadow3d?

Returns spot settings.

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

Recognizes either supported shadow descriptor.

procedure
(shadow3d-kind shadow) → (or/c 'directional 'spot)
shadow : shadow3d?

Returns descriptor kind.

procedure
(shadow3d-settings shadow) → shadow-settings3d?
shadow : shadow3d?

Returns its immutable settings.

struct
(struct prepared-shadow-bounds3d ( light-id
frame-range
bounds
light-space-bounds
diagnostics)
    #:transparent)
  light-id : symbol?
  frame-range : pair?
  bounds : aabb3?
  light-space-bounds : aabb3?
  diagnostics : immutable-hash?

A validated stable union of opaque caster bounds for one directional or spot shadow light.

procedure
(prepare-shadow-bounds3d views
#:light-id light-id
[ #:frame-range frame-range])
→ prepared-shadow-bounds3d?
  views : (or/c view3d? (nonempty-listof view3d?))
  light-id : symbol?
  frame-range : pair? = #f

Prepares one sampled view or an ordered list of project-frame view samples. The inclusive frame range must match the sample count. The light’s pose and descriptor must stay fixed across samples; prepare separate ranges for animated shadow-light poses.

procedure
(prepared-shadow-bounds3d-key prepared) → vector?
prepared : prepared-shadow-bounds3d?

Returns its immutable identity key.

procedure
(shadow-map3d-identity view
light-id
prepared) → vector?
  view : view3d?
  light-id : symbol?
  prepared : prepared-shadow-bounds3d?

Returns the depth-map cache key. It includes caster geometry, transforms, caster policy, light pose/settings, and prepared bounds, but deliberately excludes the viewing camera.

struct
(struct shadow-map3d ( width
height
depth
camera
settings
bounds
diagnostics)
    #:transparent)
  width : exact-positive-integer?
  height : exact-positive-integer?
  depth : immutable-vector?
  camera : camera3d?
  settings : shadow-settings3d?
  bounds : aabb3?
  diagnostics : immutable-hash?

An immutable, software-prepared depth map. Its depth vector stores positive light-camera depth in top-left pixel order. The reference backend owns map construction; the value is exposed for inspection and deterministic sampling.

procedure
(shadow-map3d-factor map
world-position
world-normal
light-direction) → real?
  map : shadow-map3d?
  world-position : vec3?
  world-normal : vec3?
  light-direction : vec3?

Returns the fraction of a square PCF kernel which is lit. It projects the semantic shadow-bias3d receiver offset when present; legacy descriptors use their historical depth-bias + normal-bias* (1-max (0 ,n·l)) comparison. Samples outside the fitted map are lit.

procedure
(shadow-light-camera3d light
settings
bounds) → camera3d?
  light : (or/c directional-light3d? spot-light3d?)
  settings : shadow-settings3d?
  bounds : aabb3?

Fits the deterministic light camera used by the reference map. Directional maps use a square orthographic fit and named prepared bounds snap their centre to map texels; spots use the source, outward cone, and near/far/range policy.

Current limitation. The software and OpenGL renderers create one directional or spot depth map per descriptor and multiply only diffuse and specular terms by its PCF result. Ambient and emission remain unchanged. Only opaque mesh instances cast or receive; transparent surfaces, strokes, markers, billboards, and point-light cube shadows are not supported. Direct-frame fitting can shimmer, and a too-small explicit region yields unshadowed outside samples. The OpenGL backend caches context-owned GPU maps by eligible casters, light pose/settings, and bounds, deliberately excluding viewing-camera motion. Semantic shadow-bias3d values avoid backend-specific depth tuning by moving the receiver in world space before each renderer projects it. The legacy depth/normal fields retain their original backend-specific behavior for image compatibility.

struct
(struct light-attenuation3d (mode parameters)
    #:transparent)
  mode : (or/c 'constant 'inverse-square 'polynomial)
  parameters : immutable-hash?

An immutable, inspectable finite-light attenuation policy. The parameter hash uses the named schema selected by mode.

procedure
(constant-attenuation3d [#:factor factor]) → light-attenuation3d?
factor : nonnegative-real? = 1

Creates a distance-independent multiplier.

procedure
(inverse-square-attenuation3d
[ #:reference-distance reference-distance
#:cutoff cutoff])
→ light-attenuation3d?
reference-distance : positive-real? = 1
cutoff : (or/c #f positive-real?) = #f

Creates the finite rule (r / max(d,r))2, optionally zeroing beyond cutoff. The named reference distance explicitly clamps the otherwise singular origin.

procedure
(polynomial-attenuation3d [ #:constant constant
#:linear linear
#:quadratic quadratic
#:cutoff cutoff])
→ light-attenuation3d?
  constant : nonnegative-real? = 1
  linear : nonnegative-real? = 0
  quadratic : nonnegative-real? = 0
  cutoff : (or/c #f positive-real?) = #f

Creates 1/(c + ld + qd2). At least one coefficient must be positive.

procedure
(light-attenuation3d-factor attenuation
distance) → nonnegative-real?
attenuation : light-attenuation3d?
distance : nonnegative-real?

Evaluates the named attenuation policy.

procedure
(spot-smoothstep3d progress) → (and/c real? (between/c 0 1))
progress : finite-real?

Returns the clamped cubic t2(3-2t) used for spotlight falloff.

procedure
(spot-cone-factor3d inner-angle
outer-angle
angle)
→ (and/c real? (between/c 0 1))
  inner-angle : nonnegative-real?
  outer-angle : positive-real?
  angle : nonnegative-real?

Evaluates the fixed spot cone rule.

Point and spot lights are evaluated by both the deterministic software reference renderer and the optional OpenGL backend. They use the same named constant, inverse-square, and polynomial attenuation policies, optional range, and smoothstep spot-cone rule. OpenGL packs the authored non-ambient light sequence into fixed uniform records, so it retains the frame’s light order rather than approximating finite sources as directional lights.

Current limitation. The OpenGL implementation has explicit fixed limits of four directional, eight point, and four spot lights per lit view. It rejects an over-limit frame before drawing. Directional and spot shadow maps are supported, but point-light cube shadows are not supported.

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