vcti-shader-mask

The mask shader feature: the vertex-stage cull that draws only the submeshes a client-owned mask marks.

Overview

A viewer needs to hide and show components of a mesh while the user works — and in a results viewer, to hide an element set the solver reported on, which is finer than a component. Rebuilding geometry for each of those is slow and gets slower as the model grows, so this feature does it differently: the mesh is divided once into submeshes — any subsets the client wants to address as units — every vertex carries the id of the one it belongs to, and the client keeps a mask of one byte per submesh, zero for hidden and one for drawn. The shader fetches each vertex's byte and collapses the vertex outside the clip volume when it is zero.

Hiding any scattered set of submeshes is then one texture write. No geometry is rebuilt, no buffer repacked, and the cost does not depend on how the affected submeshes are scattered through the mesh.

Which id the mask is indexed by, and what the mask means, are the client's choices per pass. A normal pass binds the visibility mask. A selection-outline pass binds the selection mask to the same shader and draws only the selected submeshes into an outline target. An isolate mode binds a third. The feature culls; the renderer composes passes.

vcti-shader-mask is the shader half of that arrangement. It ships the Slang that addresses the mask and applies its rule, a Python mirror of the same rule so a caller can build a mask and read one back, the specs saying what the cull needs bound, and the ShaderDefinition saying what the feature is.

Everything here is a declaration or fixed shader source. Nothing compiles or runs a shader; a build step does that, using what this package declares.

Installation

pip install vcti-shader-mask

Requires Python 3.12, 3.13, or 3.14, matching vcti-shader-base. Nothing native is built on that path, and nothing native is built by [test] either — only the [gl] extra pulls a GL binding, and only on 3.14 does that compile from source for want of a cp314 wheel.

In requirements.txt

vcti-shader-mask>=1.0.0

In pyproject.toml dependencies

dependencies = [
    "vcti-shader-mask>=1.0.0",
]

Quick Start

Build a mask

The client owns the mask, so building it is the first thing a caller does. One value per submesh, in id order:

from vcti.shader.mask import DRAWN, HIDDEN, pack_mask

visible = pack_mask([True, True, False, True])
assert visible == (DRAWN, DRAWN, HIDDEN, DRAWN) == (1, 1, 0, 1)

The shader's rule is an integer compared with zero, and the Python mirror is the same rule — any non-zero value draws, so a client that writes 255 is not wrong:

from vcti.shader.mask import is_drawn

assert not is_drawn(0)
assert is_drawn(1) and is_drawn(255)

A value a byte cannot hold is refused rather than truncated, because 256 would upload as 0 and hide a submesh the caller meant to draw:

from vcti.shader.mask import check_value

check_value(255)
try:
    check_value(256)
except ValueError as error:
    assert "outside 0-255" in str(error)

Upload it

The mask is an R8UI texture, one texel per submesh, with NEAREST filtering. The id is the address; there is no stride. The texture is two-dimensional, because a single row would cap the submesh count at whatever MAX_TEXTURE_SIZE a device reports; wrapped across rows, the cap is that number squared. A caller picks a width and the address wraps:

from vcti.shader.mask import rows_needed, texel

assert texel(14_000, 2048) == (1712, 6)
assert rows_needed(50_000, 2048) == 25

Both refuse a width that is not positive, and a negative id or count. The shader divides by the same width, so a bad value would otherwise surface on the GPU as a wrong texel with nothing to say so:

try:
    texel(0, 0)
except ValueError as error:
    assert "not positive" in str(error)

Pass the width as u_maskLutWidth. An unwritten or incomplete texture reads as zero and hides everything, which is the loud failure this design chooses over a quiet one.

What a build step binds

from vcti.shader.mask import vertex_attributes, vertex_uniforms

(attribute,) = vertex_attributes()
assert (attribute.name, attribute.type, attribute.semantic) == ("a_maskId", "int", "mask-id")

(uniform,) = vertex_uniforms()
assert uniform.name == "u_maskLutWidth"

The attribute is named for the feature, not for what the id counts. The client binds whichever id buffer it likes to it — a submesh id, a mesh-component id — and where another feature is keyed by the same id, binds the same buffer to that feature's attribute too.

The table sampler itself is not in there — a texture input cannot yet be expressed in vcti-shader-base, so it is contract rather than spec. See docs/design.md.

Select a pipeline

One tag for the behaviour and one naming the table encoding:

from vcti.shader.mask import DEFINITION

assert DEFINITION.id == "mask"
assert DEFINITION.role.value == "vertex"
assert set(DEFINITION.capabilities) == {"mask", "mask-lut-r8ui"}
assert DEFINITION.slang_modules == ("mask.slang", "mask_r8ui.slang")

The mask

One byte per submesh — not a bit, not a word — and no stride. A second per-submesh state — a selection, an isolate set — is a second mask of the same shape bound in a different pass, never a second bit here.

API surface

Dependencies

vcti-shader-base is the only runtime dependency — declaring a feature is pure data. vcti-shader-compiler>=4.0.0 and numpy are test-only, and a separate gl extra adds the GL binding the shader tests need to execute rather than skip.

Documentation

The full API reference is generated from the source docstrings and published in the unified VCollab docs.