solvecraft/docs/render-runtime-textures.md

Runtime planar opaque maps

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 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.

{"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}]}}

Each u and v world-space vector spans one complete repeat, in millimetres. The vectors must be nonzero, orthogonal, and 0.001–1,000,000 mm long. The origin is UV zero. Image V increases downwards; normal red and green point along the positive projected U and V directions, with handedness preserved. Projection is planar, not triplanar: surfaces parallel to the projection axes may stretch. Each body's 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 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.

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 base/data normal distinction follows the public Khronos glTF material semantics, 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 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 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.

Independent f64 tests cover explicit sRGB decoding, linear normal channels, repeat filtering, handedness, degenerate fallback, admission and lifecycle. GPU reference tests compare the actual packed storage and WGSL sampler/normal frame against those CPU utilities. GPU execution and final visual evidence must be reported separately; source/shader validation alone is not rendering proof.