solidcraft-upstream/docs/render-settings.md

Persistent render settings (R2)

Named setups save common render intent in the document. They do not start a render, apply the navigation camera or make a currently unavailable backend available. The Render workspace, scene extraction, assets, PBR materials and jobs are later slices of #620.

Commands

{"command":"render.settings.set","params":{"name":"Studio","set":{"width":1600,"height":900,"exposure_ev":1.5}}}
{"command":"render.settings.get","params":{"name":"Studio"}}
{"command":"render.settings.get","params":{}}

set creates a named setup from defaults or replaces supplied top-level fields in an existing setup. A supplied camera replaces the whole camera; it is not a recursive patch. Omitted fields retain their values. Unknown fields (including camera fields), invalid types and invalid values fail before document mutation. A new empty set saves the defaults; setting an existing setup to identical values is a no-op, preserving redo history and revision. Each effective edit is one undo step and marks the document dirty. There is no delete or rename command in this slice.

Named get returns {name, setup} or an error for a missing name. Without a name, it returns {setups, defaults}. Reads do not evaluate the model or change history.

Field	Default	Saved contract
backend	builtin	Valid R1 backend ID, at most 64 ASCII bytes; unavailable IDs survive reopen
mode	preview	R1 preview / final mode; availability checked by a future render request
camera	Existing Camera::default()	Snapshot of target, yaw, pitch, roll, distance, fov and up; mm/radians, existing Z-up default
width, height	1024, 768	Positive, each at most 4096; product at most 4,194,304 pixels
format	png	R1 output format (png / exr); saving EXR does not add an encoder
exposure_ev	0	Finite, -32 through 32
environment_rotation	0	Finite radians, magnitude at most 1,000,000
environment_intensity	1	Finite, 0 through 100
background	[236, 240, 245]	Three sRGB byte values, independent of future illumination

Camera target coordinates and positive distance are bounded to magnitude 1e9 mm; angles to 1e6 radians. FOV is finite, 0 <= fov < pi; zero means orthographic in the existing camera model. Both existing camera up axes are retained. Setup names are trimmed, nonempty, at most 128 UTF-8 bytes, without control characters. A document has at most 32 setups. Validation also runs during document deserialization.

Persistence and evaluation

Document format 21 adds render: {setups: {name: setup}}. Format-20 and older designs migrate with an empty map; empty render state is omitted when saved. Existing geometry, appearances, opacity and physical materials are untouched. Plain JSON, design containers and crash journal replay use the same document/command representation. Older builds (0.11.0 reads up to 20) reject format 21 instead of silently losing setups. This slice adds only render intent. No runtime capability, job, texture or device is saved.

The engine avoids geometry evaluation only after proving that the document differs solely in validated render settings, with unchanged active sketch and pending moves. The proof compares the complete document after normalizing the render field, so mixed geometry/appearance/placement edits take the usual conservative refresh path. It uses a document clone/comparison, not a constant-time or whole-application speedup claim. Unchanged render pointers short-circuit the check for normal modelling commands.

Render-only edits, undo/redo and checkpoint restore preserve model state, its stale marker, cached tessellation and the prepared world state. A stale live-drag result never becomes authoritative through a settings edit; the next model-reading command still settles it normally. Revision advances to let future consumers invalidate shading work. Actual render accumulation and resource invalidation are not implemented in R2.

No new third-party dependency or asset is introduced. doc depends on the existing pure render crate for its shared camera and R1 identifiers, within the L2 → L1 rule.