Shader Clip
The clip shader feature: the fragment-stage test that discards the fragments lying on the far side of any client-supplied plane.
Overview
A clip plane cuts a model open. The client names a plane; everything on the far side of it stops being drawn, so the interior becomes visible without anything being rebuilt. Moving the plane is a uniform update, not a change to geometry.
A plane is the four numbers of a plane equation — the unit normal in xyz,
the signed offset in w — and a fragment survives when it is on the near side
of every plane bound. One plane is a single cut, two facing planes a slab, six
a box; the feature applies whatever set is bound and names none of those
shapes. Binding no planes keeps everything, which is how clipping is turned
off without a second shader.
This package is the declaration of that feature: the Slang that performs the
test, a Python mirror of the same arithmetic, and the ShaderDefinition and
uniform specs saying what a build step must bind for it to work. It computes
nothing at import and draws nothing at runtime. Building a shader from the
declaration, and running it, belong elsewhere.
Installation
pip install vcti-shader-clip
In requirements.txt
vcti-shader-clip>=1.1.0
In pyproject.toml dependencies
dependencies = [
"vcti-shader-clip>=1.1.0",
]
Quick Start
Build a plane, and ask what it keeps:
from vcti.shader.clip import clip_keeps, plane_through
# The normal points into the half that survives, so this keeps z >= 0.
cut = plane_through(point=(0.0, 0.0, 0.0), normal=(0.0, 0.0, 1.0))
assert clip_keeps((0.0, 0.0, 5.0), [cut])
assert not clip_keeps((0.0, 0.0, -5.0), [cut])
# A point exactly on the plane is kept: the comparison is >= 0.
assert clip_keeps((0.0, 0.0, 0.0), [cut])
Two facing planes are a slab, and no planes at all keep everything:
slab = [
plane_through((0.0, 0.0, -1.0), (0.0, 0.0, 1.0)),
plane_through((0.0, 0.0, 1.0), (0.0, 0.0, -1.0)),
]
assert clip_keeps((0.0, 0.0, 0.5), slab)
assert not clip_keeps((0.0, 0.0, 9.0), slab)
assert clip_keeps((0.0, 0.0, 9.0), [])
A ray entering the kept region has entered every half-space, so the plane it actually passes through is the last one it enters. That is the face a cut is seen through, which is what capping needs to know to shade a cut face with the normal of the plane that cut it:
from vcti.shader.clip import clip_entry_plane, plane_through
box = [
plane_through((-1.0, 0.0, 0.0), (1.0, 0.0, 0.0)), # keeps x >= -1
plane_through((0.0, -1.0, 0.0), (0.0, 1.0, 0.0)), # keeps y >= -1
]
# Looking along +x: the ray crosses into the box through the first plane.
assert clip_entry_plane((-5.0, 0.0, 0.0), (1.0, 0.0, 0.0), box) == 0
# Looking along +y: through the second.
assert clip_entry_plane((0.0, -5.0, 0.0), (0.0, 1.0, 0.0), box) == 1
# Nothing entered — the ray travels away from both.
assert clip_entry_plane((0.0, 0.0, 0.0), (-1.0, -1.0, 0.0), box) == -1
# The answer does not depend on how the ray is written: slide the origin along
# it, or scale the direction, and the same face wins. So an orthographic caller
# passes the fragment and a view direction, having no eye to pass.
assert clip_entry_plane((-3.0, 0.0, 0.0), (7.0, 0.0, 0.0), box) == 0
What a build step binds, and the values to bind:
from vcti.shader.clip import DEFINITION, clip_uniforms, fragment_uniforms
assert DEFINITION.id == "clip"
assert [spec.name for spec in fragment_uniforms()] == ["u_clipPlanes", "u_clipPlaneCount"]
uniforms = clip_uniforms(slab)
assert uniforms["u_clipPlaneCount"] == 2
assert len(uniforms["u_clipPlanes"]) == 6 # padded to the declared length
In a composed fragment stage, the Slang side is one line. The module exports a
predicate; the layer composing features emits the discard, which is what
lets it place the test ahead of shading work a discard would waste:
if (!clipKeeps(position, u_clipPlanes, u_clipPlaneCount)) { discard; }
The one obligation a client can miss: the planes must be expressed in
whatever space position arrives in. Binding world-space planes against
eye-space positions produces a picture that looks plausible and cuts in the
wrong place. See docs/design.md.
Key API
| Name | What it is |
|---|---|
DEFINITION |
The ShaderDefinition — id clip, fragment stage, capability clip |
MAX_PLANES |
The fixed length of the uniform array — six, because six planes is a box |
SLANG_DIR |
Where clip.slang installed, for the compiler's import search path |
fragment_uniforms() |
The two UniformSpecs a build step binds |
Plane |
A plane as (nx, ny, nz, offset), with .normal and .flipped() |
plane_through(point, normal) |
A plane through point, normal normalized |
clip_keeps(point, planes) |
Whether point survives them all — the CPU mirror |
clip_entry_plane(origin, direction, planes) |
Which plane a ray enters the kept volume through, or -1 |
plane_distance(plane, point) |
The signed distance; positive on the surviving side |
check_plane / check_planes |
The bind-time validation the shader does not do |
clip_uniforms(planes) |
The two uniform values, padded and validated |
Dependencies
vcti-shader-base — the
zero-dependency ShaderDefinition, StageRole and UniformSpec types — and
nothing else at runtime. Declaring a feature is pure data.
vcti-shader-compiler and numpy are test-only: the suite compiles and runs
the shader to diff it against the Python mirror, but declaring the feature needs
neither.
Documentation
| If you want to… | Read |
|---|---|
| Understand the architecture and design decisions | docs/design.md |
| See practical, real-world usage | docs/patterns.md |
| Navigate and understand the source | docs/source-guide.md |
Metadata
Release files for vcti-shader-clip 1.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_clip-1.1.0.tar.gz | 47.7 kB | With provenance | Details for vcti_shader_clip-1.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcti_shader_clip-1.1.0-py3-none-any.whl | Python 3 | none | any | Details for vcti_shader_clip-1.1.0-py3-none-any.whl |
Total release size: 65.8 kB
Release files / vcti_shader_clip-1.1.0.tar.gz
| Download URL | vcti_shader_clip-1.1.0.tar.gz |
|---|---|
| Size | 47.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
585113bd3841f1242f18710fa0f002d7e3aad9b730c6b68215a8f9825662e9d1
|
|
BLAKE2b-256 checksum How to use checksums |
998f073e8be34da170eb8528f669ae1a7c003b1cbf7430e57e9dc06ad12a5a05
|
| 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_clip-1.1.0-py3-none-any.whl
| Download URL | vcti_shader_clip-1.1.0-py3-none-any.whl |
|---|---|
| Size | 18.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
55e819096867455e3a101bfd2a29c86dfb07ea2984a8d8c1ceb7f60a49c8bd4d
|
|
BLAKE2b-256 checksum How to use checksums |
597b01f2805f7ead279b36486475cbf04b08ac719ba3f88ae70a0a834b1d0d13
|
| 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-clip 1.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_clip-1.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.