From: Svjatoslav Agejenko Date: Sun, 27 Sep 2026 19:02:50 +0000 (+0300) Subject: feat: phased progressive GI scheduling and Wavefront OBJ loading X-Git-Url: http://www2.svjatoslav.eu/gitweb/?a=commitdiff_plain;h=9ca140487324ef91a0bf02bb64ea2e40f4195ab5;p=aukio-3d.git feat: phased progressive GI scheduling and Wavefront OBJ loading Replace the flat round-robin GI scheduler with a three-phase progressive pipeline ordered near-to-far from the camera: phase A stamps ambient + direct light at polygon centroids so the scene lights up as a visible wave; phase B converges multi-bounce indirect light at centroids scene-wide; phase C refines lightmaps per texel. Phases B and C run on a bounded 256-entry active window that graduates calm entries, re-sorting pending work when the camera moves more than 25 world units. Graduated lightmaps keep recompositing through a display-freeze tail so no centroid-stamp bias survives as visible seams. The legacy scheduler stays available via -De3d.gi.phases=false. ViewPanel now feeds the camera position into the GI system, and a torn-read guard prevents converging partial snapshots. Add a Wavefront OBJ loader (ObjLoader/ObjModel/ObjMaterial): vertices, faces in all index forms including negative and forward references, usemtl/mtllib resolution, and MTL Kd diffuse color with d/Tr opacity. Faces become SolidPolygons inside an ObjModel composite, so shading, culling and transforms work as for any composite. Extend Transform with a uniform scale applied before rotation (negative values mirror geometry and flip winding; zero and non-finite values are rejected). TransformStack bakes the scale into the composed matrix at push time, so per-vertex render cost is unchanged and unscaled scenes render bit-identically. Light two-sided polygons per side: SolidPolygon computes a reverse-side shaded color from the negated normal, and LightmappedCompositeShape emits a reversed solid back triangle for unculled polygons so undersides no longer show the front side's light. Add udev rules for RayNeo XR glasses and the 3Dconnexion SpaceNavigator, tests for transform scaling and OBJ loading, and documentation pages for octree ray tracing, GUI components, SpaceMouse input, configuration and subpixel culling. --- diff --git a/AGENTS.org b/AGENTS.org index 675193a..cd5e17b 100644 --- a/AGENTS.org +++ b/AGENTS.org @@ -559,19 +559,24 @@ rebuild the exact demo scene headlessly. :ID: 1d942e3b-6071-440f-bd9b-876c8f7c53de :END: -| Path | Topic | -|----------------------------------------------+---------------------------------------------------------------------| -| ~Documentation/index.org~ | Main: coordinate system, shapes, CSG, developer tools | -| ~Documentation/Rendering loop/index.org~ | 5-phase pipeline, multi-threaded paint | -| ~Documentation/Shading/index.org~ | Lambert shading, lights, distance attenuation | -| ~Documentation/CSG/index.org~ | Boolean ops via BSP trees | -| ~Documentation/Frustum culling/index.org~ | View frustum culling | -| ~Documentation/Near plane clip/index.org~ | Near-plane polygon clipping (straddling geometry) | -| ~Documentation/Global illumination/index.org~ | Progressive GI: lightmaps, bounces, convergence | -| ~Documentation/Perspective correct textures/index.org~ | Texture mapping math | -| ~Documentation/Stereoscopic rendering/index.org~ | Side-by-side stereo: two passes, per-eye viewports, IPD | -| ~Documentation/Depth buffer/index.org~ | Two-pass z-buffer, zw, depth margin, Hi-Z pyramid, determinism | -| ~Documentation/SDF textures/index.org~ | SDF text: glyph fields, coverage window, TextCanvas | +| Path | Topic | +|--------------------------------------------------------+---------------------------------------------------------------------------| +| ~Documentation/index.org~ | Main: coordinate system, shapes, CSG, developer tools | +| ~Documentation/Rendering loop/index.org~ | 5-phase pipeline, multi-threaded paint | +| ~Documentation/Shading/index.org~ | Lambert shading, lights, distance attenuation | +| ~Documentation/CSG/index.org~ | Boolean ops via BSP trees | +| ~Documentation/Frustum culling/index.org~ | View frustum culling | +| ~Documentation/Near plane clip/index.org~ | Near-plane polygon clipping (straddling geometry) | +| ~Documentation/Global illumination/index.org~ | Progressive GI: lightmaps, bounces, convergence | +| ~Documentation/Perspective correct textures/index.org~ | Texture mapping math | +| ~Documentation/Stereoscopic rendering/index.org~ | Side-by-side stereo: two passes, IPD, XR glasses head tracking | +| ~Documentation/SpaceMouse 6DOF/index.org~ | 3Dconnexion SpaceNavigator: 6DOF cap camera drive, hot-plug | +| ~Documentation/Depth buffer/index.org~ | Two-pass z-buffer, zw, depth margin, Hi-Z pyramid, determinism | +| ~Documentation/SDF textures/index.org~ | SDF text: glyph fields, coverage window, TextCanvas | +| ~Documentation/Octree ray tracing/index.org~ | Voxel octree (flat cell pool) + per-pixel ray tracer with shadows | +| ~Documentation/Configuration/index.org~ | Shared ~/.config/aukio/config.yaml: e3d keys, -D overrides, atomic writes | +| ~Documentation/GUI components/index.org~ | Interactive 3D widgets: focus, mouse picking, texture-UV clicks | +| ~Documentation/Subpixel culling/index.org~ | Drop sub-pixel shapes in transform; cached verdict epoch | Regenerate all HTML: ~Documentation/export-docs.sh~ (add ~--check~ for rendered screenshots of every page). diff --git a/Documentation/Configuration/Atomic write.svg b/Documentation/Configuration/Atomic write.svg new file mode 100644 index 0000000..123c7d0 --- /dev/null +++ b/Documentation/Configuration/Atomic write.svg @@ -0,0 +1,57 @@ + + + + + + + + + + + + + + + + + Writes: lock, re-read, merge, atomic rename + + + + setString + (app or UI) + + + same-JVM + writeMonitor + + + sidecar lock + <file>.lock + + + fresh re-read + under the lock + + + merge key + into YAML + + + tmp + atomic + rename + + + + + + + + + the FileLock serializes cooperating JVMs; the same-JVM monitor serializes threads + a hand edit made between the writer's read and write survives the merge + unknown keys and other sections are preserved verbatim + + caveat: SnakeYAML rewrites the file on the first set - human-written header comments are lost + caveat: an editor saving a stale buffer over newer YAML still clobbers app writes + diff --git a/Documentation/Configuration/Config precedence.svg b/Documentation/Configuration/Config precedence.svg new file mode 100644 index 0000000..f3343b5 --- /dev/null +++ b/Documentation/Configuration/Config precedence.svg @@ -0,0 +1,36 @@ + + + + + + + + + + + + + + + + + Three layers; the topmost one that has the key wins + + + + key missing + -> fall through + + + + system property: -De3d.ipd=6.3 ← WINS + + + config file: ~/.config/aukio/config.yaml (e3d: section) + + + built-in defaults (in code) + + a missing key - or a missing file - falls through to the layer below + file location override: -Daukio.config=/path/to.yaml (legacy fallback: -De3d.config=) + diff --git a/Documentation/Configuration/index.org b/Documentation/Configuration/index.org new file mode 100644 index 0000000..61c9039 --- /dev/null +++ b/Documentation/Configuration/index.org @@ -0,0 +1,137 @@ +:PROPERTIES: +:CUSTOM_ID: configuration +:END: +#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +#+TITLE: Configuration - Aukio 3D +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \setlength{\parindent}{15pt} +#+LATEX_HEADER: \usepackage{palatino} +#+LATEX_HEADER: \usepackage{charter} +#+HTML_HEAD: + +[[file:../index.html#outline-container-configuration][<- Back to index]] + +* One YAML file for the whole family +:PROPERTIES: +:CUSTOM_ID: one-file +:END: + +All Aukio programs — the engine, the workspace application, and +environment plugins — share a single configuration file: + +#+BEGIN_SRC text +~/.config/aukio/config.yaml +#+END_SRC + +A missing file is not an error: every setting falls back to its +built-in default. Override the location with +=-Daukio.config=/path/to.yaml= (the legacy =-De3d.config== is honored +as a fallback for engine-only tooling). + +The file is divided into *sections*, one per tenant, with flat +camelCase keys inside each: + +#+BEGIN_SRC yaml +e3d: # the engine (this page) + ipdCm: 6.3 + telemetryIntervalSeconds: 10 +fo4: # the Fallout 4 environment plugin + path: /home/you/games/Fallout 4 +app: # the workspace application + state: ... # written by the app at runtime +#+END_SRC + +Keys a consumer does not recognize are preserved verbatim through +writes, so sections can evolve independently. + +* Engine keys +:PROPERTIES: +:CUSTOM_ID: engine-keys +:END: + +The engine reads its settings through =EngineConfig=, a thin facade +over the shared file. Every key can *also* be set as a system +property, and the property always wins: + +| Config key (=e3d= section) | System property | Default | Controls | +|-------------------------------+----------------------------+----------------------------------+----------| +| =ipdCm= | =-De3d.ipd= | 6.5 | interpupillary distance for [[file:Stereoscopic rendering/][stereo rendering]] | +| =bugReportDir= | =-De3d.bugreport.dir= | =~/.local/share/aukio/bugreports= | where bug reports are written | +| =logDir= | =-De3d.log.dir= | =~/.cache/aukio/logs= | persistent rolling log location | +| =telemetryIntervalSeconds= | =-De3d.telemetry.interval= | 5 | seconds between telemetry log lines | + +#+CAPTION: Resolution order for every engine key: the system property wins; otherwise the config file; otherwise the built-in default. +[[file:Config precedence.svg]] + +So a permanent preference goes in the file, a one-off experiment on +the command line: + +#+BEGIN_SRC sh +java -De3d.ipd=6.3 -jar my-app.jar # this run only +#+END_SRC + +* Live reload and safe writes +:PROPERTIES: +:CUSTOM_ID: live-reload +:END: + +*Reads* check the file's (mtime, size, file-key) stamp and re-parse +only when it changed — a hand edit made while an application is +running becomes visible on the next read, with no restart and no +polling cost when nothing changed. + +*Writes* (an application storing a setting at runtime) go through +=AukioConfig.setString= and friends, and are engineered so that +concurrent human edits survive: + +#+CAPTION: The write path. The sidecar lock serializes cooperating processes; the fresh re-read under the lock means a hand edit made between the writer's read and write is merged, not clobbered. +[[file:Atomic write.svg]] + +Two honest limitations: + +- SnakeYAML rewrites the whole file on the first =set=, so + human-written header comments are lost once an application writes. + Keep conventions in documentation, not in the file's comments. +- An editor saving a *stale buffer* over newer YAML is the one race + no file format can solve — your editor's changed-on-disk warning + (Emacs has one) is the only guard. + +Instances are cached per resolved path in a per-JVM registry: +=AukioConfig.get()= returns the same instance to every caller in the +process (engine, app, plugins), so the stamp cache is shared and a +re-parse happens at most once per change per JVM. + +* Writing a consumer +:PROPERTIES: +:CUSTOM_ID: writing-a-consumer +:END: + +#+BEGIN_SRC java +import eu.svjatoslav.aukio.cfg.AukioConfig; + +// read (dotted path, caller-supplied fallback): +double ipd = AukioConfig.get().getDouble("e3d.ipdCm", 6.5); +String dir = AukioConfig.get().getString("e3d.logDir", + "~/.cache/aukio/logs"); + +// write (locks, re-reads, merges, atomic rename): +AukioConfig.get().setString("e3d.ipdCm", "6.3"); +#+END_SRC + +The class is covered by =AukioConfigTest= (9 tests) in the engine +repository, including the concurrent-write and unknown-key +preservation behavior. + +* Related classes +:PROPERTIES: +:CUSTOM_ID: related-classes +:END: + +| Class | Role | +|----------------+-------------------------------------------------------------| +| =AukioConfig= | shared YAML store: stamp-cached reads, locked atomic writes | +| =EngineConfig= | engine facade: the four =e3d= keys + property overrides | + +[[file:../index.html#outline-container-configuration][Back to main documentation]] diff --git a/Documentation/GUI components/Event dispatch.svg b/Documentation/GUI components/Event dispatch.svg new file mode 100644 index 0000000..12e8324 --- /dev/null +++ b/Documentation/GUI components/Event dispatch.svg @@ -0,0 +1,56 @@ + + + + + + + + + + + + + + + + + From AWT event to component callback + + + + + AWT event + press, release, move, wheel + + + InputManager + collects; splits shift+wheel to horizontal + + + paint pass + per-tile hit test, before clipping + + + + + + + + flush + combine: first non-null hit wins + + + RenderingContext + handlePossibleComponentMouseEvent + + + component callback + mouseClicked / hover / wheel + + + + + + stereo: only the eye whose viewport contains the cursor combines hits + enter/exit transitions fire mouseEntered / mouseExited + diff --git a/Documentation/GUI components/Focus model.svg b/Documentation/GUI components/Focus model.svg new file mode 100644 index 0000000..a88af62 --- /dev/null +++ b/Documentation/GUI components/Focus model.svg @@ -0,0 +1,43 @@ + + + + + + + + + + + + + + + + + + + + Focus is single-level + + + + WorldNavigationUserInputTracker + default: WASD + arrows fly the camera + (KeyboardFocusStack's home state) + + + GuiComponent (focused) + keys go to the widget + red wireframe border marks focus + + + push: click + + + pop: ESC / middle click + + + pop always returns to camera navigation - never to a previously focused widget + the class is called KeyboardFocusStack for historical reasons; there is no stack + push notifies the old owner with focusLost() and forgets it + diff --git a/Documentation/GUI components/Texture UV picking.svg b/Documentation/GUI components/Texture UV picking.svg new file mode 100644 index 0000000..45ce55b --- /dev/null +++ b/Documentation/GUI components/Texture UV picking.svg @@ -0,0 +1,49 @@ + + + + + + + + + + + + + + + + + A click lands in texture pixels + + + + + + + + textured panel in 3D + + + + + click (x,y) + + + + perspective-correct + UV interpolation + + + + + + + + + texture bitmap + (u,v) + + u and v arrive in primary-texture pixels, NaN when the hit shape is untextured + the same math drives hover tracking and click forwarding into captured app windows + diff --git a/Documentation/GUI components/index.org b/Documentation/GUI components/index.org new file mode 100644 index 0000000..c99b98c --- /dev/null +++ b/Documentation/GUI components/index.org @@ -0,0 +1,166 @@ +:PROPERTIES: +:CUSTOM_ID: gui-components +:END: +#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +#+TITLE: GUI Components - Aukio 3D +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \setlength{\parindent}{15pt} +#+LATEX_HEADER: \usepackage{palatino} +#+LATEX_HEADER: \usepackage{charter} +#+HTML_HEAD: + +[[file:../index.html#outline-container-gui-components][<- Back to index]] + +* Interactive widgets in 3D space +:PROPERTIES: +:CUSTOM_ID: interactive-widgets +:END: + +=GuiComponent= is the base class for interactive widgets that live +*in the world*, not in a 2D overlay: panels you can click, hover and +type into. It combines a composite shape (so it can hold any visual +content — text canvases, textures, other shapes) with two callback +interfaces: =MouseInteractionController= for the mouse and +=KeyboardInputHandler= for the keyboard. + +Click a component and it takes keyboard focus, marked by a red +wireframe border around it; press *ESC* or *middle-click* it and +focus returns to camera navigation. While a component is focused, +keyboard input goes to it instead of moving the camera. + +#+BEGIN_SRC java +GuiComponent widget = new GuiComponent( + new Transform(new Point3D(0, 0, 300)), // where in the world + viewPanel, + new Point3D(400, 300, 0)); // width, height, depth +widget.addShape(someContent); // any shapes +viewPanel.getRootShapeCollection().addShape(widget); +#+END_SRC + +* Focus is single-level +:PROPERTIES: +:CUSTOM_ID: focus-model +:END: + +=KeyboardFocusStack= owns exactly one focus owner at a time — despite +the name, there is no stack. =pushFocusOwner= replaces the current +owner (notifying the old one with =focusLost= and forgetting it); +=popFocusOwner= — triggered by ESC or a middle click — always falls +back to the default handler, =WorldNavigationUserInputTracker= +(WASD/arrow camera flight). It never restores a previously focused +widget. + +#+CAPTION: The two focus states and the transitions between them. +[[file:Focus model.svg]] + +The default handler is what makes drag-look and wheel-move keep +working even while a panel has focus: those live in the input +manager, not in the focus owner. Only discrete key events and wheel +routing change hands. + +* How events reach a component +:PROPERTIES: +:CUSTOM_ID: event-dispatch +:END: + +Mouse hit detection piggybacks on rendering. During painting, every +tile notes which interactive shape (if any) lies under the cursor — +before its clipping is applied. When the pass is flushed, the first +non-null hit across tiles becomes the view's +=currentObjectUnderMouseCursor=, and +=RenderingContext.handlePossibleComponentMouseEvent= dispatches the +callbacks: =mouseEntered= / =mouseExited= on transitions, +=mouseClicked= on presses, =mouseHover= on moves. + +#+CAPTION: The dispatch path. The hit is found as a side effect of painting, combined at flush time, and delivered to the component. +[[file:Event dispatch.svg]] + +In [[file:Stereoscopic%20rendering/][stereo mode]] the same object +sits at a different screen X per eye, so hits are combined only for +the pass whose viewport actually contains the cursor. + +Clicks carry more than a button number: for textured shapes the +engine computes the *perspective-correct texture coordinates* of the +exact clicked point, in primary-texture pixels (=NaN= for untextured +shapes). That is what lets a component forward input into a captured +application window pixel-accurately — the aukio workspace's Firefox +and terminal panels are built on it. + +#+CAPTION: Screen point to texture pixel. Hover uses the same path. +[[file:Texture UV picking.svg]] + +* The callback surface +:PROPERTIES: +:CUSTOM_ID: callback-surface +:END: + +=MouseInteractionController= (default methods shown delegate to the +simpler overloads, so override only what you need): + +| Callback | When it fires | Notes | +|----------+---------------+-------| +| =mouseClicked(button)= | any click on the component | button: 1 left, 2 middle, 3 right | +| =mouseClicked(button, u, v)= | click on a textured component | =u=, =v= in texture pixels, =NaN= untextured | +| =mouseClicked(button, u, v, focusStack)= | as above, with the view's focus stack | override this one to take focus (see below) | +| =mouseHover(u, v)= | pointer moves over the component | throttled by the caller | +| =mouseWheelMoved(vUnits, hUnits)= | wheel while the component has focus | return =false= to fall through to camera movement | +| =mouseEntered= / =mouseExited= | cursor crosses the component boundary | | + +Every callback returns =true= when the view needs a repaint as a +consequence — the engine skips rendering otherwise. + +Two dispatch rules to know: + +- Components that *take focus on click* should override the 4-arg + =mouseClicked= and use the supplied =KeyboardFocusStack= — never a + stored =ViewPanel= field. Headless scenes (the golden-image + harness) construct components with a null panel, and the field + dereference would NPE inside the render thread. +- The wheel routes to the *focused* component, and =GuiComponent= + consumes it by default, so the camera stays put while you scroll + inside a widget. Horizontal wheel input arrives from AWT as + shift-modified vertical rotation and is split out by the input + manager. + +* A complete example: the text editor +:PROPERTIES: +:CUSTOM_ID: text-editor +:END: + +=textEditorComponent/TextEditComponent= is a full multi-line editor +built on =GuiComponent= — proof the interaction layer carries real +widgets. It renders through a [[file:SDF%20textures/][TextCanvas]] +backed by a =Page= of =TextLine=s, skinnable via =LookAndFeel=, and +supports: + +- cursor navigation (arrows, Home/End, Page Up/Down) and + shift-selection +- clipboard: Ctrl+C / Ctrl+X / Ctrl+V, select-all with Ctrl+A +- word-level movement with Ctrl+Left / Ctrl+Right +- Tab indentation and Shift+Tab dedentation, single line or block +- automatic scrolling when the cursor leaves the visible area + +(Tab reaches the widget at all because =ViewPanel= disables AWT +focus-traversal keys — otherwise the focus subsystem would eat it.) + +The =TextEditorDemo= and =TextEditorDemo2= demos in aukio-3d-demos +show the editor in a scene; both build deterministically for the +golden-image harness. + +* Related classes +:PROPERTIES: +:CUSTOM_ID: related-classes +:END: + +| Class | Role | +|------------------------------+--------------------------------------------------| +| =GuiComponent= | base widget: shape + focus + mouse/keyboard glue | +| =KeyboardFocusStack= | single-level focus owner management | +| =MouseInteractionController= | the mouse callback interface | +| =KeyboardInputHandler= | the keyboard callback interface | +| =InputManager= | AWT collection, wheel routing, extra buttons | +| =TextEditComponent= | full text editor built on =GuiComponent= | + +[[file:../index.html#outline-container-gui-components][Back to main documentation]] diff --git a/Documentation/Global illumination/index.org b/Documentation/Global illumination/index.org index 9568956..5419b80 100644 --- a/Documentation/Global illumination/index.org +++ b/Documentation/Global illumination/index.org @@ -96,15 +96,56 @@ resolution, never from interpolation. (An earlier bilinear-upscaling pass produced visibly artificial results and was removed; finer texels cost more CPU on the GI threads but look right.) +* Phased scheduling: light floods near-to-far +:PROPERTIES: +:CUSTOM_ID: phased-scheduling +:END: + +The scene is lit in three strict global phases, each walking polygons +in order of distance from the camera, nearest first +(=-De3d.gi.phases=true=, default): + +1. *Phase A — centroid direct*: each polygon gets ONE direct-light + evaluation at its centroid (shadow rays to all lamps at once), and + the result is stamped onto the whole polygon in a single step. The + world goes from the uniform medium start to flat per-polygon + lighting as a visible wave sweeping away from the camera — cheap + (one sample point per polygon) and fast even on huge scenes. +2. *Phase B — centroid multi-bounce*: bounce rays from centroids only, + still one sample point per polygon, feeding the indirect field. + Converges scene-wide before any texel work starts, so phase C never + begins in an indirect dark age. +3. *Phase C — per-texel refinement*: lightmapped triangles are refined + near-to-far. A triangle entering this phase has its texels seeded + from its converged centroid values, then sampled per texel (the + two-ray visit described above) until its on-screen estimate stops + moving; it then *graduates* out of the active window — ray sampling + stops — into a *freeze tail* that keeps recompositing the now-fixed + target until the estimate has fully glided in + (=-De3d.gi.freezeThreshold=, default 0.1 light units), and only then + freezes. Without the tail, graduating at the calm threshold would + leave a few light units of the centroid stamp frozen into the + texture, visible as brightness seams between adjacent triangles. + When every lightmap has frozen, the workers idle. + +Phases B and C sample only a bounded *active window* of the nearest +entries (=-De3d.gi.activeWindow=, default 256), so near geometry +converges before CPU is spent on far geometry. If the camera moves +more than =e3d.gi.resortDistance= (default 25 world units), the +not-yet-activated work is re-sorted to the new position — finished +polygons keep their lighting. Plain (non-lightmapped) polygons finish +at phase B; their per-polygon result *is* their final resolution. +=-De3d.gi.phases=false= restores the legacy flat round-robin over all +texels at once. + * One sample: a shadow ray and a bounce ray :PROPERTIES: :CUSTOM_ID: one-sample :END: -The work list is flat: one item per lightmap texel (and one per plain -polygon, see below). Worker threads walk it round-robin, and every -visit to a texel casts exactly two rays from the texel's world -position, nudged slightly off the surface along the normal: +In phase C (or everywhere in legacy mode), every visit to a texel +casts exactly two rays from the texel's world position, nudged +slightly off the surface along the normal: 1. *Shadow ray* toward a lamp. Answers visible/occluded, cached in the texel's visibility bits. On a texel's *first* visit all lamps are @@ -165,12 +206,13 @@ Consequences of the design: light fades out gradually instead of popping — the same pair of EMAs that accumulates light also drains it. - *Convergence detection*: per-sample deltas are pure noise (and with a - constant alpha they never settle), so the system watches the average - per-texel movement of the on-screen estimate; after five composite - updates below =e3d.gi.calmThreshold= (default 1.0 light unit) the - workers drop to a low duty cycle (~50% of sweep time, capped) instead - of burning CPU. Any scene or light change rebuilds the snapshot and - restarts full-speed tracing. + constant alpha they never settle), so the system watches the movement + of the on-screen estimate instead. Phased mode graduates an entry out + of the active window after three consecutive calm judgements + (=-De3d.gi.calmThreshold=, default 1.0 light unit) and idles when the + last one graduates; legacy mode watches the average per-texel + movement and idles after five calm composite updates. Any scene or + light change rebuilds the snapshot and restarts from phase A. - *Despeckle*: at composite time the indirect channel is blended 50/50 with the mean of its valid 4-neighbors, killing single-texel Monte Carlo spikes without blurring real gradients. @@ -196,6 +238,47 @@ interface that =GlobalIllumination= installs into the Both are called from parallel render-pool threads, so they only read volatile caches — never trace. +* Two-sided surfaces +:PROPERTIES: +:CUSTOM_ID: two-sided +:END: + +Polygons rendered with backface culling off are visible from both +sides, and each side must show its own lighting — otherwise the camera +sees the front side's light through the surface (undersides glowing +with the top's light): + +- =SolidPolygon= computes a second shaded color with the negated + normal every frame; the painter picks front or reverse color by the + signed screen area, the same test backface culling uses. +- =LightmappedCompositeShape= wraps a two-sided source into a + lightmapped front triangle /plus/ a plain solid triangle of reversed + winding for the back, and turns culling on for both halves: the + lightmap only knows its front side, so the back side renders with + ordinary one-sided direct lighting. Each side's pixels are owned by + exactly one surface, so nothing z-fights and no holes appear even + when the source model's winding is inconsistent. + +* Coordinate spaces: lights are world, geometry is local +:PROPERTIES: +:CUSTOM_ID: coordinate-spaces +:END: + +Direct lighting (=SolidPolygon=) and GI both read polygon centers, +normals and lightmap coordinates in the shape's LOCAL space, while +=LightSource= positions, markers and GI rays live in WORLD space. For +shapes with identity transforms the two coincide — but a composite +with a non-identity transform (scaled/rotated OBJ model) silently +shifts every effective light position into the wrong place (mirrored, +scaled, offset — the classic symptom is light apparently coming from a +spot where no source exists, e.g. from below the ground). + +Until the engine reconciles the two spaces, demos must BAKE static +model transforms into the vertex coordinates at load time (see +=ObjLoaderDemo.buildScene=) and leave the model transform identity. +Animated transforms above a lightmapped composite were already +unsupported; this is the same rule, one level up. + * Enabling GI :PROPERTIES: :CUSTOM_ID: enabling @@ -221,6 +304,10 @@ Tuning knobs (system properties): | =e3d.gi.initialIrradiance=| 128 | uniform medium start (0..255 light units) | | =e3d.gi.calmThreshold= | 1.0 | convergence: avg estimate movement (light units) | | =e3d.gi.despeckle= | true | neighbor-smoothing of indirect at composite time | +| =e3d.gi.phases= | true | phased near-to-far scheduling; =false= = legacy flat round-robin | +| =e3d.gi.activeWindow= | 256 | phased mode: concurrently sampled entries, nearest first | +| =e3d.gi.resortDistance= | 25 | camera move (world units) that re-sorts pending work | +| =e3d.gi.freezeThreshold= | 0.1 | phase C display-freeze: tail composites stop below this estimate movement | | =e3d.gi.debug= | false | sweep statistics to stdout | | =e3d.gi.dumpLightmaps= | (unset) | dump composite lightmaps as PNGs to the given dir | diff --git a/Documentation/Octree ray tracing/Cell pool.svg b/Documentation/Octree ray tracing/Cell pool.svg new file mode 100644 index 0000000..e8e977a --- /dev/null +++ b/Documentation/Octree ray tracing/Cell pool.svg @@ -0,0 +1,67 @@ + + + + + + + + + + + + + + One cell = eight parallel int arrays + internal cell: all eight arrays are child pointers; solid leaf: state, color, illumination + + + + 0 + 1 + 2 + 3 + 4 + 5 + + + + + + + + + + + + + + + + + + + + cell1 + cell2 + cell3 + cell4 + cell5 + cell6 + cell7 + cell8 + + + state / child 1 + color / child 2 + illum. / child 3 + child 4 + child 5 + child 6 + child 7 + child 8 + + + + ← index 0 = master cell + allocation = scan for a free slot; exhaustion throws + diff --git a/Documentation/Octree ray tracing/Octree subdivision.svg b/Documentation/Octree ray tracing/Octree subdivision.svg new file mode 100644 index 0000000..2767b6b --- /dev/null +++ b/Documentation/Octree ray tracing/Octree subdivision.svg @@ -0,0 +1,63 @@ + + + + + + + + + + + + + + Recursive 8-way subdivision + a cube splits into 8 octants; only occupied octants split further + + + + + + L0 master + + + + + L1 + + + + + L2 + + 2D analogue (4 quadrants) of the 3D 8-octant split + + + + + master cell [0] + + + + + + + octant 1 + + octant 2 + + ... + level 1: 8 cells + + + + + + sub 1 + + ... + one octant splits again: level 2 + + + only occupied regions subdivide - empty space is never allocated + diff --git a/Documentation/Octree ray tracing/Ray traversal.svg b/Documentation/Octree ray tracing/Ray traversal.svg new file mode 100644 index 0000000..b04cd95 --- /dev/null +++ b/Documentation/Octree ray tracing/Ray traversal.svg @@ -0,0 +1,64 @@ + + + + + + + + + + + + + + Ray traversal: primary rays and shadow rays + + + + + + + + + + + + + + + + + + empty: skipped + empty: skipped + empty: skipped + + + + + hit voxel + + + + camera + + + + primary ray (one per pixel) + + + + light 1 + + lit + + + + light 2 + + + + blocked → shadow + + traversal descends the octree hierarchy - empty regions are skipped without touching individual voxels + diff --git a/Documentation/Octree ray tracing/index.org b/Documentation/Octree ray tracing/index.org new file mode 100644 index 0000000..2f73537 --- /dev/null +++ b/Documentation/Octree ray tracing/index.org @@ -0,0 +1,140 @@ +:PROPERTIES: +:CUSTOM_ID: octree-ray-tracing +:END: +#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +#+TITLE: Octree Ray Tracing - Aukio 3D +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \setlength{\parindent}{15pt} +#+LATEX_HEADER: \usepackage{palatino} +#+LATEX_HEADER: \usepackage{charter} +#+HTML_HEAD: + +[[file:../index.html#outline-container-octree-ray-tracing][<- Back to index]] + +* What the octree adds +:PROPERTIES: +:CUSTOM_ID: what-octree-adds +:END: + +The raster pipeline draws triangles. The =renderer/octree= package +offers a second, independent way to build a scene: a *voxel volume*. +Space is stored as an octree — a tree that recursively subdivides a +cube into eight octants — which compresses sparse or repetitive +volumes well: empty regions are never allocated, and a solid room +wall can stay one large cell until something forces it to split. + +On top of that volume, =renderer/octree/raytracer= implements a real +*ray tracer*: it casts one ray per pixel through the octree, finds +the first occupied voxel, and computes lighting by casting shadow +rays from the hit point toward every light source. The ray tracer is +a rendering curiosity next to the raster pipeline — but it is a +complete one, with per-pixel shadows and progressive on-screen +refinement. + +#+CAPTION: Left: the 2D analogue of recursive subdivision — only occupied regions split. Right: the same as a tree. Empty space costs no cells. +[[file:Octree subdivision.svg]] + +* The data structure: a flat cell pool +:PROPERTIES: +:CUSTOM_ID: cell-pool +:END: + +=OctreeVolume= stores the whole tree in a flat pool: eight parallel +=int= arrays (=cell1= ... =cell8=), and a cell is just an index into +them. The packing is economical: + +- a *solid leaf* uses =cell1= for its state marker, =cell2= for its + color and =cell3= for its illumination value; +- an *internal cell* uses all eight arrays as child pointers — + =breakSolidCell= subdivides a leaf by writing eight freshly + allocated children into =cell1= ... =cell8=, inheriting the parent's + color and illumination. + +#+CAPTION: The flat cell pool. Index 0 is the master cell covering the whole world. Allocation scans for a free slot with wraparound; when the pool is full, allocation throws =IllegalStateException= (grow the pool at =initWorld= or reduce voxel density). +[[file:Cell pool.svg]] + +There are no Java objects per cell and no pointers to chase beyond +array indexing — the same cache-friendly layout philosophy as the +raster pipeline's mesh blocks. Cell zero is the master cell, whose +edge length is =masterCellSize= world units. + +Building a volume is incremental: + +#+BEGIN_SRC java +OctreeVolume volume = new OctreeVolume(); +volume.initWorld(poolSize, masterCellSize); + +// single voxel: +volume.putCell(x, y, z, color); + +// filled box of voxels: +volume.fillRectangle(new IntegerPoint(x1, y1, z1), + new IntegerPoint(x2, y2, z2), color); +#+END_SRC + +* Ray tracing through the volume +:PROPERTIES: +:CUSTOM_ID: ray-tracing +:END: + +=RayTracer= is constructed with a target =Texture=, the volume, the +light list and a =RaytracingCamera= (which wraps the scene's raster +camera plus a magnification factor, and owns the texture the result +is painted into). It implements =Runnable= — the demo runs it on a +plain background thread: + +#+BEGIN_SRC java +RaytracingCamera rtCamera = new RaytracingCamera(viewPanel.getCamera(), magnification); +RayTracer rayTracer = new RayTracer(rtCamera.getTexture(), + octreeVolume, lights, rtCamera, viewPanel); +new Thread(rayTracer).start(); +#+END_SRC + +For each pixel, =RaytracingCamera= generates a =Ray=; traversal +(=OctreeVolume.traceCell=) descends the hierarchy, testing only the +children a ray actually crosses and skipping empty subtrees entirely +— empty space is never touched voxel by voxel. The first occupied +cell hit yields the surface point and its =cell2= color. + +Lighting is per-pixel: from the hit point a shadow ray is cast +toward every =LightSource=. If any occupied cell blocks that ray, +the point is in shadow for that light; otherwise the light +contributes to the pixel. + +#+CAPTION: A primary ray crosses the volume (empty cells are skipped wholesale), hits an occupied voxel, and shadow rays decide per-light visibility. Light 2 is blocked, so its contribution is shadowed. +[[file:Ray traversal.svg]] + +The render is *progressive*: the tracer repaints its texture roughly +once per second (=PROGRESS_UPDATE_FREQUENCY_MILLIS=), so a refining +image appears immediately and sharpens as more pixels complete — you +watch the shadows settle rather than waiting for a final image. + +* Trying it out +:PROPERTIES: +:CUSTOM_ID: trying-it-out +:END: + +The *Octree* demo in the aukio-3d-demos project +(=examples/OctreeDemo.java=) builds a voxel scene (spiral, tiled +floor, a fractal) into an =OctreeVolume=, places light sources, and +starts a background ray-trace render of the current view. The same +scene builds deterministically for the golden-image harness, so the +ray-traced output is regression-tested like every other demo. + +* Related classes +:PROPERTIES: +:CUSTOM_ID: related-classes +:END: + +| Class | Role | +|--------------------+-------------------------------------------------------------| +| =OctreeVolume= | flat-pool octree: allocation, voxel writes, ray traversal | +| =IntegerPoint= | integer 3D coordinate for voxel addressing | +| =RayTracer= | per-pixel rays, shadow rays, progressive texture updates | +| =RaytracingCamera= | wraps the raster camera; generates per-pixel rays | +| =Ray= | a single ray: origin, direction, hit point | +| =LightSource= | a light the shadow rays are cast toward | + +[[file:../index.html#outline-container-octree-ray-tracing][Back to main documentation]] diff --git a/Documentation/Rendering loop/index.org b/Documentation/Rendering loop/index.org index d1b5e83..e9bd53c 100644 --- a/Documentation/Rendering loop/index.org +++ b/Documentation/Rendering loop/index.org @@ -42,7 +42,7 @@ Each step has a specific purpose: |-----------+-------+--------+---------| | Shapes | 3D [[file:../index.org::#vertex][vertices]], [[file:../index.org::#mesh][meshes]] | Scene data | Objects waiting to be drawn | | Transform | World coordinates | Screen coordinates | Convert 3D positions to where they appear on screen (see [[file:../index.org::#coordinate-system][coordinate system]]); cull shapes outside the view frustum. Parallel: heavy subtrees fork onto the worker pool | -| Sort | Unordered shapes | Ordered by depth | Ensure correct visibility (far objects painted first). Parallel merge sort for large scenes | +| Sort | Unordered shapes | Ordered by depth | Establish the back-to-front order (translucent blending, early-z). Parallel radix sort for large scenes | | Bin | Sorted shapes | Per-tile shape lists | Each paint tile iterates only shapes that can touch it. Parallel over the worker pool | | Paint | Per-tile shape lists | Pixels in buffer | Tiles split the screen into independent work units so clearing and rasterization run in parallel across CPU cores | | Present | Pixel buffer | Screen image | Hand the completed frame to a dedicated thread that copies it to the display | @@ -196,6 +196,9 @@ Every shape exists in "world space" — its own position in the 3D world. To render it, we must convert to "screen space" — where it appears on your monitor. This involves: +- *Scale*: Optionally resize shapes uniformly about their local origin + (=Transform.setScale=); folded into the composed transform stack at + push time, so per-vertex cost is unchanged - *Translation*: Move coordinates relative to camera position - *Rotation*: Rotate coordinates based on camera orientation - *Projection*: Convert 3D (x, y, z) to 2D (x, y) screen pixels @@ -230,21 +233,36 @@ else if (z1 > z2) return -1; // z1 is farther -> sort before z2 return Integer.compare(o1.shapeId, o2.shapeId); #+END_SRC -Above 8192 queued shapes the sort runs as an instrumented parallel -merge sort on the shared worker pool; below that it is single-threaded. +Above 8192 queued shapes the sort runs as a parallel radix sort on the +shared worker pool: Z is mapped to unsigned-ordered long keys and +stable-sorted by LSD radix passes, with equal-key runs fixed to +ascending shape id — reproducing the comparator order exactly, +bit-identical between serial and parallel. Below that threshold it is a +single-threaded comparator sort. *Why sort back-to-front?* -This implements the *painter's algorithm* — like painting a landscape: -first paint the sky (farthest), then mountains, then trees, then the -foreground. Each layer covers what's behind it. +Two consumers of the order, for different reasons: + +- *Translucent surfaces* are blended, and blending is order-dependent: + the farther layer must already be in the buffer when the nearer one + mixes with it. This is the *painter's algorithm* — like painting a + landscape: first the sky (farthest), then mountains, then trees, + then the foreground. Alpha-class shapes therefore paint in queue + order, back-to-front, testing but never writing depth. #+INCLUDE: "Painter's algorithm.svg" export html -Without sorting, nearby objects might be painted first and then covered -by distant ones, causing visual errors. This is especially important for -*transparent objects* — you need to see through the near ones to what's -behind. +- *Opaque surfaces* do not need the order for correctness — the + per-pixel [[file:Depth buffer/][depth buffer]] decides visibility. + They still benefit from it as a performance optimization: the paint + loop iterates them *front-to-back* (the queue reversed), so the + nearest surface writes depth first and every covered pixel behind + it fails the depth test early, before its texture is even fetched. + +Without sorting, translucent objects would blend against the wrong +background — you would see through them to whatever happened to be +painted already, not to what is actually behind. The Z value represents distance from the camera after transformation. Larger values = further away. The id tiebreaker keeps the order @@ -289,9 +307,15 @@ piece — so cores never idle behind a busy thread. Each tile task: -1. *Clear tile*: fill its rectangle with background color -2. *Paint shapes*: rasterize the tile's bin, back-to-front, clipping - at tile bounds +1. *Clear tile*: fill its rectangle with background color and reset + its slice of the depth buffer +2. *Paint shapes*: rasterize the tile's bin in two passes — first + opaque-class shapes front-to-back (depth test + write, so covered + pixels are rejected before their texture is fetched), then + alpha-class shapes back-to-front (depth test, no write, so + translucency blends painter-coherently). All rasterization clips + at tile bounds. See [[file:Depth buffer/][Depth buffer]] for the + two-pass contract. Both operations happen within the same task, so clearing always completes before painting on that tile. Parallel clearing across diff --git a/Documentation/SpaceMouse 6DOF/SpaceMouse gestures.svg b/Documentation/SpaceMouse 6DOF/SpaceMouse gestures.svg new file mode 100644 index 0000000..079c7eb --- /dev/null +++ b/Documentation/SpaceMouse 6DOF/SpaceMouse gestures.svg @@ -0,0 +1,48 @@ + + + + + + + + + + + + + + + Six gestures, six camera axes + + + + cap gesture + camera + + + push cap right / left + strafe right / left (world X) + + + push cap away / toward you + forward / backward (world Z) + + + press cap down / pull up + down / up (world Y) + + + twist clockwise / counter-clockwise + yaw right / left (2x sensitivity) + + + tilt top away / toward you + look up / down + + + left cap button + brake: kill camera velocity + + + cap deflection = velocity - push harder to fly faster, release to stop instantly + diff --git a/Documentation/SpaceMouse 6DOF/SpaceMouse.png b/Documentation/SpaceMouse 6DOF/SpaceMouse.png new file mode 100644 index 0000000..f878e23 Binary files /dev/null and b/Documentation/SpaceMouse 6DOF/SpaceMouse.png differ diff --git a/Documentation/SpaceMouse 6DOF/index.org b/Documentation/SpaceMouse 6DOF/index.org new file mode 100644 index 0000000..99f26ca --- /dev/null +++ b/Documentation/SpaceMouse 6DOF/index.org @@ -0,0 +1,110 @@ +:PROPERTIES: +:CUSTOM_ID: spacemouse-6dof +:END: +#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +#+TITLE: SpaceMouse 6DOF - Aukio 3D +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \setlength{\parindent}{15pt} +#+LATEX_HEADER: \usepackage{palatino} +#+LATEX_HEADER: \usepackage{charter} +#+HTML_HEAD: + +[[file:../index.html#outline-container-spacemouse-6dof][<- Back to index]] + +* What the SpaceNavigator adds +:PROPERTIES: +:CUSTOM_ID: what-spacemouse-adds +:END: + +Keyboard and mouse move the camera one axis at a time. A 3Dconnexion +*SpaceNavigator* — a pressure-sensitive 6DOF cap — moves it on all +six axes at once: push, pull, slide and press the cap to translate, +tilt and twist it to rotate. The engine supports it out of the box: +when a SpaceNavigator is plugged in over USB, =ViewPanel= +automatically starts a =SpaceMouseManager= that discovers the device +over hidraw (hot-plug works at runtime), and every application and +demo flies the camera with zero setup. Unplugging returns control to +mouse and keyboard. Disable with =-De3d.spacemouse=false=. + +The package lives in =eu.svjatoslav.aukio.e3d.gui.spacemouse=. + +* How the cap maps to the camera +:PROPERTIES: +:CUSTOM_ID: cap-mapping +:END: + +The cap is *pressure-sensing*, so translation is direct proportional +drive: cap deflection maps to camera velocity (full deflection = +=TRANSLATION_SPEED_FACTOR= — 3.0 — times the camera speed limit), +applied to the camera position every frame along the camera's own +orientation. There is deliberately no acceleration integrator like +the keyboard has: releasing the cap stops the camera instantly. Push +harder to fly faster, nudge to creep. + +Rotation is split by axis: *twist* (yaw) is tuned twice as sensitive +as *tilt* (pitch) — constants =ROTATION_YAW_DEGREES= 3.0 vs +=ROTATION_PITCH_DEGREES= 1.5 in =SpaceMouseController=. + +#+CAPTION: Every cap gesture and the camera motion it drives. Sign conventions were verified live against the device. +[[file:SpaceMouse gestures.svg]] + +The *left cap button* is a brake: it zeroes the movement vector +accumulated by keyboard and scroll-wheel input (the cap itself needs +no brake — it stops when you let go). + +* Composing with other input +:PROPERTIES: +:CUSTOM_ID: composing +:END: + +SpaceMouse, head tracking and mouse drag all write the same camera +and coexist without fighting. =HeadLookController= folds external +camera writes into its base orientation every frame, so a SpaceMouse +rotation or a mouse drag stays where you left it instead of being +overwritten by the next head-tracking update. All three can be used +interchangeably mid-motion. + +* Device access (udev rule) +:PROPERTIES: +:CUSTOM_ID: udev +:END: + +Device access needs a udev rule that makes the SpaceNavigator's +hidraw node writable by the session user — without it the node is +root-only and the cap is never discovered. The rule ships in the +engine repository as +[[file:../../udev/99-spacenavigator.rules][udev/99-spacenavigator.rules]]: + +#+BEGIN_SRC text +SUBSYSTEM=="hidraw", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c626", MODE="0666" +#+END_SRC + +Install it from the repository root and replug the device: + +#+BEGIN_SRC sh +sudo install -m 644 udev/99-spacenavigator.rules /etc/udev/rules.d/ +sudo udevadm control --reload +#+END_SRC + +The device is *silent at rest* — it only sends reports while the cap +is deflected — so there is no liveness watchdog; an unplug is noticed +on the next failed read. + +* Related classes +:PROPERTIES: +:CUSTOM_ID: related-classes +:END: + +| Class | Role in SpaceMouse support | +|------------------------+------------------------------------------------------------| +| =SpaceMouseManager= | auto-start with ViewPanel, hot-plug scanning | +| =SpaceNavigatorHid= | hidraw transport: 7-byte translation/rotation/button reports | +| =SpaceMouseController= | cap axes -> camera velocity/rotation, tuning constants | + +See the *SpaceMouse 6DOF* demo in the aukio-3d-demos project +(=examples/spacemouse_demo/SpaceMouseDemo=) for a compass ring with a +live six-axis readout built to verify the mapping above. + +[[file:../index.html#outline-container-spacemouse-6dof][Back to main documentation]] diff --git a/Documentation/Stereoscopic rendering/Head tracking.svg b/Documentation/Stereoscopic rendering/Head tracking.svg new file mode 100644 index 0000000..24b96f7 --- /dev/null +++ b/Documentation/Stereoscopic rendering/Head tracking.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + + + + + Head tracking: the glasses drive the camera + RayNeo XR glasses IMU over hidraw - auto-starts with ViewPanel, hot-plug at runtime + + + + + RayNeo glasses + gyro + accel, ~500 Hz + + + RayNeoHid + hidraw, 64-byte reports + + + HeadTracker + gyro + gravity fusion + + + HeadLookController + yaw / pitch -> camera + + + + + + + HeadTrackingManager: auto-start with ViewPanel, hot-plug, frozen-stream watchdog + Scroll Lock recenters yaw drift - mouse drag and SpaceMouse compose on top of head look + diff --git a/Documentation/Stereoscopic rendering/Stereo per eye.svg b/Documentation/Stereoscopic rendering/Stereo per eye.svg index 5fc9cfd..af3193e 100644 --- a/Documentation/Stereoscopic rendering/Stereo per eye.svg +++ b/Documentation/Stereoscopic rendering/Stereo per eye.svg @@ -1,4 +1,4 @@ - + @@ -10,36 +10,36 @@ - + - What changes per eye + What changes per eye concern per-eye behavior - + camera translation.x += ±IPD/2 (restored after the pass) - + projection scale = eyeWidth/3; x += stereoViewportOffsetX - + frustum culling built from stereoViewportWidth - narrower FOV per eye - + painting clipped to [renderMinX, renderMaxX) = the eye's half - + mouse picking hits combined only for the eye containing the cursor - + HUD / overlays drawn once, spanning the full frame (zero disparity) diff --git a/Documentation/Stereoscopic rendering/index.org b/Documentation/Stereoscopic rendering/index.org index f1ceee8..261e403 100644 --- a/Documentation/Stereoscopic rendering/index.org +++ b/Documentation/Stereoscopic rendering/index.org @@ -145,6 +145,77 @@ so the viewer can tune comfort at runtime. #+CAPTION: The same scene rendered as a normal mono frame (for comparison with the pair above). Notice there is no horizontal offset to read depth from — the picture is flat. [[file:mono-comparison.png]] +* Head tracking: the glasses also drive the camera +:PROPERTIES: +:CUSTOM_ID: head-tracking +:END: + +Side-by-side stereo covers the *display* half of XR glasses. The +*input* half — turning the camera with your head — lives in the +engine too, in the =eu.svjatoslav.aukio.e3d.gui.headtrack= package, +so every application and demo gets it with zero setup. When a pair +of RayNeo XR glasses is plugged in over USB, =ViewPanel= +automatically starts a =HeadTrackingManager= that discovers the +device over hidraw: tracking begins within a couple of seconds of +plug-in (hot-plug works at runtime), and unplugging returns control +to mouse and keyboard. Disable with =-De3d.headtrack=false=. + +#+CAPTION: The head-tracking data path. The glasses stream IMU samples over hidraw; the tracker fuses them into yaw/pitch angles that the controller applies to the camera every frame. +[[file:Head tracking.svg]] + +=HeadTracker= fuses the glasses' IMU with a complementary filter: +gyroscope rates integrate into yaw/pitch angles (integration time +comes from the wall clock, never the device tick), while the +accelerometer's gravity vector slowly pulls pitch toward the true +horizon. Yaw has no absolute reference and drifts slowly — *Scroll +Lock* recenters at any time. Hold still for a second after plug-in: +gyro-bias calibration only samples while the head is stationary, so +turning during the first moment poisons it with phantom drift. + +=HeadLookController= applies the fused angles to the camera every +frame (yaw gain 2.0, pitch gain 1.0; roll is deliberately not +applied), so the virtual world stays put while you look around. +Mouse drag composes on top — drag to look further than your neck +turns, and the view stays where the mouse left it; a SpaceNavigator +6DOF cap composes the same way. + +Combined with stereo this is the full XR setup: *SHIFT+F11* gives +the glasses their side-by-side image, and the same glasses' IMU +drives the camera. Note that the world-X IPD limitation listed below +now applies to *head* motion: the eye offset is exact while facing +along Z and degrades at large yaw angles. + +Practical notes: + +- Only one process may use the glasses at a time — concurrent + consumers send conflicting IMU on/off commands and starve each + other's streams. +- Head tracking is the engine's one sanctioned native dependency: it + talks to hidraw through JNA. +- Device access needs the udev rule shown below — without it the + glasses' hidraw node is root-only and tracking never starts. + +The rule ships in the engine repository as +[[file:../../udev/99-rayneo-glasses.rules][udev/99-rayneo-glasses.rules]]: + +#+BEGIN_SRC text +ACTION=="add|change", SUBSYSTEM=="hidraw", SUBSYSTEMS=="usb", ATTRS{idVendor}=="1bbb", ATTRS{idProduct}=="af50", MODE="0666" +#+END_SRC + +Install it from the repository root and replug the glasses: + +#+BEGIN_SRC sh +sudo install -m 644 udev/99-rayneo-glasses.rules /etc/udev/rules.d/ +sudo udevadm control --reload +#+END_SRC + +| Class | Role in head tracking | +|------------------------+----------------------------------------------------------| +| =HeadTrackingManager= | auto-start with ViewPanel, hot-plug, stream watchdog | +| =RayNeoHid= | hidraw transport: enable sequence, 64-byte IMU reports | +| =HeadTracker= | IMU fusion, stationary-gated calibration, drift control | +| =HeadLookController= | applies fused yaw/pitch to the camera, folds mouse input | + * Performance and limitations :PROPERTIES: :CUSTOM_ID: limitations diff --git a/Documentation/Subpixel culling/Culling ladder.svg b/Documentation/Subpixel culling/Culling ladder.svg new file mode 100644 index 0000000..840d9ad --- /dev/null +++ b/Documentation/Subpixel culling/Culling ladder.svg @@ -0,0 +1,38 @@ + + + + + + + + + + + + + + The culling ladder: work discarded as early as possible + + + + scene: every shape in the world + + + 1. composite frustum culling - skip invisible subtrees + + + 2. screen-bounds culling - drop off-frame shapes + + + 3. subpixel culling - drop shapes smaller than a pixel + ← THIS PAGE + + + 4. Hi-Z occlusion - drop hidden blocks + + + what remains paints + + + stages 1-3 run inside transform; Hi-Z tests whole mesh blocks against last frame's depth pyramid + diff --git a/Documentation/Subpixel culling/Verdict epoch.svg b/Documentation/Subpixel culling/Verdict epoch.svg new file mode 100644 index 0000000..97b6688 --- /dev/null +++ b/Documentation/Subpixel culling/Verdict epoch.svg @@ -0,0 +1,46 @@ + + + + + + + + + + + + + + The verdict cache: skip setup, not just drawing + + + + + epoch 7: cached skips + + epoch 8: re-evaluate once, + + epoch 9: ... + + + + + camera moved > 25 units + + rotation > ~1.1 degrees + + + + + + + + + frames → + + then cached again + + while the epoch holds, a culled shape returns at the top of transform() - no vertex math at all + the epoch also bumps unconditionally every 30 frames (-Daukio.cull.subpixel.frames) + a culled shape is re-evaluated whenever the camera could have made it visible again + diff --git a/Documentation/Subpixel culling/index.org b/Documentation/Subpixel culling/index.org new file mode 100644 index 0000000..0f3cfa1 --- /dev/null +++ b/Documentation/Subpixel culling/index.org @@ -0,0 +1,115 @@ +:PROPERTIES: +:CUSTOM_ID: subpixel-culling +:END: +#+SETUPFILE: ~/.emacs.d/org-styles/html/darksun.theme +#+TITLE: Subpixel Culling - Aukio 3D +#+LANGUAGE: en +#+LATEX_HEADER: \usepackage[margin=1.0in]{geometry} +#+LATEX_HEADER: \usepackage{parskip} +#+LATEX_HEADER: \setlength{\parindent}{15pt} +#+LATEX_HEADER: \usepackage{palatino} +#+LATEX_HEADER: \usepackage{charter} +#+HTML_HEAD: + +[[file:../index.html#outline-container-subpixel-culling][<- Back to index]] + +* Shapes too small to see +:PROPERTIES: +:CUSTOM_ID: too-small-to-see +:END: + +A distant city contains thousands of triangles whose entire screen +footprint is a fraction of a pixel. They cannot influence the image — +but the pipeline still transforms their vertices, clips them against +the near plane, computes their bounds and queues them for sorting. + +*Subpixel culling* drops them at the earliest possible moment. It is +off by default; enable it with a threshold in pixels: + +#+BEGIN_SRC sh +java -Daukio.cull.subpixel=0.4 -jar my-app.jar +#+END_SRC + +The verdict is evaluated in =AbstractCoordinateShape.transform()=, +immediately after the shape's screen-space bounds are known and +*before* the shape is queued: if the raw span (=maxX - minX= and +=maxY - minY=, before any paint margins) is below the threshold on +*both* axes, the shape is dropped for this pass. The bounds were +already computed for the other culling stages, so the test itself is +nearly free. + +Subpixel culling is one rung of the engine's culling ladder — each +rung discards work earlier and more cheaply than the previous one +could have: + +#+CAPTION: The culling ladder. Subpixel culling is the third rung: frustum culling skips whole invisible subtrees, screen-bounds culling drops individual off-frame shapes, subpixel culling drops the ones too small to matter, and Hi-Z removes occluded mesh blocks. +[[file:Culling ladder.svg]] + +* The verdict cache: skip setup, not just drawing +:PROPERTIES: +:CUSTOM_ID: verdict-cache +:END: + +Re-testing every tiny shape every frame would still walk the scene +graph and run per-shape setup. So once a shape is culled, the +*verdict itself is cached* on the shape (a flag plus the epoch it was +culled in). While the epoch still matches, =transform()= returns at +the very top — no vertex transforms, no clipping, no bounds loop at +all. Tiny geometry costs literally nothing on stationary frames. + +The epoch is owned by =ShapeCollection= and advances exactly when a +culled shape could have become visible again: + +- the camera *translated* more than =-Daukio.cull.subpixel.translate= + (default 25 world units), or +- the camera *rotated* (quaternion component delta over + =-Daukio.cull.subpixel.rotate=, default 0.01 ≈ 1.1°), or +- =-Daukio.cull.subpixel.frames= frames elapsed (default 30) — an + unconditional bump that catches shape-side transform changes. + +#+CAPTION: The epoch timeline. Cached verdicts are trusted while the camera stays put; any significant camera change re-evaluates every culled shape once, then the cache settles again. +[[file:Verdict epoch.svg]] + +One safety note for engine work: the cached skip leaves the shape's +per-slot vertex state stale. That is safe only because unqueued +shapes are never painted — any future code path that reads per-slot +state for a shape that was not queued will see stale data. + +* Tuning +:PROPERTIES: +:CUSTOM_ID: tuning +:END: + +| Property | Default | Meaning | +|-------------------------------+---------+---------| +| =aukio.cull.subpixel= | 0 (off) | screen-span threshold in pixels; shapes below it on both axes are culled | +| =aukio.cull.subpixel.translate= | 25 | camera translation (world units) that invalidates the cache | +| =aukio.cull.subpixel.rotate= | 0.01 | camera rotation (quaternion delta ≈ 1.1°) that invalidates the cache | +| =aukio.cull.subpixel.frames= | 30 | unconditional invalidation period in frames | + +Measured on the Fallout 4 environment's downtown scene (a +triangle-heavy skyline at altitude): at 0.4 px the paint queue +shrank ~13% (525k to 456k shapes) and frame time dropped from ~135 +to ~125 ms, with golden-image diffs under 0.006% of pixels — visually +indistinguishable. The bigger win is the verdict cache on stationary +frames, where culled shapes cost no setup at all. + +Start at 0.4–0.5 px and raise only if artifacts are absent: too +large a threshold eats small lights, antennae and text at mid +distances. + +* Related classes +:PROPERTIES: +:CUSTOM_ID: related-classes +:END: + +| Class | Role in subpixel culling | +|-----------------------------+-----------------------------------------------------| +| =AbstractCoordinateShape= | evaluates the verdict; caches flag + epoch | +| =ShapeCollection= | owns and advances the epoch | +| =RenderingContext= | carries the threshold and the epoch into each pass | + +See also: [[file:Frustum culling/][Frustum culling]] (rung 1), +[[file:Depth%20buffer/][Depth buffer]] (the Hi-Z pyramid, rung 4). + +[[file:../index.html#outline-container-subpixel-culling][Back to main documentation]] diff --git a/Documentation/index.org b/Documentation/index.org index 78e010e..1cc4461 100644 --- a/Documentation/index.org +++ b/Documentation/index.org @@ -87,8 +87,33 @@ The cameras stay parallel and are offset by a configurable IPD pipeline, each clipped to its half of the frame buffer; per-eye projection, frustum culling and mouse picking adapt automatically. +With RayNeo XR glasses the engine also tracks the head: plugging the +glasses in over USB auto-starts IMU head tracking, so the stereo image +responds to look-around (hot-plug at runtime, Scroll Lock recenters). + See [[file:Stereoscopic%20rendering/][Stereoscopic rendering]] for the -geometry, pipeline and tuning. +geometry, pipeline and tuning, and its +[[file:Stereoscopic%20rendering/index.org::#head-tracking][head tracking]] +section for the glasses IMU support. + +** SpaceMouse 6DOF input +:PROPERTIES: +:CUSTOM_ID: spacemouse-6dof +:END: + +#+attr_html: :width 600px +#+attr_latex: :width 600px +[[file:SpaceMouse 6DOF/SpaceMouse.png]] + + +A 3Dconnexion SpaceNavigator flies the camera with its +pressure-sensitive 6DOF cap: push, pull, slide and press to move, +tilt and twist to look. Plugging it in auto-starts camera control in +every application (hot-plug at runtime), composing freely with head +tracking and mouse drag. + +See [[file:SpaceMouse%206DOF/][SpaceMouse 6DOF]] for the cap mapping, +tuning and device setup. ** Constructive Solid Geometry :PROPERTIES: @@ -121,6 +146,78 @@ under minification, all without a mipmap chain. See [[file:SDF%20textures/][SDF textures]] for the glyph pipeline, the render path, analytic minification and tuning knobs. +** Octree voxel volumes and ray tracing +:PROPERTIES: +:CUSTOM_ID: octree-ray-tracing +:END: + +[[file:Octree ray tracing/Octree subdivision.svg]] + +Beyond triangles, the engine can store a scene as a *voxel volume* in +a flat-pool octree — and render it with a real ray tracer: one ray +per pixel through the volume, per-pixel shadows from shadow rays, and +progressive on-screen refinement. + +See [[file:Octree%20ray%20tracing/][Octree ray tracing]] for the data +structure, the traversal and how to run it. + +** Interactive GUI components +:PROPERTIES: +:CUSTOM_ID: gui-components +:END: + +[[file:GUI components/Event dispatch.svg]] + +Widgets live *in the world*: clickable, focusable panels that receive +keyboard input, with perspective-correct texture coordinates for +every click and hover. A complete text editor is built on the same +base class. + +See [[file:GUI%20components/][GUI components]] for the focus model, +event dispatch and the callback surface. + +** Wavefront OBJ model loading +:PROPERTIES: +:CUSTOM_ID: obj-loading +:END: + +Existing models in the [[https://en.wikipedia.org/wiki/Wavefront_.obj_file][Wavefront OBJ]] format load +into the scene graph with one call: + +#+BEGIN_SRC java +ObjModel model = ObjLoader.load(Path.of("city1.obj")); +model.setShadingEnabled(true); +shapes.addShape(model); +#+END_SRC + +=ObjLoader= (package +=eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.obj=) +parses vertices, polygonal faces (all index forms, including forward +references from batch-flushing exporters), =usemtl=/=mtllib= material +references, and MTL =Kd= diffuse color + =d= opacity (translucent +materials blend in the alpha pass). Faces become [[https://www3.svjatoslav.eu/projects/aukio-3d/apidocs/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.html][SolidPolygon]] +instances inside an =ObjModel= composite, so transforms, shading and +backface culling work as for any composite. Coordinates load verbatim; +for standard +Y-up exports rotate the model 180° around X to stand +upright in the engine's -Y-up world. + +If the source units do not match the scene's world scale, resize the +model with the transform's uniform scale instead of editing the file — +it applies about the model's local origin, before rotation: + +#+BEGIN_SRC java +model.setTransform(Transform.fromAngles(0, 0, 0, 0, Math.PI, 0)); +model.getTransform().setScale(5.0); // grow 5x +#+END_SRC + +=Transform.setScale= works on any shape, not just loaded models: scale +is folded into the composed transform stack at push time, so per-vertex +render cost is unchanged and scenes that never set a scale render +bit-identically. Negative values mirror the geometry (flipping face +winding and thus backface culling). + +See the [[https://www3.svjatoslav.eu/projects/aukio-3d-demos/#obj-loader-city][OBJ loader city demo]] for a complete example. + * How take engine into use :PROPERTIES: :CUSTOM_ID: taking-engine-into-use @@ -161,6 +258,19 @@ Also add the repository (the library is not on Maven Central): - See [[https://www3.svjatoslav.eu/projects/aukio-3d/graphs/][*Aukio 3D* class diagrams]]. (Diagrams were generated by using [[https://www3.svjatoslav.eu/projects/javainspect/][JavaInspect]] utility) +** Configuration +:PROPERTIES: +:CUSTOM_ID: configuration +:END: + +All Aukio programs share one YAML file, =~/.config/aukio/config.yaml=. +Engine settings live in its =e3d:= section — stereo IPD, log and bug +report directories, telemetry interval — and every key can be +overridden with a =-D= system property for a single run. + +See [[file:Configuration/][Configuration]] for the key table, live +reload and write safety. + * Essential theory :PROPERTIES: :CUSTOM_ID: understanding-3d-engine @@ -690,6 +800,22 @@ See [[file:Depth%20buffer/][Depth buffer]] for the full treatment. To understand frustum culling and object-level visibility optimization, read more about [[file:Frustum culling/][frustum & view frustum culling.]] +** Subpixel culling +:PROPERTIES: +:CUSTOM_ID: subpixel-culling +:END: + +Distant geometry whose whole screen footprint is a fraction of a +pixel still costs full transform setup. *Subpixel culling* drops such +shapes right after their screen bounds are known, and caches the +verdict per shape so that stationary frames skip their setup +entirely. Off by default; enable with =-Daukio.cull.subpixel==. + +#+INCLUDE: "Subpixel culling/Culling ladder.svg" export html + +Read more about [[file:Subpixel%20culling/][subpixel culling]] — the +verdict epoch, tuning knobs and measured effect. + ** Winding Order & Backface Culling :PROPERTIES: :CUSTOM_ID: winding-order-backface-culling diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/gui/ViewPanel.java b/src/main/java/eu/svjatoslav/aukio/e3d/gui/ViewPanel.java index 9203394..5dda998 100755 --- a/src/main/java/eu/svjatoslav/aukio/e3d/gui/ViewPanel.java +++ b/src/main/java/eu/svjatoslav/aukio/e3d/gui/ViewPanel.java @@ -502,7 +502,8 @@ public class ViewPanel extends Canvas { final int threadCount) { if (globalIllumination == null) { globalIllumination = new eu.svjatoslav.aukio.e3d.renderer.raster.gi.GlobalIllumination( - rootShapeCollection, lightingManager, threadCount); + rootShapeCollection, lightingManager, threadCount, + () -> getCamera().getTransform().getTranslation()); globalIllumination.start(); } return globalIllumination; diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/math/Transform.java b/src/main/java/eu/svjatoslav/aukio/e3d/math/Transform.java index 851c6c8..81fdd35 100755 --- a/src/main/java/eu/svjatoslav/aukio/e3d/math/Transform.java +++ b/src/main/java/eu/svjatoslav/aukio/e3d/math/Transform.java @@ -7,9 +7,11 @@ package eu.svjatoslav.aukio.e3d.math; import eu.svjatoslav.aukio.e3d.geometry.Point3D; /** - * Represents a transformation in 3D space combining translation and rotation. + * Represents a transformation in 3D space combining uniform scale, rotation, + * and translation (a similarity transform). * - *

Transformations are applied in order: rotation first, then translation.

+ *

Transformations are applied in order: scale first (about the local + * origin), then rotation, then translation.

* *

Performance optimization: The rotation matrix is cached and only * recomputed when the rotation quaternion changes. This avoids allocating a @@ -43,6 +45,13 @@ public class Transform implements Cloneable { */ private final Quaternion rotation; + /** + * Uniform scale applied before rotation, about the local origin. + * Defaults to 1.0 (no scaling). Negative values mirror the geometry + * (and so flip face winding / backface culling). + */ + private double scale = 1.0; + /** * Cached rotation matrix for performance. * Lazily computed when first needed and reused for subsequent transform() calls. @@ -118,13 +127,50 @@ public class Transform implements Cloneable { } /** - * Creates a copy of this transform with cloned translation and rotation. + * Creates a copy of this transform with cloned translation and rotation, + * preserving the scale. * - * @return a new transform with the same translation and rotation values + * @return a new transform with the same translation, rotation and scale values */ @Override public Transform clone() { - return new Transform(translation, rotation); + final Transform copy = new Transform(translation, rotation); + copy.scale = scale; + return copy; + } + + /** + * Returns the uniform scale applied before rotation (about the local + * origin). Default is 1.0 (no scaling). + * + * @return the scale factor + */ + public double getScale() { + return scale; + } + + /** + * Sets the uniform scale, applied before rotation about the local origin. + * + *

Values other than 1.0 resize the geometry in its local space. + * Negative values additionally mirror the geometry, which flips face + * winding and therefore inverts backface culling. Zero is rejected + * because it would collapse all geometry onto the translation point.

+ * + *

Like the rest of this class, the new value is picked up by a + * {@link TransformStack} only on the next push (push-time snapshot + * contract).

+ * + * @param scale the scale factor (must be finite and non-zero) + * @return this transform (for chaining) + */ + public Transform setScale(final double scale) { + if (!Double.isFinite(scale) || scale == 0.0) { + throw new IllegalArgumentException( + "scale must be finite and non-zero, got " + scale); + } + this.scale = scale; + return this; } /** @@ -166,16 +212,25 @@ public class Transform implements Cloneable { } /** - * Applies this transform to a point: rotation followed by translation. + * Applies this transform to a point: uniform scale (about the local + * origin), then rotation, then translation. * *

Uses a cached rotation matrix to avoid allocation and redundant computation. * The matrix is computed once (lazily) and reused for all subsequent calls * until {@link #invalidateCache()} is called.

* + *

With the default scale of 1.0 the multiply is skipped, so existing + * rigid-motion usage produces bit-identical results.

+ * * @param point the point to transform (modified in place) * @see #withTransformed(Point3D) for the non-mutating version that returns a new point */ public void transform(final Point3D point) { + if (scale != 1.0) { + point.x *= scale; + point.y *= scale; + point.z *= scale; + } getRotationMatrix().transform(point, point); point.add(translation); } diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/math/TransformStack.java b/src/main/java/eu/svjatoslav/aukio/e3d/math/TransformStack.java index 58023c4..1335a01 100644 --- a/src/main/java/eu/svjatoslav/aukio/e3d/math/TransformStack.java +++ b/src/main/java/eu/svjatoslav/aukio/e3d/math/TransformStack.java @@ -25,15 +25,16 @@ import eu.svjatoslav.aukio.e3d.geometry.Point3D; * 3. Apply ship's position relative to the world * * - *

Implementation: eager composition. Every transform is a rigid - * motion (rotation then translation), and compositions of rigid motions are - * closed and associative, so the whole stack collapses into a single - * equivalent transform. The stack maintains the composed rotation matrix and - * translation for each level: {@link #addTransform} composes the pushed - * transform with the previous level's composite, and {@link #transform} - * applies only the top-level composite. Per-point cost is one 3x3 - * matrix-vector multiply plus one addition, independent of stack depth. - * {@link #dropTransform} restores the parent composite for free.

+ *

Implementation: eager composition. Every transform is a + * similarity transform (uniform scale, then rotation, then translation). + * Uniform scale commutes with rotation, so compositions stay closed and + * associative: the whole stack collapses into a single equivalent transform. + * The stack maintains the composed scale-rotation matrix and translation + * for each level: {@link #addTransform} folds the pushed transform's scale + * into the matrix and composes it with the previous level's composite, and + * {@link #transform} applies only the top-level composite. Per-point cost + * is one 3x3 matrix-vector multiply plus one addition, independent of stack + * depth. {@link #dropTransform} restores the parent composite for free.

* *

Contract: composition is a snapshot taken at push time. Mutating * a transform after pushing it has no effect on the stack until it is @@ -101,9 +102,14 @@ public class TransformStack { * Pushes a transform onto the stack, composing it with the current * top-level composite. * - *

If the previous composite is (Rp, tp) and the pushed transform is - * (Rn, tn), the new composite is R' = Rp * Rn, t' = Rp * tn + tp — - * the pushed transform applies first, then the previous composite.

+ *

If the previous composite is (Mp, tp) and the pushed transform has + * scale s, rotation Rn and translation tn, the new composite is + * M' = Mp * (s * Rn), t' = Mp * tn + tp — the pushed transform applies + * first, then the previous composite. Because uniform scale commutes + * with rotation, folding s into the pushed matrix keeps the composition + * closed: the stored parent matrix already carries the parent's scale. + * With the default scale of 1.0 the extra multiply is IEEE-exact, so + * rigid-motion scenes stay bit-identical.

* * @param transform the transform to push (snapshotted at push time) */ @@ -113,18 +119,19 @@ public class TransformStack { final int v = i * 3; final Matrix3x3 rm = transform.getRotationMatrix(); + final double s = transform.getScale(); final Point3D t = transform.getTranslation(); if (i == 0) { - rotations[r] = rm.m00; - rotations[r + 1] = rm.m01; - rotations[r + 2] = rm.m02; - rotations[r + 3] = rm.m10; - rotations[r + 4] = rm.m11; - rotations[r + 5] = rm.m12; - rotations[r + 6] = rm.m20; - rotations[r + 7] = rm.m21; - rotations[r + 8] = rm.m22; + rotations[r] = s * rm.m00; + rotations[r + 1] = s * rm.m01; + rotations[r + 2] = s * rm.m02; + rotations[r + 3] = s * rm.m10; + rotations[r + 4] = s * rm.m11; + rotations[r + 5] = s * rm.m12; + rotations[r + 6] = s * rm.m20; + rotations[r + 7] = s * rm.m21; + rotations[r + 8] = s * rm.m22; translations[v] = t.x; translations[v + 1] = t.y; translations[v + 2] = t.z; @@ -142,15 +149,15 @@ public class TransformStack { final double a21 = rotations[pr + 7]; final double a22 = rotations[pr + 8]; - rotations[r] = a00 * rm.m00 + a01 * rm.m10 + a02 * rm.m20; - rotations[r + 1] = a00 * rm.m01 + a01 * rm.m11 + a02 * rm.m21; - rotations[r + 2] = a00 * rm.m02 + a01 * rm.m12 + a02 * rm.m22; - rotations[r + 3] = a10 * rm.m00 + a11 * rm.m10 + a12 * rm.m20; - rotations[r + 4] = a10 * rm.m01 + a11 * rm.m11 + a12 * rm.m21; - rotations[r + 5] = a10 * rm.m02 + a11 * rm.m12 + a12 * rm.m22; - rotations[r + 6] = a20 * rm.m00 + a21 * rm.m10 + a22 * rm.m20; - rotations[r + 7] = a20 * rm.m01 + a21 * rm.m11 + a22 * rm.m21; - rotations[r + 8] = a20 * rm.m02 + a21 * rm.m12 + a22 * rm.m22; + rotations[r] = s * (a00 * rm.m00 + a01 * rm.m10 + a02 * rm.m20); + rotations[r + 1] = s * (a00 * rm.m01 + a01 * rm.m11 + a02 * rm.m21); + rotations[r + 2] = s * (a00 * rm.m02 + a01 * rm.m12 + a02 * rm.m22); + rotations[r + 3] = s * (a10 * rm.m00 + a11 * rm.m10 + a12 * rm.m20); + rotations[r + 4] = s * (a10 * rm.m01 + a11 * rm.m11 + a12 * rm.m21); + rotations[r + 5] = s * (a10 * rm.m02 + a11 * rm.m12 + a12 * rm.m22); + rotations[r + 6] = s * (a20 * rm.m00 + a21 * rm.m10 + a22 * rm.m20); + rotations[r + 7] = s * (a20 * rm.m01 + a21 * rm.m11 + a22 * rm.m21); + rotations[r + 8] = s * (a20 * rm.m02 + a21 * rm.m12 + a22 * rm.m22); translations[v] = a00 * t.x + a01 * t.y + a02 * t.z + translations[pv]; translations[v + 1] = a10 * t.x + a11 * t.y + a12 * t.z + translations[pv + 1]; diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/GlobalIllumination.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/GlobalIllumination.java index d5fa783..0e2d921 100644 --- a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/GlobalIllumination.java +++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/GlobalIllumination.java @@ -16,52 +16,95 @@ import eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.base.AbstractCom import eu.svjatoslav.aukio.e3d.renderer.raster.texture.Texture; import java.util.ArrayList; +import java.util.Arrays; +import java.util.Comparator; import java.util.IdentityHashMap; import java.util.List; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ThreadLocalRandom; import java.util.concurrent.atomic.AtomicInteger; +import java.util.function.Supplier; /** * Progressive CPU global illumination, running on dedicated low-priority * threads (never on the render ForkJoinPool). * + *

Phased scheduling (default, {@code -De3d.gi.phases=true}): + * the scene is lit in three strict global phases, each ordered by polygon + * distance from the camera, near first:

+ *
    + *
  1. A — centroid direct: each polygon gets one direct-light + * evaluation at its centroid (shadow rays to all lights). The + * result is stamped onto the whole polygon at once — the world + * lights up polygon by polygon as a visible near-to-far wave + * instead of staying at the uniform medium start until a full + * per-texel sweep completes (which does not scale to huge + * scenes).
    2. + *
  2. B — centroid multi-bounce: bounce rays from centroids, + * still one sample point per polygon, feeding the indirect field. + * Cheap enough to converge for the whole scene before any texel + * work starts.
    3. + *
  3. C — per-texel refinement: lightmapped triangles are + * refined near-to-far; a triangle entering this phase has its + * texels seeded from its converged centroid values, so detail + * glides in without a second dark age. A lightmap graduates once + * every texel has been re-sampled at least once — so no + * centroid-seeded shadow value survives — and its on-screen + * estimate has stopped moving; ray sampling then stops and a + * freeze tail keeps recompositing the now-fixed target until the + * on-screen estimate has fully glided in — without the tail, + * graduation would freeze a few light units of residual + * per-triangle stamp bias into the texture forever, visible as + * seams between adjacent triangles. When every lightmap has + * display-frozen, the workers idle.
    4. + *
+ * + *

Phases B and C run on a bounded active window + * ({@code -De3d.gi.activeWindow}, default 256 entries) so near geometry + * converges before CPU is spent on far geometry. When the camera moves + * more than {@code -De3d.gi.resortDistance} (default 25 world units) + * the not-yet-activated work is re-sorted by distance to the new + * position. Scene or light changes rebuild the snapshot and restart + * from phase A. Set {@code -De3d.gi.phases=false} for the legacy flat + * round-robin scheduler.

+ * *

Two sampling resolutions:

* * - *

Estimator: each sample casts one cosine-weighted hemisphere ray - * from the surface. At the hit it evaluates direct light with cached shadow - * tests (next-event estimation) plus the hit surface's current indirect - * estimate, so bounce light propagates deeper over sweeps without an - * explicit recursion limit. Two nested exponential moving averages shape - * what the user sees: the inner per-sample EMA smooths Monte Carlo noise in - * the indirect term, and the outer per-composite-update EMA wraps the - * complete sum ambient+direct+indirect with a fixed alpha — lightmaps start - * at a uniform medium irradiance and glide to the traced solution (lit - * areas brighten, unlit areas sink to darkness), so no black-to-lit flash - * or shadow pop is possible. Scene or light changes rebuild the - * snapshot and restart convergence. When converged, workers idle at a low - * cadence instead of burning CPU.

+ *

Estimator: each bounce sample casts one cosine-weighted + * hemisphere ray from the surface. At the hit it evaluates direct light + * with cached shadow tests (next-event estimation) plus the hit + * surface's current indirect estimate, so bounce light propagates deeper + * over sweeps without an explicit recursion limit. In phase C two nested + * exponential moving averages shape what the user sees: the inner + * per-sample EMA smooths Monte Carlo noise in the indirect term, and the + * outer per-composite-update EMA wraps the complete sum + * ambient+direct+indirect with a fixed alpha, so refinement glides — + * no black-to-lit flash or shadow pop after the deliberate phase-A + * stamp. When converged, workers idle at a low cadence instead of + * burning CPU.

* - *

Render-side cost: zero ray casting. Lightmapped triangles paint - * from their current composite texture; the flat-shading path only reads - * cached per-polygon values. Frame rate is unaffected by GI quality.

+ *

Render-side cost: zero ray casting. Lightmapped triangles + * paint from their current composite texture; the flat-shading path only + * reads cached per-polygon values. Frame rate is unaffected by GI + * quality.

* *

Limitations: diffuse light only; polygon vertices are used in - * composite-local space, so scenes combining composites with non-identity - * transforms are traced incorrectly.

+ * composite-local space, so scenes combining composites with + * non-identity transforms are traced incorrectly.

* *

Usage:

* 
{@code
@@ -102,6 +145,44 @@ public class GlobalIllumination implements GiLightProvider {
     /** Albedo for snapshot entries that carry no flat color (textured triangles). */
     private static final Color FALLBACK_ALBEDO = new Color(128, 128, 128);
 
+    /**
+     * Phased scheduler (centroid direct -> centroid bounce -> per-texel,
+     * near-to-far). False restores the legacy flat round-robin over all
+     * work items. {@code -De3d.gi.phases}.
+     */
+    private static final boolean PHASES =
+            Boolean.parseBoolean(System.getProperty("e3d.gi.phases", "true"));
+
+    /**
+     * Phases B/C: how many entries are sampled concurrently, nearest
+     * first; graduates are replaced by the next-nearest entry.
+     * {@code -De3d.gi.activeWindow}.
+     */
+    private static final int ACTIVE_WINDOW =
+            Integer.parseInt(System.getProperty("e3d.gi.activeWindow", "256"));
+
+    /**
+     * Camera translation (world units) that triggers a re-sort of the
+     * not-yet-activated work queue. {@code -De3d.gi.resortDistance}.
+     */
+    private static final double RESORT_DISTANCE =
+            Double.parseDouble(System.getProperty("e3d.gi.resortDistance", "25"));
+
+    /** Consecutive calm visits/updates that graduate an entry out of the active window. */
+    private static final int GRADUATE_CALM = 3;
+
+    /**
+     * Phase C display freeze: after sampling graduation, a lightmap keeps
+     * recompositing (rays stopped — cheap) until its per-texel estimate
+     * movement falls below this many light units. Graduation can freeze
+     * the outer EMA several light units short of the target (calm at 1.0
+     * with alpha 0.2 = residual distance < 5), which survives as visible
+     * per-triangle seams against neighboring stamps; the tail erodes it
+     * asymptotically. {@code -De3d.gi.freezeThreshold}.
+     */
+    private static final double FREEZE_THRESHOLD =
+            Double.parseDouble(System.getProperty("e3d.gi.freezeThreshold", "0.1"));
+
     /**
      * EMA policy for the inner per-sample indirect blend: "fixed" (default,
      * 0.15) keeps every ray hit equally intensive forever — fading toward
@@ -127,18 +208,33 @@ public class GlobalIllumination implements GiLightProvider {
             Double.parseDouble(System.getProperty("e3d.gi.compositeAlpha", "0.2"));
 
     /**
-     * Convergence: declared after five consecutive composite updates whose
-     * average per-texel estimate movement falls below this many light
-     * units. With a constant alpha the estimate never freezes completely
-     * (Monte Carlo jitter), so this judges the VISIBLE movement, not the
-     * per-sample deltas. {@code -De3d.gi.calmThreshold}.
+     * Convergence: legacy mode declares it after five consecutive composite
+     * updates whose average per-texel estimate movement falls below this
+     * many light units; phased mode uses it as the per-entry calm
+     * threshold for graduation. With a constant alpha the estimate never
+     * freezes completely (Monte Carlo jitter), so this judges the VISIBLE
+     * movement, not the per-sample deltas. {@code -De3d.gi.calmThreshold}.
      */
     private static final double CALM_THRESHOLD =
             Double.parseDouble(System.getProperty("e3d.gi.calmThreshold", "1.0"));
 
+    /** Progressive phases, strict global order. */
+    private enum Phase {
+        /** Direct light at polygon centroids, near-to-far, one visit each. */
+        CENTROID_DIRECT,
+        /** Multi-bounce indirect at polygon centroids, near-to-far windowed. */
+        CENTROID_BOUNCE,
+        /** Per-texel refinement of lightmapped triangles, near-to-far windowed. */
+        TEXEL,
+        /** Everything graduated; workers idle. */
+        DONE
+    }
+
     private final ShapeCollection shapes;
     private final LightingManager lightingManager;
     private final int threadCount;
+    /** Camera position source for distance ordering; null disables sorting/re-sorting. */
+    private final Supplier cameraPosition;
 
     private final List threads = new ArrayList<>();
     private volatile boolean running;
@@ -155,22 +251,53 @@ public class GlobalIllumination implements GiLightProvider {
     private final AtomicInteger workIndex = new AtomicInteger();
     private volatile int calmSweeps;
     private volatile long lastCompositeUpdate;
+
+    /** Last DEBUG heartbeat timestamp (any worker). */
+    private volatile long lastHeartbeat;
     private final java.util.concurrent.atomic.AtomicBoolean compositeUpdateInFlight =
             new java.util.concurrent.atomic.AtomicBoolean();
 
+    // --- Phased scheduler state (guarded by queueLock except where noted) ---
+
+    /** Current phase; volatile, workers read it every iteration. */
+    private volatile Phase phase = Phase.CENTROID_DIRECT;
+    private final Object queueLock = new Object();
+    /** Work queue of the current phase, sorted near-to-far. */
+    private TriangleBvh.Entry[] phaseQueue = new TriangleBvh.Entry[0];
+    /** Phase A: next entry to compute. Phases B/C: next entry to activate. */
+    private int queueCursor;
+    /** Phase A visits currently being processed by a worker. */
+    private final AtomicInteger inFlight = new AtomicInteger();
+    /** Active window entries (phases B/C). */
+    private final List activeList = new ArrayList<>();
+    /** Published snapshot of the active window for lock-free round-robin. */
+    private volatile TriangleBvh.Entry[] active = new TriangleBvh.Entry[0];
+    /** Round-robin cursor over {@link #active}. */
+    private final AtomicInteger activeCursor = new AtomicInteger();
+    /** Camera position at snapshot build / last re-sort. */
+    private double lastCameraX = Double.NaN, lastCameraY, lastCameraZ;
+
     private static class Snapshot {
         List entries;
         TriangleBvh bvh;
         List lights;
         IdentityHashMap lightIndex;
         double ambientR, ambientG, ambientB;
-        /** Flattened work list: one item per lightmap texel / plain polygon. */
+        /** Flattened work list (legacy mode): one item per lightmap texel / plain polygon. */
         WorkItem[] workItems;
         /** All lightmaps in the snapshot (for composite updates). */
         List lightmaps;
+        /** Phased mode: all entries sorted near-to-far from the camera. */
+        TriangleBvh.Entry[] sortedByDistance;
+        /** Phased mode: lightmapped entries only, sorted near-to-far. */
+        TriangleBvh.Entry[] lightmappedSorted;
+        /** Phased mode: lightmap back to its snapshot entry (phase C graduation). */
+        IdentityHashMap lightmapEntry;
+        /** Phase C lightmaps that graduated sampling but have not display-frozen yet. */
+        int tailCount;
     }
 
-    /** One unit of GI work: a lightmap texel, or a whole plain polygon. */
+    /** One unit of legacy GI work: a lightmap texel, or a whole plain polygon. */
     private static class WorkItem {
         TriangleBvh.Entry entry;
         int texel; // -1 = plain polygon
@@ -187,6 +314,7 @@ public class GlobalIllumination implements GiLightProvider {
 
     /**
      * Creates the GI system. Call {@link #start()} to begin tracing.
+     * Distance ordering is disabled (uniform order, no camera re-sort).
      *
      * @param shapes          the scene to trace
      * @param lightingManager the lights to sample
@@ -195,9 +323,27 @@ public class GlobalIllumination implements GiLightProvider {
     public GlobalIllumination(final ShapeCollection shapes,
                               final LightingManager lightingManager,
                               final int threadCount) {
+        this(shapes, lightingManager, threadCount, null);
+    }
+
+    /**
+     * Creates the GI system. Call {@link #start()} to begin tracing.
+     *
+     * @param shapes          the scene to trace
+     * @param lightingManager the lights to sample
+     * @param threadCount     dedicated worker threads (2 is a good default)
+     * @param cameraPosition  supplies the camera position for near-to-far
+     *                        ordering and re-sort triggers; null disables
+     *                        distance ordering (uniform order)
+     */
+    public GlobalIllumination(final ShapeCollection shapes,
+                              final LightingManager lightingManager,
+                              final int threadCount,
+                              final Supplier cameraPosition) {
         this.shapes = shapes;
         this.lightingManager = lightingManager;
         this.threadCount = Math.max(1, threadCount);
+        this.cameraPosition = cameraPosition;
     }
 
     /** Registers the GI provider and starts the worker threads. */
@@ -235,26 +381,31 @@ public class GlobalIllumination implements GiLightProvider {
 
     /**
      * Returns whether the solution has converged (workers idling at a low
-     * duty cycle). Convergence is declared after five consecutive composite
-     * updates whose average per-texel estimate movement is below
-     * {@code e3d.gi.calmThreshold} (default 1.0 light unit).
+     * duty cycle). Legacy mode: five consecutive composite updates below
+     * {@code e3d.gi.calmThreshold}. Phased mode: all phases drained
+     * (every entry graduated out of the active window).
      *
      * @return {@code true} when converged
      */
     public boolean isConverged() {
-        return calmSweeps >= 5;
+        return PHASES ? phase == Phase.DONE : calmSweeps >= 5;
     }
 
     /**
-     * Returns the number of work items in the current scene snapshot
-     * (one per lightmap texel plus one per plain polygon), or 0 when no
-     * snapshot has been built yet.
+     * Returns the number of schedulable work units in the current scene
+     * snapshot: phased mode counts polygons, legacy mode counts one item
+     * per lightmap texel plus one per plain polygon. 0 when no snapshot
+     * has been built yet.
      *
-     * @return the work item count
+     * @return the work unit count
      */
     public int getWorkItemCount() {
         final Snapshot snap = snapshot;
-        return snap == null || snap.workItems == null ? 0 : snap.workItems.length;
+        if (snap == null)
+            return 0;
+        if (PHASES)
+            return snap.sortedByDistance == null ? 0 : snap.sortedByDistance.length;
+        return snap.workItems == null ? 0 : snap.workItems.length;
     }
 
     // ------------------------------------------------------------------
@@ -301,46 +452,50 @@ public class GlobalIllumination implements GiLightProvider {
             try {
                 maybeRebuildSnapshot();
                 final Snapshot snap = snapshot;
-                if (snap == null || snap.workItems.length == 0) {
+                if (snap == null || snap.entries.isEmpty()) {
                     Thread.sleep(100);
                     continue;
                 }
 
-                // One sweep over all work items. Convergence is judged by
-                // composite-estimate movement inside updateComposites()
-                // (per-sample deltas are Monte Carlo noise and, with the
-                // fixed alpha, never settle).
                 final long sweepStart = System.currentTimeMillis();
-                final int size = snap.workItems.length;
-                double deltaSum = 0;
-                for (int i = 0; i < size && running; i++) {
-                    final int index = Math.floorMod(workIndex.getAndIncrement(), size);
-                    deltaSum += sample(snap, snap.workItems[index], hit, pos);
-                }
-                final double avgDelta = deltaSum / size;
+                if (PHASES)
+                    phasedStep(snap, hit, pos);
+                else
+                    legacySweep(snap, hit, pos);
 
                 // Regenerate composite textures at most every
                 // COMPOSITE_INTERVAL_MS; a paint pass is one texture swap
-                // per triangle, invisible to the render threads. Also
-                // advances the convergence counter.
+                // per triangle, invisible to the render threads.
                 final long now = System.currentTimeMillis();
                 if (now - lastCompositeUpdate >= COMPOSITE_INTERVAL_MS) {
                     updateComposites(snap);
                     lastCompositeUpdate = now;
                 }
 
-                if (DEBUG)
-                    System.out.println("[GI] sweep done, avgDelta=" + String.format("%.2f", avgDelta)
-                            + ", calmSweeps=" + calmSweeps);
+                // Heartbeat: where the scheduler sits; a stall (phase not
+                // DONE forever) shows up as an unchanging line.
+                if (DEBUG && PHASES && now - lastHeartbeat >= 10000) {
+                    lastHeartbeat = now;
+                    synchronized (queueLock) {
+                        System.out.println("[GI] heartbeat: phase=" + phase
+                                + " active=" + activeList.size()
+                                + " queue=" + queueCursor + "/" + phaseQueue.length
+                                + " tail=" + snap.tailCount);
+                    }
+                }
 
                 if (isConverged()) {
-                    // Converged: cap duty cycle at ~50% of sweep time
-                    // (a big scene's sweep takes seconds; a flat 250ms
-                    // sleep would barely throttle it). Hard cap keeps
-                    // post-edit re-convergence prompt.
-                    final long sweepMillis = System.currentTimeMillis() - sweepStart;
-                    Thread.sleep(Math.min(IDLE_SLEEP_MAX_MS,
-                            Math.max(IDLE_SLEEP_MS, sweepMillis)));
+                    // Converged: cap duty cycle. Legacy mode proportions
+                    // the sleep to the sweep; phased DONE has no sweep
+                    // concept and sleeps at the minimum cadence (a scene
+                    // edit rebuilds the snapshot and restarts phase A).
+                    if (PHASES)
+                        Thread.sleep(IDLE_SLEEP_MS);
+                    else {
+                        final long sweepMillis = System.currentTimeMillis() - sweepStart;
+                        Thread.sleep(Math.min(IDLE_SLEEP_MAX_MS,
+                                Math.max(IDLE_SLEEP_MS, sweepMillis)));
+                    }
                 }
             } catch (final InterruptedException e) {
                 return;
@@ -355,119 +510,523 @@ public class GlobalIllumination implements GiLightProvider {
         }
     }
 
-    /** One progressive sample: one shadow ray + one bounce ray. */
+    /** Legacy scheduler: one round-robin sweep over all work items. */
+    private void legacySweep(final Snapshot snap, final TriangleBvh.Hit hit, final double[] pos) {
+        if (snap.workItems.length == 0)
+            return;
+        // Convergence is judged by composite-estimate movement inside
+        // updateComposites() (per-sample deltas are Monte Carlo noise and,
+        // with the fixed alpha, never settle).
+        final int size = snap.workItems.length;
+        double deltaSum = 0;
+        for (int i = 0; i < size && running; i++) {
+            final int index = Math.floorMod(workIndex.getAndIncrement(), size);
+            deltaSum += sample(snap, snap.workItems[index], hit, pos);
+        }
+        if (DEBUG)
+            System.out.println("[GI] sweep done, avgDelta=" + String.format("%.2f", deltaSum / size)
+                    + ", calmSweeps=" + calmSweeps);
+    }
+
+    // ------------------------------------------------------------------
+    // Phased scheduler
+    // ------------------------------------------------------------------
+
+    /** One phased work step: a phase-A one-shot, or one sample in the active window. */
+    private void phasedStep(final Snapshot snap, final TriangleBvh.Hit hit,
+                            final double[] pos) throws InterruptedException {
+        maybeResort(snap);
+        switch (phase) {
+            case CENTROID_DIRECT: {
+                final TriangleBvh.Entry entry = grabPhaseA();
+                if (entry == null) {
+                    advancePhaseIfDrained(snap);
+                    Thread.sleep(10);
+                    return;
+                }
+                try {
+                    sampleCentroidDirect(snap, entry);
+                } finally {
+                    inFlight.decrementAndGet();
+                }
+                return;
+            }
+            case CENTROID_BOUNCE: {
+                final TriangleBvh.Entry entry = grabActive();
+                if (entry == null) {
+                    advancePhaseIfDrained(snap);
+                    Thread.sleep(10);
+                    return;
+                }
+                if (entry.graduated)
+                    return; // raced with graduation: the extra visit is pointless
+                final double delta = sampleCentroidBounce(snap, entry, hit);
+                if (delta < CALM_THRESHOLD) {
+                    if (++entry.calmVisits >= GRADUATE_CALM)
+                        // The sample took time; a B->C transition may have
+                        // happened meanwhile. Graduating now would mark the
+                        // entry done without phase C ever seeing it (the
+                        // window fill skips graduated entries), and would
+                        // leak a freeze-tail slot: guard on the phase.
+                        graduate(entry, Phase.CENTROID_BOUNCE);
+                } else {
+                    entry.calmVisits = 0;
+                }
+                return;
+            }
+            case TEXEL: {
+                final TriangleBvh.Entry entry = grabActive();
+                if (entry == null) {
+                    advancePhaseIfDrained(snap);
+                    Thread.sleep(10);
+                    return;
+                }
+                if (entry.graduated)
+                    return;
+                final Lightmap lightmap = entry.lightmap;
+                final int texel = lightmap.validTexels[
+                        Math.floorMod(lightmap.nextTexel++, lightmap.validTexels.length)];
+                sampleTexel(snap, entry, texel, hit, pos);
+                return;
+            }
+            default:
+                // DONE: nothing to sample; the converged sleep is in workLoop.
+        }
+    }
+
+    /** Phase A: takes the next uncomputed entry, or null when the queue is drained. */
+    private TriangleBvh.Entry grabPhaseA() {
+        synchronized (queueLock) {
+            if (queueCursor >= phaseQueue.length)
+                return null;
+            inFlight.incrementAndGet();
+            return phaseQueue[queueCursor++];
+        }
+    }
+
+    /** Phases B/C: round-robin pick from the active window, or null when empty. */
+    private TriangleBvh.Entry grabActive() {
+        final TriangleBvh.Entry[] act = active;
+        if (act.length == 0)
+            return null;
+        return act[Math.floorMod(activeCursor.getAndIncrement(), act.length)];
+    }
+
+    /**
+     * Advances the phase when the current one is drained: phase A on queue
+     * drain with zero in-flight visits, phases B/C when the window is empty
+     * and no entries remain to activate.
+     */
+    private void advancePhaseIfDrained(final Snapshot snap) {
+        synchronized (queueLock) {
+            switch (phase) {
+                case CENTROID_DIRECT:
+                    if (queueCursor >= phaseQueue.length && inFlight.get() == 0) {
+                        phase = Phase.CENTROID_BOUNCE;
+                        phaseQueue = snap.sortedByDistance;
+                        queueCursor = 0;
+                        fillActiveWindowLocked();
+                        if (DEBUG)
+                            System.out.println("[GI] phase A drained, entering centroid bounce");
+                    }
+                    break;
+                case CENTROID_BOUNCE:
+                    if (activeList.isEmpty() && queueCursor >= phaseQueue.length) {
+                        phase = Phase.TEXEL;
+                        phaseQueue = snap.lightmappedSorted;
+                        queueCursor = 0;
+                        // Phase B graduated every entry; phase C reuses the
+                        // same Entry objects, so re-arm graduation for the
+                        // per-texel convergence judgement.
+                        for (final TriangleBvh.Entry entry : phaseQueue) {
+                            entry.graduated = false;
+                            entry.calmVisits = 0;
+                        }
+                        fillActiveWindowLocked();
+                        if (DEBUG)
+                            System.out.println("[GI] phase B converged, entering per-texel refinement ("
+                                    + phaseQueue.length + " lightmaps)");
+                    }
+                    break;
+                case TEXEL:
+                    if (activeList.isEmpty() && queueCursor >= phaseQueue.length
+                            && snap.tailCount == 0) {
+                        phase = Phase.DONE;
+                        if (DEBUG)
+                            System.out.println("[GI] phase C converged, GI idling");
+                    }
+                    break;
+                default:
+            }
+        }
+    }
+
+    /**
+     * Moves an entry out of the active window and backfills from the queue.
+     * The graduation only applies when the engine is still in {@code expected}
+     * phase: a sample that started before a phase transition must not
+     * graduate the entry in the new phase (it would be skipped there
+     * forever, and in phase C would leak a freeze-tail slot).
+     */
+    private void graduate(final TriangleBvh.Entry entry, final Phase expected) {
+        synchronized (queueLock) {
+            if (phase != expected || entry.graduated)
+                return;
+            entry.graduated = true;
+            activeList.remove(entry);
+            final Snapshot snap = snapshot;
+            if (phase == Phase.TEXEL && snap != null)
+                snap.tailCount++; // enters the display-freeze tail
+            fillActiveWindowLocked();
+        }
+    }
+
+    /** Fills the active window from the queue up to {@link #ACTIVE_WINDOW}. */
+    private void fillActiveWindowLocked() {
+        while (activeList.size() < ACTIVE_WINDOW && queueCursor < phaseQueue.length) {
+            final TriangleBvh.Entry entry = phaseQueue[queueCursor++];
+            if (entry.graduated)
+                continue;
+            if (phase == Phase.TEXEL)
+                entry.lightmap.texelPhase = true;
+            activeList.add(entry);
+        }
+        active = activeList.toArray(new TriangleBvh.Entry[0]);
+    }
+
+    /**
+     * Re-sorts the not-yet-activated queue tail when the camera has moved
+     * more than {@link #RESORT_DISTANCE} since the snapshot build or the
+     * last re-sort. Active and graduated entries keep their state.
+     */
+    private void maybeResort(final Snapshot snap) {
+        if (cameraPosition == null)
+            return;
+        final Point3D cam = cameraPosition.get();
+        if (cam == null)
+            return;
+        if (Double.isNaN(lastCameraX)) {
+            lastCameraX = cam.x;
+            lastCameraY = cam.y;
+            lastCameraZ = cam.z;
+            return;
+        }
+        final double dx = cam.x - lastCameraX;
+        final double dy = cam.y - lastCameraY;
+        final double dz = cam.z - lastCameraZ;
+        if (dx * dx + dy * dy + dz * dz <= RESORT_DISTANCE * RESORT_DISTANCE)
+            return;
+        synchronized (queueLock) {
+            // Re-check under the lock: another worker may have re-sorted already.
+            final double dx2 = cam.x - lastCameraX;
+            final double dy2 = cam.y - lastCameraY;
+            final double dz2 = cam.z - lastCameraZ;
+            if (dx2 * dx2 + dy2 * dy2 + dz2 * dz2 <= RESORT_DISTANCE * RESORT_DISTANCE)
+                return;
+            lastCameraX = cam.x;
+            lastCameraY = cam.y;
+            lastCameraZ = cam.z;
+            final int from = queueCursor;
+            if (from >= phaseQueue.length)
+                return;
+            for (int i = from; i < phaseQueue.length; i++)
+                phaseQueue[i].distance = distanceSquared(phaseQueue[i], cam);
+            Arrays.sort(phaseQueue, from, phaseQueue.length,
+                    Comparator.comparingDouble(e -> e.distance));
+            if (DEBUG)
+                System.out.println("[GI] re-sorted " + (phaseQueue.length - from)
+                        + " pending entries (camera moved)");
+        }
+    }
+
+    private static float distanceSquared(final TriangleBvh.Entry entry, final Point3D cam) {
+        final double dx = entry.centroidX - cam.x;
+        final double dy = entry.centroidY - cam.y;
+        final double dz = entry.centroidZ - cam.z;
+        return (float) (dx * dx + dy * dy + dz * dz);
+    }
+
+    // ------------------------------------------------------------------
+    // Sampling
+    // ------------------------------------------------------------------
+
+    /** One legacy progressive sample: one shadow ray + one bounce ray. */
     private double sample(final Snapshot snap, final WorkItem item,
                           final TriangleBvh.Hit hit, final double[] pos) {
-        final TriangleBvh.Entry entry = item.entry;
-        final Lightmap lightmap = entry.lightmap;
+        if (item.entry.lightmap != null)
+            return sampleTexel(snap, item.entry, item.texel, hit, pos);
+        return samplePlain(snap, item.entry, true, hit);
+    }
 
-        final double ox, oy, oz, nx, ny, nz;
-        if (lightmap != null) {
-            lightmap.texelWorldPosition(item.texel, pos);
-            nx = lightmap.normalX;
-            ny = lightmap.normalY;
-            nz = lightmap.normalZ;
-            ox = pos[0] + nx * ORIGIN_EPSILON;
-            oy = pos[1] + ny * ORIGIN_EPSILON;
-            oz = pos[2] + nz * ORIGIN_EPSILON;
-        } else {
-            nx = entry.normal[0];
-            ny = entry.normal[1];
-            nz = entry.normal[2];
-            ox = entry.centroidX + nx * ORIGIN_EPSILON;
-            oy = entry.centroidY + ny * ORIGIN_EPSILON;
-            oz = entry.centroidZ + nz * ORIGIN_EPSILON;
-        }
+    /**
+     * Samples one lightmap texel: shadow ray(s) plus one bounce ray and
+     * the per-texel indirect EMA update. Used by the legacy scheduler and
+     * by phased mode's phase C.
+     *
+     * @return the EMA-weighted estimate delta (convergence signal)
+     */
+    private double sampleTexel(final Snapshot snap, final TriangleBvh.Entry entry,
+                               final int texel, final TriangleBvh.Hit hit, final double[] pos) {
+        final Lightmap lightmap = entry.lightmap;
+        lightmap.texelWorldPosition(texel, pos);
+        final double nx = lightmap.normalX;
+        final double ny = lightmap.normalY;
+        final double nz = lightmap.normalZ;
+        final double ox = pos[0] + nx * ORIGIN_EPSILON;
+        final double oy = pos[1] + ny * ORIGIN_EPSILON;
+        final double oz = pos[2] + nz * ORIGIN_EPSILON;
 
         // 1. Shadow rays. First visit per texel: test ALL lights, so direct
         // light + hard shadows appear after one sweep instead of trickling
         // in over lightCount sweeps. Afterwards: one light, round-robin.
         final int lightCount = snap.lights.size();
+        final boolean firstVisit = lightmap.sampleCounts[texel] == 0;
+        if (firstVisit)
+            lightmap.texelsSampled++; // graduation requires full coverage
         if (lightCount > 0) {
-            if (lightmap != null) {
-                lightmap.ensureLightCapacity(lightCount);
-                final boolean firstVisit = lightmap.sampleCounts[item.texel] == 0;
-                if (firstVisit) {
-                    for (int i = 0; i < lightCount && i < MAX_TRACKED_LIGHTS; i++)
-                        lightmap.lightVisibility[item.texel * lightCount + i] =
-                                shadowTest(snap, ox, oy, oz, nx, ny, nz, snap.lights.get(i))
-                                        ? Lightmap.VISIBILITY_VISIBLE : Lightmap.VISIBILITY_OCCLUDED;
-                } else {
-                    final int lightIdx = lightmap.nextLight++ % lightCount;
-                    lightmap.lightVisibility[item.texel * lightCount + lightIdx] =
-                            shadowTest(snap, ox, oy, oz, nx, ny, nz, snap.lights.get(lightIdx))
+            lightmap.ensureLightCapacity(lightCount);
+            if (firstVisit) {
+                for (int i = 0; i < lightCount && i < MAX_TRACKED_LIGHTS; i++)
+                    lightmap.lightVisibility[texel * lightCount + i] =
+                            shadowTest(snap, ox, oy, oz, nx, ny, nz, snap.lights.get(i))
                                     ? Lightmap.VISIBILITY_VISIBLE : Lightmap.VISIBILITY_OCCLUDED;
-                }
             } else {
-                final GiState state = states.computeIfAbsent(entry.polygon, p -> new GiState());
-                final int lightIdx = state.nextLight++ % lightCount;
-                final boolean visible = shadowTest(snap, ox, oy, oz, nx, ny, nz, snap.lights.get(lightIdx));
-                final long bit = 1L << lightIdx;
-                synchronized (state) {
-                    state.visibleBits = visible ? (state.visibleBits | bit) : (state.visibleBits & ~bit);
-                    state.knownBits |= bit;
-                }
+                final int lightIdx = lightmap.nextLight++ % lightCount;
+                lightmap.lightVisibility[texel * lightCount + lightIdx] =
+                        shadowTest(snap, ox, oy, oz, nx, ny, nz, snap.lights.get(lightIdx))
+                                ? Lightmap.VISIBILITY_VISIBLE : Lightmap.VISIBILITY_OCCLUDED;
             }
         }
 
-        // 2. Bounce ray: cosine-weighted hemisphere around the normal.
-        final double[] dir = cosineHemisphere(nx, ny, nz, ThreadLocalRandom.current());
+        // 2. Bounce ray + per-texel EMA update.
+        final double[] target = bounceTarget(snap, nx, ny, nz, ox, oy, oz, hit);
+
+        final int count = Math.min(32000, ++lightmap.sampleCounts[texel]);
+        final float alpha = "fixed".equals(ALPHA_MODE) ? 0.15f
+                : (float) Math.max(ALPHA_FLOOR, 2f / (2f + count));
+        final float dR = (float) (target[0] - lightmap.indirectR[texel]);
+        final float dG = (float) (target[1] - lightmap.indirectG[texel]);
+        final float dB = (float) (target[2] - lightmap.indirectB[texel]);
+        lightmap.indirectR[texel] += alpha * dR;
+        lightmap.indirectG[texel] += alpha * dG;
+        lightmap.indirectB[texel] += alpha * dB;
+        return Math.max(Math.abs(dR), Math.max(Math.abs(dG), Math.abs(dB))) * alpha;
+    }
 
-        double targetR = 0, targetG = 0, targetB = 0;
-        if (snap.bvh.nearest(ox, oy, oz, dir[0], dir[1], dir[2], hit)) {
-            // Direct irradiance at the hit point (clamped to display range)
-            // plus the hit surface's current indirect estimate.
-            final double[] irr = directIrradiance(snap, hit);
-            final Color hitColor = colorOf(hit.entry);
-            final float hiR, hiG, hiB;
-            if (hit.entry.lightmap != null) {
-                final int hitTexel = hit.entry.lightmap.texelAt(hit.pointX, hit.pointY, hit.pointZ);
-                hiR = hit.entry.lightmap.indirectR[hitTexel];
-                hiG = hit.entry.lightmap.indirectG[hitTexel];
-                hiB = hit.entry.lightmap.indirectB[hitTexel];
-            } else {
-                final GiState hitState = states.get(hit.entry.polygon);
-                hiR = hitState == null ? 0 : hitState.indirectR;
-                hiG = hitState == null ? 0 : hitState.indirectG;
-                hiB = hitState == null ? 0 : hitState.indirectB;
+    /**
+     * Per-polygon sample for plain solid polygons: one bounce ray and the
+     * indirect EMA update, plus shadow rays unless they were settled in
+     * phase A.
+     *
+     * @param withShadowRays true in legacy mode (one light, round-robin);
+     *                       false in phased mode's phase B
+     * @return the EMA-weighted estimate delta (convergence signal)
+     */
+    private double samplePlain(final Snapshot snap, final TriangleBvh.Entry entry,
+                               final boolean withShadowRays, final TriangleBvh.Hit hit) {
+        final double nx = entry.normal[0];
+        final double ny = entry.normal[1];
+        final double nz = entry.normal[2];
+        final double ox = entry.centroidX + nx * ORIGIN_EPSILON;
+        final double oy = entry.centroidY + ny * ORIGIN_EPSILON;
+        final double oz = entry.centroidZ + nz * ORIGIN_EPSILON;
+
+        final GiState state = states.computeIfAbsent(entry.polygon, p -> new GiState());
+        final int lightCount = snap.lights.size();
+        if (withShadowRays && lightCount > 0) {
+            final int lightIdx = state.nextLight++ % lightCount;
+            final boolean visible = shadowTest(snap, ox, oy, oz, nx, ny, nz, snap.lights.get(lightIdx));
+            final long bit = 1L << lightIdx;
+            synchronized (state) {
+                state.visibleBits = visible ? (state.visibleBits | bit) : (state.visibleBits & ~bit);
+                state.knownBits |= bit;
             }
-            targetR = BOUNCE_GAIN * hitColor.r * (irr[0] + hiR) / 255.0;
-            targetG = BOUNCE_GAIN * hitColor.g * (irr[1] + hiG) / 255.0;
-            targetB = BOUNCE_GAIN * hitColor.b * (irr[2] + hiB) / 255.0;
         }
 
-        // Inner EMA update. "fixed" mode (default): every ray hit lands
-        // with the same weight forever, so unlit areas keep fading to
-        // darkness at the same rate lit areas brighten. "adaptive" mode:
-        // alpha starts at ~1 and decays with sample count (floored).
-        if (lightmap != null) {
-            final int count = Math.min(32000, ++lightmap.sampleCounts[item.texel]);
+        final double[] target = bounceTarget(snap, nx, ny, nz, ox, oy, oz, hit);
+        synchronized (state) {
+            final int count = Math.min(32000, ++state.samples);
             final float alpha = "fixed".equals(ALPHA_MODE) ? 0.15f
                     : (float) Math.max(ALPHA_FLOOR, 2f / (2f + count));
-            final float dR = (float) (targetR - lightmap.indirectR[item.texel]);
-            final float dG = (float) (targetG - lightmap.indirectG[item.texel]);
-            final float dB = (float) (targetB - lightmap.indirectB[item.texel]);
-            lightmap.indirectR[item.texel] += alpha * dR;
-            lightmap.indirectG[item.texel] += alpha * dG;
-            lightmap.indirectB[item.texel] += alpha * dB;
+            final float dR = (float) (target[0] - state.indirectR);
+            final float dG = (float) (target[1] - state.indirectG);
+            final float dB = (float) (target[2] - state.indirectB);
+            state.indirectR += alpha * dR;
+            state.indirectG += alpha * dG;
+            state.indirectB += alpha * dB;
             return Math.max(Math.abs(dR), Math.max(Math.abs(dG), Math.abs(dB))) * alpha;
+        }
+    }
+
+    /**
+     * Phase A: computes ambient + direct irradiance at the polygon
+     * centroid with shadow rays to ALL lights, then stamps the result
+     * onto the whole polygon at once. Lightmapped triangles flip their
+     * composite texture to the flat centroid value (the visible wave);
+     * plain polygons publish per-light visibility for the flat-shading
+     * path.
+     */
+    private void sampleCentroidDirect(final Snapshot snap, final TriangleBvh.Entry entry) {
+        final double nx = entry.normal[0];
+        final double ny = entry.normal[1];
+        final double nz = entry.normal[2];
+        final double ox = entry.centroidX + nx * ORIGIN_EPSILON;
+        final double oy = entry.centroidY + ny * ORIGIN_EPSILON;
+        final double oz = entry.centroidZ + nz * ORIGIN_EPSILON;
+
+        final int lightCount = snap.lights.size();
+        final int tracked = Math.min(lightCount, MAX_TRACKED_LIGHTS);
+        final boolean[] visible = new boolean[tracked];
+
+        double r = snap.ambientR, g = snap.ambientG, b = snap.ambientB;
+        for (int i = 0; i < tracked; i++) {
+            final LightSource light = snap.lights.get(i);
+            visible[i] = shadowTest(snap, ox, oy, oz, nx, ny, nz, light);
+            if (!visible[i])
+                continue;
+            final Point3D lightPos = light.getPosition();
+            final double dx = lightPos.x - ox;
+            final double dy = lightPos.y - oy;
+            final double dz = lightPos.z - oz;
+            final double dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+            if (dist < 0.0001)
+                continue;
+            final double dot = (nx * dx + ny * dy + nz * dz) / dist;
+            if (dot <= 0)
+                continue;
+            final double attenuation = 1.0 / (1.0 + 0.0001 * dist * dist);
+            final double intensity = dot * attenuation * light.getIntensity();
+            final Color lightColor = light.getColor();
+            r += lightColor.r * intensity;
+            g += lightColor.g * intensity;
+            b += lightColor.b * intensity;
+        }
+
+        final Lightmap lightmap = entry.lightmap;
+        if (lightmap != null) {
+            lightmap.ensureLightCapacity(lightCount);
+            if (tracked > 0) {
+                final byte[] centroidVisibility = new byte[lightCount];
+                for (int i = 0; i < tracked; i++)
+                    centroidVisibility[i] = visible[i]
+                            ? Lightmap.VISIBILITY_VISIBLE : Lightmap.VISIBILITY_OCCLUDED;
+                lightmap.seedCentroidVisibility(centroidVisibility);
+            }
+            lightmap.centroidR = (float) Math.min(255, r);
+            lightmap.centroidG = (float) Math.min(255, g);
+            lightmap.centroidB = (float) Math.min(255, b);
+            lightmap.seedDisplay(lightmap.centroidR, lightmap.centroidG, lightmap.centroidB);
+            lightmap.centroidReady = true;
         } else {
             final GiState state = states.computeIfAbsent(entry.polygon, p -> new GiState());
             synchronized (state) {
-                final int count = Math.min(32000, ++state.samples);
-                final float alpha = "fixed".equals(ALPHA_MODE) ? 0.15f
-                        : (float) Math.max(ALPHA_FLOOR, 2f / (2f + count));
-                final float dR = (float) (targetR - state.indirectR);
-                final float dG = (float) (targetG - state.indirectG);
-                final float dB = (float) (targetB - state.indirectB);
-                state.indirectR += alpha * dR;
-                state.indirectG += alpha * dG;
-                state.indirectB += alpha * dB;
-                return Math.max(Math.abs(dR), Math.max(Math.abs(dG), Math.abs(dB))) * alpha;
+                for (int i = 0; i < tracked; i++) {
+                    final long bit = 1L << i;
+                    state.visibleBits = visible[i]
+                            ? (state.visibleBits | bit) : (state.visibleBits & ~bit);
+                    state.knownBits |= bit;
+                }
             }
         }
     }
 
+    /**
+     * Phase B: one bounce ray from the polygon centroid, blended into the
+     * centroid indirect estimate. Cheap enough to run scene-wide before
+     * any per-texel work starts.
+     *
+     * @return the normalized graduation signal: the EMA-weighted centroid
+     *         indirect delta scaled so that "calm" means below 1 light unit
+     *         or below 2% of the tracked magnitude (bright entries must be
+     *         able to graduate)
+     */
+    private double sampleCentroidBounce(final Snapshot snap, final TriangleBvh.Entry entry,
+                                        final TriangleBvh.Hit hit) {
+        final double nx = entry.normal[0];
+        final double ny = entry.normal[1];
+        final double nz = entry.normal[2];
+        final double ox = entry.centroidX + nx * ORIGIN_EPSILON;
+        final double oy = entry.centroidY + ny * ORIGIN_EPSILON;
+        final double oz = entry.centroidZ + nz * ORIGIN_EPSILON;
+
+        final double[] target = bounceTarget(snap, nx, ny, nz, ox, oy, oz, hit);
+
+        final int count = Math.min(32000, ++entry.centroidSamples);
+        final float alpha = "fixed".equals(ALPHA_MODE) ? 0.15f
+                : (float) Math.max(ALPHA_FLOOR, 2f / (2f + count));
+        final Lightmap lightmap = entry.lightmap;
+        if (lightmap != null) {
+            final float dR = (float) (target[0] - lightmap.centroidIndirectR);
+            final float dG = (float) (target[1] - lightmap.centroidIndirectG);
+            final float dB = (float) (target[2] - lightmap.centroidIndirectB);
+            lightmap.centroidIndirectR += alpha * dR;
+            lightmap.centroidIndirectG += alpha * dG;
+            lightmap.centroidIndirectB += alpha * dB;
+            return graduationSignal(
+                    Math.max(Math.abs(dR), Math.max(Math.abs(dG), Math.abs(dB))) * alpha,
+                    (lightmap.centroidIndirectR + lightmap.centroidIndirectG
+                            + lightmap.centroidIndirectB) / 3.0);
+        }
+        final GiState state = states.computeIfAbsent(entry.polygon, p -> new GiState());
+        synchronized (state) {
+            final float dR = (float) (target[0] - state.indirectR);
+            final float dG = (float) (target[1] - state.indirectG);
+            final float dB = (float) (target[2] - state.indirectB);
+            state.indirectR += alpha * dR;
+            state.indirectG += alpha * dG;
+            state.indirectB += alpha * dB;
+            return graduationSignal(
+                    Math.max(Math.abs(dR), Math.max(Math.abs(dG), Math.abs(dB))) * alpha,
+                    (state.indirectR + state.indirectG + state.indirectB) / 3.0);
+        }
+    }
+
+    /**
+     * Normalizes a graduation delta against the magnitude of the value being
+     * tracked: Monte Carlo jitter scales with brightness, so an absolute
+     * threshold can never be reached by a bright entry (it would squat in
+     * the active window forever and starve everything behind it). Calm when
+     * the raw delta is below 1.0 light unit or below 2% of the magnitude.
+     */
+    private static double graduationSignal(final double rawDelta, final double magnitude) {
+        return rawDelta / Math.max(1.0, 0.02 * magnitude);
+    }
+
+    /**
+     * One cosine-weighted bounce ray from the given surface point.
+     *
+     * @return bounce target radiance contribution {r, g, b}, zeros on a miss
+     */
+    private double[] bounceTarget(final Snapshot snap,
+                                  final double nx, final double ny, final double nz,
+                                  final double ox, final double oy, final double oz,
+                                  final TriangleBvh.Hit hit) {
+        final double[] dir = cosineHemisphere(nx, ny, nz, ThreadLocalRandom.current());
+        if (!snap.bvh.nearest(ox, oy, oz, dir[0], dir[1], dir[2], hit))
+            return new double[3];
+
+        // Direct irradiance at the hit point (clamped to display range)
+        // plus the hit surface's current indirect estimate.
+        final double[] irr = directIrradiance(snap, hit);
+        final Color hitColor = colorOf(hit.entry);
+        final float hiR, hiG, hiB;
+        if (hit.entry.lightmap != null) {
+            final int hitTexel = hit.entry.lightmap.texelAt(hit.pointX, hit.pointY, hit.pointZ);
+            hiR = hit.entry.lightmap.indirectR[hitTexel];
+            hiG = hit.entry.lightmap.indirectG[hitTexel];
+            hiB = hit.entry.lightmap.indirectB[hitTexel];
+        } else {
+            final GiState hitState = states.get(hit.entry.polygon);
+            hiR = hitState == null ? 0 : hitState.indirectR;
+            hiG = hitState == null ? 0 : hitState.indirectG;
+            hiB = hitState == null ? 0 : hitState.indirectB;
+        }
+        return new double[]{
+                BOUNCE_GAIN * hitColor.r * (irr[0] + hiR) / 255.0,
+                BOUNCE_GAIN * hitColor.g * (irr[1] + hiG) / 255.0,
+                BOUNCE_GAIN * hitColor.b * (irr[2] + hiB) / 255.0};
+    }
+
     /** Shadow ray from a surface point toward a light. */
     private boolean shadowTest(final Snapshot snap,
                                final double ox, final double oy, final double oz,
@@ -564,136 +1123,229 @@ public class GlobalIllumination implements GiLightProvider {
         if (!compositeUpdateInFlight.compareAndSet(false, true))
             return;
         try {
-            final int lightCount = snap.lights.size();
-            final double[] pos = new double[3];
-            double movementSum = 0;
-            long texelTotal = 0;
-            for (final Lightmap lightmap : snap.lightmaps) {
-                lightmap.ensureLightCapacity(lightCount);
-                final int width = lightmap.width;
-                final int height = lightmap.height;
-                final int texelCount = width * height;
-
-                // 1. Total irradiance per valid texel (float, no clamping yet).
-                final float[] irrR = new float[texelCount];
-                final float[] irrG = new float[texelCount];
-                final float[] irrB = new float[texelCount];
-                for (final int texel : lightmap.validTexels) {
-                    lightmap.texelWorldPosition(texel, pos);
-                    double r = snap.ambientR, g = snap.ambientG, b = snap.ambientB;
-                    for (int i = 0; i < lightCount && i < MAX_TRACKED_LIGHTS; i++) {
-                        if (lightmap.lightVisibility[texel * lightCount + i] == Lightmap.VISIBILITY_OCCLUDED)
-                            continue;
-                        final LightSource light = snap.lights.get(i);
-                        final Point3D lightPos = light.getPosition();
-                        final double dx = lightPos.x - pos[0];
-                        final double dy = lightPos.y - pos[1];
-                        final double dz = lightPos.z - pos[2];
-                        final double dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
-                        if (dist < 0.0001)
-                            continue;
-                        final double dot = (lightmap.normalX * dx + lightmap.normalY * dy
-                                + lightmap.normalZ * dz) / dist;
-                        if (dot <= 0)
-                            continue;
-                        final double attenuation = 1.0 / (1.0 + 0.0001 * dist * dist);
-                        final double intensity = dot * attenuation * light.getIntensity();
-                        final Color lightColor = light.getColor();
-                        r += lightColor.r * intensity;
-                        g += lightColor.g * intensity;
-                        b += lightColor.b * intensity;
+            if (PHASES)
+                updateCompositesPhased(snap);
+            else
+                updateCompositesLegacy(snap);
+        } finally {
+            compositeUpdateInFlight.set(false);
+        }
+    }
+
+    /**
+     * Phased composite routing: pre-refinement lightmaps composite
+     * uniformly from their centroid values; lightmaps in the texel phase
+     * get the full per-texel recomputation plus per-lightmap convergence
+     * judgement; graduated (tail) lightmaps keep recompositing without
+     * any further ray sampling until the estimate has fully glided to the
+     * frozen target; frozen lightmaps are skipped entirely.
+     */
+    private void updateCompositesPhased(final Snapshot snap) {
+        final int lightCount = snap.lights.size();
+        final double[] pos = new double[3];
+        for (final Lightmap lightmap : snap.lightmaps) {
+            if (!lightmap.texelPhase) {
+                // Phases A/B: the whole triangle shows its centroid value.
+                if (lightmap.centroidReady)
+                    lightmap.compositeFromCentroid();
+                continue;
+            }
+            final TriangleBvh.Entry entry = snap.lightmapEntry.get(lightmap);
+            if (entry != null && entry.frozen)
+                continue; // fully settled: texture already final
+
+            final double movementSum = compositeTexels(snap, lightmap, lightCount, pos);
+            final double avgMovement = movementSum / ((long) lightmap.width * lightmap.height);
+            if (entry == null)
+                continue;
+            if (!entry.graduated) {
+                // Sampling graduation: every texel re-tested at least once
+                // (no centroid-seeded visibility may survive) AND a calm
+                // estimate -> stop casting rays. The calm limit is relative:
+                // Monte Carlo jitter scales with brightness, so a bright
+                // lightmap can never fall below a fixed threshold and would
+                // squat in the active window forever, starving far entries.
+                double estimateSum = 0;
+                for (final int t : lightmap.validTexels)
+                    estimateSum += (lightmap.estimateR[t] + lightmap.estimateG[t]
+                            + lightmap.estimateB[t]) / 3.0;
+                final double calmLimit = Math.max(CALM_THRESHOLD,
+                        0.02 * estimateSum / lightmap.validTexels.length);
+                final boolean covered =
+                        lightmap.texelsSampled >= lightmap.validTexels.length;
+                if (covered && avgMovement < calmLimit) {
+                    if (++lightmap.calmComposites >= GRADUATE_CALM) {
+                        lightmap.calmComposites = 0; // re-used for the freeze tail
+                        graduate(entry, Phase.TEXEL);
                     }
-                    // Indirect, lightly blended with valid 4-neighbors:
-                    // single-texel Monte Carlo spikes are smoothed without
-                    // blurring real gradients (texels are sub-pixel at 4K).
-                    final float smoothedR = DESPECKLE ? smoothedIndirect(lightmap.indirectR, lightmap, texel) : lightmap.indirectR[texel];
-                    final float smoothedG = DESPECKLE ? smoothedIndirect(lightmap.indirectG, lightmap, texel) : lightmap.indirectG[texel];
-                    final float smoothedB = DESPECKLE ? smoothedIndirect(lightmap.indirectB, lightmap, texel) : lightmap.indirectB[texel];
-                    irrR[texel] = (float) Math.min(255, r) + smoothedR;
-                    irrG[texel] = (float) Math.min(255, g) + smoothedG;
-                    irrB[texel] = (float) Math.min(255, b) + smoothedB;
+                } else {
+                    lightmap.calmComposites = 0;
                 }
-
-                // 2. Fill the invalid half (u+v > 1) from nearest valid
-                //    neighbors, so bilinear upsampling never reads garbage.
-                final boolean[] filled = new boolean[texelCount];
-                for (final int texel : lightmap.validTexels)
-                    filled[texel] = true;
-                boolean progressed = true;
-                while (progressed) {
-                    progressed = false;
-                    for (int t = 0; t < texelCount; t++) {
-                        if (filled[t])
-                            continue;
-                        final int i = t % width;
-                        final int j = t / width;
-                        final int left = i > 0 ? t - 1 : -1;
-                        final int right = i < width - 1 ? t + 1 : -1;
-                        final int up = j > 0 ? t - width : -1;
-                        final int down = j < height - 1 ? t + width : -1;
-                        final int source = left >= 0 && filled[left] ? left
-                                : right >= 0 && filled[right] ? right
-                                : up >= 0 && filled[up] ? up
-                                : down >= 0 && filled[down] ? down : -1;
-                        if (source >= 0) {
-                            irrR[t] = irrR[source];
-                            irrG[t] = irrG[source];
-                            irrB[t] = irrB[source];
-                            filled[t] = true;
-                            progressed = true;
+                if (DEBUG)
+                    System.out.println("[GI] composite update (texel phase), avgMovement="
+                            + String.format("%.2f", avgMovement));
+            } else {
+                // Tail: no new samples, the target is frozen, so movement
+                // decays monotonically (pure EMA glide) until invisible.
+                if (avgMovement < FREEZE_THRESHOLD) {
+                    if (++lightmap.calmComposites >= GRADUATE_CALM) {
+                        entry.frozen = true;
+                        synchronized (queueLock) {
+                            snap.tailCount--;
+                            if (DEBUG)
+                                System.out.println("[GI] frozen, tail left=" + snap.tailCount);
                         }
                     }
+                } else {
+                    lightmap.calmComposites = 0;
                 }
+            }
+        }
+    }
 
-                // 3. Blend the computed irradiance into the persistent
-                //    per-texel estimate (the outer EMA), then write the
-                //    composite texture 1:1 from the ESTIMATE — the texture
-                //    can only move COMPOSITE_ALPHA of the remaining
-                //    distance per update, so direct light, shadows and
-                //    indirect all fade in/out gradually.
-                final Texture back = lightmap.backTexture();
-                final int[] pixels = back.primaryBitmap.pixels;
-                for (int j = 0; j < height; j++)
-                    for (int i = 0; i < width; i++) {
-                        final int t = j * width + i;
-                        final float dR = (float) (COMPOSITE_ALPHA * (irrR[t] - lightmap.estimateR[t]));
-                        final float dG = (float) (COMPOSITE_ALPHA * (irrG[t] - lightmap.estimateG[t]));
-                        final float dB = (float) (COMPOSITE_ALPHA * (irrB[t] - lightmap.estimateB[t]));
-                        lightmap.estimateR[t] += dR;
-                        lightmap.estimateG[t] += dG;
-                        lightmap.estimateB[t] += dB;
-                        movementSum += Math.max(Math.abs(dR), Math.max(Math.abs(dG), Math.abs(dB)));
-                        texelTotal++;
-                        pixels[t] = compositePixel(lightmap,
-                                lightmap.estimateR[t], lightmap.estimateG[t], lightmap.estimateB[t]);
-                    }
+    /** Legacy composite path with global convergence judgement. */
+    private void updateCompositesLegacy(final Snapshot snap) {
+        final int lightCount = snap.lights.size();
+        final double[] pos = new double[3];
+        double movementSum = 0;
+        long texelTotal = 0;
+        for (final Lightmap lightmap : snap.lightmaps) {
+            movementSum += compositeTexels(snap, lightmap, lightCount, pos);
+            texelTotal += (long) lightmap.width * lightmap.height;
+        }
+
+        // Convergence: average per-texel movement of the on-screen
+        // estimate. With a constant alpha the estimate never fully
+        // freezes (Monte Carlo jitter), so CALM_THRESHOLD judges the
+        // VISIBLE movement; five calm updates in a row -> idle.
+        final double avgMovement = texelTotal > 0 ? movementSum / texelTotal : 0;
+        if (avgMovement < CALM_THRESHOLD)
+            calmSweeps++;
+        else
+            calmSweeps = 0;
+        if (DEBUG)
+            System.out.println("[GI] composite update, avgMovement="
+                    + String.format("%.2f", avgMovement));
+    }
+
+    /**
+     * Regenerates one lightmap's composite texture from the current
+     * per-texel visibility and indirect state, blending into the
+     * persistent per-texel estimate (the outer EMA).
+     *
+     * @return the sum of per-texel estimate movement (convergence signal)
+     */
+    private double compositeTexels(final Snapshot snap, final Lightmap lightmap,
+                                   final int lightCount, final double[] pos) {
+        lightmap.ensureLightCapacity(lightCount);
+        final int width = lightmap.width;
+        final int height = lightmap.height;
+        final int texelCount = width * height;
+
+        // 1. Total irradiance per valid texel (float, no clamping yet).
+        final float[] irrR = new float[texelCount];
+        final float[] irrG = new float[texelCount];
+        final float[] irrB = new float[texelCount];
+        for (final int texel : lightmap.validTexels) {
+            lightmap.texelWorldPosition(texel, pos);
+            double r = snap.ambientR, g = snap.ambientG, b = snap.ambientB;
+            for (int i = 0; i < lightCount && i < MAX_TRACKED_LIGHTS; i++) {
+                if (lightmap.lightVisibility[texel * lightCount + i] == Lightmap.VISIBILITY_OCCLUDED)
+                    continue;
+                final LightSource light = snap.lights.get(i);
+                final Point3D lightPos = light.getPosition();
+                final double dx = lightPos.x - pos[0];
+                final double dy = lightPos.y - pos[1];
+                final double dz = lightPos.z - pos[2];
+                final double dist = Math.sqrt(dx * dx + dy * dy + dz * dz);
+                if (dist < 0.0001)
+                    continue;
+                final double dot = (lightmap.normalX * dx + lightmap.normalY * dy
+                        + lightmap.normalZ * dz) / dist;
+                if (dot <= 0)
+                    continue;
+                final double attenuation = 1.0 / (1.0 + 0.0001 * dist * dist);
+                final double intensity = dot * attenuation * light.getIntensity();
+                final Color lightColor = light.getColor();
+                r += lightColor.r * intensity;
+                g += lightColor.g * intensity;
+                b += lightColor.b * intensity;
+            }
+            // Indirect, lightly blended with valid 4-neighbors:
+            // single-texel Monte Carlo spikes are smoothed without
+            // blurring real gradients (texels are sub-pixel at 4K).
+            final float smoothedR = DESPECKLE ? smoothedIndirect(lightmap.indirectR, lightmap, texel) : lightmap.indirectR[texel];
+            final float smoothedG = DESPECKLE ? smoothedIndirect(lightmap.indirectG, lightmap, texel) : lightmap.indirectG[texel];
+            final float smoothedB = DESPECKLE ? smoothedIndirect(lightmap.indirectB, lightmap, texel) : lightmap.indirectB[texel];
+            irrR[texel] = (float) Math.min(255, r) + smoothedR;
+            irrG[texel] = (float) Math.min(255, g) + smoothedG;
+            irrB[texel] = (float) Math.min(255, b) + smoothedB;
+        }
 
-                back.resetResampledBitmapCache();
-                if (lightmap.owner != null) {
-                    lightmap.owner.setTexture(back);
-                    lightmap.swapBuffers();
+        // 2. Fill the invalid half (u+v > 1) from nearest valid
+        //    neighbors, so bilinear upsampling never reads garbage.
+        final boolean[] filled = new boolean[texelCount];
+        for (final int texel : lightmap.validTexels)
+            filled[texel] = true;
+        boolean progressed = true;
+        while (progressed) {
+            progressed = false;
+            for (int t = 0; t < texelCount; t++) {
+                if (filled[t])
+                    continue;
+                final int i = t % width;
+                final int j = t / width;
+                final int left = i > 0 ? t - 1 : -1;
+                final int right = i < width - 1 ? t + 1 : -1;
+                final int up = j > 0 ? t - width : -1;
+                final int down = j < height - 1 ? t + width : -1;
+                final int source = left >= 0 && filled[left] ? left
+                        : right >= 0 && filled[right] ? right
+                        : up >= 0 && filled[up] ? up
+                        : down >= 0 && filled[down] ? down : -1;
+                if (source >= 0) {
+                    irrR[t] = irrR[source];
+                    irrG[t] = irrG[source];
+                    irrB[t] = irrB[source];
+                    filled[t] = true;
+                    progressed = true;
                 }
+            }
+        }
 
-                // Debug: -De3d.gi.dumpLightmaps=/tmp/lm dumps composites as PNGs.
-                if (DUMP_DIR != null)
-                    dumpLightmap(lightmap, pixels);
+        // 3. Blend the computed irradiance into the persistent
+        //    per-texel estimate (the outer EMA), then write the
+        //    composite texture 1:1 from the ESTIMATE — the texture
+        //    can only move COMPOSITE_ALPHA of the remaining
+        //    distance per update, so direct light, shadows and
+        //    indirect all fade in/out gradually.
+        double movementSum = 0;
+        final Texture back = lightmap.backTexture();
+        final int[] pixels = back.primaryBitmap.pixels;
+        for (int j = 0; j < height; j++)
+            for (int i = 0; i < width; i++) {
+                final int t = j * width + i;
+                final float dR = (float) (COMPOSITE_ALPHA * (irrR[t] - lightmap.estimateR[t]));
+                final float dG = (float) (COMPOSITE_ALPHA * (irrG[t] - lightmap.estimateG[t]));
+                final float dB = (float) (COMPOSITE_ALPHA * (irrB[t] - lightmap.estimateB[t]));
+                lightmap.estimateR[t] += dR;
+                lightmap.estimateG[t] += dG;
+                lightmap.estimateB[t] += dB;
+                movementSum += Math.max(Math.abs(dR), Math.max(Math.abs(dG), Math.abs(dB)));
+                pixels[t] = compositePixel(lightmap,
+                        lightmap.estimateR[t], lightmap.estimateG[t], lightmap.estimateB[t]);
             }
 
-            // Convergence: average per-texel movement of the on-screen
-            // estimate. With a constant alpha the estimate never fully
-            // freezes (Monte Carlo jitter), so CALM_THRESHOLD judges the
-            // VISIBLE movement; five calm updates in a row -> idle.
-            final double avgMovement = texelTotal > 0 ? movementSum / texelTotal : 0;
-            if (avgMovement < CALM_THRESHOLD)
-                calmSweeps++;
-            else
-                calmSweeps = 0;
-            if (DEBUG)
-                System.out.println("[GI] composite update, avgMovement="
-                        + String.format("%.2f", avgMovement));
-        } finally {
-            compositeUpdateInFlight.set(false);
+        back.resetResampledBitmapCache();
+        if (lightmap.owner != null) {
+            lightmap.owner.setTexture(back);
+            lightmap.swapBuffers();
         }
+
+        // Debug: -De3d.gi.dumpLightmaps=/tmp/lm dumps composites as PNGs.
+        if (DUMP_DIR != null)
+            dumpLightmap(lightmap, pixels);
+        return movementSum;
     }
 
     private static final String DUMP_DIR = System.getProperty("e3d.gi.dumpLightmaps");
@@ -766,9 +1418,22 @@ public class GlobalIllumination implements GiLightProvider {
         final double lightSignature = lightSignature();
         if (version == lastSeenRenderListVersion && lightSignature == lastLightSignature)
             return;
+        if (DEBUG)
+            System.out.println("[GI] rebuild trigger: renderListVersion "
+                    + lastSeenRenderListVersion + " -> " + version
+                    + ", lightSignature " + lastLightSignature + " -> " + lightSignature
+                    + ", phase was " + phase);
 
         final List triangles = new ArrayList<>();
         shapes.collectRenderTriangles(triangles);
+        // Torn-read guard: a nested composite's cache can rebuild between
+        // the version read above and this collect, yielding a partial
+        // triangle set for a version that will never trigger again (the
+        // bump already happened). Re-read: if it moved, let the next loop
+        // rebuild from a consistent state instead of converging a partial
+        // scene to DONE and idling forever.
+        if (AbstractCompositeShape.getGlobalRenderListVersion() != version)
+            return;
 
         final Snapshot snap = new Snapshot();
         snap.entries = new ArrayList<>(triangles.size());
@@ -792,25 +1457,66 @@ public class GlobalIllumination implements GiLightProvider {
         snap.ambientG = ambient.g;
         snap.ambientB = ambient.b;
 
-        // Flattened work list: one item per valid lightmap texel,
-        // one per plain polygon.
-        final List workItems = new ArrayList<>();
-        for (final TriangleBvh.Entry entry : snap.entries) {
-            if (entry.lightmap != null) {
-                for (final int texel : entry.lightmap.validTexels) {
+        if (PHASES) {
+            // Distance ordering from the camera position at build time.
+            final Point3D cam = cameraPosition == null ? null : cameraPosition.get();
+            for (final TriangleBvh.Entry entry : snap.entries)
+                entry.distance = cam == null ? 0f : distanceSquared(entry, cam);
+            snap.sortedByDistance = snap.entries.stream()
+                    .sorted(Comparator.comparingDouble(e -> e.distance))
+                    .toArray(TriangleBvh.Entry[]::new);
+            snap.lightmappedSorted = snap.entries.stream()
+                    .filter(e -> e.lightmap != null)
+                    .sorted(Comparator.comparingDouble(e -> e.distance))
+                    .toArray(TriangleBvh.Entry[]::new);
+            snap.lightmapEntry = new IdentityHashMap<>();
+            for (final TriangleBvh.Entry entry : snap.entries)
+                if (entry.lightmap != null) {
+                    entry.lightmap.resetPhasedState();
+                    snap.lightmapEntry.put(entry.lightmap, entry);
+                }
+            synchronized (queueLock) {
+                phase = Phase.CENTROID_DIRECT;
+                phaseQueue = snap.sortedByDistance;
+                queueCursor = 0;
+                // inFlight must NOT be zeroed here: a worker that grabbed
+                // an entry just before the rebuild decrements it after,
+                // so set(0) would drive the counter negative and the
+                // phase-A drain condition (== 0) would never hold again.
+                // The counter is conserved on its own: pre-rebuild
+                // samples finish and decrement normally.
+                activeList.clear();
+                active = new TriangleBvh.Entry[0];
+                activeCursor.set(0);
+            }
+            if (cam != null) {
+                lastCameraX = cam.x;
+                lastCameraY = cam.y;
+                lastCameraZ = cam.z;
+            } else {
+                lastCameraX = Double.NaN;
+            }
+        } else {
+            // Flattened work list: one item per valid lightmap texel,
+            // one per plain polygon.
+            final List workItems = new ArrayList<>();
+            for (final TriangleBvh.Entry entry : snap.entries) {
+                if (entry.lightmap != null) {
+                    for (final int texel : entry.lightmap.validTexels) {
+                        final WorkItem item = new WorkItem();
+                        item.entry = entry;
+                        item.texel = texel;
+                        workItems.add(item);
+                    }
+                } else {
                     final WorkItem item = new WorkItem();
                     item.entry = entry;
-                    item.texel = texel;
+                    item.texel = -1;
                     workItems.add(item);
                 }
-            } else {
-                final WorkItem item = new WorkItem();
-                item.entry = entry;
-                item.texel = -1;
-                workItems.add(item);
             }
+            snap.workItems = workItems.toArray(new WorkItem[0]);
         }
-        snap.workItems = workItems.toArray(new WorkItem[0]);
 
         snapshot = snap;
         states.clear();
@@ -818,11 +1524,17 @@ public class GlobalIllumination implements GiLightProvider {
         lastLightSignature = lightSignature;
         calmSweeps = 0; // scene changed: back to full-speed tracing
 
-        if (DEBUG)
-            System.out.println("[GI] snapshot: " + snap.entries.size() + " triangles, "
-                    + snap.workItems.length + " work items, "
-                    + snap.lightmaps.size() + " lightmaps, "
-                    + snap.lights.size() + " lights");
+        if (DEBUG) {
+            if (PHASES)
+                System.out.println("[GI] snapshot: " + snap.entries.size() + " triangles, "
+                        + snap.lightmaps.size() + " lightmaps, "
+                        + snap.lights.size() + " lights, phased scheduling near-to-far");
+            else
+                System.out.println("[GI] snapshot: " + snap.entries.size() + " triangles, "
+                        + snap.workItems.length + " work items, "
+                        + snap.lightmaps.size() + " lightmaps, "
+                        + snap.lights.size() + " lights");
+        }
     }
 
     private double lightSignature() {
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/Lightmap.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/Lightmap.java
index 4acf19e..dffa1a8 100644
--- a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/Lightmap.java
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/Lightmap.java
@@ -105,6 +105,52 @@ public class Lightmap {
     public byte[] lightVisibility;
     public int lightCount;
 
+    // --- Phased progressive GI state (-De3d.gi.phases, default on) ---
+
+    /**
+     * Total direct irradiance at the triangle centroid (ambient + direct
+     * with shadows, clamped to display range), computed in phase A. The
+     * whole triangle displays this uniform value until per-texel
+     * refinement reaches it in phase C.
+     */
+    public volatile float centroidR, centroidG, centroidB;
+
+    /**
+     * Indirect irradiance estimated at the centroid during phase B. Texel
+     * indirect arrays are seeded from this so bounce rays hitting a
+     * not-yet-refined triangle read a plausible uniform value.
+     */
+    public volatile float centroidIndirectR, centroidIndirectG, centroidIndirectB;
+
+    /**
+     * True once per-texel refinement (phase C) has reached this lightmap.
+     * Before that, composite updates fill the texture uniformly from the
+     * centroid values instead of recomputing per texel.
+     */
+    public volatile boolean texelPhase;
+
+    /** True once phase A has stamped the centroid direct value (GI threads only). */
+    public volatile boolean centroidReady;
+
+    /** Round-robin cursor over {@link #validTexels} in phase C (GI threads only). */
+    public int nextTexel;
+
+    /** Consecutive calm composite updates, drives phase C graduation (GI threads only). */
+    public int calmComposites;
+
+    /**
+     * Phase C: valid texels that have been sampled at least once. Graduation
+     * must not fire before this reaches {@code validTexels.length}: an
+     * unvisited texel still shows its centroid-seeded light visibility
+     * (e.g. "fully shadowed" if the centroid happened to sit in shadow),
+     * and a frozen seed survives forever as a dark polygon with lit detail
+     * only on the visited fraction.
+     */
+    public int texelsSampled;
+
+    /** Last composited centroid totals; skips redundant uniform recomposites. */
+    private float lastCompositeR = Float.NaN, lastCompositeG, lastCompositeB;
+
     /** Double-buffered composite textures; the triangle shows one, GI fills the other. */
     private final Texture[] buffers = new Texture[2];
     private int shownBuffer;
@@ -159,6 +205,8 @@ public class Lightmap {
         java.util.Arrays.fill(estimateG, (float) INITIAL_IRRADIANCE);
         java.util.Arrays.fill(estimateB, (float) INITIAL_IRRADIANCE);
         sampleCounts = new short[width * height];
+        texelsSampled = 0;
+        calmComposites = 0;
 
         final int[] valid = new int[width * height];
         int count = 0;
@@ -254,6 +302,108 @@ public class Lightmap {
         }
     }
 
+    /**
+     * Phase A: stamps the centroid direct irradiance onto the whole
+     * triangle at once — estimate arrays, composite texture and buffer
+     * swap in one go, so the polygon flips from the uniform medium start
+     * to its true flat lighting in a single visible step (the progressive
+     * "wave"). Per-texel refinement later glides away from this seed via
+     * the normal composite EMA.
+     *
+     * @param r total direct irradiance, red channel (light units)
+     * @param g green channel
+     * @param b blue channel
+     */
+    public void seedDisplay(final float r, final float g, final float b) {
+        java.util.Arrays.fill(estimateR, r);
+        java.util.Arrays.fill(estimateG, g);
+        java.util.Arrays.fill(estimateB, b);
+        lastCompositeR = r;
+        lastCompositeG = g;
+        lastCompositeB = b;
+        final Texture back = backTexture();
+        java.util.Arrays.fill(back.primaryBitmap.pixels, compositeSeedPixel(r, g, b));
+        back.resetResampledBitmapCache();
+        if (owner != null) {
+            owner.setTexture(back);
+            swapBuffers();
+        }
+    }
+
+    /** Uniform composite pixel for {@link #seedDisplay}. */
+    private int compositeSeedPixel(final float irrR, final float irrG, final float irrB) {
+        final int r = Math.min(255, (int) (irrR * baseColor.r / 255));
+        final int g = Math.min(255, (int) (irrG * baseColor.g / 255));
+        final int b = Math.min(255, (int) (irrB * baseColor.b / 255));
+        return 0xFF000000 | (r << 16) | (g << 8) | b;
+    }
+
+    /**
+     * Phase A: fills the per-texel visibility array uniformly with the
+     * centroid shadow-test results, so bounce rays hitting this triangle
+     * before per-texel refinement see plausible shadowed direct light.
+     * Assumes {@link #ensureLightCapacity} has run.
+     *
+     * @param centroidVisibility per-light visibility bytes (length = lightCount)
+     */
+    public void seedCentroidVisibility(final byte[] centroidVisibility) {
+        final int texelCount = width * height;
+        for (int t = 0; t < texelCount; t++)
+            System.arraycopy(centroidVisibility, 0, lightVisibility, t * lightCount, lightCount);
+    }
+
+    /**
+     * Phase B / pre-refinement composite: reseeds the display estimate
+     * uniformly from the centroid direct plus the current centroid
+     * indirect, and fills the texel indirect arrays from the centroid
+     * indirect so bounce-target reads stay uniform. Runs at composite
+     * cadence, not per sample.
+     */
+    public void compositeFromCentroid() {
+        final float totalR = centroidR + centroidIndirectR;
+        final float totalG = centroidG + centroidIndirectG;
+        final float totalB = centroidB + centroidIndirectB;
+        if (totalR == lastCompositeR && totalG == lastCompositeG && totalB == lastCompositeB)
+            return; // centroid values unchanged since the last stamp: nothing to do
+        lastCompositeR = totalR;
+        lastCompositeG = totalG;
+        lastCompositeB = totalB;
+        java.util.Arrays.fill(estimateR, totalR);
+        java.util.Arrays.fill(estimateG, totalG);
+        java.util.Arrays.fill(estimateB, totalB);
+        java.util.Arrays.fill(indirectR, centroidIndirectR);
+        java.util.Arrays.fill(indirectG, centroidIndirectG);
+        java.util.Arrays.fill(indirectB, centroidIndirectB);
+        final Texture back = backTexture();
+        final int[] pixels = back.primaryBitmap.pixels;
+        final int pixel = compositeSeedPixel(totalR, totalG, totalB);
+        java.util.Arrays.fill(pixels, pixel);
+        back.resetResampledBitmapCache();
+        if (owner != null) {
+            owner.setTexture(back);
+            swapBuffers();
+        }
+    }
+
+    /**
+     * Resets the phased-progression state for a new GI snapshot (scene or
+     * light change): back to the centroid phases, per-texel shadow tracing
+     * re-armed. The display estimate arrays deliberately keep their old
+     * values so the re-traced solution fades in instead of flashing.
+     */
+    public void resetPhasedState() {
+        texelPhase = false;
+        centroidReady = false;
+        nextTexel = 0;
+        calmComposites = 0;
+        texelsSampled = 0;
+        centroidIndirectR = 0;
+        centroidIndirectG = 0;
+        centroidIndirectB = 0;
+        lastCompositeR = Float.NaN;
+        java.util.Arrays.fill(sampleCounts, (short) 0);
+    }
+
     /**
      * The texture the triangle should show right now.
      *
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/TriangleBvh.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/TriangleBvh.java
index 5e099ae..d7ffcb6 100644
--- a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/TriangleBvh.java
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/gi/TriangleBvh.java
@@ -34,6 +34,19 @@ public class TriangleBvh {
         /** Unit surface normal, world space. */
         public volatile float[] normal;
 
+        // --- Phased progressive GI bookkeeping (GI threads only) ---
+
+        /** Squared distance from the camera at snapshot build / last re-sort. */
+        public float distance;
+        /** Phase B/C: true once this entry's estimate has calmed down and it left the active window. */
+        public volatile boolean graduated;
+        /** Phase C: true once the composite estimate has fully glided to the frozen target (display freeze). */
+        public volatile boolean frozen;
+        /** Consecutive calm phase-B visits (GI threads only). */
+        public int calmVisits;
+        /** Centroid bounce sample count, drives the adaptive alpha in phase B (GI threads only). */
+        public int centroidSamples;
+
         public Entry(final AbstractCoordinateShape polygon) {
             this.polygon = polygon;
         }
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java
index 3a3ca1d..e8d315d 100644
--- a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/basic/solidpolygon/SolidPolygon.java
@@ -93,6 +93,17 @@ public class SolidPolygon extends AbstractCoordinateShape {
      * Computed once during transform phase, used during paint phase.
      */
     private final Color shadedColor = new Color();
+    /**
+     * Shaded color of the REVERSE side, computed with the negated normal.
+     * Used when backface culling is off and the camera sees the polygon's
+     * back: the back is a different surface and must not show the front
+     * side's lighting (an underside must not glow with the top's light).
+     */
+    private final Color backShadedColor = new Color();
+    /**
+     * Reusable negated normal for the reverse-side lighting pass.
+     */
+    private final Point3D cachedBackNormal = new Point3D();
     /**
      * Reusable point for polygon center calculation.
      */
@@ -697,17 +708,6 @@ public class SolidPolygon extends AbstractCoordinateShape {
             return;
         }
 
-        // Use pre-computed shaded color (computed during transform phase)
-        final Color paintColor = shadingEnabled ? shadedColor : color;
-
-        // Z-buffer two-pass classification: opaque polygons paint in
-        // pass 1 (depth test + write), translucent ones in pass 2
-        // (depth test, no write — translucency must not occlude).
-        // See RenderAggregator.paintSorted.
-        final boolean alphaClass = paintColor.a != 255;
-        if ((renderBuffer.depthPass == 1) == alphaClass)
-            return;
-
         // Get thread-local screen points array
         final Point2D[] screenPoints = getScreenPoints(active.size());
         final double[] cameraZ = getCameraZ(active.size());
@@ -719,13 +719,29 @@ public class SolidPolygon extends AbstractCoordinateShape {
             cameraZ[i] = vertex.transformedCoordinate(renderBuffer).z;
         }
 
+        // Facing from the signed screen area (same convention as the
+        // backface culling test below: >= 0 means the back side shows).
+        final double signedArea = (backfaceCulling || shadingEnabled)
+                ? calculateSignedArea(screenPoints, active.size())
+                : -1;
+
         // Backface culling check
-        if (backfaceCulling) {
-            final double signedArea = calculateSignedArea(screenPoints, active.size());
-            if (signedArea >= 0) {
-                return;
-            }
-        }
+        if (backfaceCulling && signedArea >= 0)
+            return;
+
+        // Two-sided lighting: a visible back side paints with the
+        // reverse-lit color, never the front side's light.
+        final Color paintColor = shadingEnabled
+                ? (signedArea >= 0 ? backShadedColor : shadedColor)
+                : color;
+
+        // Z-buffer two-pass classification: opaque polygons paint in
+        // pass 1 (depth test + write), translucent ones in pass 2
+        // (depth test, no write — translucency must not occlude).
+        // See RenderAggregator.paintSorted.
+        final boolean alphaClass = paintColor.a != 255;
+        if ((renderBuffer.depthPass == 1) == alphaClass)
+            return;
 
         // Mouse interaction
         if (mouseInteractionController != null && renderBuffer.getMouseEvent() != null) {
@@ -818,6 +834,16 @@ public class SolidPolygon extends AbstractCoordinateShape {
             );
             renderingContext.lightingManager.computeLighting(
                     this, cachedCenter, cachedNormal, color, shadedColor);
+            if (!backfaceCulling) {
+                // Two-sided lighting: when the camera sees the polygon's
+                // back (culling off), that side is lit by its own facing
+                // direction, so relight with the negated normal.
+                cachedBackNormal.x = -cachedNormal.x;
+                cachedBackNormal.y = -cachedNormal.y;
+                cachedBackNormal.z = -cachedNormal.z;
+                renderingContext.lightingManager.computeLighting(
+                        this, cachedCenter, cachedBackNormal, color, backShadedColor);
+            }
         }
     }
 }
\ No newline at end of file
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/LightmappedCompositeShape.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/LightmappedCompositeShape.java
index 9aba6d4..b03e1e7 100644
--- a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/LightmappedCompositeShape.java
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/LightmappedCompositeShape.java
@@ -126,7 +126,7 @@ public class LightmappedCompositeShape extends AbstractCompositeShape {
     private void wrapLightmapped(final SolidPolygon polygon, final List out) {
         final int vertexCount = polygon.getVertexCount();
         if (vertexCount == 3) {
-            out.add(wrapTriangle(polygon));
+            emitWrapped(polygon, out);
             return;
         }
         // Fan: anchor vertex 0, then consecutive pairs
@@ -140,15 +140,46 @@ public class LightmappedCompositeShape extends AbstractCompositeShape {
             triangle.setShadingEnabled(polygon.isShadingEnabled());
             triangle.setBackfaceCulling(polygon.isBackfaceCullingEnabled());
             triangle.setMouseInteractionController(polygon.mouseInteractionController);
-            out.add(wrapTriangle(triangle));
+            emitWrapped(triangle, out);
         }
     }
 
+    /**
+     * Emits one lightmapped triangle for the front side. When the source
+     * polygon is two-sided (backface culling off), also emits a plain
+     * solid triangle with reversed winding for the back side, and turns
+     * culling on for both halves: a lightmap only knows its front side,
+     * so without a real back surface the camera would see the front
+     * side's light through the polygon (undersides glowing with the
+     * top's light). The reversed solid renders with ordinary one-sided
+     * direct lighting — correctly dark where the front is lit — and each
+     * side's pixels are owned by exactly one surface, so nothing
+     * z-fights.
+     */
+    private void emitWrapped(final SolidPolygon triangle, final List out) {
+        final LightmappedTriangle front = wrapTriangle(triangle);
+        if (triangle.isBackfaceCullingEnabled()) {
+            out.add(front);
+            return;
+        }
+        front.setBackfaceCulling(true);
+        final SolidPolygon back = new SolidPolygon(
+                triangle.vertices.get(0).coordinate,
+                triangle.vertices.get(2).coordinate,
+                triangle.vertices.get(1).coordinate,
+                triangle.getColor());
+        back.setShadingEnabled(triangle.isShadingEnabled());
+        back.setBackfaceCulling(true);
+        back.setMouseInteractionController(triangle.mouseInteractionController);
+        out.add(front);
+        out.add(back);
+    }
+
     /**
      * Wraps one triangle into a lightmapped textured triangle with the
      * same geometry, color and culling.
      */
-    private AbstractCoordinateShape wrapTriangle(final SolidPolygon polygon) {
+    private LightmappedTriangle wrapTriangle(final SolidPolygon polygon) {
         final Point3D a = polygon.vertices.get(0).coordinate;
         final Point3D b = polygon.vertices.get(1).coordinate;
         final Point3D c = polygon.vertices.get(2).coordinate;
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjLoader.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjLoader.java
new file mode 100644
index 0000000..2da4ca2
--- /dev/null
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjLoader.java
@@ -0,0 +1,341 @@
+/*
+ * Aukio 3D engine. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.obj;
+
+import eu.svjatoslav.aukio.e3d.geometry.Point3D;
+import eu.svjatoslav.aukio.e3d.renderer.raster.Color;
+import eu.svjatoslav.aukio.e3d.renderer.raster.shapes.basic.solidpolygon.SolidPolygon;
+
+import java.io.BufferedReader;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.DirectoryStream;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.ArrayList;
+import java.util.HashMap;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Map;
+import java.util.Set;
+import java.util.function.Function;
+
+/**
+ * Loader for Wavefront OBJ geometry files (with MTL material libraries).
+ *
+ * 
Supported OBJ statements:

+ * 
    
+ *   
  • {@code v x y z} — vertex positions (extra components ignored)
    • 
+ *   
  • {@code f v1 v2 v3 [v4 ...]} — faces; each index may be in any of
+ *       the standard forms {@code v}, {@code v/vt}, {@code v//vn},
+ *       {@code v/vt/vn}; negative indices are relative to the most recently
+ *       defined vertex. Faces may reference vertices defined later in the
+ *       file (batch-flushing exporters do this). Texture/normal indices are
+ *       parsed past and ignored.
    • 
+ *   
  • {@code usemtl name} — selects the material for following faces
    • 
+ *   
  • {@code mtllib file [file ...]} — material library, resolved relative
+ *       to the OBJ file (or via the caller-provided resolver)
    • 
+ *   
  • {@code o}, {@code g}, {@code s}, {@code vt}, {@code vn}, {@code #} —
+ *       parsed past and ignored
    • 
+ * 

+ *
+ * 
Supported MTL statements: {@code newmtl}, {@code Kd} (diffuse color),
+ * {@code d} (opacity) and {@code Tr} (transparency). Everything else is
+ * ignored.

+ *
+ * 
Coordinates are loaded verbatim — no axis conversion. Note the engine's
+ * world convention is "+Y points down", which matches OBJ exporters that
+ * wrote scenes for y-down pipelines; for standard "+Y up" exports rotate
+ * the resulting model 180° around X via its transform.

+ *
+ * 
Limitation: faces are rendered as convex polygons (fan triangulation);
+ * non-convex faces may render with overlapping triangles.

+ *
+ * 
Usage:

+ * 
{@code
+ * ObjModel model = ObjLoader.load(Path.of("city1.obj"));
+ * model.setShadingEnabled(true);
+ * shapes.addShape(model);
+ * }

+ */
+public final class ObjLoader {
+
+    /** Utility class, not meant to be instantiated. */
+    private ObjLoader() {
+    }
+
+    /**
+     * Loads an OBJ file, resolving {@code mtllib} references against the
+     * file's own directory.
+     *
+     * @param objFile path to the .obj file
+     * @return the parsed model, ready to add to a scene
+     * @throws IOException on read errors, malformed statements, or a
+     *                     missing material library
+     */
+    public static ObjModel load(final Path objFile) throws IOException {
+        final Path directory = objFile.toAbsolutePath().getParent();
+        final Function resolver = name -> {
+            final Path direct = directory.resolve(name);
+            try {
+                if (Files.exists(direct)) {
+                    return Files.newInputStream(direct);
+                }
+                // DOS-era exports often disagree with the filesystem on case.
+                try (DirectoryStream entries = Files.newDirectoryStream(directory)) {
+                    for (final Path entry : entries) {
+                        if (entry.getFileName().toString().equalsIgnoreCase(name)) {
+                            return Files.newInputStream(entry);
+                        }
+                    }
+                }
+                return null;
+            } catch (final IOException e) {
+                return null;
+            }
+        };
+        try (InputStream stream = Files.newInputStream(objFile)) {
+            return load(stream, objFile.getFileName().toString(), resolver);
+        }
+    }
+
+    /**
+     * Loads an OBJ document from a stream.
+     *
+     * @param objStream        the OBJ content
+     * @param sourceName       name used in error messages
+     * @param resourceResolver opens referenced material libraries by name;
+     *                         may return {@code null} when not found
+     * @return the parsed model, ready to add to a scene
+     * @throws IOException on read errors or malformed statements
+     */
+    public static ObjModel load(final InputStream objStream, final String sourceName,
+                                final Function resourceResolver)
+            throws IOException {
+        final List vertices = new ArrayList<>();
+        final Map materials = new HashMap<>();
+        final Set usedMaterials = new HashSet<>();
+        final List faces = new ArrayList<>();
+
+        ObjMaterial currentMaterial = ObjMaterial.DEFAULT;
+
+        final BufferedReader reader = new BufferedReader(
+                new InputStreamReader(objStream, StandardCharsets.UTF_8));
+        String line;
+        int lineNumber = 0;
+        // OBJ line continuation: a trailing backslash joins with the next line.
+        StringBuilder pending = new StringBuilder();
+        while ((line = reader.readLine()) != null) {
+            lineNumber++;
+            final String trimmed = line.trim();
+            if (trimmed.endsWith("\\")) {
+                pending.append(trimmed, 0, trimmed.length() - 1).append(' ');
+                continue;
+            }
+            pending.append(trimmed);
+            final String statement = pending.toString();
+            pending.setLength(0);
+
+            if (statement.isEmpty() || statement.startsWith("#")) {
+                continue;
+            }
+            final String[] tokens = statement.split("\\s+");
+            switch (tokens[0]) {
+                case "v":
+                    vertices.add(new Point3D(
+                            parseDouble(tokens, 1, sourceName, lineNumber),
+                            parseDouble(tokens, 2, sourceName, lineNumber),
+                            parseDouble(tokens, 3, sourceName, lineNumber)));
+                    break;
+                case "f": {
+                    if (tokens.length < 4) {
+                        throw malformed(sourceName, lineNumber,
+                                "face needs at least 3 vertices: " + statement);
+                    }
+                    // Positive indices are validated and resolved only after
+                    // the whole file is parsed: exporters that flush vertices
+                    // in batches (e.g. 3D Synthezier's 3dparse) legally emit
+                    // faces referencing vertices defined LATER in the file.
+                    // Negative (relative) indices resolve immediately — they
+                    // are relative to the vertex count at this point.
+                    final int[] indices = new int[tokens.length - 1];
+                    for (int i = 1; i < tokens.length; i++) {
+                        indices[i - 1] = resolveIndex(tokens[i], vertices.size(),
+                                sourceName, lineNumber);
+                    }
+                    faces.add(new PendingFace(indices, currentMaterial, lineNumber));
+                    usedMaterials.add(currentMaterial.getName());
+                    break;
+                }
+                case "usemtl":
+                    if (tokens.length < 2) {
+                        throw malformed(sourceName, lineNumber, "usemtl needs a name");
+                    }
+                    currentMaterial = materials.getOrDefault(tokens[1], ObjMaterial.DEFAULT);
+                    break;
+                case "mtllib":
+                    if (tokens.length < 2) {
+                        throw malformed(sourceName, lineNumber, "mtllib needs a file name");
+                    }
+                    for (int i = 1; i < tokens.length; i++) {
+                        loadMaterialLibrary(tokens[i], sourceName, resourceResolver, materials);
+                    }
+                    break;
+                default:
+                    // o, g, s, vt, vn, ... — not needed for flat-colored polygons.
+                    break;
+            }
+        }
+
+        final ObjModel result = new ObjModel(vertices.size(), faces.size(),
+                usedMaterials.size());
+        for (final PendingFace face : faces) {
+            final Point3D[] facePoints = new Point3D[face.indices.length];
+            for (int i = 0; i < face.indices.length; i++) {
+                final int index = face.indices[i];
+                if (index >= vertices.size()) {
+                    throw malformed(sourceName, face.lineNumber,
+                            "face index out of range: " + (index + 1));
+                }
+                // Copy: faces must not alias one mutable Point3D.
+                facePoints[i] = new Point3D(vertices.get(index));
+            }
+            result.addShape(new SolidPolygon(facePoints, face.material.getColor()));
+        }
+        return result;
+    }
+
+    /** A face statement captured mid-parse, before vertices are complete. */
+    private static final class PendingFace {
+        private final int[] indices;
+        private final ObjMaterial material;
+        private final int lineNumber;
+
+        private PendingFace(final int[] indices, final ObjMaterial material,
+                            final int lineNumber) {
+            this.indices = indices;
+            this.material = material;
+            this.lineNumber = lineNumber;
+        }
+    }
+
+    private static void loadMaterialLibrary(final String fileName, final String sourceName,
+                                            final Function resourceResolver,
+                                            final Map materials)
+            throws IOException {
+        try (InputStream stream = resourceResolver.apply(fileName)) {
+            if (stream == null) {
+                throw new IOException(sourceName + ": material library not found: " + fileName);
+            }
+            parseMaterialLibrary(stream, fileName, materials);
+        }
+    }
+
+    private static void parseMaterialLibrary(final InputStream stream, final String fileName,
+                                             final Map materials)
+            throws IOException {
+        final BufferedReader reader = new BufferedReader(
+                new InputStreamReader(stream, StandardCharsets.UTF_8));
+        String name = null;
+        double r = 0.5, g = 0.5, b = 0.5, opacity = 1.0;
+        String line;
+        int lineNumber = 0;
+        while ((line = reader.readLine()) != null) {
+            lineNumber++;
+            final String trimmed = line.trim();
+            if (trimmed.isEmpty() || trimmed.startsWith("#")) {
+                continue;
+            }
+            final String[] tokens = trimmed.split("\\s+");
+            switch (tokens[0]) {
+                case "newmtl":
+                    if (name != null) {
+                        materials.put(name, new ObjMaterial(name,
+                                new Color(r, g, b, opacity)));
+                    }
+                    if (tokens.length < 2) {
+                        throw malformed(fileName, lineNumber, "newmtl needs a name");
+                    }
+                    name = tokens[1];
+                    r = g = b = 0.5;
+                    opacity = 1.0;
+                    break;
+                case "Kd":
+                    r = parseDouble(tokens, 1, fileName, lineNumber);
+                    g = parseDouble(tokens, 2, fileName, lineNumber);
+                    b = parseDouble(tokens, 3, fileName, lineNumber);
+                    break;
+                case "d":
+                    opacity = parseDouble(tokens, 1, fileName, lineNumber);
+                    break;
+                case "Tr":
+                    opacity = 1.0 - parseDouble(tokens, 1, fileName, lineNumber);
+                    break;
+                default:
+                    // Ns, Ks, Ka, illum, map_*, ... — ignored.
+                    break;
+            }
+        }
+        if (name != null) {
+            materials.put(name, new ObjMaterial(name, new Color(r, g, b, opacity)));
+        }
+    }
+
+    /**
+     * Resolves an OBJ face index token ({@code v}, {@code v/vt}, {@code v//vn}
+     * or {@code v/vt/vn}) to a 0-based index. Positive indices (1-based) are
+     * returned as-is minus one WITHOUT a range check — the exporter may define
+     * the referenced vertex later in the file; the range is validated against
+     * the final vertex count when the model is assembled. Negative indices are
+     * relative to the vertex count at this point and are range-checked
+     * immediately.
+     */
+    private static int resolveIndex(final String token, final int vertexCount,
+                                    final String sourceName, final int lineNumber)
+            throws IOException {
+        final int slash = token.indexOf('/');
+        final String indexText = slash < 0 ? token : token.substring(0, slash);
+        final int raw;
+        try {
+            raw = Integer.parseInt(indexText);
+        } catch (final NumberFormatException e) {
+            throw malformed(sourceName, lineNumber, "bad face index: " + token);
+        }
+        if (raw == 0) {
+            throw malformed(sourceName, lineNumber,
+                    "face index out of range: " + token);
+        }
+        if (raw < 0) {
+            final int index = vertexCount + raw;
+            if (index < 0 || index >= vertexCount) {
+                throw malformed(sourceName, lineNumber,
+                        "face index out of range: " + token);
+            }
+            return index;
+        }
+        return raw - 1;
+    }
+
+    private static double parseDouble(final String[] tokens, final int position,
+                                      final String sourceName, final int lineNumber)
+            throws IOException {
+        if (position >= tokens.length) {
+            throw malformed(sourceName, lineNumber,
+                    "expected number at position " + (position + 1));
+        }
+        try {
+            return Double.parseDouble(tokens[position]);
+        } catch (final NumberFormatException e) {
+            throw malformed(sourceName, lineNumber, "bad number: " + tokens[position]);
+        }
+    }
+
+    private static IOException malformed(final String sourceName, final int lineNumber,
+                                         final String detail) {
+        return new IOException(sourceName + ":" + lineNumber + ": " + detail);
+    }
+}
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjMaterial.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjMaterial.java
new file mode 100644
index 0000000..3a00497
--- /dev/null
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjMaterial.java
@@ -0,0 +1,45 @@
+/*
+ * Aukio 3D engine. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.obj;
+
+import eu.svjatoslav.aukio.e3d.renderer.raster.Color;
+
+/**
+ * A single material from a Wavefront MTL library.
+ *
+ * 
Only the subset of MTL attributes relevant to the rasterizer is
+ * captured: diffuse color ({@code Kd}) and opacity ({@code d}, or
+ * {@code Tr} transparency) — combined into the engine's {@link Color}
+ * (alpha 255 = opaque, lower = translucent). Specular/ambient/texture-map
+ * attributes ({@code Ks}, {@code Ka}, {@code Ns}, {@code illum},
+ * {@code map_*}) are parsed past and ignored.

+ */
+public class ObjMaterial {
+
+    /** Fallback material for faces whose {@code usemtl} is unknown or missing. */
+    public static final ObjMaterial DEFAULT = new ObjMaterial("default",
+            new Color(160, 160, 160, 255));
+
+    private final String name;
+    private final Color color;
+
+    public ObjMaterial(final String name, final Color color) {
+        this.name = name;
+        this.color = color;
+    }
+
+    /** Material name from the {@code newmtl} statement. */
+    public String getName() {
+        return name;
+    }
+
+    /**
+     * Diffuse color ({@code Kd}) with alpha taken from {@code d}
+     * (1.0 → alpha 255 opaque, lower values → translucent).
+     */
+    public Color getColor() {
+        return color;
+    }
+}
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjModel.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjModel.java
new file mode 100644
index 0000000..8e3037e
--- /dev/null
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjModel.java
@@ -0,0 +1,54 @@
+/*
+ * Aukio 3D engine. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.obj;
+
+import eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.LightmappedCompositeShape;
+
+/**
+ * A 3D model loaded from a Wavefront OBJ file, as a composite of
+ * solid polygons (one {@code SolidPolygon} per OBJ face, colored by the
+ * face's {@code usemtl} material).
+ *
+ * 
Instances are built by {@link ObjLoader}; treat the model as an
+ * ordinary composite: position it with {@link #setTransform}, toggle
+ * {@link #setShadingEnabled} / {@link #setBackfaceCulling}, and add it to
+ * the scene graph.

+ *
+ * @see ObjLoader
+ */
+public class ObjModel extends LightmappedCompositeShape {
+
+    /** Number of {@code v} statements in the source file. */
+    private final int sourceVertexCount;
+
+    /** Number of {@code f} statements (one child polygon each). */
+    private final int faceCount;
+
+    /** Number of materials actually referenced by faces. */
+    private final int usedMaterialCount;
+
+    public ObjModel(final int sourceVertexCount, final int faceCount,
+                    final int usedMaterialCount) {
+        super();
+        this.sourceVertexCount = sourceVertexCount;
+        this.faceCount = faceCount;
+        this.usedMaterialCount = usedMaterialCount;
+    }
+
+    /** Number of vertices declared in the OBJ source. */
+    public int getSourceVertexCount() {
+        return sourceVertexCount;
+    }
+
+    /** Number of faces (= child polygons) in the model. */
+    public int getFaceCount() {
+        return faceCount;
+    }
+
+    /** Number of distinct materials referenced by the model's faces. */
+    public int getUsedMaterialCount() {
+        return usedMaterialCount;
+    }
+}
diff --git a/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/package-info.java b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/package-info.java
new file mode 100644
index 0000000..cfd4efe
--- /dev/null
+++ b/src/main/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/package-info.java
@@ -0,0 +1,11 @@
+/*
+ * Aukio 3D engine. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+
+/**
+ * Wavefront OBJ/MTL model loading: {@link ObjLoader} parses the files and
+ * builds an {@link ObjModel} composite of solid polygons, colored per face
+ * from the material library.
+ */
+package eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.obj;
diff --git a/src/test/java/eu/svjatoslav/aukio/e3d/math/TransformStackTest.java b/src/test/java/eu/svjatoslav/aukio/e3d/math/TransformStackTest.java
index ed5275b..eb4de15 100644
--- a/src/test/java/eu/svjatoslav/aukio/e3d/math/TransformStackTest.java
+++ b/src/test/java/eu/svjatoslav/aukio/e3d/math/TransformStackTest.java
@@ -136,4 +136,208 @@ public class TransformStackTest {
         assertEquals(p.y, result.y, EPSILON);
         assertEquals(p.z, result.z, EPSILON);
     }
+
+    @Test
+    public void uniformScaleComposesThroughStack() {
+        // Parent scales 2x, child scales 3x, both rotated and translated:
+        // the composed stack must match sequential per-level application,
+        // where each level applies scale, then rotation, then translation.
+        final Random rnd = new Random(7);
+
+        for (int depth = 2; depth <= 5; depth++) {
+            final Transform[] chain = new Transform[depth];
+            final TransformStack stack = new TransformStack();
+            for (int i = 0; i < depth; i++) {
+                chain[i] = Transform.fromAngles(
+                        (rnd.nextDouble() - 0.5) * 1000,
+                        (rnd.nextDouble() - 0.5) * 1000,
+                        (rnd.nextDouble() - 0.5) * 1000,
+                        (rnd.nextDouble() - 0.5) * Math.PI * 2,
+                        (rnd.nextDouble() - 0.5) * Math.PI,
+                        (rnd.nextDouble() - 0.5) * Math.PI);
+                chain[i].setScale(0.5 + rnd.nextDouble() * 3);
+                stack.addTransform(chain[i]);
+            }
+
+            for (int k = 0; k < 50; k++) {
+                final Point3D p = new Point3D(
+                        (rnd.nextDouble() - 0.5) * 100,
+                        (rnd.nextDouble() - 0.5) * 100,
+                        (rnd.nextDouble() - 0.5) * 100);
+
+                final Point3D expected = new Point3D(p);
+                for (int i = depth - 1; i >= 0; i--) {
+                    chain[i].transform(expected);
+                }
+
+                final Point3D result = new Point3D();
+                stack.transform(p, result);
+
+                // Scaled coordinates amplify absolute error, so use a
+                // relative-ish tolerance sized by the accumulated scale.
+                assertEquals("depth " + depth + " x", expected.x, result.x, 1e-6 * magnitude(expected));
+                assertEquals("depth " + depth + " y", expected.y, result.y, 1e-6 * magnitude(expected));
+                assertEquals("depth " + depth + " z", expected.z, result.z, 1e-6 * magnitude(expected));
+            }
+        }
+    }
+
+    private static double magnitude(final Point3D p) {
+        return Math.max(1.0, Math.sqrt(p.x * p.x + p.y * p.y + p.z * p.z));
+    }
+
+    @Test
+    public void scaleAppliesAboutLocalOrigin() {
+        // Scale first, then rotation (identity here), then translation:
+        // the local point is scaled, the translation is not.
+        final Transform t = Transform.fromAngles(10, 20, 30, 0, 0, 0);
+        t.setScale(2.0);
+
+        final Point3D p = new Point3D(3, 4, 5);
+        t.transform(p);
+
+        assertEquals(16, p.x, EPSILON);
+        assertEquals(28, p.y, EPSILON);
+        assertEquals(40, p.z, EPSILON);
+    }
+
+    @Test
+    public void nestedScalesMultiply() {
+        // No rotations: point (1,0,0) -> child: 1*3 + 10 = 13
+        // -> parent: 13*2 + 100 = 126.
+        final Transform parent = Transform.fromAngles(100, 0, 0, 0, 0, 0);
+        parent.setScale(2.0);
+        final Transform child = Transform.fromAngles(10, 0, 0, 0, 0, 0);
+        child.setScale(3.0);
+
+        final TransformStack stack = new TransformStack();
+        stack.addTransform(parent);
+        stack.addTransform(child);
+
+        final Point3D result = new Point3D();
+        stack.transform(new Point3D(1, 0, 0), result);
+
+        assertEquals(126, result.x, EPSILON);
+        assertEquals(0, result.y, EPSILON);
+        assertEquals(0, result.z, EPSILON);
+    }
+
+    @Test
+    public void negativeScaleMirrors() {
+        final Transform t = Transform.fromAngles(1, 2, 3, 0, 0, 0);
+        t.setScale(-2.0);
+
+        final Point3D p = new Point3D(1, 1, 1);
+        t.transform(p);
+
+        assertEquals(-1, p.x, EPSILON);
+        assertEquals(0, p.y, EPSILON);
+        assertEquals(1, p.z, EPSILON);
+    }
+
+    @Test
+    public void setScaleRejectsZeroAndNonFinite() {
+        final Transform t = new Transform();
+        for (final double bad : new double[]{0.0, Double.NaN,
+                Double.POSITIVE_INFINITY, Double.NEGATIVE_INFINITY}) {
+            try {
+                t.setScale(bad);
+                throw new AssertionError("expected IllegalArgumentException for " + bad);
+            } catch (final IllegalArgumentException expected) {
+                // expected
+            }
+        }
+        assertEquals(1.0, t.getScale(), 0.0);
+    }
+
+    @Test
+    public void explicitScaleOneIsBitIdenticalToDefault() {
+        // The fold multiplies by the scale at push time; with s == 1.0 that
+        // multiply must be IEEE-exact so rigid scenes stay bit-identical.
+        final Random rnd = new Random(99);
+
+        for (int depth = 1; depth <= 4; depth++) {
+            final TransformStack plain = new TransformStack();
+            final TransformStack explicit = new TransformStack();
+            for (int i = 0; i < depth; i++) {
+                final double x = (rnd.nextDouble() - 0.5) * 1000;
+                final double y = (rnd.nextDouble() - 0.5) * 1000;
+                final double z = (rnd.nextDouble() - 0.5) * 1000;
+                final double yaw = (rnd.nextDouble() - 0.5) * Math.PI * 2;
+                final double pitch = (rnd.nextDouble() - 0.5) * Math.PI;
+                final double roll = (rnd.nextDouble() - 0.5) * Math.PI;
+
+                plain.addTransform(Transform.fromAngles(x, y, z, yaw, pitch, roll));
+                explicit.addTransform(Transform.fromAngles(x, y, z, yaw, pitch, roll)
+                        .setScale(1.0));
+            }
+
+            for (int k = 0; k < 20; k++) {
+                final Point3D p = new Point3D(
+                        (rnd.nextDouble() - 0.5) * 2000,
+                        (rnd.nextDouble() - 0.5) * 2000,
+                        (rnd.nextDouble() - 0.5) * 2000);
+                final Point3D a = new Point3D();
+                final Point3D b = new Point3D();
+                plain.transform(p, a);
+                explicit.transform(p, b);
+
+                assertEquals(0.0, Double.compare(a.x, b.x), 0.0);
+                assertEquals(0.0, Double.compare(a.y, b.y), 0.0);
+                assertEquals(0.0, Double.compare(a.z, b.z), 0.0);
+            }
+        }
+    }
+
+    @Test
+    public void scaleMutationAfterPushHasNoEffect() {
+        final Transform transform = Transform.fromAngles(10, 0, 0, 0, 0, 0);
+        transform.setScale(3.0);
+
+        final TransformStack stack = new TransformStack();
+        stack.addTransform(transform);
+
+        // Push-time snapshot: later scale changes must not leak in.
+        transform.setScale(100.0);
+
+        final Point3D result = new Point3D();
+        stack.transform(new Point3D(1, 0, 0), result);
+
+        assertEquals(13, result.x, EPSILON);
+    }
+
+    @Test
+    public void topTransformCarriesScale() {
+        // getTopTransform is the bulk path used by TriangleMeshBlock; it must
+        // agree with transform() bit-for-bit, scale included.
+        final Transform parent = Transform.fromAngles(50, -20, 70, 0.4, -0.2, 0.1);
+        parent.setScale(2.5);
+        final Transform child = Transform.fromAngles(-5, 8, 3, -0.3, 0.7, 0.2);
+        child.setScale(0.75);
+
+        final TransformStack stack = new TransformStack();
+        stack.addTransform(parent);
+        stack.addTransform(child);
+
+        final double[] m = new double[12];
+        stack.getTopTransform(m);
+
+        final Random rnd = new Random(5);
+        for (int k = 0; k < 50; k++) {
+            final double x = (rnd.nextDouble() - 0.5) * 100;
+            final double y = (rnd.nextDouble() - 0.5) * 100;
+            final double z = (rnd.nextDouble() - 0.5) * 100;
+
+            final Point3D viaStack = new Point3D();
+            stack.transform(new Point3D(x, y, z), viaStack);
+
+            final double bx = m[0] * x + m[1] * y + m[2] * z + m[9];
+            final double by = m[3] * x + m[4] * y + m[5] * z + m[10];
+            final double bz = m[6] * x + m[7] * y + m[8] * z + m[11];
+
+            assertEquals(0.0, Double.compare(viaStack.x, bx), 0.0);
+            assertEquals(0.0, Double.compare(viaStack.y, by), 0.0);
+            assertEquals(0.0, Double.compare(viaStack.z, bz), 0.0);
+        }
+    }
 }
diff --git a/src/test/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjLoaderTest.java b/src/test/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjLoaderTest.java
new file mode 100644
index 0000000..eb677ea
--- /dev/null
+++ b/src/test/java/eu/svjatoslav/aukio/e3d/renderer/raster/shapes/composite/obj/ObjLoaderTest.java
@@ -0,0 +1,241 @@
+/*
+ * Aukio 3D engine. Author: Svjatoslav Agejenko.
+ * This project is released under Creative Commons Zero (CC0) license.
+ */
+package eu.svjatoslav.aukio.e3d.renderer.raster.shapes.composite.obj;
+
+import eu.svjatoslav.aukio.e3d.renderer.raster.shapes.basic.solidpolygon.SolidPolygon;
+import org.junit.Test;
+
+import java.io.ByteArrayInputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assert.fail;
+
+/**
+ * Unit tests for {@link ObjLoader}: statement parsing, face index forms,
+ * material resolution, alpha, and error reporting.
+ */
+public class ObjLoaderTest {
+
+    private static final String MTL = """
+            # comment
+            newmtl red
+            Kd 1.0 0.0 0.0
+            d 1.0
+
+            newmtl glass
+            Kd 0.0 0.0 1.0
+            d 0.5
+            """;
+
+    private static Map mtlFiles() {
+        final Map files = new HashMap<>();
+        files.put("test.mtl", MTL);
+        return files;
+    }
+
+    private static ObjModel load(final String obj, final Map files)
+            throws IOException {
+        return ObjLoader.load(
+                new ByteArrayInputStream(obj.getBytes(StandardCharsets.UTF_8)),
+                "test.obj",
+                name -> {
+                    final String content = files.get(name);
+                    return content == null ? null
+                            : new ByteArrayInputStream(content.getBytes(StandardCharsets.UTF_8));
+                });
+    }
+
+    @Test
+    public void parsesQuadAndTriangleWithMaterials() throws IOException {
+        final ObjModel model = load("""
+                mtllib test.mtl
+                v 0 0 0
+                v 10 0 0
+                v 10 10 0
+                v 0 10 0
+                v 20 0 0
+                usemtl red
+                f 1 2 3 4
+                usemtl glass
+                f 2 5 3
+                """, mtlFiles());
+
+        assertEquals(5, model.getSourceVertexCount());
+        assertEquals(2, model.getFaceCount());
+        assertEquals(2, model.getUsedMaterialCount());
+
+        final List polygons = model.extractSolidPolygons();
+        assertEquals(2, polygons.size());
+
+        // Winding/vertex order must be preserved verbatim.
+        final SolidPolygon quad = polygons.get(0);
+        assertEquals(4, quad.vertices.size());
+        assertEquals(10.0, quad.vertices.get(2).coordinate.x, 1e-9);
+        assertEquals(10.0, quad.vertices.get(2).coordinate.y, 1e-9);
+        assertEquals(255, quad.getColor().r);
+        assertEquals(255, quad.getColor().a);
+
+        final SolidPolygon triangle = polygons.get(1);
+        assertEquals(3, triangle.vertices.size());
+        assertEquals(255, triangle.getColor().b);
+        // d 0.5 -> alpha ~127/128 (0.5*255 truncation is allowed either way)
+        assertTrue(Math.abs(triangle.getColor().a - 127) <= 1);
+    }
+
+    @Test
+    public void acceptsAllFaceIndexForms() throws IOException {
+        final ObjModel model = load("""
+                v 0 0 0 1.0 0.5 0.5
+                v 1 0 0
+                v 1 1 0
+                v 0 1 0
+                vt 0 0
+                vn 0 0 1
+                f 1 2 3
+                f 1/1 2/1 3/1
+                f 1//1 2//1 3//1
+                f 1/1/1 2/1/1 3/1/1
+                f -4 -3 -2 -1
+                """, mtlFiles());
+        assertEquals(5, model.getFaceCount());
+        // Negative indices are relative: -4..-1 == vertices 1..4 (0,0,0)..(0,1,0).
+        final SolidPolygon last = model.extractSolidPolygons().get(4);
+        assertEquals(0.0, last.vertices.get(0).coordinate.x, 1e-9);
+        assertEquals(0.0, last.vertices.get(3).coordinate.x, 1e-9);
+        assertEquals(1.0, last.vertices.get(3).coordinate.y, 1e-9);
+    }
+
+    @Test
+    public void unknownMaterialFallsBackToDefault() throws IOException {
+        final ObjModel model = load("""
+                v 0 0 0
+                v 1 0 0
+                v 1 1 0
+                usemtl nope
+                f 1 2 3
+                """, mtlFiles());
+        final SolidPolygon polygon = model.extractSolidPolygons().get(0);
+        assertEquals(160, polygon.getColor().r);
+        assertEquals(255, polygon.getColor().a);
+    }
+
+    @Test
+    public void faceWithoutAnyMaterialUsesDefault() throws IOException {
+        final ObjModel model = load("""
+                v 0 0 0
+                v 1 0 0
+                v 1 1 0
+                f 1 2 3
+                """, mtlFiles());
+        assertEquals(160, model.extractSolidPolygons().get(0).getColor().r);
+    }
+
+    @Test
+    public void forwardVertexReferencesResolve() throws IOException {
+        // Batch-flushing exporters (3D Synthezier's 3dparse) emit faces that
+        // reference vertices defined later in the file — valid OBJ.
+        final ObjModel model = load("""
+                f 1 2 3
+                v 0 0 0
+                v 1 0 0
+                v 1 1 0
+                """, mtlFiles());
+        assertEquals(1, model.getFaceCount());
+        final SolidPolygon polygon = model.extractSolidPolygons().get(0);
+        assertEquals(1.0, polygon.vertices.get(2).coordinate.x, 1e-9);
+        assertEquals(1.0, polygon.vertices.get(2).coordinate.y, 1e-9);
+    }
+
+    @Test
+    public void rejectsOutOfRangeFaceIndex() throws IOException {
+        try {
+            load("""
+                    v 0 0 0
+                    v 1 0 0
+                    v 1 1 0
+                    f 1 2 4
+                    """, mtlFiles());
+            fail("expected IOException for out-of-range face index");
+        } catch (final IOException e) {
+            assertTrue(e.getMessage(), e.getMessage().contains("test.obj:4"));
+        }
+    }
+
+    @Test(expected = IOException.class)
+    public void rejectsDegenerateFace() throws IOException {
+        load("""
+                v 0 0 0
+                v 1 0 0
+                f 1 2
+                """, mtlFiles());
+    }
+
+    @Test
+    public void missingMaterialLibraryIsAnError() throws IOException {
+        try {
+            load("""
+                    mtllib absent.mtl
+                    v 0 0 0
+                    v 1 0 0
+                    v 1 1 0
+                    f 1 2 3
+                    """, mtlFiles());
+            fail("expected IOException for missing material library");
+        } catch (final IOException e) {
+            assertTrue(e.getMessage(), e.getMessage().contains("absent.mtl"));
+        }
+    }
+
+    @Test
+    public void trTransparencyComplementsOpacity() throws IOException {
+        final Map files = new HashMap<>();
+        files.put("tr.mtl", "newmtl half\nKd 0 1 0\nTr 0.25\n");
+        final ObjModel model = load("""
+                mtllib tr.mtl
+                v 0 0 0
+                v 1 0 0
+                v 1 1 0
+                usemtl half
+                f 1 2 3
+                """, files);
+        assertEquals(191, model.extractSolidPolygons().get(0).getColor().a);
+        assertEquals(255, model.extractSolidPolygons().get(0).getColor().g);
+    }
+
+    @Test
+    public void lineContinuationJoinsStatements() throws IOException {
+        final ObjModel model = load("v 0 0 \\\n0\nv 1 0 0\nv 1 1 0\nf 1 2 3\n", mtlFiles());
+        assertEquals(3, model.getSourceVertexCount());
+        assertEquals(1, model.getFaceCount());
+    }
+
+    @Test
+    public void pathLoadResolvesMtllibCaseInsensitively() throws IOException {
+        final Path dir = Files.createTempDirectory("objloader-test");
+        final Path obj = dir.resolve("scene.obj");
+        Files.writeString(obj, """
+                mtllib materials.mtl
+                v 0 0 0
+                v 1 0 0
+                v 1 1 0
+                usemtl green
+                f 1 2 3
+                """);
+        // Filesystem has a different case than the mtllib reference.
+        Files.writeString(dir.resolve("MATERIALS.MTL"), "newmtl green\nKd 0 1 0\nd 1\n");
+
+        final ObjModel model = ObjLoader.load(obj);
+        assertEquals(1, model.getFaceCount());
+        assertEquals(255, model.extractSolidPolygons().get(0).getColor().g);
+    }
+}
diff --git a/udev/99-rayneo-glasses.rules b/udev/99-rayneo-glasses.rules
new file mode 100644
index 0000000..8e716cf
--- /dev/null
+++ b/udev/99-rayneo-glasses.rules
@@ -0,0 +1 @@
+ACTION=="add|change", SUBSYSTEM=="hidraw", SUBSYSTEMS=="usb", ATTRS{idVendor}=="1bbb", ATTRS{idProduct}=="af50", MODE="0666"
diff --git a/udev/99-spacenavigator.rules b/udev/99-spacenavigator.rules
new file mode 100644
index 0000000..524cfde
--- /dev/null
+++ b/udev/99-spacenavigator.rules
@@ -0,0 +1 @@
+SUBSYSTEM=="hidraw", ATTRS{idVendor}=="046d", ATTRS{idProduct}=="c626", MODE="0666"