design: optional RGB band depth encoding (t980u)

Authored 2026-11-07 · 7 days ago

Hash: a1800952c19cbd168a960f64a6f36f56eefd834e
Parent: c0f91f8a
Pipeline: Obsolete

1 file changed +4 −0

design.md +4 −0

@@ -404,3 +404,7 @@ A **Render alles** button renders the whole project in one batch: every configur

404 404

Exports no longer pile up as `renders/run-<id>/` folders. Each result lives in `renders/<sex>-<settype>-atlas/` and holds only the newest complete render (loose PNGs, atlases, `.ppda`, manifests). A new render is built in a temporary in-progress folder inside `renders/` (also used for resume). Only after it is fully complete and verified is the previous `<sex>-<settype>-atlas/` removed and the new folder renamed into place. A crash or cancel therefore never loses the last good result, and an unfinished run can still be resumed. Older `run-*` folders from earlier versions are not deleted automatically; the 2D preview ignores them with a notice. The 2D preview and **Render alles** use these fixed folders.

405 405

406 406

Implementation (2026-11-07): the build folder is `renders/inprogress-<stamp>-<pid>-<sex>-<settype>/` (the only resumable kind). After `complete.json` the run is re-validated with `AtlasSet::open_run`, its lock released, the old result renamed to `.replaced-<name>-<stamp>`, the build renamed to `<sex>-<settype>-atlas`, then the old one removed (restored if the rename fails). `resume::recover` runs before every render: a `.replaced-*` folder is restored when its result folder is missing (else removed), and a completed, unlocked, validating `inprogress-*` folder is promoted. The 2D preview only opens `*-atlas` folders whose name matches their `.ppda` sex/settype; `run-*` folders are skipped with a notice; `inprogress-*`/`.replaced-*` are ignored silently.

407

408 ## Decision 2026-11-07 (Tim t980u): optional RGB band depth encoding

409

410

A boolean project setting in `.ppd`, `depth_rgb_bands`, default **off**. Off: depth is exported as today (16-bit gray+alpha, `distance = near + (gray/65535)·(far−near)`). On: the depth map is exported as **8-bit RGBA "bands"**: with `t = (d − near)/(far − near)` clamped to 0..1, `v = round(t·765)`, `R = min(v, 255)`, `G = clamp(v − 255, 0, 255)`, `B = clamp(v − 510, 0, 255)`; decode `v = R + G + B`, `d = near + (v/765)·(far − near)`. This gives 766 levels; alpha is kept. The encoding is recorded in `render.json` and in the `.ppda` (`depth_encoding` value plus a boolean `depth_rgb_bands`), so the game renderer and the 2D previewer decode it correctly; the previewer/compositor support both encodings. Older `.ppda` files without the boolean are read as gray16. The setting is part of the render contract (changing it is a contract difference for resume).

@@ -404,3 +404,7 @@ A **Render alles** button renders the whole project in one batch: every configur

404

Exports no longer pile up as `renders/run-<id>/` folders. Each result lives in `renders/<sex>-<settype>-atlas/` and holds only the newest complete render (loose PNGs, atlases, `.ppda`, manifests). A new render is built in a temporary in-progress folder inside `renders/` (also used for resume). Only after it is fully complete and verified is the previous `<sex>-<settype>-atlas/` removed and the new folder renamed into place. A crash or cancel therefore never loses the last good result, and an unfinished run can still be resumed. Older `run-*` folders from earlier versions are not deleted automatically; the 2D preview ignores them with a notice. The 2D preview and **Render alles** use these fixed folders.

404

Exports no longer pile up as `renders/run-<id>/` folders. Each result lives in `renders/<sex>-<settype>-atlas/` and holds only the newest complete render (loose PNGs, atlases, `.ppda`, manifests). A new render is built in a temporary in-progress folder inside `renders/` (also used for resume). Only after it is fully complete and verified is the previous `<sex>-<settype>-atlas/` removed and the new folder renamed into place. A crash or cancel therefore never loses the last good result, and an unfinished run can still be resumed. Older `run-*` folders from earlier versions are not deleted automatically; the 2D preview ignores them with a notice. The 2D preview and **Render alles** use these fixed folders.

405

406

Implementation (2026-11-07): the build folder is `renders/inprogress-<stamp>-<pid>-<sex>-<settype>/` (the only resumable kind). After `complete.json` the run is re-validated with `AtlasSet::open_run`, its lock released, the old result renamed to `.replaced-<name>-<stamp>`, the build renamed to `<sex>-<settype>-atlas`, then the old one removed (restored if the rename fails). `resume::recover` runs before every render: a `.replaced-*` folder is restored when its result folder is missing (else removed), and a completed, unlocked, validating `inprogress-*` folder is promoted. The 2D preview only opens `*-atlas` folders whose name matches their `.ppda` sex/settype; `run-*` folders are skipped with a notice; `inprogress-*`/`.replaced-*` are ignored silently.

406

Implementation (2026-11-07): the build folder is `renders/inprogress-<stamp>-<pid>-<sex>-<settype>/` (the only resumable kind). After `complete.json` the run is re-validated with `AtlasSet::open_run`, its lock released, the old result renamed to `.replaced-<name>-<stamp>`, the build renamed to `<sex>-<settype>-atlas`, then the old one removed (restored if the rename fails). `resume::recover` runs before every render: a `.replaced-*` folder is restored when its result folder is missing (else removed), and a completed, unlocked, validating `inprogress-*` folder is promoted. The 2D preview only opens `*-atlas` folders whose name matches their `.ppda` sex/settype; `run-*` folders are skipped with a notice; `inprogress-*`/`.replaced-*` are ignored silently.

407

408## Decision 2026-11-07 (Tim t980u): optional RGB band depth encoding

409

410

A boolean project setting in `.ppd`, `depth_rgb_bands`, default **off**. Off: depth is exported as today (16-bit gray+alpha, `distance = near + (gray/65535)·(far−near)`). On: the depth map is exported as **8-bit RGBA "bands"**: with `t = (d − near)/(far − near)` clamped to 0..1, `v = round(t·765)`, `R = min(v, 255)`, `G = clamp(v − 255, 0, 255)`, `B = clamp(v − 510, 0, 255)`; decode `v = R + G + B`, `d = near + (v/765)·(far − near)`. This gives 766 levels; alpha is kept. The encoding is recorded in `render.json` and in the `.ppda` (`depth_encoding` value plus a boolean `depth_rgb_bands`), so the game renderer and the 2D previewer decode it correctly; the previewer/compositor support both encodings. Older `.ppda` files without the boolean are read as gray16. The setting is part of the render contract (changing it is a contract difference for resume).