Ray-marching quality
What Auto does, when to override it, and how to diagnose a shape that will not appear
The viewport draws your model by ray marching: for every pixel it steps along a ray, asking the shape "how far away is your surface from here?" and jumping that far. Repeat until the answer is near zero ā that pixel hit the surface.
The whole method rests on one promise: the shape never reports more distance than there really is. A shape that overstates makes the renderer jump too far, straight through the surface, and the pixel comes back empty. That is why geometry sometimes seems to vanish at one camera angle and reappear at another.
What Auto does
Auto (recommended), in the Tracer row of the Quality category of the settings page (Ctrl+,), is the default and it is not merely "pick something sensible". Every shape in the library ships with a measured number saying how much it can overstate distance. Auto adds those up for the shapes your scene actually uses and shortens each step to match, giving longer-running rays more steps to work with so they still arrive.
The practical consequences:
- A scene of ordinary shapes costs nothing extra. Most of the library reports distance exactly, so Auto leaves the budget alone.
- A scene using a taper, a domain warp or a heavy noise displacement costs more, because those genuinely distort distance and the renderer has to be more careful. That is the price of drawing them correctly.
- Turning a slider up on one of those shapes tightens the budget automatically. You do not have to know which shapes are expensive.
Leave it on Auto unless you have a reason. Everything below is that reason.
Something is missing from the viewport
Work down this list; it is ordered by how often each one is the answer.
1. Look at the diagnostic view
March diagnostics (RGB), in the Visualization row of the Shading category of the settings page, replaces the shaded image with what the renderer actually did. Three channels:
| Colour | Meaning |
|---|---|
| Red | how much of the step budget that pixel used |
| Green | how often the shape overstated its distance |
| Blue | why the ray stopped ā dark: it hit something; mid: it left the scene; bright: it ran out of steps |
Read it like this:
- Bright green over the missing area ā the shape is overstating distance and the renderer is walking through it. Go to step 2.
- Bright blue, red saturated ā rays are running out of steps before arriving. Go to step 3.
- Mid blue, red low ā the rays left the scene without meeting anything. Nothing is wrong with the marching; the geometry is not where you think it is, or Max ray distance is shorter than the distance to it.
2. Green ā the shape is overstating distance
If the scene uses a taper, a warp, a displacement or a non-uniform scale, this is expected and Auto already accounts for it. If it is still missing:
- Lower Step scale. Halving it halves how far each jump goes.
- Raise Max steps to match, or the rays will simply run out instead.
If the scene uses none of those shapes, the diagnostic is telling you something the library did not know. That is worth reporting ā attach the scene file. A shape that overstates distance without declaring it is a defect in the shape, not in your model.
3. Bright blue ā rays are running out
A ray that runs out of steps near a surface draws that surface. A ray that runs out far from every surface draws the background: it did not find a surface, so the viewport does not invent one where it stopped.
Raise Max ray steps. Auto already raises it for shapes that need it, so hitting this ceiling usually means one of:
- a very large scene viewed from far away (raise Max ray distance too ā a ray that stops before reaching your model is not a marching problem),
- surfaces seen almost edge-on, where rays creep along at a crawl,
- many nested distorting shapes multiplying each other's cost.
4. Only then, change the algorithm
The Tracer list holds every marching strategy the engine ships, and Auto resolves to the one measured as the best general default. The Algorithm row follows the tracer you choose. The others exist because they win on particular scenes:
- Some trade a little accuracy at the surface for speed.
- Some spend extra work to be certain they have not stepped through anything.
Selecting one shows its own settings underneath, with the defaults the benchmark measured. Changing the algorithm is a last resort, not a first step: if geometry is missing, steps 2 and 3 fix it more reliably.
A scene of many items is slow
Each item at the top of the scene tree is a root. For each point of a ray, the viewport skips every root that cannot be the nearest one: it knows how fast the root's distance can change, and how far the ray moved since it last measured that root. The picture does not change. Under Auto, each root also steps by its own bound, not by the bound of the scene's worst shape.
Each root also gets a box that holds its surface, a short time after the scene loads or changes. A ray does not measure a root whose box is farther than the nearest root, and far from the box of a shape that overstates its distance (a strong warp or taper), it steps by the box, not by the shape's short step. The picture does not change, except where rays used to run out of steps on their way past such a shape. A fold and a repeat get no box, so their items stay as slow as before.
To see what the viewport does, set Visualization to Root evaluations, in the Shading category of the settings page:
| Color | Meaning |
|---|---|
| Red | the share of the roots measured at each point of the ray. Full red is every root at every point |
| Green | how much of the step budget the ray used, as red in March diagnostics |
| Blue | which root was the nearest at the end: brighter is later in the scene tree |
Bright green over most of the picture means the rays run out of steps. Look for the item that blue names: a shape that overstates its distance a lot (a strong warp, a strong taper) slows every ray that passes near it, and inside its box the box does not help. Give it a smaller amount, or put it in a scene of its own.
While a heavy scene refines to full resolution, the viewport leaves the GPU idle between its parts, at least as long as each part took. The refined picture is the full size of the viewport, and a hover keeps it: the hover highlight does not draw the scene again. The rest of the desktop shares the GPU and stays responsive. No part may take more than the submit budget (100 ms), unless one pixel alone takes longer. On a software renderer, such as Mesa's lavapipe, the viewport does not wait between the parts: no other program draws with it.
The contact shadow under the items skips roots in the same way when it measures the heights of the scene, so its shadow is the same and costs less on a scene of many items.
The secondary march follows the same settings
In the path-traced mode every shadow ray and every bounce is a second march through the same field, with the same algorithm and the same step scale as the primary ray. What the primary march gets from Auto, the secondary march gets too. Its own two numbers live in the Path tracing category of the settings page: Secondary steps caps how far a bounce ray marches before it counts as a grazing hit, and Secondary epsilon is the hit tolerance. A scene that needs a higher step budget for its silhouette usually needs more secondary steps for its shadows as well.
Where the numbers come from
None of the defaults here are taste. Each shape's distance behaviour is measured by a harness that compares the renderer against exact geometry, and the step-budget formula is fitted to where it measured the failure actually beginning. If you want to look at that evidence, or measure your own scene, see Render Lab.