Skip to main content

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)

Source distribution for vcti-shader-scenarios 1.0.0
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)

Table of built distributions (wheels) for vcti-shader-scenarios 1.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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 log

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

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page