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. 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
# The tag carries the strategy's correctness limit, because nothing in a
# declaration package can enforce it: several clip planes give a wrong shading
# normal over part of the picture, and no error anywhere.
assert DEFINITION.capabilities == ("cap-backface-single-plane",)
# 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")
# No uniform of its own: the cut is described entirely by clip's planes, and
# these are clip's specs re-exported rather than restated.
assert [u.name for u in fragment_uniforms(CapStrategy.BACKFACE)] == [
"u_clipPlanes",
"u_clipPlaneCount",
]
The Slang it ships answers three questions and acts on none of them, so the composed stage decides where the work goes:
if (!clipKeeps(position, u_clipPlanes, u_clipPlaneCount)) { discard; }
// Culling is off for this draw, so the shader stands in for it.
if (capCulled(gl_FrontFacing, v_capEnabled)) { discard; }
float3 n = capShadingNormal(v_normal, u_clipPlanes[0], gl_FrontFacing, v_capEnabled);
outColor = shade(n, materialColor);
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)
One plane, and the tag says so. With a box cut, which plane cut the window a
back face is seen through varies per fragment, and answering that needs a
function over a ray that vcti-shader-clip does not have. This package ships no
runtime, so it cannot check that only one plane is bound — declining to claim
more than it does is the only mechanism it has. When clipEntryPlane lands the
tag becomes cap-backface, and that is a breaking change for anyone selecting
on the string. See the implementation plan.
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 1.0.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-1.0.0.tar.gz | 38.1 kB | With provenance | Details for vcti_shader_cap-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcti_shader_cap-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for vcti_shader_cap-1.0.0-py3-none-any.whl |
Total release size: 54.0 kB
Release files / vcti_shader_cap-1.0.0.tar.gz
| Download URL | vcti_shader_cap-1.0.0.tar.gz |
|---|---|
| Size | 38.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d313e8732d9097373b98acb51c2094856cb983da63bcc2301b665a64598cd75f
|
|
BLAKE2b-256 checksum How to use checksums |
3a4c5a72e22017919aca6a2481d8dac580558dcea07c4034809841c5ad288672
|
| 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 21, 2026.
Transparency logRelease files / vcti_shader_cap-1.0.0-py3-none-any.whl
| Download URL | vcti_shader_cap-1.0.0-py3-none-any.whl |
|---|---|
| Size | 16.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a37d8621a527d0f5304fc41b619b10f5fb0b47f7fd055e5c0692434118ab946c
|
|
BLAKE2b-256 checksum How to use checksums |
cd5ba4f355e902c546a58fff83128f3832667978ed1f303b2af510f3eb533d9b
|
| 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 21, 2026.
Transparency logSecurity for vcti-shader-cap 1.0.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-1.0.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 21, 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.