solvecraft/docs/render-backends.md

# Render backend capabilities (R1)

Native progressive opaque PNG rendering is described in [Progressive product images](render-path.md). It registers alongside the CPU executor.

This page describes the R1 metadata contract. The installed GPU viewport and CPU
product-job hosts extend it through complete profiles; HDR input preparation adds
no lighting capability. See [the integrated phase boundaries](render-integration.md).

`render.backends` discovers render metadata without opening a window, probing a GPU,
evaluating the model or changing the document, camera, dirty state or undo/redo history.
It also leaves a model made stale by a live sketch gesture stale.

```sh
solidcraft-cli exec render.backends '{}'
```

The control channel and MCP `execute` use the same engine command. Parameters must be
an empty object; a null parameter value is normalized to `{}` by the engine. Other
parameters fail with a normal command error.

## Discovery schema

The command returns this JSON object (schema version 1):

```json
{
  "schema_version": 1,
  "default_backend": "builtin",
  "backends": [{
    "id": "builtin",
    "label": "Integrated",
    "availability": {"status": "available"},
    "executors": [{
      "id": "cpu-raster",
      "availability": {"status": "available"},
      "profiles": [{
        "mode": "preview",
        "operation": "image",
        "formats": ["png"],
        "features": []
      }],
      "limits": {
        "max_dimension": 4096,
        "max_pixels": 4194304,
        "max_scratch_bytes": 268435456
      },
      "scratch": {
        "sample_scale": 2,
        "sample_bytes_per_pixel": 8,
        "output_bytes_per_pixel": 8,
        "encoding_bytes_per_pixel": 8
      }
    }]
  }]
}
```

An unavailable backend or executor instead has
`"availability": {"status": "unavailable", "reason": "..."}`. These are runtime
descriptors, not design-file settings. Executor IDs are scoped to their backend.
Backend/executor IDs are 1–64 ASCII bytes: a lowercase letter followed by lowercase
letters, digits, `.`, `_` or `-`. Both construction and deserialization validate IDs.

Without runtime hosts the integrated backend describes the existing CPU raster snapshot
path. Its `preview`/`image` profile exports PNG; it does not claim HDRI, PBR,
refraction, progressive rendering or a final-quality integrator. The existing GPU
viewport registers separately when the UI installs its actual device/pipelines.
The installed GPU product viewport and CPU product-image host support the subsequent
[opaque PBR consumer](render-opaque-pbr.md); this does not alter the static raster
descriptor or enable HDRI/refraction/final rendering. CPU and GPU are execution paths, not separate
user-selectable engine families.

## Installed image methods

An installed CPU host advertises `cpu-product` first. A real native CPU worker with
`raytrace-cpu` compiled in also advertises `cpu-raytrace`; cooperative hosts and builds
without that feature do not. A stopped native host retains an unavailable descriptor.
The second method supports PNG with PBR, HDRI and explicit CPU optical contracts.
Without Path, dielectrics remain certified sheets or strict axis-aligned boxes.
Explicit [CPU Path](render-cpu-path.md) adds indirect lighting and its certified
general-Glass domain. [Progressive sampling](render-cpu-progressive.md) publishes
complete provisional passes; compatible output options retain a final raw EXR.
The profile's Preview mode is metadata, not a claim of final image quality.
Geometry, material combinations and resource admission still validate each request.
See [the detailed parity matrix](render-parity.md); a generic Refraction feature
flag never proves that every boundary or combination is supported.
The `cpu-raytrace` ID is reserved for this native method, including while it is absent;
applications cannot register another image or viewport host under that name.

Discovery preserves the default raster path. Image jobs choose CPU raytracing explicitly
with `integrator: "raytrace"`; GPU path jobs use `progressive: true` and require a separate
installed executor with that capability. CPU sampling instead uses the nested
`raytrace.progressive` option; it does not repurpose that top-level GPU selector
or advertise a new arbitrary progressive executor. Discovering either method never creates a
worker/device, starts a render, modifies a document or reserves image memory.

## Pure request resolution

`solidcraft_render::resolve_request` accepts a descriptor slice and a `RenderRequest`.
It validates and resolves metadata only: it does not allocate an image, start a job,
reroute `snapshot` or call a renderer. A request can be deserialized from:

```json
{
  "backend": "builtin",
  "mode": "preview",
  "operation": "image",
  "width": 640,
  "height": 480,
  "format": "png",
  "features": [],
  "policy": "strict"
}
```

`backend` defaults to `builtin` when absent/null. `features` defaults to `[]`, and
`policy` defaults to `strict`. Mode, operation and positive integer dimensions are
required. An image requires a supported format; a viewport requires absent/null
`format`. Unknown fields, enum values, invalid IDs and incorrectly typed values fail
deserialization. Dimensions are checked by the resolver. No floating-point request
fields are introduced.

Modes are `quick`, `preview`, `final`; operations are `viewport`, `image`; formats
are `png`, `exr`. Required features can be `hdri`, `pbr`, `refraction`, `progressive`.
These names define requests, not promises of support. Each executor lists complete
mode/operation profiles with their formats and features. Capabilities are never
combined across executors to create an unsupported profile.

Resolution rejects duplicate backend IDs, executor IDs within a backend and duplicate
mode/operation profiles. Registry sizes are bounded to 32 backends, 16 executors per
backend and 16 profiles per executor; a request allows at most 32 feature entries.
Available executors are considered in lexicographic ID order, and the first executor
that satisfies the entire request is selected. Registry order does not convey priority.
Returned profile formats/features are sorted, so their declaration order does not
change the resolved result. If every candidate fails, the first matching executor's
error is returned; unsupported profile is reported when none has that combination.

The resolved value contains `backend`, `executor`, `profile`, `width`, `height`,
`format`, `estimated_scratch_bytes` and `warnings`. Under strict policy warnings are
empty and no requested setting is downgraded. Errors are typed `ResolveError` values:
invalid IDs/request/registry, duplicate IDs, unknown/unavailable backend, no available
executor, unsupported profile/format/feature, invalid dimensions, exceeded limits or
size overflow. There is no fallback policy or public job API in R1.

## Resource admission policy

The new resolver's default limits are conservative policy values, not measured adapter
capacity: 1–4096 pixels per dimension, at most 4,194,304 output pixels and a 256 MiB
estimated pixel-buffer budget. Each executor supplies configurable `RenderLimits` and
a `ScratchLayout`. Checked arithmetic covers dimensions, supersampling, buffer products,
sums and the target's addressable allocation size, including wasm32.

For the existing CPU raster path the estimate is 48 bytes per output pixel: four
supersamples at 8 bytes each (RGBA8 plus f32 depth), an 8-byte output canvas, and an
8-byte allowance for an RGBA copy and encoded output. At 640 × 480 this is 14,745,600
bytes; at 2048 × 2048 it is 201,326,592 bytes. A 4096 × 4096 request exceeds the pixel
limit despite each dimension being permitted.

This is an admission estimate, not a total process-memory bound. It excludes scene,
texture, projected-geometry, acceleration-structure and codec-internal allocations.
Future execution hosts must enforce their own complete allocation/cancellation policy.
The legacy rasterizer, CLI snapshots and GPU viewport keep their existing behaviour
and limits; none is routed through this resolver in R1.

The follow-on Render workspace, persistent setups, job hosts and optional engines are
tracked in [#620](https://github.com/bherbruck/solidcraft/issues/620). The implemented
foundation is scoped by [#642](https://github.com/bherbruck/solidcraft/issues/642).