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

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

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

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

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

Select from 2 files

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