vcti-shader-base
The vocabulary a shader feature declares itself with: attribute/uniform/table/output specs and the ShaderDefinition record. Zero dependencies.
Overview
Shaders in this system are compiled ahead of time.
A build step turns Slang sources into GLSL ES text. Whatever draws with the result later — a web viewer, a test harness — did not compile it and cannot inspect it. So it has to be told what the shader expects:
- which buffer belongs in each vertex attribute,
- which uniforms exist and how large they are,
- which integer selects which mode,
- which lookup table goes in which sampler, and in what format it is uploaded.
Writing that down is what this package is for.
A shader feature is one piece of composable shading math. Here are some examples:
deformmoves geometry,fringecolors it by bands,derivecomputes a quantity from a source field — scalar, vector, 6-DOF or tensor,maskculls the submeshes a client-bound table marks hidden.
Each ships as its own installable package. Each declares what its own math needs, and says what it is.
vcti-shader-base is the vocabulary for writing exactly that declaration, and
nothing more:
- Field specs —
AttributeSpec(per-vertex inputs),UniformSpec(draw-constant values),TableSpec(lookup tables the shader reads),OutputSpec(fragment outputs). - The definition —
ShaderDefinition, withStageRole: how a feature names the stage it runs in, the Slang modules it ships, and the capability tags it introduces.
Declaring a feature needs nothing else — no compiler, no build toolchain, no other package.
Installation
pip install vcti-shader-base
Requires Python 3.12, 3.13, or 3.14. No runtime dependencies.
In requirements.txt
vcti-shader-base>=2.0.0
In pyproject.toml dependencies
dependencies = [
"vcti-shader-base>=2.0.0",
]
Quick Start
Declare what the shading math needs
Consider a structural analysis. A CAE solver reports how far each node of a mesh moves under a load, and we want to draw the deformed shape.
Every vertex carries two values — where it sits, and how far it moved. Both vary per vertex, so both are attributes. We also want to exaggerate the movement, scaling it independently in x, y and z; that factor is the same for every vertex in the draw, so it is a uniform:
from vcti.shader.base import AttributeSpec, UniformSpec
inputs = (
AttributeSpec("a_position", "vec3", "coordinates"),
AttributeSpec("a_deformation", "vec3", "deformation"),
)
uniforms = (UniformSpec("u_deformScale", "vec3"),)
a_position and a_deformation are the names the shader source uses. The
third argument is the semantic, and it is what makes the declaration useful
to a caller. A caller has buffers of its own — node coordinates, a displacement
field — and must know which one goes where. The name cannot answer that: it is a
shader-source detail and can be renamed. The semantic names the data instead, so
coordinates means mesh node positions and deformation means the displacement
vector.
Two optional fields are worth knowing. array_length stays a number so Python
can size a buffer, and gl_type joins it onto the type only where the type is
emitted:
UniformSpec("u_bandColors", "vec4", array_length=8).gl_type # 'vec4[8]'
UniformSpec("u_deformScale", "vec3").gl_type # 'vec3'
named_values turns an integer a caller would otherwise hard-code into something
nameable:
mode = UniformSpec("u_deformMode", "int", named_values={"displacement": 0, "rotation": 1})
mode.named_values["rotation"] # 1 — the value to write
Data with one row per addressable thing — per submesh, per component — is too large and too model-dependent for uniforms, so a feature reads it from a texture and declares that too:
from vcti.shader.base import TableSpec
tables = (TableSpec("u_maskLut", "Texture2D<uint4>", format="r8ui", semantic="mask"),)
type is the declaration as the feature writes it in Slang, not as one target
renders it. format names the texture to upload — a sampler type carries
signedness and dimensions but never channel count or bit depth — and it is
spelled as a GLSL layout qualifier, which is also SPIR-V's image format, because
a sampled texture carries no format in the shader languages at all. It is
therefore nobody's API constant: r8ui is R8UI to GL and r8uint to WebGPU,
and a consumer maps it as it maps vec3. And semantic
matters more here than on an attribute: emitting GLSL ES pairs the texture with
a dummy sampler and names the combination itself, so the declared name is not
what reaches the program, and the semantic is what a caller matches on.
Every texture declared this way is an unfiltered lookup table — read with
texelFetch, filtered NEAREST, no mipmaps. Addressing is the feature's own:
a width to wrap at, a stride, a slot, each an ordinary uniform.
A feature in the fragment stage also declares what it writes:
from vcti.shader.base import OutputSpec
outputs = (OutputSpec("fragColor", "vec4"),)
Describe the feature itself
The specs say what the shading math needs. A ShaderDefinition says what the
feature is. Each feature constructs exactly one and exports it as DEFINITION:
from pathlib import Path
from vcti.shader.base import ShaderDefinition, StageRole
DEFINITION = ShaderDefinition(
id="deform",
role=StageRole.VERTEX,
capabilities=("deform3", "deform6"),
slang_modules=("deform.slang",),
slang_dir=Path(__file__).parent / "slang",
description="deform3 scaled displacement; deform6 Rodrigues rotation.",
)
roleis where the feature's math runs.VERTEXmoves geometry;FRAGMENTdecides color.capabilitiesare the tags this feature offers. They are opaque strings and each feature owns its own, so adding one needs no release of this package.slang_modulesnames the Slang modules this feature publishes for a shader to import.slang_dirsays where they live — and it is the field with teeth: the.slangfiles are installed inside the feature's own package, so only the feature can resolve the directory, and the build passes it to the compiler as animportsearch path. This package only records the path; it never opens it, so confirming the files are really there is the feature's own test's job.
A feature that stops here is complete: it constructs one ShaderDefinition,
exports it as DEFINITION, and declares the specs its math needs.
Type Reference
| Type | Fields | Notes |
|---|---|---|
AttributeSpec |
name, type, semantic |
A per-vertex input, and what its data is |
UniformSpec |
name, type, array_length=None, named_values=None |
gl_type joins the array suffix; named_values only on dispatch uniforms |
TableSpec |
name, type, format, semantic |
An unfiltered lookup table; type is the Slang declaration, format what the client uploads |
OutputSpec |
name, type |
A fragment output; no semantic, since there is nothing to bind |
ShaderDefinition |
id, role, capabilities, slang_modules, slang_dir, description="" |
One feature's self-declaration |
StageRole |
VERTEX, FRAGMENT |
Where the feature's math runs |
Every type is immutable and compared by value, and every one is hashable — so specs can go in a set or a dict key, and duplicates drop out on their own.
Dependencies
None — the standard library covers it. A feature can declare its specs and its definition without installing a compiler or a build toolchain behind it.
Development extras: test (pytest, pytest-cov), lint (ruff), typecheck
(mypy).
Documentation
| If you want to… | Read |
|---|---|
| Get started using the package | Quick Start above |
| Build and ship a complete feature, and avoid the pitfalls | docs/patterns.md |
| Understand what these types describe and why | docs/design.md |
| Navigate or modify the source | docs/source-guide.md |
Metadata
Release files for vcti-shader-base 2.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_base-2.0.0.tar.gz | 25.9 kB | With provenance | Details for vcti_shader_base-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcti_shader_base-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for vcti_shader_base-2.0.0-py3-none-any.whl |
Total release size: 38.6 kB
Release files / vcti_shader_base-2.0.0.tar.gz
| Download URL | vcti_shader_base-2.0.0.tar.gz |
|---|---|
| Size | 25.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dac26223505bfff21b6fe3b0294183c4cc6a5dad57532584dd27364457c9da2e
|
|
BLAKE2b-256 checksum How to use checksums |
9adfb4a1b303e43143b4f40e2e41582f5c14f40c58d8e72319d76b2ad455b23a
|
| 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 16, 2026.
Transparency logRelease files / vcti_shader_base-2.0.0-py3-none-any.whl
| Download URL | vcti_shader_base-2.0.0-py3-none-any.whl |
|---|---|
| Size | 12.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0351f988594ee403fa29d383e63c7a09d9ba0371e18e19c0bd04ed4283e6f0e6
|
|
BLAKE2b-256 checksum How to use checksums |
b8f6c708edf944de0c616961cc7677bf948b8b65b82a959f87dcd65d797a512a
|
| 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 16, 2026.
Transparency logSecurity for vcti-shader-base 2.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_base-2.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 16, 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.