@unikia/upe-renderer 0.186.110 → 0.187.11

package/README.md

@@ -1,12 +1,12 @@
 # @unikia/upe-renderer
 
-Unikia's three.js. It is three.js r186 with the API Uniplay games were reaching into private internals for, and a WebGPU device set up to use what the GPU offers. Games install it as `three` through an npm alias, so game code, the SDK and libraries such as `three-avbd` keep importing `three`:
+Unikia's three.js. It is three.js r187 with the API Uniplay games were reaching into private internals for, and a WebGPU device set up to use what the GPU offers. Games install it as `three` through an npm alias, so game code, the SDK and libraries such as `three-avbd` keep importing `three`:
 
 ```json
-"dependencies": { "three": "npm:@unikia/upe-renderer@0.186.110" }
+"dependencies": { "three": "npm:@unikia/upe-renderer@0.187.11" }
 ```
 
-It keeps three's entry points (`three`, `three/webgpu`, `three/tsl`, `three/addons/*`) and ships the `@types/three` 0.186 declarations beside the code, so code written against `@types/three` keeps compiling.
+It keeps three's entry points (`three`, `three/webgpu`, `three/tsl`, `three/addons/*`) and ships the `@types/three` 0.186 declarations beside the code, so code written against `@types/three` keeps compiling. `@types/three` 0.187 isn't out yet, so what r187 adds (`Light.registerNode()`, `renderer.drawingPipeline`, `StandardDrawingPipeline`) has no types until it is, and what it removed (`CubeUVReflectionMapping`) still has them.
 
 **For AI coding agents:** integrating a game with this renderer (and the SDK's `render` module) is
 described in the `upe-integrate` skill, in `@unikia/upe-sdk` (`skills/upe-integrate/SKILL.md`) or
@@ -17,9 +17,7 @@ game's `three` or porting it to `WebGPURenderer`.
 
 All of it is in `WebGPURenderer` (`three/webgpu`); everything three.js already does works as before.
 
-- **`BufferAttribute.dispose()` frees the attribute's GPU buffer.** three.js has the method but the renderer never listened to it. Drawing the attribute again uploads it afresh.
 - **`renderer.releaseObject(object)`** frees what the renderer keeps for an object and everything under it: its render objects in every pass (shadow passes too), with their pipelines, bindings and node state, and the buffers they were drawn with besides their geometries' own (an instanced mesh's instance buffers, buffers their materials' nodes made). Buffers anything else still draws with are kept; geometries, materials and textures are left to their own `dispose()`.
-- **A disposed shared geometry no longer keeps a scene alive.** three.js's geometry dispose listener held the first render object drawn with the geometry, and through it that object's whole tree, for as long as the geometry lived; it could also be added twice and never removed. It now holds only the geometry, and frees the node attributes of every render object drawing it.
 - **`renderer.getGPUTimings()`** (after `resolveTimestampsAsync()`, or **`resolveGPUTimingsAsync()`** for both) gives the last resolved frame's render and compute passes with their start, end and duration, their `sum`, and their `union`: the time the GPU was busy. Passes overlap on tile-based GPUs (Apple's), where the sum overstates the frame several times over. A pass whose end timestamp the GPU never wrote (one that draws nothing, on Apple GPUs) is counted in `unwritten` and left out, here and in `resolveTimestampsAsync()`'s total, which three.js made hugely negative.
 - **`renderer.capabilities`**, read once at `init()`: the `tier` (`webgpu-full` with subgroups, immediates and WGSL `buffer_view`; `webgpu-core` with compute and indirect draws; `webgl2`), the device's `features` and `limits`, `adapterFeatures`, `wgslLanguageFeatures`, `subgroupSizes`, `adapterInfo`, `compatibilityMode`, and `api` (`multiDrawIndirect`, `transientAttachments`, `immediates`). Choose code paths from these, never from the browser's name.
 - **The WebGPU device asks for everything the adapter offers**: every feature (three.js asks only for those it knows by name, leaving out `subgroup-size-control`, `primitive-index` and others) and every limit (three.js keeps WebGPU's defaults, 8 storage buffers per stage and 4 bind groups whatever the GPU offers). `requiredLimits: 'default'` gives the defaults back; an object asks for exactly those limits.
@@ -27,12 +25,12 @@ All of it is in `WebGPURenderer` (`three/webgpu`); everything three.js already d
 - **`GPUInstanceCuller`** picks which instances of a group of instanced meshes are drawn, and in which version, in a compute pass that writes indirect draws: the CPU never sorts, uploads or reads back instance matrices. You give it distance bands (`{ until, inView }`, nearest first) and per instance a matrix, a bounding sphere and, per band, the meshes that draw it (a tree's bark and leaves, near, far or distant). Call `culler.update(renderer, camera)` once a frame before rendering. It takes the meshes over: they share one storage buffer of matrices and draw indirectly from geometries of their own that share the originals' buffers; shadow passes draw what the camera's pass picked. It needs the WebGPU backend (both tiers); on WebGL 2, cull on the CPU. `GPUInstanceCuller.recommended(renderer)` says whether to use it: on `webgpu-full` only, since in a WKWebView (`webgpu-core`) its indirect draws measured slower than culling on the CPU, at half the frame rate in Project Zarya's forest on an M3 Max. `bun run test:gpu` checks it against the CPU rules in Chrome and, on macOS, in a WKWebView.
 
 - **Uniform buffers are written once per submit.** Each uniform buffer is a slice of a few large GPU buffers with a CPU copy; an update is a copy into memory, and just before each submit the updated slices go up in one `writeBuffer` per run of nearby slices, instead of a `writeBuffer` per buffer. The GPU sees the same data (the last write before a submit wins, as before). Buffers over 64 KB keep their own.
-- **Instanced meshes send only what they draw.** An instance buffer marked `needsUpdate` with no update ranges sends the instances up to the mesh's `count`, not its whole capacity, so a culler refilling the first few hundred of thousands of slots sends those; when `count` later grows, the instances that weren't sent go up before the draw, as they stand then. Matrices kept in a uniform buffer (up to 1024 instances) go up when they change, not on every frame, so as in WebGL, a change reaches the GPU only with `needsUpdate`. More than 1024 matrices always take an instance buffer, even where the device allows larger uniform buffers (WebKit's does).
+- **Instanced meshes send only what they draw.** An instance buffer marked `needsUpdate` with no update ranges sends the instances up to the mesh's `count`, not its whole capacity, so a culler refilling the first few hundred of thousands of slots sends those; when `count` later grows, the instances that weren't sent go up before the draw, as they stand then. three.js r187 gives each instanced mesh an instance buffer and shares its shaders between meshes; a mesh whose geometry leaves no vertex buffer free for one (and the `instance()` TSL function) still keeps up to 1024 matrices in a uniform buffer. Those go up when they change, not on every frame, so as in WebGL, a change reaches the GPU only with `needsUpdate`. More than 1024 matrices always take an instance buffer, even where the device allows larger uniform buffers (WebKit's does).
 
 - **Dynamic buffers go up when flagged, as in WebGL.** An attribute or interleaved buffer with `DynamicDrawUsage` reaches the GPU when its version moves (`needsUpdate`), with its update ranges, instead of whole on every frame. Only a buffer three.js makes around a plain array (`dynamicBufferAttribute(array)`), which has no `needsUpdate` of its own, still goes up every frame.
 
 Transient attachments: three.js r186 already makes a multisampled buffer transient when its render target says its multisampled data aren't needed after the pass (`storeMultisampledColorBuffer` or `storeMultisampledDepthBuffer: false`). A transient attachment can't be read by a later pass, so render targets a later pass samples (a scene pass's depth and normals for ambient occlusion, bloom's chain) can't be transient.
 
-Each build has a name, `r<three.js revision>p<our revision>`: `r186p10` is three.js r186 with our revision 10 (`UPE_RENDERER` and `UPE_REVISION` in `three`, which the SDK's debug panel shows). Our revision counts on across three.js releases, so the next build on r187 is `r187p11`. Versions carry both: `0.<three minor>.<three patch × 100 + our revision>`, so `r186p10`, built on three 0.186.1, is `0.186.110`, and `r187p11` on three 0.187.0 would be `0.187.11`. Install a version range on the three.js minor (`~0.186.110`) to follow our fixes without moving three.js.
+Each build has a name, `r<three.js revision>p<our revision>`: `r186p10` is three.js r186 with our revision 10 (`UPE_RENDERER` and `UPE_REVISION` in `three`, which the SDK's debug panel shows). Our revision counts on across three.js releases, so the first build on r187 is `r187p11`. Versions carry both: `0.<three minor>.<three patch × 100 + our revision>`, so `r186p10`, built on three 0.186.1, is `0.186.110`, and `r187p11`, on three 0.187.0, is `0.187.11`. Install a version range on the three.js minor (`~0.187.11`) to follow our fixes without moving three.js.
 
 See `UPSTREAM.md` for how the package tracks three.js.

package/UPSTREAM.md

@@ -1,10 +1,10 @@
 # Upstream
 
-This package starts from a snapshot of three.js, not its git history:
+This package started from a snapshot of three.js, not its git history, and has since been merged forward:
 
-- `src/`, `examples/jsm/`, `build/three.cjs` and `LICENSE`: the `three` npm package, version **0.186.1** (r186), unchanged in the commit that imported them.
-- Every `.d.ts` file and `LICENSE.types`: the `@types/three` npm package, version **0.186.0**, placed beside the JavaScript it describes, as `@types/three` lays them out.
-- `utils/build/rollup.config.js`: three.js's build at the `r186` tag. Building the imported sources with it gives three's published `build/` byte for byte.
+- `src/`, `examples/jsm/`, `build/three.cjs` and `LICENSE`: the `three` npm package, now version **0.187.0** (r187); the snapshot was 0.186.1 (r186), unchanged in the commit that imported it.
+- Every `.d.ts` file and `LICENSE.types`: the `@types/three` npm package, still version **0.186.0**, placed beside the JavaScript it describes, as `@types/three` lays them out. 0.187.0 wasn't published when r187 came out: run `bun run upstream 0.187.0 0.187.0` once it is.
+- `utils/build/rollup.config.js`: three.js's build at the `r187` tag.
 
 `package.json`'s `upstream` field records the versions this package is based on. To move to a newer three.js, run `bun run upstream <three version> [<@types/three version>]`: it three-way merges the change between the recorded and the new upstream into this package, leaving conflict markers where our changes overlap theirs. A single upstream fix can be taken the same way, by applying its pull request's patch with `git apply -3 --directory=packages/renderer`, since the files keep three's layout.