87 3D: Materials and lights

9.3

Racket

87 3D: Materials and lights🔗ℹ

procedure
(material3d [ #:color color
#:shading shading
#:lighting lighting
#:ambient ambient
#:diffuse diffuse
#:specular specular
#:specular-color specular-color
#:roughness roughness
#:emission emission
#:emission-strength emission-strength
#:double-sided? double-sided?
#:casts-shadow? casts-shadow?
#:receives-shadow? receives-shadow?
#:wireframe? wireframe?])
→ material3d?
  color : color-spec? = "cornflowerblue"
  shading : (or/c 'unlit 'flat 'smooth) = 'flat
  lighting : (or/c 'lambert 'blinn-phong) = 'lambert
  ambient : nonnegative-real? = 1
  diffuse : nonnegative-real? = 1
  specular : nonnegative-real? = 0
  specular-color : color-spec? = "white"
  roughness : (and/c positive-real? (<=/c 1)) = 1
  emission : color-spec? = "black"
  emission-strength : nonnegative-real? = 0
  double-sided? : boolean? = #f
  casts-shadow? : boolean? = #t
  receives-shadow? : boolean? = #t
  wireframe? : boolean? = #f

Constructs an immutable surface material. Its three colour fields retain color-spec? values, including theme roles and expressions; all are resolved once from the frame’s selected theme before either built-in renderer classifies opacity or shades fragments. 'unlit uses its base colour and then adds emission * emission-strength, without consulting lights. 'flat evaluates one face normal using ambient and directional lights; 'smooth interpolates supplied vertex normals. 'lambert uses ambient plus diffuse illumination. 'blinn-phong additionally adds a directional-light highlight, scaled by specular and specular-color. The colour may include alpha; the renderer’s explicit transparent pass controls its compositing policy.

The OpenGL preparation resolves the complete ordered light list once under the same request-owned color context. Uniform packing and shadow-light selection consume those numerical RGBA values; authored light values remain unchanged for inspection. A resolved translucent light is rejected before a GPU draw.

For Blinn–Phong the roughness r maps identically in the reference and OpenGL renderers to

n = max(1,2/r^2 - 2)

. roughness must be finite in (0,1]; ambient, diffuse, specular, and emission-strength must be finite and nonnegative. Coefficients larger than one are intentionally accepted for illustrative effects; the current renderers retain their linear energy through composition and apply the owning viewport’s final tone-map policy only when storing output pixels.

emission is added after ambient, diffuse, and specular terms and is therefore not reduced by shadows. casts-shadow? and receives-shadow? are durable material policy. The software and OpenGL renderers include only opaque mesh instances with casts-shadow? in a depth map and apply receiver policy to diffuse and specular illumination. Transparent surfaces, strokes, markers, and billboards do not cast shadows or receive a shadow-map lookup. OpenGL shadow reuse is keyed by the prepared eligible-caster set, so a themed vertex-alpha change that adds or removes a caster refreshes the depth map while an RGB-only change may reuse it.

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

Recognizes a material.

procedure
(material3d-color material) → color-spec?
material : material3d?

Returns the retained base colour specification.

procedure
(material3d-shading material) → (or/c 'unlit 'flat 'smooth)
material : material3d?

Returns its active shading mode.

procedure
(material3d-lighting material) → (or/c 'lambert 'blinn-phong)
material : material3d?

Returns its lighting model.

procedure
(material3d-ambient material) → nonnegative-real?
material : material3d?

Returns ambient coefficient.

procedure
(material3d-diffuse material) → nonnegative-real?
material : material3d?

Returns diffuse coefficient.

procedure
(material3d-specular material) → nonnegative-real?
material : material3d?

Returns specular coefficient.

procedure
(material3d-specular-color material) → color-spec?
material : material3d?

Returns the retained highlight colour specification.

procedure
(material3d-roughness material)
→ (and/c positive-real? (<=/c 1))
material : material3d?

Returns roughness.

procedure
(material3d-specular-exponent material) → positive-real?
material : material3d?

Returns the derived max(1,2/r2-2) Blinn–Phong exponent shown by the spatial inspector.

procedure
(material3d-emission material) → color-spec?
material : material3d?

Returns the retained additive emission colour specification.

procedure
(material3d-emission-strength material) → nonnegative-real?
material : material3d?

Returns emission strength.

procedure
(material3d-double-sided? material) → boolean?
material : material3d?

Reports whether back-face culling is disabled for this mesh.

procedure
(material3d-casts-shadow? material) → boolean?
material : material3d?

Returns shadow-caster policy. Only opaque mesh instances with true policy enter a software depth map.

procedure
(material3d-receives-shadow? material) → boolean?
material : material3d?

Returns whether an opaque mesh receiver applies the software shadow factor.

procedure
(material3d-wireframe? material) → boolean?
material : material3d?

Returns retained wireframe intent.

procedure
(material3d-with-color material color) → material3d?
material : material3d?
color : color-spec?

Returns material with only its base colour replaced.

procedure
(material3d-with-roughness material
roughness) → material3d?
material : material3d?
roughness : (and/c positive-real? (<=/c 1))

Returns material with only its roughness replaced.

procedure
(material3d-with-emission material
emission
[ #:strength strength]) → material3d?
  material : material3d?
  emission : color-spec?
   strength : nonnegative-real?
= (material3d-emission-strength material)

Returns material with emission fields replaced.

procedure
(material3d-with-shadow-policy
material
[ #:casts-shadow? casts-shadow?
#:receives-shadow? receives-shadow?])
→ material3d?
  material : material3d?
  casts-shadow? : boolean? = (material3d-casts-shadow? material)
   receives-shadow? : boolean?
= (material3d-receives-shadow? material)

Returns material with its shadow policy replaced.

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