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")

# 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.
# 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 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; }

// 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(u_viewPosition, position - u_viewPosition,
                            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(gl_FrontFacing, v_capEnabled)) { discard; }

// Everything still reading a plane has a real window; the clamp only keeps the
// index in range for front faces, which ignore it.
float3 n = capShadingNormal(v_normal, u_clipPlanes[max(window, 0)],
                            gl_FrontFacing, v_capEnabled);
float3 c = capColor(materialColor, u_capTint, gl_FrontFacing, v_capEnabled);
outColor = shade(n, c);

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

u_viewPosition is the eye, which vcti-shader-material declares among its lighting uniforms — scene state its specs say another lit feature may share, since identical declarations merge by value. Cap does not declare it: it is camera data, like the clip-space transform. An orthographic renderer has no eye 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.

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.0.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.0.0
File Size Uploaded Provenance Actions
vcti_shader_cap-2.0.0.tar.gz 49.8 kB With provenance Details for vcti_shader_cap-2.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-shader-cap 2.0.0
File Interpreter ABI Platform Actions
vcti_shader_cap-2.0.0-py3-none-any.whl Python 3 none any Details for vcti_shader_cap-2.0.0-py3-none-any.whl

Total release size: 70.3 kB

Release files / vcti_shader_cap-2.0.0.tar.gz

Download URL vcti_shader_cap-2.0.0.tar.gz
Size 49.8 kB
Tags Source
SHA-256 checksum
How to use checksums
15de524cccd8f66c3834c73abadec7c44029683c8a772f3fade6dad404e17c6e
BLAKE2b-256 checksum
How to use checksums
b6386ba1512d5e316d8c83e457255833cae812d02d109bb911073a7a360cfb9b
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.0.0-py3-none-any.whl

Download URL vcti_shader_cap-2.0.0-py3-none-any.whl
Size 20.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ca0cf8c1b9d9da87ea201f71678fb9f41145dea9321eceb683bc90da6f0c8990
BLAKE2b-256 checksum
How to use checksums
c1f95167197919c7445fe536e0893a12e35a6083f419fa58eb8d0f62a231f211
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.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.

Select from 2 files

Attestation for vcti_shader_cap-2.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 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