Metadata-Version: 2.4
Name: vcti-shader-cap
Version: 2.1.0
Summary: 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.
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-shader-cap
Project-URL: Changelog, https://github.com/vcollab/vcti-python-shader-cap/blob/main/CHANGELOG.md
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: vcti-shader-base>=2.3.0
Requires-Dist: vcti-shader-clip>=1.1.0
Provides-Extra: gl
Requires-Dist: vcti-shader-compiler[gl]>=4.0.0; extra == "gl"
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: vcti-shader-compiler>=4.0.0; extra == "test"
Requires-Dist: numpy; extra == "test"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# 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, against any number of clip planes.
`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](docs/design.md) records what both strategies agree on and why
the package is shaped this way; [docs/implementation-plan.md](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:

```python
from vcti.shader.cap import DEFINITION, CapStrategy, fragment_inputs, fragment_uniforms

assert DEFINITION.capabilities == ("cap-backface",)

# 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")

# Clip's planes describe the cut, re-exported rather than restated so the two
# declarations are identical by construction. `u_capTint` is the one uniform
# capping owns: how a cut face is presented, which nothing else would bind.
assert [u.name for u in fragment_uniforms(CapStrategy.BACKFACE)] == [
    "u_clipPlanes",
    "u_clipPlaneCount",
    "u_capTint",
]
```

The Slang it ships answers questions and acts on none of them, so the composed
stage decides where the work goes:

```glsl
// `position` and `eye` are in the space the PLANES are in — that is what
// clipKeeps and clipEntryPlane work in. `v_normal` is in the space the SHADING
// works in. Those are the same space in some compositions and not in others,
// and the difference decides the normal line at the bottom.
if (!clipKeeps(position, u_clipPlanes, u_clipPlaneCount)) { discard; }

// `gl_FrontFacing` describes the triangle *after* it was transformed, so a
// mirrored part reports every facing inverted. Omit this only where nothing is
// ever placed with a negative determinant.
bool facing = capFacing(gl_FrontFacing, v_windingFlipped);

// Culling is off for this draw, so the shader stands in for it.
if (capCulled(facing, v_capEnabled)) { discard; }

// Which plane cut the window this back face is seen through. Under a box cut
// that differs by screen region, so it cannot be a uniform index.
int window = clipEntryPlane(eye, position - eye, u_clipPlanes, u_clipPlaneCount);

// -1: the ray entered no half-space, so nothing cut this fragment. `capFills`
// only reads the facing and the flag, so a back face reaches the cap branch
// whether or not there is a cut behind it. This one is a surface culling would
// have removed, so it goes the way `capCulled`'s do.
if (window < 0 && capFills(facing, v_capEnabled)) { discard; }

// ONE SPACE ONLY. capShadingNormal picks between `v_normal` and the plane's
// normal and returns one vector, so it assumes those two already agree. If your
// planes and your shading are in different spaces, this line is the bug — take
// the two-space form below instead. Nothing else in this block changes.
float3 n = capShadingNormal(v_normal, u_clipPlanes[max(window, 0)],
                            facing, v_capEnabled);

// Everything reading a plane here has a real window; the clamp only keeps the
// index in range for front faces, which ignore it.
float3 c = capColor(materialColor, u_capTint, facing, v_capEnabled);
outColor = shade(n, c);
```

`capFacing` is the one call whose absence is invisible until it matters.
`gl_FrontFacing` is the sign of a triangle's area in *window* space, so a part
placed with a negative-determinant transform reports every facing inverted —
capping then fills its **entry** faces, painting the near surface as a flat cut
and leaving the real cut open. The part looks solid and uncut while its
neighbors cap correctly, which reads as *capping does not apply here* rather
than as a bug.

It cannot be corrected outside the shader in this renderer: the usual remedy is
per-draw front-face state, but part transforms come from a palette indexed in
the vertex stage while draws are spatial slabs, so one draw carries parts of
both handednesses. Pass zero, or omit the call, where nothing is ever mirrored.

```python
from vcti.shader.cap import cap_facing, cap_fills

# On an unmirrored part the rasterizer's answer is the geometry's.
assert cap_facing(False, False) is False
assert cap_fills(cap_facing(False, False), True) is True  # a back face caps

# On a mirrored one it is inverted, so the raster *front* face is the cut.
assert cap_facing(True, True) is False
assert cap_fills(cap_facing(True, True), True) is True

# Uncorrected, that same fragment is read as a front face and nothing caps.
assert cap_fills(True, True) is False
```

A cap in the exact material color is correct and is also indistinguishable from
real geometry. `u_capTint` modulates it — `rgb` is the color to move toward, `a`
is how far — applied to the color going *into* the shading, so the cap stays
lit. Zero is off, which is what an unbound uniform already reads as, and one
gives every cut face a single color regardless of material.

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:

```python
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)
```

```python
from vcti.shader.cap import cap_color

material = (0.2, 0.4, 0.6)

# Off by default, and exactly off: the material survives bit for bit.
assert cap_color(material, (1.0, 0.0, 0.0, 0.0), False, True) == material

# Fully tinted: one color for every cut face, whatever the material.
assert cap_color(material, (0.1, 0.2, 0.3, 1.0), False, True) == (0.1, 0.2, 0.3)

# Only a cap is tinted. A front face is the rest of the model.
assert cap_color(material, (1.0, 0.0, 0.0, 1.0), True, True) == material
```

`eye` is written as a placeholder rather than a uniform name, because it is not
one of cap's — every other name in that sketch is in `fragment_uniforms()`, and
this one would be an assertion about a composition cap cannot see. **It must be
the eye in the space the planes are in**, which is where `clipEntryPlane` works.
A composition that shades in view space has an eye uniform that is zero there;
passing it computes a ray from the wrong origin, correct only while the camera
sits at it. The reference composition, `vcti-shader-foundry`, calls the value
this needs `u_modelEyePosition`.

An orthographic renderer has no eye at all and passes the fragment with a
constant view direction instead, which works because `clipEntryPlane`'s answer
does not depend on how the ray is parameterized.

**If the shading works in a different space than the planes** — planes kept
fixed to the model while lighting runs in view space, say — use `capFills` and
`capNormal` directly and carry the direction across yourself, with the same 3×3
the surface normal goes through:

```glsl
float3 n = capFills(facing, v_capEnabled)
    ? normalize(mul((float3x3)u_modelViewMatrix, capNormal(u_clipPlanes[max(window, 0)])))
    : v_normal;
```

**That one line is the only change.** The clip test, both discards,
`clipEntryPlane`, `capColor` and the shade call are all identical — the window
index has no space, and the tint operates on colors rather than directions.
`capShadingNormal` is simply never called, which is the normal outcome for a
two-space composition rather than a workaround.

**Choosing the plane is the composition's job.** `cap.slang` takes one plane and
never sees the array, which is what keeps it from ever drifting from clip's
capacity. Which plane a given cap fragment shades with comes from
`clipEntryPlane`, because under a box cut that differs by screen region and no
uniform index can carry it. Pass the wrong plane and nothing fails — the cut is
merely lit as though it faced somewhere else — so the sketch above is the
documented composition rather than a suggestion, and `tests/test_interface.py`
compiles it.

## Installation

```bash
pip install vcti-shader-cap
```

## Dependencies

[`vcti-shader-clip`](https://github.com/vcollab/vcti-python-shader-clip), whose
planes describe the cut and whose uniform specs this package re-exports rather
than restates, and
[`vcti-shader-base`](https://github.com/vcollab/vcti-python-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](docs/design.md) |
| See the two strategies in full, and what would decide between them | [docs/implementation-plan.md](docs/implementation-plan.md) |
| Know where the shipped strategy draws a wrong picture | [Known-incorrect cases](docs/implementation-plan.md#known-incorrect-cases--release-criteria) |
