solvecraft/docs/render-cpu-output.md

CPU output presentation and native masters

CPU ray tracing can apply the same presentation operators as GPU path tracing to its captured transport result. Presentation is independent of the optional CPU physical lens, guided noise reduction and opaque path lighting; those options keep their own admission and compatibility checks. CPU adaptive sampling and conditional Path Glass/subsurface transport also use this output pipeline. Their compatibility limits remain independent; see renderer parity. Raw EXR is unfiltered film data, including when the displayed PNG is denoised.

A portable CPU job may include:

{
  "width": 512, "height": 512, "exposure_ev": 1,
  "job": { "method": "cpu_raytrace", "options": {
    "progressive": { "samples_per_pixel": 16, "seed": 81 },
    "output": {
      "tone_map": "aces_fitted",
      "finishing": { "rgb_gain": [1.2, 0.9, 1],
        "bloom": { "strength": 0.2, "threshold": 1.5, "radius": 8 },
        "photographic": { "grain": 0.02, "seed": 42 }
      },
      "linear_exr": true
    }
  }}
}

The runtime equivalent is raytrace.output. Output never owns another exposure, background or transparency value. Setup exposure still lowers once into CPU raytrace exposure; the captured image request owns the display background and transparent-background flag. Opaque remains the default; explicit true exports straight-alpha geometric coverage. Unknown or GPU transport fields inside output are refused.

Missing/null output and identity presentation keep the original f64 PNG exactly. EXR-only retention also preserves that display path. Nonidentity presentation converts one complete pass to FLOAT32, premultiplied by primary coverage, before shared Display/Bloom/Photographic stages. Fixed CPU captures raw radiance before its existing per-pixel display write; progressive CPU converts the complete f64 film mean. Every provisional pass has the same effects and deterministic seeds as a standalone final target at that pass count.

A raw master is created only for final completion, before exposure, tone mapping, finishing, bloom, photographic effects and the display backdrop. RGB is relative scene-linear sRGB/D65 and coverage-premultiplied; A is primary coverage. The CPU producer has its own exact native software metadata profile. Regrading accepts only the exact retained native CPU/GPU profiles; it does not import arbitrary EXR.

The shared output envelope remains 8192 pixels per side and 16,777,216 pixels in total. A larger CPU profile does not raise that separate envelope. Active output is validated before HDR IO or scene capture, and offline saved setups validate it as well. Original CPU images without these output stages retain their existing profile bounds.

Admission adds one 16-byte-per-pixel conversion, bounded bloom scratch (24 bytes per pixel), optional photographic scratch (8 bytes per pixel plus 16 KiB), final EXR capacity and fixed stage/options metadata. The existing RGBA/PNG reservation is moved into the output stage, not duplicated. Conversion, each bounded output operation and final digest scans debit the same cumulative CPU work budget. Cancellation cannot install a late PNG or raw master.

Raw masters, final PNGs and at most two provisional PNG slots use the existing host pool. A final has its own lease and cannot borrow a pinned preview slot. Externally retained final/preview Arcs remain charged until their last owner is dropped. A cancelled job leaves the previous completed image intact.

The Render workspace saves and reloads CPU presentation through the shared Effects, Environment and Output editors. EXR export is enabled only by an actual selected completed image with a retained master. Enabling retention for a future job or showing a provisional PNG cannot manufacture an exportable EXR.

Focused validation

Executed renderer regressions cover the original f64 PNG identity, analytic raw radiance and coverage, every complete progressive prefix, worker quantum independence, each output stage's cancellation and cumulative work ceiling, and retained preview/final leases. Earlier saved-document and engine runs exercised strict round trips, cold output refusal before HDR IO, actual CPU rendering, raw-master export and regrading; they do not qualify later combined additions.

An earlier-snapshot Render workspace suite passed with the CPU feature enabled and a real GPU required. It included the real Render button's saved CPU effects and exported EXR, presentation Undo/reload, camera preservation, progressive controls, live selection overlays, cancellation and clean cold-entry shot switching. That earlier result does not qualify the later combined alpha, denoising, GI or saved-optics additions, whose document/engine/UI/native workflow gates remain pending. Executed combined renderer checks do not replace repository-wide or platform CI.

Transparent PNG coverage

CPU runtime requests accept the existing top-level transparent_background flag. Saved CPU jobs keep it beside options, with false as the default, like the other image methods. Omission and false retain the original opaque f64 PNG and work route. The Output checkbox and Environment Clear action use this same flag; there is no second alpha setting inside options or output.

True exports straight RGB and 8-bit alpha from primary geometric coverage for fixed 1/4/16 AA and progressive camera sampling. The scene radiance is divided by coverage before exposure/tone/colour adjustments, never multiplied by alpha in the PNG. Alpha is rounded geometric coverage; fully clear pixels have canonical zero RGB. Background colour is not composited into a transparent PNG. Body and face opacity must remain 100%: this is background removal/edge coverage, not partial material opacity or a general transmissive-glass matte. A primary glass hit retains its existing geometry footprint.

The shared colour presentation is available with alpha. Active camera backdrops, bloom and photographic operators still require opaque output and refuse without removing authored values. Raw EXR always retains the same premultiplied linear radiance and coverage, byte for byte, independent of PNG background choice. No additional image plane, ray, reservation envelope or work limit is introduced. Only the completed final PNG is exportable; previews remain nonexportable and cancellation retains the existing publication barrier. Export writes the exact retained straight-alpha PNG bytes.

For explicit CPU independent-pilot allocation, raw linear means and coverage use each pixel's production sample count. Completed-pass presentation borrows the film's exact count plane for integer PNG alpha rounding; it does not copy a new image-sized count plane or write pilot radiance to the final raw EXR. Captured sampling metadata remains in the existing job report rather than a second, conflicting linear-master schema. This outside integration requires compilation and numerical/export qualification before advertising the CPU adaptive route.