Metadata-Version: 2.4
Name: vcti-shader-cap
Version: 1.0.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.0.1
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. `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

# The tag carries the strategy's correctness limit, because nothing in a
# declaration package can enforce it: several clip planes give a wrong shading
# normal over part of the picture, and no error anywhere.
assert DEFINITION.capabilities == ("cap-backface-single-plane",)

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

# No uniform of its own: the cut is described entirely by clip's planes, and
# these are clip's specs re-exported rather than restated.
assert [u.name for u in fragment_uniforms(CapStrategy.BACKFACE)] == [
    "u_clipPlanes",
    "u_clipPlaneCount",
]
```

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

```glsl
if (!clipKeeps(position, u_clipPlanes, u_clipPlaneCount)) { discard; }

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

float3 n = capShadingNormal(v_normal, u_clipPlanes[0], gl_FrontFacing, v_capEnabled);
outColor = shade(n, materialColor);
```

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

**One plane, and the tag says so.** With a box cut, which plane cut the window a
back face is seen through varies per fragment, and answering that needs a
function over a ray that `vcti-shader-clip` does not have. This package ships no
runtime, so it cannot check that only one plane is bound — declining to claim
more than it does is the only mechanism it has. When `clipEntryPlane` lands the
tag becomes `cap-backface`, and that is a breaking change for anyone selecting
on the string. See the implementation plan.

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