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:
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user