Understand viewport transport and performance

The Construct viewport renders on a worker thread with its own GPU context, then hands each finished frame to the editor window. The hand-off is called the transport. The editor picks the transport automatically per platform. There is nothing to configure.

Which transport your platform uses

Zero-copy means the worker renders straight into a GPU texture that the editor window samples directly. The frame never crosses the CPU, so the hand-off costs close to nothing per frame. On Windows 11 this is the default and needs no setup.

Readback means the finished frame is copied from the GPU to memory once, then drawn into the window. This is the portable path, and it is also the automatic fallback everywhere: if zero-copy is unavailable — a second GPU, a driver that refuses the shared texture — the viewport falls back to readback and keeps working. Nothing goes black and nothing needs restarting.

The application log always states which transport runs. Search the log for lines starting with transport: — you will find either transport: ZERO-COPY leg ACTIVE or a line naming the readback leg and the reason.

Responsiveness and scene size

Editor responsiveness does not scale with the size of the scene. One edit costs one bounded unit of work: the editor re-evaluates only the values that depend on what you changed, and it renders one frame for it. A change to one parameter in a scene of a thousand instances costs the same as the same change in a scene of ten.

Earlier releases did not behave this way. Every single-parameter change re-evaluated every expression in the document, so a model got slower to edit as it grew. If you were told that "it gets sluggish on big scenes" is expected, that advice is out of date. A scene that is slow to edit today is a problem to report, with the log and the FPS counter readings below.

Two things still grow with the scene, and both are render costs rather than edit costs: the first frame after a structural change (adding or removing items rebuilds the GPU scene once), and the raymarch itself at high resolution.

Large tet volumes

A tet volume's cost grows with its number of tetrahedra, and the bake resolution decides that number. Each doubling of the cell count makes about eight times as many tetrahedra. The "Auto" resolution, 256 cells across the largest extent, gives about 22 million tetrahedra on a model of a sphere and a box joined together.

What happens after a tet bake:

1. The bake runs as a job. The editor stays usable.
2. The finished volume goes to the scene without a read of its file.
3. The outline of the volume (its boundary) is computed in the background. The volume shows when that is done. At the "Auto" resolution this can take half a minute.

Until step 3 is done, the volume does not show, but the camera, the gizmos and every other item respond. A deleted volume leaves the view at once. Opening a scene that holds a tet volume reads the volume's file in the background in the same way.

If a volume is larger than you need, bake it again at a lower resolution in the bake dialog. Half the cells gives an eighth of the tetrahedra.

Solve sizes

A solve of a tet volume (Tet ▸ Solve…) has three unknowns for each node. Its time and memory grow with the unknowns, and the solver decides how fast.

Auto picks Direct up to 15 000 unknowns and Iterative above. The Solve dialog shows the unknowns and the memory of each choice before you solve.

Measured on a 64-thread Linux workstation with 125 GiB, on a sphere and a box joined together, in steel:

The times include the assembly and the stress. Other work on the machine gave a load average of 4 to 13 while they ran. A quadratic volume (Tet ▸ Quadratic elements) has about six and a half times the unknowns of the same linear one, and each unknown costs about twice the memory. It is more accurate in bending.

The solve runs on one thread. A solve that needs more memory than any machine of the pool has is refused before it starts, with the reason.

Field values, probes and labels at scale

The value under the pointer, the probes and the labels of a solved volume read the field through a locator of its tetrahedra. The locator builds once for each volume, on a background thread. The first hover after a solve says "Locating…" until it is ready.

These figures are from a release build on a 64-thread Linux workstation with an RTX 5070, at a load average of 16 to 64 from other work. The volume is a ball of 989 808 tetrahedra and 176 093 nodes:

The probe table computes 256 rows at a time, only for the rows that show, so a table of one million probes scrolls without a wait for the rest. A CSV of that size writes in the background, with a progress row, on every core.

The labels lay out 1 000 anchors in 0.6 ms and paint the 64 boxes that show and the 1 000 marks in 1.8 ms, into a 2560 × 1440 view. Past 64 boxes, an anchor draws its mark only.

A kernel over one million elements takes 6 ms on eight threads for the von Mises stress and 44 ms for the principal stresses. The range of a field, its peaks and its extremes take 30 ms or less each.

Every presenter of a volume adds about 1 % to a frame of the handwheel scene. With no other item in the view, the same presenters add about a third to a frame of 1.8 ms.

While a deformation animates, the SDF items keep the image of their last ray march, and each tick of the animation copies it in under the moving volume. On the handwheel scene with a volume of one million tetrahedra, a tick takes 0.48 ms of GPU time at 1280 × 720 and 1.4 ms at 2560 × 1440, about as much as a frame where nothing moves. A frame that moves the camera marches again: 71 ms and 264 ms. The animation stops while its window is in the background.

Developers measure these figures with construct-bench field-sample, hover-deformed, labels, field-kernels, field-stream, threshold-rebuild, cut-caps and presenter-frame-cost (with --animate for an animation). Each verb prints its counts with its times.

Path-traced rendering and the GPU

The path tracer of the viewport, a render job and the window all share one GPU. The GPU runs its work in the order it gets it, with no priority, so a long piece of tracer work makes the next frame of the window wait. One pacer per process stands in front of the GPU and decides how long each piece of background work can be and when it can start. Each host asks the pacer before it submits its work, and reports what the work cost after it: the GPU time where the device measures it, and the wall time otherwise.

The pacer sorts work into three classes:

"While you work" means up to 500 ms after the last mouse, key, wheel, touch or tablet event in the application.

The GPU share

GPU share for background rendering, in the This machine category of the settings page (Ctrl+,), is the duty cap: the share of each second that progressive and batch work together can keep the GPU busy. The default is 0.8, and the range is 0.1 to 1.0. At 0.8 the background work gets at most 800 ms of GPU time in any one second, and the window and the desktop compositor always have the other 200 ms. When the next slice would pass the cap, the host waits until enough of the older slices leave the one-second window.

Background GPU slice (ms), in the same category, is the longest slice of progressive work while you work: 8 ms by default, from 1 ms to 50 ms. A shorter slice makes input smoother, because no frame of the window waits long behind a slice. It also makes refinement a little slower, because each slice has a fixed cost.

Both settings take effect at once and are stored on this machine only, because the right values depend on the GPU and its driver. Two viewports that path trace ask the same pacer, so they share the cap rather than double it.

In the viewport, the tracer runs its slices for at most 20 ms of each viewport tick, and ends the tick early when a sample is complete, so that the sample can show. A still view shows a new image every 100 ms in the first second, then less often, up to every 2 s. When the view is done, the tracer issues no GPU work at all.

The pixel size

Viewport pixel size, in the Path tracing category, is the size of one traced pixel on the screen: 1×, 2×, 4×, 8× or Automatic, the default. Automatic follows the pixel ratio of the display, rounded down to 1, 2, 4 or 8, so a display at a ratio of 2 traces one pixel for each block of 2 × 2 screen pixels. Each step from 1× to 2× to 4× traces a quarter of the pixels of the step before, and so costs about a quarter of the time per sample.

While the view moves, a frame starts at eight times the pixel size, and its long side never gets shorter than 128 pixels. The frame time is 1/60 s. A frame that costs more than 1.4 times the frame time doubles the divider, and the divider never gets finer while the view moves. One frame time after the last change, the view traces at the pixel size again. While the view moves decides what shows when even the coarsest frame costs more than twice the frame time: Automatic shows the Environment-lit PBR engine then, Material shading always shows it while the view moves, and Coarse trace never does.

See Troubleshoot rendering problems for the steps to take when the viewport stutters.

Reading the FPS counter

The viewport's FPS counter shows two rates: the render rate (frames that carried new pixels) and the delivered rate. The interface reference explains what each number counts and why they can differ.

Numbers for a bug report

If you report a performance problem, attach the application log — the transport: line and the FPS counter readings carry most of what a developer needs. If the viewport stops following a drag, start the application with --tick-trace and reproduce it: the flag writes a timeline of render ticks that shows whether a frame was never requested, never served, or served late. See Collect useful logs.

Developers can additionally run the frame bench, which records per-frame timings into a SQLite database (construct-bench frames --frames <n> --db <path>). The bench is a developer tool; its documentation lives with the internal test harness docs, not here.

Numbers for a slow path-traced render

If a path-traced export is slow, or path tracing in the viewport makes the window lag, run the bench that measures it and attach its output to the report, with the application log. construct-bench is built with the other tools. After kiln build it is debug/construct-bench/construct-bench in the build folder. Each bench prints its numbers to the terminal, one line per measurement.

Run the benches on your own scene where they take one, and attach every line that they print:

construct-bench pathtrace-export --scene my-scene.construct --size 1920x1080 --frames 3
construct-bench pathtrace-viewport --scene my-scene.construct --size 1280x720 --seconds 10 --script orbit
construct-bench pathtrace-stages --scene my-scene.construct --size 1280x720 --samples 8
construct-bench material-cost
construct-bench denoise-cost --size 1920x1080 --tile-side 1024 --runs 5

Without --scene, the path-tracing benches render builtin:sphere-lattice, a lattice of 75 spheres, and material-cost renders builtin:materials-113, 113 spheres with a material each. builtin:sky, a ground plane and three spheres under the physical sky, is the third scene of the bench set. A report with the numbers of your scene and of builtin:sphere-lattice on the same machine shows whether the scene or the machine is slow.

The options that change what the benches measure:

A bench exits with code 0 when it measured, 1 when the scene or the render failed, and 2 when an option is wrong. To compare a frame of your scene with and without adaptive sampling, run pathtrace-export twice, once with --noise-threshold 0.01.

Compare a change before and after

construct-bench wgp runs the frame bench on a set of scenes and compares two runs. It has five verbs:

On another platform, startup, pacing and idle exit with code 2 and do nothing.

Measure, make the change, build, and measure again:

construct-bench wgp run --label before --build-dir <build> --qt-bin <Qt bin folder>
construct-bench wgp run --label after --build-dir <build> --qt-bin <Qt bin folder>
construct-bench wgp compare --before before --after after --build-dir <build>

--build-dir is the build folder that holds the programs. Without it, the verbs use the programs in the same folder as construct-bench. --qt-bin puts the Qt folder first on the search path of each program that the verb starts. Windows needs it to find the Qt libraries. construct-bench wgp <verb> --help lists all options of a verb.

run stops with exit code 1 if one bench run fails. A bench run that does not stop in --timeout seconds (900 by default) counts as a failure.

On Windows, Profile Construct on Windows shows how to name the GPU passes for PIX, read the start-up timing lines, and record frame pacing with PresentMon.