vcti-shader-scenarios
Run a shader pipeline on inputs you supply, and check that what it produced is what it should produce.
Overview
vcti-shader-foundry composes and emits the shader artifact set, and proves
each pipeline compiles, links and rasterizes. What it cannot say is whether
this pipeline, given these attributes and these uniforms, still produces
the image it produced yesterday. This package answers that.
A scenario declares a run — a pipeline id, the attribute arrays, the uniform values — and validates itself against the pipeline's own contract, so a missing attribute or a mis-shaped buffer is a message rather than a garbled picture. A runner owns one GL context and compiles each pipeline once, so a matrix of a hundred scenarios costs one context and fifteen compiles. The result is a float32 framebuffer plus a record of what produced it: the shaders, the toolchain, this package's own version, and the GL driver.
Two ways to use it. Declare scenarios in tests and compare the framebuffer with numpy — that is the regression matrix. Or run one from a terminal and look at the output — that is the debugging path, where the expectation is the thing in doubt.
Installation
pip install vcti-shader-scenarios # declare and validate scenarios
pip install "vcti-shader-scenarios[gl]" # and run them
GL is an extra rather than a dependency: building and checking a scenario needs
no context. The shader compilers (slangc, spirv-cross, glslang) are
external and pinned — discovered via SLANG_DIR / SPIRV_CROSS_DIR /
GLSLANG_DIR or PATH.
Quick Start
Declare a scenario, run it, and assert on the result:
from vcti.shader.scenarios import (
Runner, Scenario, assert_close, cartesian_grid, demo_style,
diagonal_ramp, pipeline_contract,
)
positions, indices = cartesian_grid(32)
scenario = Scenario(
pipeline="scalar.fringe-float",
attributes={"a_position": positions, "a_result0": diagonal_ramp(positions)},
uniforms=demo_style().uniforms(pipeline_contract("scalar.fringe-float")),
indices=indices,
size=(128, 128),
)
with Runner() as runner:
result = runner.run(scenario)
# The demo colormap runs blue -> red along the diagonal, so the corners are the
# ends of the ramp. This pins the colour lookup and the image orientation.
assert_close(result.framebuffer[-1, 0, 2], 1.0, atol=1e-3) # blue end
assert_close(result.framebuffer[0, -1, 0], 1.0, atol=1e-3) # red end
One runner serves a whole matrix — in pytest, make it a session-scoped fixture:
@pytest.fixture(scope="session")
def runner():
with Runner() as instance:
yield instance
@pytest.mark.parametrize("pipeline", pipeline_ids())
def test_every_pipeline_draws(runner, pipeline):
result = runner.run(scenario_for(pipeline))
assert len(np.unique(result.framebuffer.reshape(-1, 4), axis=0)) > 1
From a terminal, to look at one rather than assert on it:
$ shader-scenarios pipelines
$ shader-scenarios run tests.scenarios:SCALAR_RAMP -o out.png
$ shader-scenarios run --pipeline scalar.fringe-float \
--attributes vertices.npz --indices tris.npy --uniforms style.toml \
--size 256x256 -o out.npz
The extension decides the format: .png to look at, .npy for the float
framebuffer, .npz for the framebuffer and its provenance together.
Key API
Scenario |
a pipeline, its attributes, uniforms, indices and size — validated on construction |
Runner |
one GL context and one compile cache; run(scenario) -> RunResult |
RunResult |
.framebuffer (float32, read-only) and .provenance |
assert_close |
comparison with a tolerance, and a failure message worth reading |
cartesian_grid, diagonal_ramp |
test geometry and a demo field |
demo_style, FringeStyle |
a colormap, packed into a pipeline's uniforms |
quantise, to_png |
float framebuffer to 8-bit, and to PNG bytes |
pipeline_ids, pipeline_contract |
what can be run, and what it needs |
A scenario may pin what it was built against — expected_contract_sha256 for
compatibility, expected_stage_sha256 for the exact emitted GLSL — and the
runner refuses rather than quietly exercising different shader code.
Dependencies
vcti-shader-foundry (the pipeline matrix and the composed Slang),
vcti-shader-compiler, vcti-shader-fringe (the band model a style is built
from), and numpy. moderngl comes with the gl extra. The shader toolchain
executables are external, not pip dependencies.
Documentation
| If you want to… | Read |
|---|---|
| Get started | Quick Start above |
| Write scenarios for real work | docs/patterns.md |
| Understand the design and its boundaries | docs/design.md |
| Navigate and modify the source | docs/source-guide.md |
| Add a pipeline type, a style, or a scenario | docs/extending.md |
| Look up a specific function or type | docs/api.md |
Metadata
Release files for vcti-shader-scenarios 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| vcti_shader_scenarios-1.0.0.tar.gz | 66.5 kB | With provenance | Details for vcti_shader_scenarios-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcti_shader_scenarios-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for vcti_shader_scenarios-1.0.0-py3-none-any.whl |
Total release size: 106.9 kB
Release files / vcti_shader_scenarios-1.0.0.tar.gz
| Download URL | vcti_shader_scenarios-1.0.0.tar.gz |
|---|---|
| Size | 66.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fe8bd1e221df08c055cc17ee8dba3002294620b86ff8e4fe8e2162af5e5d7fa4
|
|
BLAKE2b-256 checksum How to use checksums |
5245e22cc5775672c25af4042015cb05aae7ab82527a7cc7ddade7bc2c53dec4
|
| 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 13, 2026.
Transparency logRelease files / vcti_shader_scenarios-1.0.0-py3-none-any.whl
| Download URL | vcti_shader_scenarios-1.0.0-py3-none-any.whl |
|---|---|
| Size | 40.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ca0e49903db1f9c9c3d8556e3a6fdfd492bbc3397f12c52050fa752863446096
|
|
BLAKE2b-256 checksum How to use checksums |
9ecdf69a4ed6fb3047f1d354ad9f3f5abf82e356b170302a45e146e06e3732af
|
| 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 13, 2026.
Transparency logSecurity for vcti-shader-scenarios 1.0.0
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.
Attestation for vcti_shader_scenarios-1.0.0.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 13, 2026.
Transparency logA 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.