Render: save wood images with physical grain controls (#1599)

* Render: save wood images with physical grain controls

* Render: prepare plain glass before marking the GPU host ready
This commit is contained in:
selune
2026-11-05 04:49:46 +00:00
committed by GitHub
parent 6d2465b52d
commit 8691cefbbf
60 changed files with 5776 additions and 238 deletions
+66 -5
View File
@@ -4,11 +4,11 @@ Integration-branch implementation, not a release acceptance claim. Source, type/
## Saved surfaces
`RenderSetup.surfaces` stores at most 128 built-in surface bindings: a `SURF-nnn` ID, resource version, four encoded SHA-256 receipts, an exact definition/producing-feature/component/occurrence-path target, a definition-local planar frame in millimetres, and normal strength. The roles are base color, OpenGL normal, roughness and metallic. Height remains authoring-only. Existing body IOR is retained. Engineering material cards, mass, topology and the CAD timeline are unchanged.
`RenderSetup.surfaces` stores at most 128 surface bindings. Built-in sources retain: a `SURF-nnn` ID, resource version, four encoded SHA-256 receipts, an exact definition/producing-feature/component/occurrence-path target, a definition-local planar frame in millimetres, and normal strength. The roles are base color, OpenGL normal, roughness and metallic. Height remains authoring-only. Existing body IOR is retained. Engineering material cards, mass, topology and the CAD timeline are unchanged.
No captured body ordinal, GPU object or external path is saved. Every Check and Start resolves the semantic target, transforms its local frame into current world coordinates, then produces the ordinary bounded GPU texture request. Motion follows that transform; another instance does not inherit the assignment. Missing, hidden, ambiguous, renamed or replaced definitions/features refuse instead of selecting a similar body. An occurrence label may change while its ID path remains valid. Definition renaming and topology-producing feature changes currently require explicit rebinding.
No captured body ordinal, GPU object or external path is saved. Every Check and Start resolves the semantic target, transforms its local frame into current world coordinates, then produces the ordinary bounded texture request for the selected executor. Motion follows that transform; another instance does not inherit the assignment. Missing, hidden, ambiguous, renamed or replaced definitions/features refuse instead of selecting a similar body. An occurrence label may change while its ID path remains valid. Definition renaming and topology-producing feature changes currently require explicit rebinding.
Bindings are path-independent **for the pinned built-in pack**, not a general embedded external-texture format. Reopening preserves references, but execution refuses an unavailable resource or version/digest mismatch. A future installed pack must still supply those exact bytes; an old ID must never be silently reinterpreted.
Built-in bindings are path-independent **for the pinned built-in pack**. Reopening preserves references, but execution refuses an unavailable resource or version/digest mismatch. A future installed pack must still supply those exact bytes; an old ID must never be silently reinterpreted.
Send the following to `render.library.surface.bind` after inspecting `render.scene`:
@@ -18,7 +18,7 @@ Send the following to `render.library.surface.bind` after inspecting `render.sce
"set": {"job": {"method": "gpu_path", "options": {"samples": 128}}},
"surface": {
"id": "SURF-001", "body_index": 0, "body_name": "Panel",
"plane": "xy", "scale": 1.0
"plane": "xy", "scale": 1.0, "rotation_rad": 0.7853981633974483
},
"replace": false
}
@@ -26,10 +26,71 @@ Send the following to `render.library.surface.bind` after inspecting `render.sce
The temporary ordinal/name pair is checked once, its semantic identity is captured, and the opaque target and planar precision bounds are validated before one atomic setup change/undo. `replace: true` explicitly replaces a prior binding; an identical application is a no-op. The full setup is returned.
`render.library.surface.unbind` takes setup `name` and the exact saved `target`. It can remove an obsolete association without current geometry or a device. Switching a bound setup to CPU/raster without removing GPU-only maps refuses. Temporary optical overrides and unsaved external HDR capture cannot silently supersede saved maps; save the HDR first or explicitly remove the temporary inputs.
`render.library.surface.unbind` takes setup `name` and the exact saved `target`. It can remove an obsolete association without current geometry or a device. Saved opaque maps work with native CPU raytracing and GPU path tracing. Switching to raster refuses instead of dropping the maps. Temporary optical overrides and unsaved external HDR capture cannot silently supersede saved maps; save the HDR first or explicitly remove the temporary inputs.
The existing Render library adds Save maps to this setup and saved-binding inspection/removal. The older temporary-map action stays separate. No alternate UI shell, new artwork or runtime Python dependency is introduced.
## Imported wood and other opaque surface images
The Surfaces panel can import a local color image, choose its physical U/V repeat
and grain angle, and save it with the selected shot. Import records the supplied
author, source and license as inert declared provenance. It does not fetch a URL
or approve licensing. The full frame is saved in definition-local millimetres;
rotating or moving an occurrence carries its grain with it. Physical materials,
mechanical axes, mass and geometry are unchanged.
`render.surface.import` captures exact static 8-bit PNG/JPEG bytes and binds the
image in one undo step. Example after inspecting `render.scene`:
```json
{
"name": "Wood",
"set": {"job": {"method": "gpu_path", "options": {"samples": 128}}},
"body_index": 0, "body_name": "Panel",
"frame": {"origin": [0,0,0], "u": [240,0,0], "v": [0,480,0]},
"maps": {"base_color_srgb": {"path": "/textures/original-wood.png"}},
"provenance": {"author": "Your name", "source": "Original photograph", "license": "Your declared terms"}
}
```
Map inputs also accept `normal_opengl`, `roughness_linear` and `metallic_linear`.
Each map takes `path` and optional `expected_sha256`; a changed selection refuses.
The role is explicit: color normalizes from sRGB before filtering, while normals
and scalar maps remain linear data. Portable base-color PNG declarations must
agree with normalized sRGB. Static metadata and encoding checks apply to portable
imports; older built-in and temporary GPU maps retain their prior decoder admission,
explicit-role interpretation, single-level bilinear sampling and face-map precedence.
Newly imported GPU resources opt into full mip chains and yield to explicit scalar
face appearances. Native CPU maps use full mip chains. `normal_strength` defaults to one and
`flip_v` defaults to false. `replace: true` is required for an existing binding.
The design deduplicates bytes by SHA-256, independently of role. Importing an
existing digest reuses its first recorded provenance; later imports do not replace
that author, source or license metadata. The design stores at most
32 unique images and 64 MiB total encoded storage; each image is at most 16 MiB
and 1024×1024. Complete decode and metadata validation happen before publishing
any resource. Native containers reuse verified `blobs/` entries; portable JSON
uses bounded canonical base64. Save, delete the source file, and reopen offline:
no filesystem path is retained or reopened. Failed import/open leaves the prior
design intact. Older applications refuse the newer format instead of discarding
its resources.
`render.texture.list` reports digests, dimensions, declared provenance and setup
users. `render.texture.remove` refuses referenced images and lists their users;
explicitly unbind them first. Import, unbind, removal and their undo operations
preserve the exact bytes. Completed render handles retain metadata rather than
keeping an uncharged encoded-image cache alive.
The native CPU consumer prepares rows and complete mip chains cooperatively,
then maps the opaque closure used for direct lights and HDR illumination. It
accepts only noninterlaced 8-bit PNG when importing into a CPU setup. Supported
JPEG8 and interlaced PNG remain GPU inputs; explicitly normalize them before CPU use. It
rejects incompatible selected reflections, glass, anisotropy and procedural
surface overrides. Browser execution and unsupported source encodings refuse
explicitly. Projection remains planar: use separately oriented bindings for
separate boards. This is an opaque image-based wood preview, not a volumetric
end-grain or measured wood-scattering model.
## Passive stages
`RenderSetup.stage` stores up to 32 finite passive rectangles, each with ID, world-mm center/half-edge vectors and exact linear RGB reflectance. They are two-sided diffuse surfaces, with zero emission and no transmission. They are appended only to the captured render scene, preserving product ordinals. No engineering bodies or mass are created.
+42 -14
View File
@@ -3,8 +3,11 @@
The renderer supports built-in sources, absolute-color mode, explicit V orientation, linear roughness/metallic maps and content-addressed texture sharing. See [built-in library](render-built-in-library.md) for its bounded resource contract. Legacy examples below retain modulation and rows-down defaults.
Progressive GPU jobs accept immutable per-body base-color and OpenGL tangent-space
normal maps. No document, appearance, recovery, or saved material format changes.
Only explicit runtime commands capture file bytes; queued work does not reopen paths.
normal maps. Runtime commands capture file bytes once; queued work does not reopen paths.
Existing saved built-in and temporary GPU maps retain single-level bilinear
sampling. Newly imported design-owned maps opt into footprint-filtered mip chains. See
[portable surfaces](render-portable-surfaces-and-stages.md) for design-owned bytes,
physical grain orientation, offline reopening and native CPU execution.
```json
{"progressive":true,"raytrace":{"textures":[{"body_index":3,"body_name":"Walnut tabletop","frame":{"origin":[0,0,480],"u":[900,0,0],"v":[0,90,0]},"base_color_srgb":"C:/art/wood.png","normal_opengl":"C:/art/wood-normal.png","normal_strength":0.35}]}}
@@ -19,32 +22,57 @@ bounding-box corners must remain within ±128 repeats; the frame origin must be
within 10 million mm of the camera target. These caps limit f32 coordinate loss.
Base RGB is explicitly sRGB, converted to linear reflectance before bilinear
filtering and multiplied by the body's linear base color. Use a white base to
reproduce the map's color. Normal channels are untransformed linear data. Normal
filtering. Legacy runtime maps multiply the body's linear base color; authored
and imported saved surfaces replace it with the map's absolute reflectance. Normal channels are untransformed linear data. Normal
strength scales tangent XY in 0..1 before normalization; degenerate vectors, an
invalid tangent projection, or a normal behind the geometric/view hemisphere
fall back to the original shading normal. Alpha is ignored by this opaque-only
consumer. Glass, scalar opacity, roughness, metalness, displacement, height and
alpha maps are rejected or unsupported; they are not silently interpreted.
consumer. Linear roughness and metallic maps replace those scalar parameters.
An explicit scalar face appearance suppresses newly imported body maps on that face.
Existing GPU built-in and temporary map roles retain their previous precedence,
including when a request mixes legacy and imported roles.
Displacement, height and alpha maps are unsupported.
Sampling uses bilinear level-zero periodic filtering at texel centers, including
negative UV repeats. There is no mipmapping, anisotropic filter or UV mesh import
in this increment, so fine distant patterns may alias. PNG/JPEG input is 8-bit,
maximum 1024×1024 per map. Embedded ICC profiles and nonidentity orientation must
be normalized beforehand; no implicit color-management guess is made. The sRGB
Newly imported GPU maps and native CPU maps prepare complete floor-halved, linear area-filtered mip chains through
1×1. It interpolates bilinearly within each level and linearly between levels.
LOD uses the largest singular value of the unwrapped UV-to-texel Jacobian;
negative repeats and repeat seams do not create false derivatives. Magnification
retains level zero. GPU primary footprints analytically differentiate the camera ray and
its intersection with the hit tangent plane, holding the lens sample fixed and
using one output-pixel spacing. Secondary GPU footprints use a conservative camera ray cone scaled by
path length and grazing angle. That approximation can blur stretched footprints;
it does not implement anisotropic filtering or specular ray differentials. Legacy GPU
maps retain only their exact decoded level-zero pixels and bypass LOD selection.
Content/role sharing also includes this policy, so mixed requests cannot silently
replace legacy sampling with the imported-map policy or conversely.
PNG/JPEG input is 8-bit, maximum 1024×1024 per map. Embedded ICC profiles and nonidentity orientation must
be normalized beforehand. Temporary GPU maps retain their historical decoder
admission and explicit-role interpretation: ancillary PNG color declarations do
not change their encoded samples or introduce a new refusal. Portable design-owned
imports require normalized sRGB declarations for base color and validate static
metadata before publication. The native CPU metadata worker also rejects conflicting
base-color declarations. Normal and scalar roles retain their raw numerical channels.
No implicit color-profile conversion is performed. The sRGB
base/data normal distinction follows the public
[Khronos glTF material semantics](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#materials),
without adopting its document format or copying implementation code.
At most 16 exact name-and-index body bindings retain 16 MiB encoded capacity and
32 MiB linear pixel data collectively. Admission counts captured bytes, codec
scratch, normalized pixels, staging and device storage against the existing job
At most 128 exact name-and-index body bindings retain 64 MiB encoded capacity and
96 MiB level-zero linear pixel data collectively. Admission counts captured bytes, codec
scratch, normalized pixels, any prepared mip chains, staging and device storage against the existing job
budget. Codecs execute on the worker with cancellation checks before/after each
bounded decode and during conversion/upload preparation. Public status contains
metadata only; completion or cancellation releases captured source bytes even
when callers retain job/status/frame handles. GPU preparation also releases
source bytes after preparing the pixel buffer.
The GPU executor selects a bounded opaque pipeline when the captured scene has
no physical transmission or active volume. Glass and active volume rendering
retain the general pipeline. Both honor each map's captured filtering and face-precedence policy.
Disjoint media use one private stack entry; certified nested media retain their
sixteen-entry capacity. Captured scene options select at most six cached programs.
The independent progressive device requests six storage buffers per shader
stage. An adapter limited to fewer cannot install this executor; raster and
tessellation device requirements remain unchanged.
+6
View File
@@ -151,6 +151,12 @@ completed drawings publish atomically. The browser still exports synchronously.
## Render foundation
- Wood surface images (#1345): native CPU and GPU opaque rendering share physical
repeat frames and filtered mip chains. Imported maps retain exact bytes and
declared provenance in the design, reopen offline, and expose grain-angle
controls. Scalar face appearances suppress body maps. Planar projection and
CPU encoding/optical limits remain explicit; see [portable surfaces](render-portable-surfaces-and-stages.md).
- Original starter appearances (#1722): 34 opaque recipes through existing commands, with six explicitly unavailable glass recipes and preserved legacy looks; see [the contract](render-starter-appearances.md).
- Bounded linear film accumulation (#1696) supplies caller-admitted mean/variance storage and complete-pass views; actual progressive consumers remain separate. See [the film contract](render-film.md).