2026-10-11

[markaren]

The short version: the Vulkan ocean keeps what boats leave on it (a wake field of foam, bubbles and the waves a hull makes, for up to eight vessels on one sea), Python gets a set of vehicle rigs (three sea drones, an AUV, five aircraft and a car, each built from one spec file with its sources cited), text follows the font's real curves and is UTF-8, a Vulkan process exits in milliseconds instead of 20 seconds, the Vulkan renderer runs on a GPU without ray tracing, and the web build is lit by its environment and plays sound. Three new OpenGL demos load no assets at all: showpiece, MarbleRun and SandTable.

Figures below come from the commits that measured them, on the hardware those commits name. They were not re-benchmarked for this release.

---

⚠️ Breaking and behaviour changes

API

• type() returns const std::string& on Object3D, Material, BufferGeometry and everything under them. It returned a std::string by value, which cost a heap allocation per call for the longer names, several times per draw. Callers compile unchanged. A class of your own that overrides type() must take the new return type.
• Font::glyphs is keyed by Unicode code point, not by char.
• Removed from VulkanRenderer: setDeferredDenoise / deferredDenoise (use setDenoise / denoise), setVolumetricFog (a no-op since the fog unification; Python's volumetric_fog goes with it), and the VulkanRendererCore.hpp header and alias.
• FireEffect::Params::legacyEmbers and emberRate are gone, with vulkan_fire --legacy-embers. The embers are a ParticleField.
• PhysxVehicle: Settings::stickyDampingLongitudinal and stickyDampingLateral are gone. The vehicle now chooses between stickyDamping and stickyDampingHold each step (see the grade hold below).
• Texture::premultiplyAlpha is removed. Neither renderer read it. The key in an old scene file is ignored on load.
• Material::clipping is gone from the base class. It shadowed MaterialWithClipping::clipping, which is the one that remains.
• PhysxSoftBody::registerGlTexture returns bool, like registerVulkanMemory.
• THREEPP_DLSS_JITTER_SIGN is removed. The per-axis THREEPP_DLSS_JITTER_SIGN_X / _Y stay.
• ABI: many classes changed layout. Rebuild everything that links threepp.

Behaviour

• Canvas::Parameters::fastExit is on by default. A process on its way out leaves its Vulkan device to the OS instead of destroying it, which on NVIDIA drivers could wait about 20 s in vkDestroyDevice. An app that tears its renderer down and builds a new one while the process goes on sets fastExit(false). Python's Canvas(fast_exit=...) keeps its False default, since interpreter exit is covered automatically.
• VulkanRenderer is created on a device without ray tracing. It used to throw there. It now draws a degraded frame (see the no-ray-tracing mode under New). Code that caught the exception to fall back to GLRenderer asks rayTracingSupported() (Python ray_tracing) instead. Where there are several devices, one with ray tracing is still preferred.
• A Vulkan readback inside the frame returns that frame. readRGBPixels(), writeFramebuffer() and Python's save_frame used to copy a swapchain image up to three frames old, so a script that changed the scene and saved a still got the old scene. The readback now ends the open frame first. An ortho HUD pass that arrives after the readback in the same iteration is skipped with a one-time hint: put it before the readback. Baselines captured through this path change once.
• Python: VulkanRenderer draws an OrthographicCamera as a 3D view (orthographic_scene_rendering, on by default). A top-down render used to come out as unlit fills in scene order with a black background. The C++ default is unchanged, but a lit mesh sent down the 2D path now prints a one-time hint that names the call to make.
• The Vulkan 2D pass honours renderOrder, as GLRenderer does: opaque before transparent, then the enclosing group's order, then the object's own. It used to draw in traversal order with every sprite last.
• RenderTarget::Options::generateMipmaps is honoured on GL (default false, as in three.js). It was never read, and every target regenerated its chain after each render.
• Python SVGLoader.load / parse return strokes as well as fills, in document order, named after the element's id and layered by render_order. fill="none" no longer yields a white mesh.
• A DisplacedMesh of more than 512 cells a side is ray traced through a coarser proxy (rtProxyCells, default 512; 0 restores the full grid). The raster keeps the full grid.
• A braked PhysxVehicle holds on a grade. It used to creep downhill at about 0.7 km/h. Scripted drives on the flat are bit-identical per step.

Scenes that look different

• Text. TrueType glyphs were drawn through their control polygons (flattened bowls, a notch in the D). They now follow their curves. Non-ASCII characters render instead of one ? per byte.
• glTF models with COLOR_0 show their vertex colours, multiplied into the base colour as the format specifies.
• SVG rounded rects get the radius they ask for. Corners used to be spread over twice the radius and collapsed for pills and ellipses.
• OpenGL scenes with a Reflector or Water may be lit differently: see the light-version fix below.
• Vulkan ocean: no vessel foam ahead of the stem and a thinner trail, a hull-exclusion margin that scales with the hull (0.6 x half-beam, clamped to 0.3 to 2 m), and far water that averages the fine waves' slope along the view instead of speckling. sampleWakeHeight sums every vessel's wake.
• Vulkan, other:
  • Reflections and anything seen through glass read their textures over the pixel's footprint, so they are smoother.
  • Textures that are not a power of two get an area-weighted mip chain.
  • Sprite textures use their own filters and wrap modes.
  • Sprites under murky water seen from the air are foreshortened (setUnderwaterSpriteForeshortening(false) restores the old look).
  • Water is lit by point lights and by every light of its cluster.

Examples that moved

• Python: vulkan_ui.py is now ui_demo.py --vulkan, and warp_nebula_vk.py is warp_nebula.py --vulkan. warp_squishy_ball.py is removed. The rover demo and slope sweep are in rover/, and drone_rig.py is in rigs/. Demos write to an out/ folder beside the script unless told otherwise.
• C++: vulkan_aov_audit, vulkan_lidar_audit, vulkan_furnace_test and rg_ab are in examples/vulkan/audits/. Target names are unchanged.

---

New

Ocean and marine (Vulkan)

• Wake field (DisplacedMesh::WakeField; Python ocean.wake_field, wake_patch(i), add_wake_source(...), clear_wake_sources()). Square patches of simulated surface, anchored in the world and not tiled. Each texel carries foam, the bubbles under the surface, turbulence, a lane where the short waves are damped, and the water's own velocity. A source is a capsule with a radius, a velocity and an amount of each quantity. Off by default: nothing is allocated and the frame is the same to the pixel.
• Ripples in the wake field (WakeField::rippleResolution, WakePatch::rippleSize). A patch can hold a small linear sea that is forced by the pressure its sources bear down with (WakeSource::push). Nothing draws a V: a source moving at speed U makes the Kelvin wake of that speed, bent where it turned, and several superpose.
• marine::VesselWash (C++) and tp.VesselWash (Python): what a vessel leaves on the wake field. Her propulsors' races by momentum theory, the lane her hulls drag, and the waves her weight makes, spread down to her draft.
• One ocean carries up to eight vessels, each with its own footprint and wake (vesselHull(i), vesselWake(i); Python ocean.vessel(i)). Vessel 0 is the existing hullExclusion and wake, so current scenes are unchanged.
• rtProxyCells: on a 1024 x 1024 ocean the per-frame BLAS refit went from 5.0 to 0.4 ms (RTX 4070).
• Water takes the hue of what is under it. Per-channel murk extinction (setUnderwaterMurk(Vector3, Color), murkExtinctionFromColor; Python set_underwater_murk(density, color, chromatic=...)) and setUnderwaterAmbientFalloff(k), both opt-in. A hull 3 m down no longer reads as lying at the surface.
• WakeField::albedo scales what the film and bubbles turn back, for night scenes.

Vulkan

• The renderer runs without hardware ray tracing. On a device without VK_KHR_ray_query, or on any device under THREEPP_VULKAN_NO_RT=1, it is a raster renderer in which every ray misses. No acceleration structures are built. GI is sky and environment light, and reflections and refraction show the environment. RT AO, probe GI, traced fog shadowing and auto-LOD are off. The sun casts screen-space shadows, marched through the depth buffer, so only what the camera sees casts one; lamps cast none. A lidar scan throws, and so do the sensors built on it. rayTracingSupported() (Python ray_tracing) says which mode is running. With ray tracing nothing changes: the ray-traced shaders' SPIR-V and an A/B render were compared and are identical.
• Thin-walled glass is usable from inside a cabin. What a pane shows is lit where it is, not by the light level at the pane (hillsides beyond a windscreen were black). It takes the lamps of its own cluster cell (head lamps now light the road through the windscreen), and its soft sun shadow uses one fixed pattern instead of unresolved dots.
• An emissive light is sampled only where it can show. A faint lamp used to cost every pixel of the frame. On a large day scene with a moored boat's lanterns and twelve cars' tail lamps: 19.8 to 17.5 ms (RTX 4070, 1280x720).
• Lighting views (setLightingView / lighting_view): show one term in place of the lit frame, such as the unshadowed direct light, the shadowed direct light, the diffuse bounce or the reflections. probeGrid() / probe_grid() returns the fitted probe grid, with the SH store as numpy.
• The render graph times every pass, per view: FrameTimings::passes, Python pass_timings, rg_ab --time, and a tree in the ImGui timings node. Python's frame_timings now names every pass (ocean, particle and splat stages, probe_gi_ms, tlas_refit_ms).
• Static BLASes are compacted and no longer built updatable. On a 2,300-mesh site the auto-LOD level BLASes went from 220 to 87 MB. THREEPP_VK_BLAS_COMPACT=0 turns it off.
• Auto-LOD chains land on a fence instead of a queue wait inside render(): scene build while chains land went from 27.7 to 4.7 ms on the same site. With the clock pinned (setSimTime), the frame a chain lands on is now a function of the scene, so runs replay under load.
• A cap on the cutout texels a shadow ray tests (setCutoutRayCap(texels, fromDistance), setCutoutRayDistance; Python cutout_ray_cap, cutout_ray_cap_from, cutout_ray_distance). Off by default. In a scene of card trees, 2 texels from 40 m took 15 to 18 % off the frame from the air.
• HUD pass: up to 256 sprites a frame (was 64), and small text keeps its strokes (see fixes).
• Fast exit. A headless canvas on a hidden-window surface no longer presents (22 to 35 s off its exit; THREEPP_VULKAN_SUPPRESS_PRESENT=0 restores presents). The pipeline cache blob is capped at 64 MB and not rewritten when unchanged; one had grown to 475 MB. THREEPP_VK_EXIT_TIMING=1 prints where a teardown spends its time.
• Python: sharpen_strength, motion_blur, and PointLight.radius / SpotLight.radius for ray-traced soft shadows.
• Diagnostics: THREEPP_VK_SHADE_SPEC_MASK, THREEPP_VK_SHADE_SPEC_PROBE and THREEPP_VK_ASYNC_PILOT (an async-compute pilot; a loss on an RTX 4070, kept for measurement).

OpenGL, core and loaders

• FXAAPass, ported from three.js r186. It runs after an OutputPass and smooths the edges MSAA leaves stepped next to bright emitters.
• Fonts measure text: Font::advance, ascender and descender, also from Python. The TTF loader takes Latin-1, Extended-A, Greek and the common punctuation, arrow and maths blocks.
• TextSprite can size text by the font's line (TextBox::Line): every string gets one glyph size and one baseline, so HUD text can be laid out without measuring each string. The default stays Ink.
• OBJLoader loads polylines (l records) as LineSegments.
• Material::linewidth and defaultAttributeValues reach GL (see known issues for wide lines).
• AsyncGroup::hasFailed(), and math::spatialHash for the cell hash five sites wrote out by hand.

Physics

• PhysxVehicle::associate(node): sensors at or under a node ride the vehicle's chassis.
• Engine braking for the direct-drive vehicle: Settings::engineBrakeTorque and engineBrakeIdleSpeed (Python engine_brake_torque, engine_brake_idle_speed). Off by default.
• PhysX soft bodies feed the GL renderer zero-copy through the CUDA-GL interop (physx_softbody). Phong materials get GPU tet skinning.
• Python: RigidBody.add_force_at_pos and add_torque.

Python

• ScalarField.from_numpy: any field computed in numpy (a fused TSDF, an analytic SDF) can go through marching_cubes.
• Texture.to_numpy() returns a uint8 texture's pixels.
• MeshStandardMaterial terrain bands (terrain_weight_map, set_terrain_band, and their knobs) for a terrain loaded from a file.
• Stencil test on every material (color_write, stencil_*, StencilFunc, StencilOp), so one draw can clip another. GL only.
• threepp.lesson (experimental, opt-in): the explainer-video toolkit, with a Stage, a Hud, measured-speech timing, a film writer and a shared command line. Extras threepp[lesson] and threepp[narration]. The films made with it live in threepp-lessons.
• A node fetched from a C++-owned subtree keeps its owner alive. hub = model.get_object_by_name("hub"); del model used to dangle.

Vehicle rigs (python/examples/rigs)

Each vehicle has a spec JSON that holds every number with its source, a generator that builds the .glb through headless Blender, and a flight or motion model that imports no renderer. The .glb files are generated, not shipped. Numbers that are not from the cited source are marked as assumed.

• usv_rig.py: strip-theory buoyancy on a 6-DOF body (StripHull), three drives (waterjet, azimuth pods, fixed pods), the hull's wake and wash, and an opt-in 3-DOF manoeuvring model with a current. Boats: the Mariner (6 m, waterjet), the Otter X (4.6 m catamaran) and the Otter (2 m catamaran), all after Maritime Robotics' sea drones. Run them with usv/usv_ocean.py --boat mariner|otterx|otter.
• x8_rig.py: the Skywalker X8 fixed wing on the 6-DOF model of Løw-Hansen et al. (CEAS Aeronautical Journal, 2025).
• remus_rig.py: the REMUS 100 AUV on Prestero's 6-DOF model (MIT / WHOI, 2001).
• m350_rig.py: the DJI Matrice 350 RTK as a multirotor in wind, with Dryden turbulence, a mission layer and a gimbal. There is no published model behind it.
• babyshark_rig.py: the Foxtech Babyshark 260 VTOL quadplane on Graesdal's wing model (NTNU, 2021), with uav/babyshark_fly.py to fly it from the keyboard.
• aerosonde_rig.py and bixler3_rig.py: Beard and McLain's Aerosonde, and the Bix3 that Simmons identified from flight tests (Virginia Tech, 2018).
• evoque_rig.py: the Range Rover Evoque on PhysxVehicle, with head lamps that light, a seat a camera rides in, and keys that steer by sideways acceleration.

Examples

• C++, OpenGL, no assets loaded:
  • showpiece: a car in a chrome vortex with soft shadows, glass with iridescence and dispersion, and a composer chain of MSAA, GTAO, bloom, outline and FXAA.
  • MarbleRun: a rolling-ball sculpture. 96 marbles, instanced glass with transmission, marbles that carry lights, a marble camera, a mirror-polished floor, depth of field, and chimes played from where each hoop is.
  • SandTable: a box of sand and water to dig, flood and drain. Shallow water on a 240 x 160 grid, sand that slumps and erodes, a tap, a drain and rain. About 3 ms of physics a frame on one core.
  • SpheroControl is rebuilt as a Sphero RVR at its real size that follows a ball by its own camera.
• Python:
  • turbine/: five robots inspect an offshore wind turbine from blade tip to seabed (the IEA 15 MW reference turbine, a drone, two sea drones, an ROV and a snake robot).
  • uav/m350_acoustic.py: nine microphones locate the M350 by the sound of its rotors (GCC-PHAT and SRP-PHAT; 0.44 m median error on a held-out flight, with the rotor timbre assumed).
  • warp_soft_tentacle.py: soft tentacles that wrap a ball each and lift it.
  • warp_round_trip.py: cloth, sparks and the frame shared between Warp and the renderer.
  • warp_sailboat.py leaves her mark through the wake field. The white patch astern at sailing speeds is gone.
• The gtao example gets a panel for every knob and shows its data outputs without the tone curve.

Web build

• Scenes are lit by their environment. The PMREM shaders named desktop GLSL and did not compile under WebGL2, so every web example lit through scene.environment was drawn without it.
• Sound plays. The examples export HEAPF32, and the engine mixes 2048 frames at a time in the browser.
• The shell page scales the canvas to fit the window instead of clipping it, also after a round trip through fullscreen.
• MarbleRun, SandTable, SpheroControl and showpiece are built for the web, and transmission now has its HDR.

Build

• A CMake regeneration no longer recompiles tinyusdz, Canvas and EmbeddedFonts.
• threepp_data is pinned to 9689df3, which adds empty_warehouse_01_2k.hdr.
• The Vulkan shaders share their camera, light, geometry and cluster declarations through includes instead of per-shader copies. The generated SPIR-V is unchanged where it was compared.
• The deferred shade, froxel inject and particle lighting shaders are compiled twice, the second time without ray queries, for the no-ray-tracing mode.
• CI's Vulkan runtime gate (on lavapipe) runs the no-ray-tracing mode. Compiling the ray-traced shade kernel on the CPU took about 18 GB on a runner with 15.6 GB, and the job passed or took the runner down depending on the machine. The gate step now passes in under two minutes with under 3 GB in use. The ray-traced path is validated by VulkanValidation_test on a real GPU, no longer in CI.
• No user names or machine paths remain in scripts, docstrings or defaults.

---

Fixes

OpenGL

• A material wired to a nested pass's lights (a Reflector or Water mirror pass) passed for up to date in the main pass, which was then lit from the mirror camera's side. With a second render target in the frame it showed as a floor flickering at half the frame rate. Every Lights now shares one version counter, as in three.js.
• A ShaderMaterial that asked for clipping never got its planes.
• Material::linewidth never reached GL, and defaultAttributeValues was never applied.
• The 1x1 fallback texture uploaded uninitialised bytes, and the draw-buffer cache was built with 1029 elements.
• A cloned InterleavedBufferAttribute had no elements, so a cloned Sprite had no corners.
• The opaque sort compared a program id that was always 0.
• Web: copyTextureToImage left the framebuffer cache naming the wrong target.

Vulkan

• Device lost: setEmissiveCastsLight shared a flag bit with "the index buffer is uint16". Turning a mesh back on made every ray that hit it read out of bounds, and large meshes crumpled in reflections.
• Device lost: occlusion culling skipped its descriptor writes when a recreated buffer came back with the same handle value. The same comparison is replaced with object serials in eight other caches.
• Sync validation: a BLAS build raced the write of its vertex data (476 hazards on a large scene, now 0), and the G-buffer init clears (8, now 0).
• Small HUD text lost its strokes ("DEPTH UNDER KEEL" read "DCPTII UNDCR KCCL"): odd-sized sprite atlases now get an area-weighted mip chain.
• A point light left the water under it black, and so did any spot light outside the eight strongest.
• The air haze's sun glow reached a submerged camera unattenuated, as a grey band above eye level.
• Textured surfaces behind glass or in a reflection were finest-mip speckle.
• One-shot submits and host maps whose results were ignored are now checked.

Core and loaders

• TrueType curves and UTF-8 text (above). Each glyph's vertex list is freed, not only the last one.
• SVGLoader rect corners, and radii clamped to half the side as the SVG spec requires.
• CubeTextureLoader took its channel count from whichever face decoded last, so a mixed jpg and png set declared one count and held another.
• OBJLoader read past its buffer when the uv count did not match the vertex count.
• AsyncGroup swallowed a throwing loader and stayed unloaded forever, silently.
• TerrainScatter's cell hash overflowed a signed int (undefined behaviour) for cells beyond 29.

Python

• drone_rig's gimbal stood 12 degrees off its target on average (Euler order).
• The stubs declare the terrain bands, and vector members (CatmullRomCurve3.points, LidarModel.elevation_angles, ...) say that they are copies: assign the whole list.
• A second PhysxWorld in one process raises with advice on how to release the first.

---

Known open issues

• OpenGL scenes with a Reflector or Water had the light-version fault too, so their lighting may move. Only MarbleRun was compared before and after.
• Vulkan: what a clear thin pane shows is not denoised, so it carries grain from a moving camera.
• Vulkan: the emissive range gate covers the first 64 emissive instances. Beyond that every light is sampled everywhere, as before.
• Vulkan without ray tracing: the mode has run only through THREEPP_VULKAN_NO_RT=1, on an RTX 4070 and on lavapipe, not on a device that lacks ray query. The sun's screen-space shadows miss casters that are off screen or hidden, and lamps cast no shadows.
• OpenGL: wide lines are not available on the desktop's forward-compatible core context. linewidth is declined there without an error, as in WebGL.
• PhysX: on ground that itself moves, a braked car still slips at about 0.2 m/s.
• Web: a mouse press is reported at the position of the last move, so a tap without a preceding move can land on a stale position. Each linked shader program prints an empty warning line. The transmission page is 24 MB because of its 4k HDR.

---

This discussion was created from the release 2026-10-11.