hilo3d 2.0.0-alpha.1 → 2.0.0-alpha.3

package/CHANGELOG.md

@@ -1,3 +1,72 @@
+# 2.0.0-alpha.2 (2026-07-26)
+
+### Breaking changes
+
+- Expand the fixed `MaterialBlock` std140 ABI for layered PBR material data and reserve WebGPU group
+  3 bindings 0/1 for the pass-global opaque scene texture. Portable custom uniform blocks retain
+  registration order and now start at WebGPU group 3 binding 2.
+
+### Changes
+
+- Replace the legacy PBR lighting core with correlated Smith-GGX, Burley diffuse, anisotropic GGX,
+  energy-compensated/specular-occluded IBL, layered clearcoat, and physically smooth punctual-light
+  attenuation. Add glTF parsing and material shader support for `KHR_materials_anisotropy`,
+  `KHR_materials_clearcoat`, `KHR_materials_transmission`, `KHR_materials_volume`, and
+  `KHR_materials_ior`, plus spectrally integrated thin-film `KHR_materials_iridescence`.
+- Add forward opaque scene-color capture and pass-global transparent-material sampling through the
+  Render Graph/RHI path. Add a linear-HDR `PostProcessRenderPipelineFactory`, engine-owned
+  soft-knee/13-tap/tent-pyramid `Bloom`, and a one-pass `ColorUber` display transform with LMS white
+  balance, grading, PBR Neutral/ACES/Reinhard tone mapping, vignette, exact sRGB output, and
+  display-space dithering.
+- Replace the Bloom example's application-owned RenderTarget/Gaussian/composite implementation with
+  the built-in HDR Bloom and Color Uber pipeline.
+- Add a layered PBR studio with live anisotropy, clearcoat, transmission, and volume comparisons,
+  plus a switchable Khronos glTF material gallery using the attributed Anisotropy Barn Lamp,
+  Clearcoat Wicker, Dragon Attenuation, and animated Iridescent Dish with Olives sample assets.
+- Replace the overlapping legacy PBR sphere stack with a controlled 30-sample Material Lab,
+  switchable steel/copper/gold/ceramic families, explicit metallic/roughness axes, studio lighting,
+  and the engine HDR post-processing pipeline.
+- Remove the twelve low-resolution baked/cloud cube-map images from the examples. Shared PBR and
+  glTF pages now use a seam-coherent procedural studio environment with neutral fill, warm/cool
+  softboxes, generated mipmaps, and runtime PNG face URLs for the CubeTextureLoader/image-release
+  examples.
+- Add measured-width `Text2D` wrapping for mixed CJK/Latin content, max-line clipping and ellipsis,
+  baseline, paragraph spacing, and letter spacing. Add in-place Sprite source replacement,
+  material-only Sprite initialization, atlas-batched `SlicedSprite`, four-state `UiButton`, and
+  ImageGen-authored responsive text/nine-slice examples for WebGL 2 and WebGPU.
+- Add Node-level `sortingLayer` and `zIndex` for Sprite/Text2D display order, retain stable
+  scene-tree order for ties, make pointer picking select the same topmost 2D node, and restrict
+  transparent instancing to adjacent compatible items so batching cannot reorder interleaved
+  textures. Document the independent top-left Camera2D and centered Sprite-anchor contracts, and add
+  an ImageGen-authored pixel-town example with A* walking, click-to-route interaction, and foot-Y
+  ordering across both backends.
+- Lower the supported development and package runtime floor to Node.js 20.19.0, the shared minimum
+  accepted by Vite 8 and ESLint 10, and pin npm 10.9.4 so the declared package manager also runs on
+  Node 20.
+
+### Fixes
+
+- Keep float scene-color variants linear by suppressing material-local gamma encoding and legacy
+  per-material tone mapping until the final display transform. Preserve HDR Bloom energy with
+  normalized Karis weights, remove the non-physical far-distance light floor, and use refracted
+  volume path length for Beer-Lambert attenuation.
+- Rebalance the Khronos layered-material gallery around neutral photographic key/fill lighting,
+  readable opaque transmission backdrops, restrained warm highlights, and a 90-degree orbit pitch so
+  dark metals and iridescent glass remain legible without clipping the top view.
+- Define one portable coordinate contract for fullscreen render targets, native fragment
+  coordinates, top-left managed 2D textures, cube-map face rows, BRDF/LTC lookup tables, compute
+  storage rows, pointer input, and readback. Apply it to Bloom, Color Uber, graph present,
+  transmission, ShaderToy, Life Game, the compute particle field, the compute path tracer, and
+  built-in material/environment sampling so WebGL 2 and WebGPU retain the same Y orientation.
+- Correct `SpriteFrame`'s top-left atlas-row offset for `flipY` textures on both backends. Full
+  textures were unaffected, but subframes previously selected the vertically opposite source row,
+  swapping nine-slice top/bottom pieces and requiring reversed character-direction maps. Use a
+  strictly nine-slice-safe postal UI atlas with uniform stretchable edges and deterministically
+  mirrored corners/edge lighting.
+- Expand the game-building skill's coordinate contract: Sprite positions target their anchor in the
+  parent local coordinate system, and the default center anchor does not become top-left merely
+  because Camera2D uses a top-left screen origin.
+
 # 2.0.0-alpha.1 (2026-07-25)
 
 ### Breaking changes
@@ -37,6 +106,13 @@
 - Redesign the examples gallery with categorized metadata, search, responsive navigation, accessible
   controls, isolated per-example query parameters, source/direct links, loading states, and a shared
   renderer statistics panel that reports the active WebGL 2 or WebGPU backend.
+- Curate the gallery into focused Highlights and All Examples collections, replace generic
+  descriptions with capability-oriented copy, merge five primitive micro-pages into one visual
+  geometry lab, rename the two CanvasTexture demos, and remove obsolete OSG/SMD/TGA loaders,
+  duplicated Polly content, unused media, and the non-visual math fixture page.
+- Refresh the shared example lighting and dark canvas treatment, and rebuild Quick Start, point
+  lights, instancing, and bloom around deterministic showcase scenes. Add an ImageGen-authored
+  graphite/cyan/violet showroom-floor texture used by the new scenes.
 - Add renderer-local scriptable render pipelines through `RendererCommonOptions.renderPipeline`,
   reusable `RenderPipelineFactory` configurations, frame-scoped culling/renderer-list handles, a
   narrow `ScriptableRenderGraph`, retained pass-parameter pools, recovery-aware persistent targets,

package/README.md

@@ -192,6 +192,36 @@ failure handling, performance gates, and the capability-gated route to storage b
 Those compute/storage capability names are currently fail-closed rather than partially emulated on
 WebGL 2.
 
+### HDR PBR and built-in post-processing
+
+Use the turnkey post-process factory for linear `rgba16float` lighting, engine-owned opaque scene
+color, high-quality pyramid Bloom, and one final Color Uber display transform:
+
+```ts
+const stage = await Hilo3d.Stage.create({
+    backend: 'auto',
+    container: document.querySelector('#app')!,
+    camera,
+    renderPipeline: new Hilo3d.PostProcessRenderPipelineFactory({
+        bloom: { threshold: 1, knee: 0.5, intensity: 0.8, scatter: 0.7 },
+        colorUber: { toneMapping: 'pbr-neutral', exposure: 0 },
+        opaqueTexture: true
+    })
+});
+```
+
+PBR lighting uses correlated Smith-GGX, Burley diffuse, energy-compensated specular IBL, layered
+clearcoat, thin-film iridescence, anisotropic GGX, inverse-square punctual lights, and screen-space
+transmission with Beer-Lambert volume attenuation. The glTF loader supports
+`KHR_materials_anisotropy`, `KHR_materials_clearcoat`, `KHR_materials_transmission`,
+`KHR_materials_volume`, and `KHR_materials_ior`, plus `KHR_materials_iridescence`. See the
+[PBR/HDR contract](./documentation/PBR_AND_POST_PROCESSING.md) for color-space rules, algorithms,
+and the explicit screen-space transmission limits. The
+[layered PBR studio](https://hilo3d.js.org/examples/pbr_layered_materials.html) demonstrates the
+direct material API, while the
+[Khronos material gallery](https://hilo3d.js.org/examples/gltf_material_extensions.html) exercises
+the same path with attributed production glTF assets.
+
 ## Modern renderer architecture
 
 - `src/render` owns the single public Renderer, scene traversal, frame planning, render-target
@@ -314,6 +344,7 @@ shared Renderer/RenderTarget API.
 - [glTF viewer](https://hilo3d.js.org/examples/glTFViewer/index.html)
 - [Engineering documentation index](./documentation/README.md)
 - [Current rendering architecture](./documentation/RENDERING_ARCHITECTURE.md)
+- [PBR, HDR, and post-processing](./documentation/PBR_AND_POST_PROCESSING.md)
 - [vNext renderer engineering record](./documentation/ENGINEERING_MODERNIZATION.md#双后端渲染与-shader-abi)
 - [ShaderMaterial migration guide](./documentation/ENGINEERING_MODERNIZATION.md#shadermaterial-迁移)
 - [Breaking changes](./CHANGELOG.md#breaking-changes)

package/README_ZH.md

@@ -180,6 +180,34 @@ fullscreen feature 采样 scene color；
 buffer/compute 的 capability-gated 扩展路线。当前 compute/storage
 capability 会明确失败，不会在 WebGL 2 上提供不完整模拟。
 
+### HDR PBR 与内置后处理
+
+完整的线性 `rgba16float` 光照、引擎 opaque scene color、高质量 pyramid Bloom 与最终 Color
+Uber 显示变换可以直接使用：
+
+```ts
+const stage = await Hilo3d.Stage.create({
+    backend: 'auto',
+    container: document.querySelector('#app')!,
+    camera,
+    renderPipeline: new Hilo3d.PostProcessRenderPipelineFactory({
+        bloom: { threshold: 1, knee: 0.5, intensity: 0.8, scatter: 0.7 },
+        colorUber: { toneMapping: 'pbr-neutral', exposure: 0 },
+        opaqueTexture: true
+    })
+});
+```
+
+PBR 光照使用 correlated Smith-GGX、Burley diffuse、带能量补偿的 specular
+IBL、分层 clearcoat、薄膜干涉 iridescence、anisotropic GGX、inverse-square punctual
+light，以及 screen-space transmission 和 Beer-Lambert volume attenuation。glTF loader 支持
+`KHR_materials_anisotropy`、
+`KHR_materials_clearcoat`、`KHR_materials_transmission`、`KHR_materials_volume` 与
+`KHR_materials_ior`，并支持 `KHR_materials_iridescence`。颜色空间、算法和屏幕空间折射边界见
+[PBR/HDR 合同](./documentation/PBR_AND_POST_PROCESSING.md)。可在
+[分层 PBR 材质展厅](https://hilo3d.js.org/examples/pbr_layered_materials.html)体验直接材质API，也可在
+[Khronos 材质模型展厅](https://hilo3d.js.org/examples/gltf_material_extensions.html)检查同一渲染路径上的真实 glTF 资产。
+
 ## 现代渲染架构
 
 - `src/render` 负责唯一公开的 Renderer、scene traversal、frame planning、render target 契约、std140
@@ -291,6 +319,7 @@ API。
 - [glTF Viewer](https://hilo3d.js.org/examples/glTFViewer/index.html)
 - [工程文档索引](./documentation/README.md)
 - [当前渲染架构](./documentation/RENDERING_ARCHITECTURE.md)
+- [PBR、HDR 与后处理](./documentation/PBR_AND_POST_PROCESSING.md)
 - [vNext 渲染工程记录](./documentation/ENGINEERING_MODERNIZATION.md#双后端渲染与-shader-abi)
 - [ShaderMaterial 迁移指南](./documentation/ENGINEERING_MODERNIZATION.md#shadermaterial-迁移)
 - [Breaking changes](./CHANGELOG.md#breaking-changes)