Shader Cap
The capping shader feature: the fragment-stage fill that closes the cut a clip plane leaves open, in the material color of the solid being cut.
Overview
A clip plane cuts a model open, and the fragments that would have formed the cut surface were never generated — so a clipped solid reads as hollow. Capping fills that cut, in the material color of the solid being cut, so the model reads as solid again.
Coloring a section by result values — stress on the cut face — is a different feature, served by cut-sections computed on the server and drawn as real geometry on the client. Nothing here is a substitute for that, and the two do not share a path.
Status
cap-backface is implemented, against any number of clip planes.
cap-stencil is specified and not built.
Capping has two viable GPU strategies, and they ship from this one package with
a capability tag each. cap-backface branches on gl_FrontFacing in the
fragment stage: no extra pass, no stencil, no offscreen target. cap-stencil
runs a parity count, a material capture and a masked quad per plane: correct in
depth and indifferent to triangle winding, at two full-geometry passes per
plane.
One package rather than two, because what the strategies share is policy — what the cap's color means, the shading normal, which primitives are cappable — and policy that lives in two places drifts. Adding the second is a tag and a Slang module, not a package.
docs/design.md records what both strategies agree on and why the package is shaped this way; docs/implementation-plan.md carries both in full, including what would decide between them.
Quick Start
The feature declares itself, and something else composes it:
from vcti.shader.cap import DEFINITION, CapStrategy, fragment_inputs, fragment_uniforms
assert DEFINITION.capabilities == ("cap-backface",)
# Capping is incomplete on its own: the cut it fills is clip's, so a composition
# holding cap without clip has a cap with nothing to fill.
assert DEFINITION.requires == ("clip",)
# One attribute — whether this primitive participates in capping. Carry it to
# the fragment stage as a `flat` varying.
(cap_flag,) = fragment_inputs(CapStrategy.BACKFACE)
assert (cap_flag.name, cap_flag.type) == ("a_capEnabled", "int")
# Clip's planes describe the cut, re-exported rather than restated so the two
# declarations are identical by construction. `u_capTint` is the one uniform
# capping owns: how a cut face is presented, which nothing else would bind.
assert [u.name for u in fragment_uniforms(CapStrategy.BACKFACE)] == [
"u_clipPlanes",
"u_clipPlaneCount",
"u_capTint",
]
The Slang it ships answers questions and acts on none of them, so the composed stage decides where the work goes:
// `position` and `eye` are in the space the PLANES are in — that is what
// clipKeeps and clipEntryPlane work in. `v_normal` is in the space the SHADING
// works in. Those are the same space in some compositions and not in others,
// and the difference decides the normal line at the bottom.
if (!clipKeeps(position, u_clipPlanes, u_clipPlaneCount)) { discard; }
// `gl_FrontFacing` describes the triangle *after* it was transformed, so a
// mirrored part reports every facing inverted. Omit this only where nothing is
// ever placed with a negative determinant.
bool facing = capFacing(gl_FrontFacing, v_windingFlipped);
// Culling is off for this draw, so the shader stands in for it.
if (capCulled(facing, v_capEnabled)) { discard; }
// Which plane cut the window this back face is seen through. Under a box cut
// that differs by screen region, so it cannot be a uniform index.
int window = clipEntryPlane(eye, position - eye, u_clipPlanes, u_clipPlaneCount);
// -1: the ray entered no half-space, so nothing cut this fragment. `capFills`
// only reads the facing and the flag, so a back face reaches the cap branch
// whether or not there is a cut behind it. This one is a surface culling would
// have removed, so it goes the way `capCulled`'s do.
if (window < 0 && capFills(facing, v_capEnabled)) { discard; }
// ONE SPACE ONLY. capShadingNormal picks between `v_normal` and the plane's
// normal and returns one vector, so it assumes those two already agree. If your
// planes and your shading are in different spaces, this line is the bug — take
// the two-space form below instead. Nothing else in this block changes.
float3 n = capShadingNormal(v_normal, u_clipPlanes[max(window, 0)],
facing, v_capEnabled);
// Everything reading a plane here has a real window; the clamp only keeps the
// index in range for front faces, which ignore it.
float3 c = capColor(materialColor, u_capTint, facing, v_capEnabled);
outColor = shade(n, c);
capFacing is the one call whose absence is invisible until it matters.
gl_FrontFacing is the sign of a triangle's area in window space, so a part
placed with a negative-determinant transform reports every facing inverted —
capping then fills its entry faces, painting the near surface as a flat cut
and leaving the real cut open. The part looks solid and uncut while its
neighbors cap correctly, which reads as capping does not apply here rather
than as a bug.
It cannot be corrected outside the shader in this renderer: the usual remedy is per-draw front-face state, but part transforms come from a palette indexed in the vertex stage while draws are spatial slabs, so one draw carries parts of both handednesses. Pass zero, or omit the call, where nothing is ever mirrored.
from vcti.shader.cap import cap_facing, cap_fills
# On an unmirrored part the rasterizer's answer is the geometry's.
assert cap_facing(False, False) is False
assert cap_fills(cap_facing(False, False), True) is True # a back face caps
# On a mirrored one it is inverted, so the raster *front* face is the cut.
assert cap_facing(True, True) is False
assert cap_fills(cap_facing(True, True), True) is True
# Uncorrected, that same fragment is read as a front face and nothing caps.
assert cap_fills(True, True) is False
A cap in the exact material color is correct and is also indistinguishable from
real geometry. u_capTint modulates it — rgb is the color to move toward, a
is how far — applied to the color going into the shading, so the cap stays
lit. Zero is off, which is what an unbound uniform already reads as, and one
gives every cut face a single color regardless of material.
The same arithmetic is mirrored in Python, which is what the Slang is validated against — and it is where the one counter-intuitive part is written down:
from vcti.shader.cap import cap_shading_normal
plane = (0.0, 0.0, 1.0, 0.0) # keeps +Z; the eye is on the -Z side
# A cappable back face is a cap, and it faces the eye: the plane's normal,
# negated. Shading with +Z would light the cut as though backlit.
assert cap_shading_normal((1.0, 0.0, 0.0), plane, False, True) == (0.0, 0.0, -1.0)
# A front face is ordinary geometry, which is what keeps a bore open.
assert cap_shading_normal((1.0, 0.0, 0.0), plane, True, True) == (1.0, 0.0, 0.0)
from vcti.shader.cap import cap_color
material = (0.2, 0.4, 0.6)
# Off by default, and exactly off: the material survives bit for bit.
assert cap_color(material, (1.0, 0.0, 0.0, 0.0), False, True) == material
# Fully tinted: one color for every cut face, whatever the material.
assert cap_color(material, (0.1, 0.2, 0.3, 1.0), False, True) == (0.1, 0.2, 0.3)
# Only a cap is tinted. A front face is the rest of the model.
assert cap_color(material, (1.0, 0.0, 0.0, 1.0), True, True) == material
eye is written as a placeholder rather than a uniform name, because it is not
one of cap's — every other name in that sketch is in fragment_uniforms(), and
this one would be an assertion about a composition cap cannot see. It must be
the eye in the space the planes are in, which is where clipEntryPlane works.
A composition that shades in view space has an eye uniform that is zero there;
passing it computes a ray from the wrong origin, correct only while the camera
sits at it. The reference composition, vcti-shader-foundry, calls the value
this needs u_modelEyePosition.
An orthographic renderer has no eye at all and passes the fragment with a
constant view direction instead, which works because clipEntryPlane's answer
does not depend on how the ray is parameterized.
If the shading works in a different space than the planes — planes kept
fixed to the model while lighting runs in view space, say — use capFills and
capNormal directly and carry the direction across yourself, with the same 3×3
the surface normal goes through:
float3 n = capFills(facing, v_capEnabled)
? normalize(mul((float3x3)u_modelViewMatrix, capNormal(u_clipPlanes[max(window, 0)])))
: v_normal;
That one line is the only change. The clip test, both discards,
clipEntryPlane, capColor and the shade call are all identical — the window
index has no space, and the tint operates on colors rather than directions.
capShadingNormal is simply never called, which is the normal outcome for a
two-space composition rather than a workaround.
Choosing the plane is the composition's job. cap.slang takes one plane and
never sees the array, which is what keeps it from ever drifting from clip's
capacity. Which plane a given cap fragment shades with comes from
clipEntryPlane, because under a box cut that differs by screen region and no
uniform index can carry it. Pass the wrong plane and nothing fails — the cut is
merely lit as though it faced somewhere else — so the sketch above is the
documented composition rather than a suggestion, and tests/test_interface.py
compiles it.
Installation
pip install vcti-shader-cap
Dependencies
vcti-shader-clip, whose
planes describe the cut and whose uniform specs this package re-exports rather
than restates, and
vcti-shader-base for the
declaration vocabulary. Both are pure data, so installing this package pulls in
no toolchain and no GL binding.
The compiler and a GL binding are [test] and [gl] extras: they run the
shipped Slang headlessly and diff it against the Python mirror, which is how the
feature is validated, but declaring a feature needs neither.
Documentation
| If you want to… | Read |
|---|---|
| Understand the architecture and design decisions | docs/design.md |
| See the two strategies in full, and what would decide between them | docs/implementation-plan.md |
| Know where the shipped strategy draws a wrong picture | Known-incorrect cases |
Metadata
Release files for vcti-shader-cap 2.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vcti_shader_cap-2.1.0.tar.gz | 55.4 kB | With provenance | Details for vcti_shader_cap-2.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcti_shader_cap-2.1.0-py3-none-any.whl | Python 3 | none | any | Details for vcti_shader_cap-2.1.0-py3-none-any.whl |
Total release size: 79.5 kB
Release files / vcti_shader_cap-2.1.0.tar.gz
| Download URL | vcti_shader_cap-2.1.0.tar.gz |
|---|---|
| Size | 55.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0f645b67e861b0a7aaf0ca703199692cb50abf414637c293e26c0e36ebd7b5d5
|
|
BLAKE2b-256 checksum How to use checksums |
a073defd213099b91dc21c2d44f696cfd7db0dad21dbb08f9750c6fcbd58fd36
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / vcti_shader_cap-2.1.0-py3-none-any.whl
| Download URL | vcti_shader_cap-2.1.0-py3-none-any.whl |
|---|---|
| Size | 24.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
75f7b8b1082f67b61ac4801f946080b29527f11e42f96f3013fa15130e2d39c2
|
|
BLAKE2b-256 checksum How to use checksums |
119f0565acc1e9c6f6f0513adf22d9f12fa660a85d83920454887bcb3030dbc4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logSecurity for vcti-shader-cap 2.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for vcti_shader_cap-2.1.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.