@photivra/engine 2.6.0 → 2.8.0

package/docs/api/facade-scene-radiance.md

@@ -2,6 +2,31 @@
 
 The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
+## CALLER_MATERIAL_SCENE_MAX_MATERIALS
+
+Most materials a {@link CallerMaterialScene} may list.
+
+```ts
+CALLER_MATERIAL_SCENE_MAX_MATERIALS = 65_536
+```
+
+## CallerMaterialScene
+
+2.7 (#386): a piecewise-constant caller scene, lit by the facade illuminant like a reflectance function. `materials` are
+reflectances as a chart's patches take them (a neutral number in [0, 1] or a reflectance spectrum covering 380–780 nm, at
+most {@link CALLER_MATERIAL_SCENE_MAX_MATERIALS}); `materialAt` returns the index of the material at a plane point (an
+integer from 0 to materials.length − 1). The radiance at a point is that material's, exactly as for a reflectance function
+returning its reflectance, but renderers can tabulate each material once: the display view then takes the chart path.
+
+```ts
+export interface CallerMaterialScene {
+  kind: "material-function";
+  sceneId: string;
+  materials: readonly ChartReflectance[];
+  materialAt(point: Readonly<SceneMaterialPoint>): number;
+}
+```
+
 ## CallerRadianceScene
 
 Caller absolute spectral radiance in W·m⁻²·sr⁻¹·nm⁻¹; the facade illuminant is not used.
@@ -65,7 +90,7 @@ provider `providerProfileId`.
 
 ```ts
 export function createPlanarSceneRadianceProvider(input: {
-  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
   illuminant: CaptureIlluminant;
   illuminanceLux: number;
   distanceM: number;
@@ -140,6 +165,14 @@ export interface ResolvedCaptureIlluminant {
 }
 ```
 
+## SceneMaterialPoint
+
+2.7: a scene-plane point without a wavelength, passed to a material scene's `materialAt`.
+
+```ts
+export type SceneMaterialPoint = Omit<ScenePlanePoint, "wavelengthNanometers">;
+```
+
 ## ScenePlanePoint
 
 A point of the scene plane passed to caller scene functions.

package/docs/api/facade-simulate-capture.md

@@ -264,7 +264,7 @@ export interface SimulateCaptureOptions {
     compensationStops?: number;
   };
   /** Required: an engine chart (for example `{ preset: "uniform" }`, an 18 % grey card) or a caller reflectance/radiance function. */
-  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene;
+  scene: ChartScene | CallerReflectanceScene | CallerRadianceScene | CallerMaterialScene;
   /** Distance from the camera to the scene plane in metres. Default 5. */
   subjectDistanceM?: number;
   /**

package/docs/api/facade-simulate-display-view.md

@@ -2,6 +2,45 @@
 
 The package and root API versions are recorded once in [Navigation](../API_REFERENCE.md) · [Developer guide](https://github.com/Photivra/photivra/blob/main/docs/DEVELOPERS.md). Generated signatures retain independent schema/model versions. Only the exports listed here are root-package contracts; module-local helpers are not supported deep imports.
 
+## PreparedDisplayView
+
+2.7: a display-view request resolved once (`prepareDisplayView`). `render(view)` gives the same result as
+`simulateDisplayView(options, view)` for the prepared options, byte for byte (samples, view, exposure, scene, diagnostics
+and assumptions; only `diagnostics.timingsMs` differ, and they cover the render only), without repeating the request's
+setup: use it to render one view in many regions, for example on each worker of a progressive display.
+
+```ts
+export interface PreparedDisplayView {
+  /** Renders a view of the prepared request. Renders may run concurrently; they share no state except read-only setup. */
+  render(view: SimulateDisplayViewOptions, renderOptions?: PreparedDisplayViewRenderOptions): Promise<DisplayViewResult>;
+}
+```
+
+## PreparedDisplayViewRenderOptions
+
+Options of one {@link PreparedDisplayView} render.
+
+```ts
+export interface PreparedDisplayViewRenderOptions {
+  /** Aborting cancels this render only; the promise rejects with a domain error. The request's own `signal` applies to preparing only. */
+  signal?: AbortSignal;
+}
+```
+
+## prepareDisplayView
+
+2.7 (#387): resolves a {@link simulateDisplayView} request once, without a view, and returns a handle whose `render(view)`
+renders its views. The setup it does once (request validation, the camera, lens, scene, chart and illuminant, the channel
+responses through the environment chain, the diffraction kernels, readout moments, demosaic tables and colour matrix) costs
+about 0.3–1.3 s per call on a 24 MP request; a region costs only its own pixels. Errors in the request are raised here;
+errors in the view by `render`.
+
+```ts
+export async function prepareDisplayView(options: SimulateCaptureOptions): Promise<PreparedDisplayView>;
+```
+
+This call is asynchronous; byte hashing uses the caller runtime's Web Crypto.
+
 ## simulateDisplayView
 
 The display view of a capture request: the image the real full-resolution capture (`simulateCapture(options)`) would

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photivra/engine",
-  "version": "2.6.0",
+  "version": "2.8.0",
   "private": false,
   "description": "Scientific TypeScript engine for camera optics, exposure, focus, motion, sensor sampling, diffraction, and digital imaging calculations.",
   "type": "module",