vcti-shader-base 1.0.0__tar.gz

vcti_shader_base-1.0.0/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_shader_base-1.0.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: vcti-shader-base
+Version: 1.0.0
+Summary: The vocabulary a shader feature declares itself with: attribute/uniform/output specs and the ShaderDefinition record. Zero dependencies.
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Repository, https://github.com/vcollab/vcti-python-shader-base
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-shader-base/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
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# vcti-shader-base
+
+The vocabulary a shader feature declares itself with: attribute/uniform/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.
+
+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,
+- `atom-lut` culls hidden atoms.
+
+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), `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
+
+```bash
+pip install vcti-shader-base
+```
+
+Requires Python 3.12, 3.13, or 3.14. No runtime dependencies.
+
+### In `requirements.txt`
+
+```
+vcti-shader-base>=1.0.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-shader-base>=1.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**:
+
+```python
+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:
+
+```python
+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:
+
+```python
+mode = UniformSpec("u_deformMode", "int", named_values={"displacement": 0, "rotation": 1})
+mode.named_values["rotation"]      # 1 — the value to write
+```
+
+A feature in the fragment stage also declares what it writes:
+
+```python
+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`:
+
+```python
+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` moves geometry;
+  `FRAGMENT` decides color.
+- **`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 |
+| `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](docs/patterns.md) |
+| Understand what these types describe and why | [docs/design.md](docs/design.md) |
+| Navigate or modify the source | [docs/source-guide.md](docs/source-guide.md) |

vcti_shader_base-1.0.0/README.md

@@ -0,0 +1,181 @@
+# vcti-shader-base
+
+The vocabulary a shader feature declares itself with: attribute/uniform/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.
+
+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,
+- `atom-lut` culls hidden atoms.
+
+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), `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
+
+```bash
+pip install vcti-shader-base
+```
+
+Requires Python 3.12, 3.13, or 3.14. No runtime dependencies.
+
+### In `requirements.txt`
+
+```
+vcti-shader-base>=1.0.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-shader-base>=1.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**:
+
+```python
+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:
+
+```python
+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:
+
+```python
+mode = UniformSpec("u_deformMode", "int", named_values={"displacement": 0, "rotation": 1})
+mode.named_values["rotation"]      # 1 — the value to write
+```
+
+A feature in the fragment stage also declares what it writes:
+
+```python
+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`:
+
+```python
+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` moves geometry;
+  `FRAGMENT` decides color.
+- **`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 |
+| `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](docs/patterns.md) |
+| Understand what these types describe and why | [docs/design.md](docs/design.md) |
+| Navigate or modify the source | [docs/source-guide.md](docs/source-guide.md) |

vcti_shader_base-1.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=77.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vcti-shader-base"
+version = "1.0.0"
+description = "The vocabulary a shader feature declares itself with: attribute/uniform/output specs and the ShaderDefinition record. Zero dependencies."
+readme = "README.md"
+authors = [
+    {name = "Visual Collaboration Technologies Inc."}
+]
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+classifiers = [
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+requires-python = ">=3.12,<3.15"
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/vcollab/vcti-python-shader-base"
+Changelog = "https://github.com/vcollab/vcti-python-shader-base/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["vcti.shader.base", "vcti.shader.base.*"]
+
+[tool.setuptools.package-data]
+"vcti.shader.base" = ["py.typed"]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-cov"]
+lint = ["ruff"]
+typecheck = ["mypy"]
+
+[tool.pytest.ini_options]
+addopts = "--cov=vcti.shader.base --cov-report=term-missing --cov-fail-under=95"
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src"]
+namespace_packages = true
+explicit_package_bases = true
+mypy_path = ["src"]
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_also = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "if __name__ == .__main__.:",
+    "@(abc\\.)?abstractmethod",
+    "\\.\\.\\.",
+]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]

vcti_shader_base-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vcti_shader_base-1.0.0/src/vcti/shader/base/__init__.py

@@ -0,0 +1,27 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.shader.base — the vocabulary a shader feature declares itself with.
+
+The field specs a feature declares — :class:`AttributeSpec`, :class:`UniformSpec`,
+:class:`OutputSpec` — and the :class:`ShaderDefinition` record (with
+:class:`StageRole`) by which a feature names its stage, Slang modules, and
+capability tags. Types, not behavior, and zero runtime dependencies: a
+shader feature (deform, fringe, derive, atom-lut, …) declares itself against this
+alone, with nothing about how shaders are built in view. See ``docs/design.md``.
+"""
+
+from importlib.metadata import version
+
+from .definition import ShaderDefinition, StageRole
+from .specs import AttributeSpec, OutputSpec, UniformSpec
+
+__version__ = version("vcti-shader-base")
+
+__all__ = [
+    "AttributeSpec",
+    "OutputSpec",
+    "ShaderDefinition",
+    "StageRole",
+    "UniformSpec",
+    "__version__",
+]

vcti_shader_base-1.0.0/src/vcti/shader/base/definition.py

@@ -0,0 +1,60 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""The shader-feature definition: how one feature declares what it is.
+
+A **shader feature** — fringe, deform, derive, atom-lut, and any future one — is
+one piece of composable shading math, shipped as its own installable package. Each
+declares a single :class:`ShaderDefinition` naming the stage its math runs in, the
+Slang modules it ships, and the capability tags it offers. This is the pure-data
+record a feature constructs and exports as ``DEFINITION``, so a feature declares
+itself against this package alone.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+
+
+class StageRole(StrEnum):
+    """Which of the two shader stages a feature's math runs in.
+
+    The values are a serialization contract: they reach build artifacts and the
+    consumers that read them back, so renaming a member is source-compatible but
+    changing a value is a breaking change.
+    """
+
+    VERTEX = "vertex"  # transforms gl_Position (deform, atom-lut)
+    FRAGMENT = "fragment"  # produces the fragment output (derive, fringe)
+
+
+@dataclass(frozen=True)
+class ShaderDefinition:
+    """One shader feature: identity, stage, capability tags, and Slang modules.
+
+    ``id`` names the feature for logs and diagnostics. ``capabilities`` are the
+    (open) tag strings this feature offers; nothing here interprets them, which is
+    why they are plain strings and not a closed enum — introducing a tag needs no
+    release of this package.
+
+    ``slang_modules`` names the Slang modules this feature publishes for a shader
+    to import; ``slang_dir`` is the directory holding them. A build step adds that
+    directory to the compiler's ``import`` search path so a shader can resolve
+    modules living inside a feature's own installed package — which is also why
+    only the feature can supply it. The path is only recorded here: this package
+    never opens or resolves it, so a directory that does not exist is accepted
+    without complaint, and checking that the modules are really shipped is a
+    feature's own test's job.
+
+    ``description`` is the only defaulted field, which fixes the argument order:
+    a new required field must go before it, or the class raises ``TypeError`` at
+    import for a non-default argument following a default one.
+    """
+
+    id: str
+    role: StageRole
+    capabilities: tuple[str, ...]
+    slang_modules: tuple[str, ...]
+    slang_dir: Path
+    description: str = ""

vcti_shader_base-1.0.0/src/vcti/shader/base/specs.py

@@ -0,0 +1,86 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""The field specs a shader feature declares: attributes, uniforms, and outputs.
+
+A shader feature describes the shading math it contributes as a set of per-vertex
+inputs (:class:`AttributeSpec`), draw-constant values (:class:`UniformSpec`), and
+fragment outputs (:class:`OutputSpec`). These are pure data types with no
+behavior beyond describing a shape; nothing here validates a GLSL type name, an
+array length, or a semantic, because a feature declares its specs in isolation —
+before any complete shader exists — so a check that needs to see more than one
+feature cannot be answered here.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class AttributeSpec:
+    """A vertex attribute input: name, GLSL type, and its data semantic.
+
+    ``name`` is the attribute's identifier in the shader source; ``semantic``
+    names what the data *is* (``coordinates``, ``deformation``, ``result.0``), so
+    a caller knows which of its own buffers belongs here. The semantic vocabulary
+    belongs to the features — nothing here interprets the string.
+    """
+
+    name: str
+    type: str
+    semantic: str
+
+
+@dataclass(frozen=True)
+class UniformSpec:
+    """A uniform: name, base GLSL type, optional array length and named values.
+
+    ``array_length`` is held as a number rather than baked into ``type`` so Python
+    can size a buffer or check that a value fits; :attr:`gl_type` joins the two
+    only where the type is emitted. ``named_values`` is the name-to-number map of a
+    *dispatch* uniform — an ``int`` selecting a branch inside the shader — so a
+    caller can write the value by name instead of hard-coding it. It is ``None`` on
+    every other uniform.
+    """
+
+    name: str
+    type: str
+    array_length: int | None = None
+    named_values: Mapping[str, int] | None = None
+
+    @property
+    def gl_type(self) -> str:
+        """The declared type, with an array suffix when the uniform is an array."""
+        if self.array_length is None:
+            return self.type
+        return f"{self.type}[{self.array_length}]"
+
+    def __hash__(self) -> int:
+        """Hash by value, folding ``named_values`` into a hashable form.
+
+        ``frozen=True`` promises hashability, but the generated ``__hash__``
+        hashes the fields as-is and ``named_values`` holds a mapping — so a uniform
+        that declares one raised ``TypeError`` the moment anything put it in a set,
+        de-duplicated a group of specs, or used one as a dict key. The field stays a
+        ``Mapping`` (callers pass plain dicts); only the hash normalizes, sorted so
+        that two equal maps written in different orders hash alike.
+
+        A field added to this class must be added here too, or two different
+        uniforms collide in a set; the tests pin the field list so the omission
+        fails rather than passing silently.
+        """
+        values = None if self.named_values is None else tuple(sorted(self.named_values.items()))
+        return hash((self.name, self.type, self.array_length, values))
+
+
+@dataclass(frozen=True)
+class OutputSpec:
+    """A fragment output: name and GLSL type.
+
+    Separate from :class:`AttributeSpec` because it carries no semantic: there is
+    nothing for a caller to bind, only a result the shader writes.
+    """
+
+    name: str
+    type: str

vcti_shader_base-1.0.0/src/vcti_shader_base.egg-info/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: vcti-shader-base
+Version: 1.0.0
+Summary: The vocabulary a shader feature declares itself with: attribute/uniform/output specs and the ShaderDefinition record. Zero dependencies.
+Author: Visual Collaboration Technologies Inc.
+License-Expression: LicenseRef-Proprietary
+Project-URL: Repository, https://github.com/vcollab/vcti-python-shader-base
+Project-URL: Changelog, https://github.com/vcollab/vcti-python-shader-base/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
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Dynamic: license-file
+
+# vcti-shader-base
+
+The vocabulary a shader feature declares itself with: attribute/uniform/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.
+
+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,
+- `atom-lut` culls hidden atoms.
+
+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), `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
+
+```bash
+pip install vcti-shader-base
+```
+
+Requires Python 3.12, 3.13, or 3.14. No runtime dependencies.
+
+### In `requirements.txt`
+
+```
+vcti-shader-base>=1.0.0
+```
+
+### In `pyproject.toml` dependencies
+
+```toml
+dependencies = [
+    "vcti-shader-base>=1.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**:
+
+```python
+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:
+
+```python
+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:
+
+```python
+mode = UniformSpec("u_deformMode", "int", named_values={"displacement": 0, "rotation": 1})
+mode.named_values["rotation"]      # 1 — the value to write
+```
+
+A feature in the fragment stage also declares what it writes:
+
+```python
+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`:
+
+```python
+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` moves geometry;
+  `FRAGMENT` decides color.
+- **`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 |
+| `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](docs/patterns.md) |
+| Understand what these types describe and why | [docs/design.md](docs/design.md) |
+| Navigate or modify the source | [docs/source-guide.md](docs/source-guide.md) |

vcti_shader_base-1.0.0/src/vcti_shader_base.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/vcti/shader/base/__init__.py
+src/vcti/shader/base/definition.py
+src/vcti/shader/base/py.typed
+src/vcti/shader/base/specs.py
+src/vcti_shader_base.egg-info/PKG-INFO
+src/vcti_shader_base.egg-info/SOURCES.txt
+src/vcti_shader_base.egg-info/dependency_links.txt
+src/vcti_shader_base.egg-info/requires.txt
+src/vcti_shader_base.egg-info/top_level.txt
+tests/test_definition.py
+tests/test_specs.py
+tests/test_version.py

vcti_shader_base-1.0.0/src/vcti_shader_base.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vcti_shader_base-1.0.0/src/vcti_shader_base.egg-info/requires.txt

@@ -0,0 +1,10 @@
+
+[lint]
+ruff
+
+[test]
+pytest
+pytest-cov
+
+[typecheck]
+mypy

vcti_shader_base-1.0.0/src/vcti_shader_base.egg-info/top_level.txt

@@ -0,0 +1 @@
+vcti

vcti_shader_base-1.0.0/tests/test_definition.py

@@ -0,0 +1,78 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for the ShaderDefinition record and its stage-role enum."""
+
+import dataclasses
+from pathlib import Path
+
+import pytest
+
+from vcti.shader.base import ShaderDefinition, StageRole
+
+
+class TestStageRole:
+    # The values are serialized, so they are pinned individually, not as a set.
+    def test_values(self):
+        assert StageRole.VERTEX == "vertex"
+        assert StageRole.FRAGMENT == "fragment"
+
+    def test_members(self):
+        assert list(StageRole) == [StageRole.VERTEX, StageRole.FRAGMENT]
+
+
+class TestShaderDefinition:
+    def test_declares_a_feature(self):
+        definition = ShaderDefinition(
+            id="fringe",
+            role=StageRole.FRAGMENT,
+            capabilities=("fringe",),
+            slang_modules=("colormap.slang",),
+            slang_dir=Path("slang"),
+            description="Band-list fringe colormap.",
+        )
+        assert definition.id == "fringe"
+        assert definition.role is StageRole.FRAGMENT
+        assert definition.capabilities == ("fringe",)
+        assert definition.slang_modules == ("colormap.slang",)
+        assert definition.slang_dir == Path("slang")
+        assert definition.description == "Band-list fringe colormap."
+
+    def test_description_defaults_empty(self):
+        definition = ShaderDefinition(
+            "deform",
+            StageRole.VERTEX,
+            ("deform3",),
+            ("deform.slang",),
+            Path("."),
+        )
+        assert definition.description == ""
+
+    def test_description_stays_the_last_field(self):
+        # It is the only defaulted field, so a new required field placed after it
+        # raises TypeError when the class is created — at import.
+        assert [field.name for field in dataclasses.fields(ShaderDefinition)][-1] == "description"
+
+    def test_frozen(self):
+        definition = ShaderDefinition(
+            "deform",
+            StageRole.VERTEX,
+            ("deform3",),
+            ("deform.slang",),
+            Path("."),
+        )
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            definition.id = "other"  # type: ignore[misc]
+
+    def test_hashable_and_compared_by_value(self):
+        # A builder collects definitions into a set and de-duplicates slang_dirs.
+        def make():
+            return ShaderDefinition(
+                "deform",
+                StageRole.VERTEX,
+                ("deform3", "deform6"),
+                ("deform.slang",),
+                Path("slang"),
+            )
+
+        assert make() == make()
+        assert len({make(), make()}) == 1

vcti_shader_base-1.0.0/tests/test_specs.py

@@ -0,0 +1,98 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Tests for the field spec types."""
+
+import dataclasses
+
+import pytest
+
+from vcti.shader.base import AttributeSpec, OutputSpec, UniformSpec
+
+
+class TestUniformSpec:
+    def test_gl_type_plain(self):
+        assert UniformSpec("u_scale", "float").gl_type == "float"
+
+    def test_gl_type_array(self):
+        assert UniformSpec("u_bandBounds", "vec2", array_length=72).gl_type == "vec2[72]"
+
+    def test_named_values_is_optional(self):
+        assert UniformSpec("u_x", "int").named_values is None
+        assert UniformSpec("u_mode", "int", named_values={"a": 0}).named_values == {"a": 0}
+
+    def test_hashable_without_named_values(self):
+        spec = UniformSpec("u_scale", "float")
+        assert spec in {spec}
+
+    def test_hashable_with_named_values(self):
+        # A dispatch uniform holds a dict; it must still go in a set.
+        spec = UniformSpec("u_mode", "int", named_values={"a": 0, "b": 1})
+        assert spec in {spec}
+
+    def test_equal_named_values_hash_alike_regardless_of_order(self):
+        a = UniformSpec("u_mode", "int", named_values={"a": 0, "b": 1})
+        b = UniformSpec("u_mode", "int", named_values={"b": 1, "a": 0})
+        assert a == b
+        assert hash(a) == hash(b)
+
+    def test_differing_named_values_do_not_collide(self):
+        a = UniformSpec("u_mode", "int", named_values={"a": 0})
+        b = UniformSpec("u_mode", "int", named_values={"a": 1})
+        assert a != b
+        assert len({a, b}) == 2
+
+    def test_hash_covers_every_field(self):
+        # __hash__ is hand-written, so a new field is silently left out of it and
+        # two different uniforms start colliding in a set. The field list is pinned
+        # here so adding one fails until __hash__ is extended to match.
+        assert [field.name for field in dataclasses.fields(UniformSpec)] == [
+            "name",
+            "type",
+            "array_length",
+            "named_values",
+        ]
+
+    def test_array_length_is_part_of_identity(self):
+        assert UniformSpec("u_bands", "vec2", array_length=8) != UniformSpec(
+            "u_bands", "vec2", array_length=16
+        )
+
+    def test_frozen(self):
+        spec = UniformSpec("u_scale", "float")
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            spec.name = "x"  # type: ignore[misc]
+
+
+class TestAttributeSpec:
+    def test_carries_the_semantic(self):
+        attr = AttributeSpec("a_position", "vec3", "coordinates")
+        assert (attr.name, attr.type, attr.semantic) == ("a_position", "vec3", "coordinates")
+
+    def test_semantic_is_part_of_identity(self):
+        # The name is a shader-source detail; the semantic names the data, so two
+        # attributes differing only in semantic are different declarations.
+        a = AttributeSpec("a_result0", "vec3", "result.0")
+        b = AttributeSpec("a_result0", "vec3", "result.1")
+        assert a != b
+        assert len({a, b}) == 2
+
+    def test_frozen(self):
+        attr = AttributeSpec("a_position", "vec3", "coordinates")
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            attr.name = "x"  # type: ignore[misc]
+
+
+class TestOutputSpec:
+    def test_fields(self):
+        out = OutputSpec("fragColor", "vec4")
+        assert out.name == "fragColor"
+        assert out.type == "vec4"
+
+    def test_hashable_and_compared_by_value(self):
+        assert OutputSpec("fragColor", "vec4") == OutputSpec("fragColor", "vec4")
+        assert len({OutputSpec("fragColor", "vec4"), OutputSpec("fragColor", "vec4")}) == 1
+
+    def test_frozen(self):
+        out = OutputSpec("fragColor", "vec4")
+        with pytest.raises(dataclasses.FrozenInstanceError):
+            out.type = "vec3"  # type: ignore[misc]

vcti_shader_base-1.0.0/tests/test_version.py

@@ -0,0 +1,32 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Version and public-surface tests for vcti-shader-base."""
+
+import re
+
+import vcti.shader.base
+
+
+class TestVersion:
+    def test_version_exists(self):
+        assert hasattr(vcti.shader.base, "__version__")
+
+    def test_version_is_valid_semver(self):
+        assert re.match(r"^\d+\.\d+\.\d+", vcti.shader.base.__version__)
+
+
+class TestPublicSurface:
+    def test_all_is_the_documented_vocabulary(self):
+        # The package is a vocabulary: what it exports *is* its contract.
+        assert vcti.shader.base.__all__ == [
+            "AttributeSpec",
+            "OutputSpec",
+            "ShaderDefinition",
+            "StageRole",
+            "UniformSpec",
+            "__version__",
+        ]
+
+    def test_every_name_in_all_is_importable(self):
+        for name in vcti.shader.base.__all__:
+            assert hasattr(vcti.shader.base, name), name