Skip to main content

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,
  • and what the attachment it writes into has to be.

Writing that down is what this package is for.

A shader feature is one piece of composable shading math. Here are some examples:

  • deform moves geometry,
  • fringe colors it by bands,
  • derive computes a quantity from a source field — scalar, vector, 6-DOF or tensor,
  • mask culls 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, with StageRole: 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.1.0

In pyproject.toml dependencies

dependencies = [
    "vcti-shader-base>=2.1.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"),)
targets = (OutputSpec("pickTarget", "uvec4", format="rgba32ui"),)

format says what the attachment has to be, in the same spelling TableSpec uses. It is optional, and omitting it is a claim rather than a gap: no exact format required, which is what a colour written to the default framebuffer means. Not any attachment will do — type already demands a matching numeric category, and a vec4 output against an integer attachment is rejected outright. What format adds is the channel count and the bit depth, which is the half that fails quietly: a uvec4 output says nothing about bit depth, so an rgba8ui attachment satisfies the type and truncates every value written.

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.",
)
  • role is where the feature's math runs: VERTEX per vertex, before rasterization; FRAGMENT per fragment, after it. It says where and not what — a feature in the fragment stage may write the shader's output or may compose with the one that does.
  • capabilities are 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_modules names the Slang modules this feature publishes for a shader to import. slang_dir says where they live — and it is the field with teeth: the .slang files 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 an import search 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, format=None A fragment output; format constrains the attachment, None means it does not
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.1.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-base 2.1.0
File Size Uploaded Provenance Actions
vcti_shader_base-2.1.0.tar.gz 27.7 kB With provenance Details for vcti_shader_base-2.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for vcti-shader-base 2.1.0
File Interpreter ABI Platform Actions
vcti_shader_base-2.1.0-py3-none-any.whl Python 3 none any Details for vcti_shader_base-2.1.0-py3-none-any.whl

Total release size: 41.5 kB

Release files / vcti_shader_base-2.1.0.tar.gz

Download URL vcti_shader_base-2.1.0.tar.gz
Size 27.7 kB
Tags Source
SHA-256 checksum
How to use checksums
fe8dafa4167f6793c7aad93fad1ba3451658e01fe96a1116da815190bd55f997
BLAKE2b-256 checksum
How to use checksums
3e1086139adaf65f5be17b3eb8354f902071141d606c0f5cbb5ddd5d47eba0a7
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 17, 2026.

Transparency log

Release files / vcti_shader_base-2.1.0-py3-none-any.whl

Download URL vcti_shader_base-2.1.0-py3-none-any.whl
Size 13.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bcf5555ec29b940777956a0f22c9b941e6a4702a623e41af62a05f6c1a12421f
BLAKE2b-256 checksum
How to use checksums
1b22619c1fb0b06d3c28b6f91df889c58132d60d972902b68874af610c684fcf
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 17, 2026.

Transparency log

Security for vcti-shader-base 2.1.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_base-2.1.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 17, 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

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