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

In pyproject.toml dependencies

dependencies = [
    "vcti-shader-clip>=1.0.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), [])

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

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