Skip to main content

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)

Source distribution for vcti-shader-clip 1.1.0
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)

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

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

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

Select from 2 files

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