Metadata-Version: 2.4
Name: vcti-shader-foundry
Version: 6.0.0
Summary: Shader artifact-set builder: composes the installed shader features into the pipeline matrix, drives the compiler, and emits the artifact set for VCollab renderers
Author: Visual Collaboration Technologies Inc.
License-Expression: LicenseRef-Proprietary
Project-URL: Repository, https://github.com/vcollab/vcti-python-shader-foundry
Project-URL: Changelog, https://github.com/vcollab/vcti-python-shader-foundry/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-compiler>=4.2.0
Requires-Dist: vcti-shader-base>=2.3.0
Requires-Dist: vcti-shader-deform>=2.0.1
Requires-Dist: vcti-shader-derive>=3.0.0
Requires-Dist: vcti-shader-fringe>=2.1.0
Requires-Dist: vcti-shader-mask>=1.1.0
Requires-Dist: vcti-shader-transform>=2.0.0
Requires-Dist: vcti-shader-clip>=1.1.0
Requires-Dist: vcti-shader-cap>=2.1.0
Requires-Dist: vcti-shader-pick>=2.0.0
Requires-Dist: vcti-shader-material>=1.2.0
Requires-Dist: vcti-derived>=4.0
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Requires-Dist: numpy>=1.26; extra == "test"
Provides-Extra: gl
Requires-Dist: vcti-shader-compiler[gl]>=4.1.0; extra == "gl"
Provides-Extra: lint
Requires-Dist: ruff; extra == "lint"
Provides-Extra: typecheck
Requires-Dist: mypy; extra == "typecheck"
Dynamic: license-file

# vcti-shader-foundry

The shader artifact-set **builder**: composes the installed shader features into the pipeline matrix, drives the compiler, and emits the artifact set for VCollab renderers.

## Overview

`vcti-shader-foundry` is the assembler of the shader system — the offline build
tool that turns the installed shader features into the artifact set the
runtime ships. It composes nine feature packages — mask, deform, transform,
derive, fringe, clip, cap, pick and material — into nine fragment shapes drawn
through three vertex variants, capped and uncapped, generates the Slang that wires them, drives
`vcti-shader-compiler` to emit and validate GLSL ES, checks every result
against its contract and the GLSL ES 3.00 budgets, and packs the shaders, one
envelope per pipeline and the `registry.json` index into a single archive,
written atomically, for a consumer to take as it likes.

Composition is the whole job, and it is the part no feature can do: each
feature declares its own fields and cannot see what it is combined with, so the
builder is where the uniforms that belong to nobody are added — the clip-space
transform, the color selector, the opacity — where a name two features
declare differently is rejected, where the features run in the one order they
each require, and where the manifest, the only contract the runtime reads, is
written. Mask, transform, clip and the surface finish are in every pipeline
with their off state supplied as data; the argument for that, and for which
pipelines exist at all, is in [docs/pipeline-matrix.md](docs/pipeline-matrix.md).

It is **not** the toolchain and **not** the vocabulary: the `.slang → GLSL ES`
machinery lives in `vcti-shader-compiler`, the specs you declare fields with in
`vcti-shader-base`, and each shader feature in its own package. See
[docs/design.md](docs/design.md) for the system design and
[docs/extending.md](docs/extending.md) for adding a shader feature.

## Installation

```bash
pip install vcti-shader-foundry
```

This is a build tool, not a runtime dependency; install it in the authoring
environment alongside the feature packages you want built. The shader compilers
(`slangc`, `spirv-cross`, `glslang`) are external and pinned — discovered via
`SLANG_DIR` / `SPIRV_CROSS_DIR` / `GLSLANG_DIR` or `PATH`.

## Quick Start

Build the artifact set as one archive:

```console
$ shader-foundry emit
wrote shaders-6.0.0-5496bf45.zip: 54 pipeline(s), 3,670,840 bytes, sha256 5496bf45…
  registry.json, pipelines/*.json (54), shaders/*.glsl (108)
  toolchain slangc 2026.12.0.1, spirv-cross vulkan-sdk-1.4.357.0, glslang 11:16.5.0 (pinned)
```

One file, three kinds of content, because the same build is read three ways:
`registry.json` for a consumer choosing a pipeline, one self-contained envelope
per pipeline — contract, uniform layout, sampler bindings and sources inline —
for one rendering it, and the `.glsl` files for a person. The archive is
written whole or not at all: everything is built and checked in memory, then
written to a temporary file and renamed into place. It is also reproducible, so
identical inputs give an identical file and the hash above identifies the set.
`--out` takes any path, with `{version}` and `{sha8}` filled in wherever they
appear.

Give a directory instead of a `.zip` path and the same files are unpacked into
it — to read them, or to build a subset with `--pipeline ID` (repeatable) while
iterating on one shape. A subset carries no `registry.json` and cannot become
an archive. `shader-foundry pipelines` lists the ids, and needs no toolchain.

The executable versions a set is built with are pinned in the package. `emit`
warns when the installed tools differ from the pins and refuses with
`--strict-toolchain`; the manifest records what was actually used either way.

The same from Python, when a build needs to do more around it:

```python
# requires: the shader toolchain (slangc, spirv-cross, glslang)
from vcti.shader.compiler import discover_toolchain
from vcti.shader.foundry import build_artifact_set, build_manifest, toolchain_info, write_archive

toolchain = discover_toolchain()
artifact_set = build_artifact_set(build_manifest(toolchain_info(toolchain)), toolchain)
print(write_archive(artifact_set))          # shaders-<version>-<sha8>.zip, the default name
```

Inspect the matrix without compiling anything — nine shapes through three
vertex variants, capped and uncapped:

```python
from vcti.shader.foundry import build_pipelines

for pipeline in build_pipelines():
    print(pipeline.id, [t.semantic for t in pipeline.tables])
# deform3.symtensor ['mask', 'transform', 'material']
# deform3.symtensor.capped ['mask', 'transform', 'material']
# pick ['mask', 'transform']
```

## Dependencies

`vcti-shader-compiler`, `vcti-shader-base`, the nine feature packages
(`vcti-shader-mask`, `-deform`, `-transform`, `-derive`, `-fringe`, `-clip`, `-cap`,
`-pick`, `-material`), plus `vcti-derived`. The shader toolchain executables
(`slangc`, `spirv-cross`, `glslang`) are external, not pip dependencies.
Nothing here needs a GL context: `moderngl` lives in the `gl` extra, for the
tests that prove each emitted pair links, binds and draws what its contract
says; `pip install "vcti-shader-foundry[gl]"` pulls it in on a machine that has
a GL stack.

## Documentation

| If you want to… | Read |
|---|---|
| Understand the system design and decisions | [docs/design.md](docs/design.md) |
| See which pipelines are emitted and why | [docs/pipeline-matrix.md](docs/pipeline-matrix.md) |
| See what features expect of each other, and where they disagree | [docs/composition-expectations.md](docs/composition-expectations.md) |
| Add a new shader feature | [docs/extending.md](docs/extending.md) |
| See practical build workflows | [docs/patterns.md](docs/patterns.md) |
| Navigate and modify the builder source | [docs/source-guide.md](docs/source-guide.md) |
| Look up a specific function or type | [docs/api.md](docs/api.md) |
