Repository navigation
Adds a dynamic heightfield surface (Heightfield), a headless GPU pick pass for OffscreenRenderer, and
fixes a blank view when enableTAA is on without the SSAO/silhouette composite. One behaviour change to
read about: uniformTessellationFactor = .loadAdaptive no longer reacts to a GPU that was idle-clocked
before a frame. Nothing is source-incompatible.
Changed (read before upgrading)
uniformTessellationFactor = .loadAdaptive(withadaptiveTessellation = false) lowers the factor
only when the GPU is saturated (#241). A frame the GPU was busy for less than 95% of the time since
the previous frame ended (the first frame after a pause, a debug build, on-demand drawing, a
display-paced or clock-stretched frame) can raise the factor but no longer lowers it. Frames run back
to back at or over the budget lower it exactly as before, so a genuinely overloaded GPU still drops
the factor. Debug builds therefore keep the maximum factor instead of settling lower than release. The
defaultadaptiveTessellation = truenever read GPU time and is unchanged.
Added
Heightfield: a dynamic heightfield surface (#139). A grid of cell heights with a per-cell
attribute (coloured through a 256-entry ramp) and an optional per-cell id, attached with
ViewportBody.heightfieldand edited in place withreplace(region:heights:attributes:ids:). Only the
64 x 64-cell tiles an edit touched are uploaded, so replacing a 130 x 120 region 200 times per frame
is cheap. It is drawn as instanced tiles at per-tile levels of detail with crack-free seams, in the
shaded, translucent, shadow, depth, selection-outline, overlay and pick passes of both
ViewportRendererandOffscreenRenderer. Both initialisers throwHeightfieldErrorfor a field that
cannot be drawn (Heightfield.maximumDimensionis 16,321 cells per side);.float16heights halve the
height upload..wireframedraws nothing for a heightfield.
Only verified on an M4 Mac: measurements on an iPhone or iPad are still to be done (#139), and the
coarse levels use a conservative minimum so a step edge can sit up to 1.5 mesh cells from its true
position (seedocs/reference/Heightfield.md).- Picking a heightfield.
PickResult.heightfield(cell, height, attribute, id),
ViewportController.refinePick(_:ndc:bodies:)(makes a click's cell exact at every level of detail;
MetalViewportViewapplies it to every tap) andHeightfield.raycast(origin:direction:maxDistance:),
an exact grid march thatSceneRaycastuses, so the dynamic pivot and focus-on-point work on a
heightfield.Heightfield.recomputeHeightRange()resets the running height range after edits that
lower the surface. ViewportConfiguration.heightfieldMeshCellPixelsand
OffscreenRenderOptions.heightfieldMeshCellPixels: the target size in pixels of a heightfield mesh
cell (default 4, range1...32; 2 px costs about nine times as much GPU time as 4 px).- A headless GPU pick pass for
OffscreenRenderer(#236).renderPickMap(bodies:options:),
performPick(bodies:at:options:)andperformRegionPick(bodies:rect:options:)return the same
PickResultas the liveperformPick/performRegionPickfor the same scene and camera (faces on
every path, edges, arcs, vertices, point clouds, overlay bodies; clip planes, display mode and body
transforms applied).OffscreenPickMapis the pick texture of one render, withpick(at:)and
pickRegion(_:);OffscreenRenderOptionsgainspickRadiusandselectionFilter.
Fixed
- A blank view with
enableTAAon and no SSAO/silhouette composite (#244). With SSAO and silhouettes
both off, or in.unlit/.wireframe, nothing copied the TAA output to the drawable: a live view
showed nothing and a headless readback returned uninitialised memory. The output is now copied to the
final target (one extra fullscreen pass, only in that case). The defaultenableSilhouettes: true
had hidden it. TessellationLoadGovernordropping the uniform tessellation factor to its minimum because the GPU
was idle-clocked before a frame (#241, see Changed).- A stale cached bounding box when a body changes in place without its
generationchanging (#237).
Caches of per-body bounds now key on an internalViewportBody.boundsKey, andgenerationdocuments
the invariant.
Docs and tooling
- GPU frame time, and so
.loadAdaptive, is not comparable between debug and release builds: a frame
that follows an idle GPU is 1.6-2.5x slower (an M4 measurement) and a debug build's slow CPU-side
encoding makes every frame such a frame. Use.fixed(_:)to compare quality across builds and measure
GPU time in release (#238). - New reference page
docs/reference/Heightfield.mdand cookbook page
docs/guides/cookbook/heightfield-surfaces.md; updates to the Rendering, Picking, Configuration and
ViewportBody pages. ViewportRendererandOffscreenRenderernow encode the GPU pick pass through one shared function;
no behaviour change for the live viewport.
Full changelog: https://github.com/SecondMouseAU/OCCTSwiftViewport/blob/v1.3.2/docs/CHANGELOG.md