Skip to main content

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)

Source distribution for vcti-shader-cap 2.1.0
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)

Table of built distributions (wheels) for vcti-shader-cap 2.1.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page