Measures every item's distance along viewMatrix's forward axis, sorts the
list with §66's sort key 4 in place, and returns it (R-10 key 4, 2026-08-09).
Why this is a verb and not a default (decision, R-8)
The same reason groupRenderListByPipeline is, and it is worth restating
because the reason is correctness, not caution. §61 fixes the depth
function at LEQUAL, so of two opaque surfaces at the same depth the one
submitted later wins — which is what makes a §58 stroke paint over its own
fill and a later sibling draw on top. All of this engine's 2D content sits at
one depth, so a depth key applied to it permutes co-planar draws whose order
is the picture: sorting a 2D scene by depth repaints it. §66 lists key 4
for content whose overlap the depth buffer resolves, and no property of a
render item distinguishes that content from a stack of flat shapes. So the
caller who knows their scene is depth-resolved asks for the key, and every
existing scene keeps the order it has had since 2026-08-06 — byte for byte,
since neither builder is edited by this function's existence.
Why it is per-view, and why it could not be written before R-8
Depth is measured along a camera. One list served every view until this
packet, so a depth key computed for one camera would have ordered every other
view of the same list by the wrong number: a key written then would have been
wrong, not merely disruptive (recorded 2026-08-09). Sorting a derived
list is what makes the measurement belong to the view that uses it — and it
is why this verb takes a view matrix rather than reading one off a camera the
list does not know about.
Key 3 outranks key 4 (R-8 follow-up a)
§66's order is layer → opaque/transparent → pipeline/material → depth →
explicit order. After writing viewDepth, this verb applies
compareRenderItems — the one comparator that carries every key.
Transparent items still sort back-to-front, but only within the same
pipeline and material. A scene that never calls this function is untouched:
the builders still sort with keys 1, 2 and 5 only.
What is measured
The item's world-space origin — the translation column of its
worldMatrix — transformed into view space, negated so that larger means
farther from the camera. Not the centroid of its bounds, and the difference
is worth stating because §66 asks for transparent sorting's limitations to be
documented: a long floor plane whose origin is at one corner sorts by that
corner, and two interpenetrating transparent surfaces cannot be ordered by
any single number at all. Per-triangle ordering, weighted-blended
transparency, and OIT are §66's own named extension points and none of them
is this function.
A non-finite measurement — a NaN in a world matrix — is written as 0
rather than propagated: a comparator that returns NaN makes
Array.prototype.sort produce an implementation-defined order, which would
turn one bad matrix into a scene-wide reordering.
Measures every item's distance along
viewMatrix's forward axis, sorts the list with §66's sort key 4 in place, and returns it (R-10 key 4, 2026-08-09).Why this is a verb and not a default (decision, R-8)
The same reason
groupRenderListByPipelineis, and it is worth restating because the reason is correctness, not caution. §61 fixes the depth function atLEQUAL, so of two opaque surfaces at the same depth the one submitted later wins — which is what makes a §58 stroke paint over its own fill and a later sibling draw on top. All of this engine's 2D content sits at one depth, so a depth key applied to it permutes co-planar draws whose order is the picture: sorting a 2D scene by depth repaints it. §66 lists key 4 for content whose overlap the depth buffer resolves, and no property of a render item distinguishes that content from a stack of flat shapes. So the caller who knows their scene is depth-resolved asks for the key, and every existing scene keeps the order it has had since 2026-08-06 — byte for byte, since neither builder is edited by this function's existence.Why it is per-view, and why it could not be written before R-8
Depth is measured along a camera. One list served every view until this packet, so a depth key computed for one camera would have ordered every other view of the same list by the wrong number: a key written then would have been wrong, not merely disruptive (recorded 2026-08-09). Sorting a derived list is what makes the measurement belong to the view that uses it — and it is why this verb takes a view matrix rather than reading one off a camera the list does not know about.
Key 3 outranks key 4 (R-8 follow-up a)
§66's order is layer → opaque/transparent → pipeline/material → depth → explicit order. After writing
viewDepth, this verb applies compareRenderItems — the one comparator that carries every key. Transparent items still sort back-to-front, but only within the same pipeline and material. A scene that never calls this function is untouched: the builders still sort with keys 1, 2 and 5 only.What is measured
The item's world-space origin — the translation column of its
worldMatrix— transformed into view space, negated so that larger means farther from the camera. Not the centroid of its bounds, and the difference is worth stating because §66 asks for transparent sorting's limitations to be documented: a long floor plane whose origin is at one corner sorts by that corner, and two interpenetrating transparent surfaces cannot be ordered by any single number at all. Per-triangle ordering, weighted-blended transparency, and OIT are §66's own named extension points and none of them is this function.A non-finite measurement — a
NaNin a world matrix — is written as0rather than propagated: a comparator that returnsNaNmakesArray.prototype.sortproduce an implementation-defined order, which would turn one bad matrix into a scene-wide reordering.