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

In pyproject.toml dependencies

dependencies = [
    "vcti-shader-clip>=1.0.1",
]

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), [])

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

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.0.1
File Size Uploaded Provenance Actions
vcti_shader_clip-1.0.1.tar.gz 40.4 kB With provenance Details for vcti_shader_clip-1.0.1.tar.gz

Built distribution (wheel)

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

Total release size: 55.8 kB

Release files / vcti_shader_clip-1.0.1.tar.gz

Download URL vcti_shader_clip-1.0.1.tar.gz
Size 40.4 kB
Tags Source
SHA-256 checksum
How to use checksums
53697ac4f176119c5ae927e547fe492bf2fb95f8826f4c3c101b3cbafa93e970
BLAKE2b-256 checksum
How to use checksums
963769e47fee3d8792ee20362c274b1bc31e03523a4f252c244c2ecd64d83ee4
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 20, 2026.

Transparency log

Release files / vcti_shader_clip-1.0.1-py3-none-any.whl

Download URL vcti_shader_clip-1.0.1-py3-none-any.whl
Size 15.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bde1073385dab3d6669f109c95b0da3f565c5f1157d2efdb488df1448eb0a394
BLAKE2b-256 checksum
How to use checksums
f86637a9bceb877158e16d453b18555a2af0a3400cfc6b31a1b94f1ae43cd139
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 20, 2026.

Transparency log

Security for vcti-shader-clip 1.0.1

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.0.1.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 20, 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