solvecraft/docs/render-cpu-progressive.md

CPU progressive camera sampling

The limits below describe the compatibility Compact profile. Explicit Studio and Workstation envelopes are documented in CPU resource profiles; their implementation batch still requires consolidated validation.

CPU progressive rendering repeatedly traces fresh camera samples into a bounded linear-light film. Checkpoints are complete image passes, at 1, 2, 4, 8, 16 and 32 samples per pixel when below the requested final sample count. The exact requested count produces the final PNG, including non-powers of two such as 3 or 5. A one-sample job has no provisional checkpoint.

This mode uses the native cpu-raytrace executor and its existing direct-light and selected-reflection transport. It does not add diffuse global illumination, caustics, adaptive convergence, a denoiser, or general glass path tracing.

Request and saved intent

The CPU option is nested inside raytrace. The top-level progressive: true request continues to select the registered GPU path executor.

{
  "integrator": "raytrace",
  "settings": { "width": 512, "height": 512 },
  "raytrace": {
    "progressive": { "samples_per_pixel": 32, "seed": 81 },
    "primary_samples": 1,
    "exposure_ev": 0,
    "shadows": true
  }
}

Both render.preflight and render.start use this request. Missing or null raytrace.progressive preserves the existing fixed 1/4/16 spatial AA route. An explicit empty progressive object defaults to 16 samples and seed 0. The seed is an unsigned 32-bit integer. Unknown fields are rejected.

The corresponding portable setup is:

{
  "name": "CPU film",
  "set": {
    "width": 512,
    "height": 512,
    "exposure_ev": 1,
    "job": {
      "method": "cpu_raytrace",
      "options": {
        "progressive": { "samples_per_pixel": 32, "seed": 81 },
        "primary_samples": 1
      }
    }
  }
}

This is a render.settings.set request. Exposure is stored once in the setup; normalization transfers it into the CPU request. Film storage, checkpoint PNGs, job identities, cancellation state and host reservations are never serialized into the design. Saving validates pixel and camera-sample bounds even when no render host is installed.

Supported combinations and limits

Control	Initial CPU progressive contract
Dimensions	Each side 1..4096; at most 1,048,576 pixels
Samples per pixel	1..64
Total camera samples	At most 16,777,216 (width × height × samples_per_pixel)
Fixed spatial AA	primary_samples must be 1
Selected mirror / isotropic rough reflection	Existing bounded depth; reflections.samples must be 1 when bodies are selected
Directional / point / spot sources	Existing CPU light contracts and limits
Constant / captured HDR environment	Existing CPU contracts; HDR plus rough reflections still requires certified fully metallic selected bodies and effective faces
Surface emission / isotropic surface effects	Existing CPU appearance contracts; emission is visible radiance
Area / LED sources	Explicitly rejected in this initial progressive mode
Dielectric / anisotropic face overrides	Explicitly rejected in this initial progressive mode
Output	Opaque PNG with the existing display background

An incompatible request fails; it does not remove settings or switch methods. The fixed CPU route retains its existing area, dielectric and anisotropy support. At 1024 × 1024 the camera-sample cap allows at most 16 samples per pixel; at 512 × 512 it allows 64. Requests are also subject to the existing geometry, 384 MiB CPU job and 512 MiB shared host-pool admission limits. Traversal, shading, film updates, resolve, PNG encoding and hashing share one cumulative 1,000,000,000-unit work ceiling. The count is not reset at a pass boundary. The camera-sample limit is a cold upper bound, not a promise that every scene will finish below the cumulative runtime work ceiling.

Sampling, linear film and display

Camera jitter is a deterministic counter sequence keyed by the u32 seed, pixel index and absolute sample ordinal. Reflection and HDR-direct variates use separate domains of the same counter. Target sample count, worker quantum and checkpoint cadence are not keys. Consequently, for an unchanged captured request and scene, a checkpoint at N samples has exactly the same sample prefix and PNG bytes as a job whose final target is N.

Each pixel stores three f64 sums and a primary coverage count. Only complete, uniform passes can be resolved. Camera misses add zero scene radiance and zero coverage. The resolve computes the mean scene radiance, applies exposure and the existing tone curve once to covered radiance, composites the display-linear backplate by coverage, and encodes sRGB once. The background is not illuminated or exposed. Averaging already tone-mapped sample pixels is not equivalent and is not used.

film::primary::PrimaryFilm is a compact camera-specific accumulator alongside the existing statistical FilmAccumulator. It has incremental initialization and requires the exact next scanline pixel and absolute ordinal on every update. The existing general FilmAccumulator/borrowed FilmPngTask APIs are retained; the owned image job uses the shared PngEncoding pipeline without a self-referential borrowed task or a second independent pool.

Preview publication and final export

JobStatus.preview, when present, contains:

PreviewInfo {
    frame_sequence: u32,
    samples_per_pixel: u32,
    frame: FrameInfo
}

JobHandle::preview() returns an Arc<RenderPreview> whose png() is the immutable encoded snapshot. The first checkpoint has sequence 1. The job's JobId { session, serial, generation } and captured scene_generation remain unchanged across every pass. frame_sequence is a separate monotonic counter. Clients cache previews by (JobId, frame_sequence) and may retain an older snapshot without mutating it.

The preview slot is separate from JobStatus.frame/JobHandle::frame(). A preview cannot be exported through render.export, cannot become the session's last completed image, and does not release the running task or film. The final PNG is published only after its digest is complete; it clears the preview slot and is the only new exportable result. render.export writes those exact PNG bytes and does not render or re-encode them.

Cancellation clears the preview slot immediately. Failure and completion also clear it. Publication checks the cancellation token while holding the same record lock used for cancellation, including after the final digest chunk. The worker cannot publish a late checkpoint into a cancelled or replaced job. An externally retained preview remains an immutable snapshot of its original job, but cannot replace a previous successfully completed final frame.

Allocation and retained snapshots

Admission reserves the working film, existing RGBA/encoder/final-PNG capacity, and the maximum encoded capacity plus metadata for every possible nonfinal checkpoint. This conservative upper bound covers a consumer retaining all checkpoints at once. Actual film and PNG capacities are checked against their admitted capacities after fallible allocation.

A completed checkpoint moves its PNG allocation into the preview object. Reservation::split transfers that allocation's share of the running lease without increasing or decreasing the pool total. Replacing or clearing the host preview drops only the host's Arc; any external Arc keeps its memory billed. At final completion the task releases its working buffers before the remaining lease shrinks to the final PNG. Dropping each last external snapshot releases only that snapshot's reservation. There is no full-film clone per checkpoint.

Regression coverage

The source includes regressions for deterministic prefixes and worker quanta, fresh primary rays, non-power-of-two targets, actual HDR/rough-reflection PNGs, linear averaging before tone mapping, coverage and unexposed backgrounds, bounded/cancelled film mutations, and the single cumulative work budget.

Host tests manually advance the worker to the digest/publication boundary. They hold multiple preview Arcs through replacement, cancellation and completion, check allocation identity and exact pool release, and reject an invalid checkpoint sequence. Document tests cover offline limits and saved round trips. Engine tests cover Check/Start equality, cold rejection before HDR capture, session ownership, exact final export, and retention of the previous completed image after a progressive job is cancelled. Execution evidence belongs to the integrated CI receipts; this source handoff does not claim those gates passed.