vcti-shader-pick
The pick shader feature: the fragment-stage pass that writes identifiers for the geometry at each pixel.
Overview
A viewer has to answer "what did the user just click on", and the only thing that knows which surface covers which pixel is the rasterizer. So the answer is produced the same way the picture is: by drawing. A pick pass renders the scene to an integer target and writes, at every pixel, identifiers for the geometry that landed there — plus how far away it was.
Reading one texel back then answers the click. What that identifier means is not this package's business: it is opaque, resolved by whoever minted it. That is what lets the same pass serve an element, a face, a triangle, or something not yet invented, without changing a line of shader source.
vcti-shader-pick ships the Slang that packs a texel, a Python mirror of the
same layout for decoding a readback, and the ShaderDefinition saying what the
feature is. Everything here is a declaration or fixed shader source; nothing
compiles, runs, or reads back a shader.
Installation
pip install vcti-shader-pick
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-pick>=2.0.0
In pyproject.toml dependencies
dependencies = [
"vcti-shader-pick>=2.0.0",
]
Quick Start
What a build step binds
The feature declares one per-vertex identifier and one integer target. The
identifier must reach the fragment stage as a flat varying — GLSL ES requires
that of every integer varying, and it is what keeps it exact:
from vcti.shader.pick import fragment_inputs, fragment_outputs, fragment_uniforms
inputs = fragment_inputs()
assert [attribute.name for attribute in inputs] == ["a_primitiveId"]
assert inputs[0].semantic == "primitive-id"
assert fragment_outputs()[0].name == "pickTarget"
assert fragment_uniforms() == ()
a_primitiveId stands in for the gl_PrimitiveID that GLSL ES 3.00 does not
have: it is minted where the vertex data is built and baked into the vertices,
because that is the only route to a fragment. It is opaque to everything in the
shader and to this package — whoever mints it owns the table it indexes, so it
can name an element, a face, a triangle, or a tuple of all three.
Reading a click back
The target is four unsigned 32-bit channels. Clear it to PICK_EMPTY before the
pass, and draw the pass depth-tested, unblended and single-sampled — each of
those is the caller's to get right, and each fails silently, which
design.md explains. Then decode the texel under the cursor:
from vcti.shader.pick import PICK_EMPTY, decode, float_to_bits
nothing = decode((PICK_EMPTY, PICK_EMPTY, PICK_EMPTY, PICK_EMPTY))
assert nothing is None
hit = decode((4_210_001, float_to_bits(12.5), 0, 0))
assert hit is not None
assert hit.primitive_id == 4_210_001
assert hit.depth == 12.5
The depth is measured along the camera's forward axis — -z in view space,
positive in front of the camera — not from the eye to the point. Give it the
pixel's ray, and reconstruct_view_position returns the point:
from vcti.shader.pick import reconstruct_view_position
# A perspective ray: the origin is the eye, at the view-space origin.
point = reconstruct_view_position(12.5, (0.0, 0.0, 0.0), (0.3, 0.2, -1.0))
assert point == (3.75, 2.5, -12.5)
# An orthographic ray: parallel, each starting at its own point.
point = reconstruct_view_position(12.5, (2.0, 1.0, -0.1), (0.0, 0.0, -1.0))
assert point == (2.0, 1.0, -12.5)
The ray is yours to build — inverting the projection and knowing which way the
viewport's Y runs are the caller's, because the caller owns the camera. What the
depth means is this package's, which is why the inverse ships here rather than
being a formula every caller re-derives. direction need not be normalized, and
the origin need not sit on the camera plane: a ray unprojected to the near plane
works as given.
A Euclidean distance from the eye would have cost the same channel and been wrong for any ray not starting at a single shared point.
Note that depth is reinterpreted from its bits rather than converted:
from vcti.shader.pick import bits_to_float
assert bits_to_float(float_to_bits(12.5)) == 12.5
assert float_to_bits(1.0) > 1_000_000_000 # the same bits read as an int
Selecting a pipeline
from vcti.shader.pick import DEFINITION
assert DEFINITION.id == "pick"
assert DEFINITION.role.value == "fragment"
assert DEFINITION.capabilities == ("pick",)
The texel
| Channel | Holds |
|---|---|
R |
a_primitiveId |
G |
the view depth, as reinterpreted float32 bits |
B |
reserved, written as zero |
A |
reserved, written as zero |
An integer target rather than a float one because identifiers must survive
exactly: a float32 carries consecutive integers only to 2²⁴, above which one
arrives as its neighbour and resolves to different geometry — a failure that
looks like a mis-click rather than like corruption.
API surface
| Name | What it is |
|---|---|
DEFINITION |
the ShaderDefinition a build step imports to compose this feature |
SLANG_DIR |
the installed Slang directory |
fragment_inputs, fragment_outputs, fragment_uniforms |
what a build step binds |
decode, is_empty, Pick |
read a texel of a pick readback |
bits_to_float, float_to_bits |
the bit reinterpretation, on its own |
reconstruct_view_position |
a ray and a depth to the view-space point |
PICK_EMPTY, PICK_RESERVED, CHANNELS |
the layout, as data |
TARGET_NAME, TARGET_TYPE, TARGET_FORMAT |
the output's name, GLSL type, and the attachment it needs |
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
| If you want to… | Read |
|---|---|
| Get started using the package | Quick Start above |
| Understand the texel contract and the decisions behind it | docs/design.md |
| Navigate or modify the source, including the Slang | docs/source-guide.md |
The full API reference is generated from the source docstrings and published in the unified VCollab docs.
Metadata
Release files for vcti-shader-pick 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_pick-2.0.0.tar.gz | 34.5 kB | With provenance | Details for vcti_shader_pick-2.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| vcti_shader_pick-2.0.0-py3-none-any.whl | Python 3 | none | any | Details for vcti_shader_pick-2.0.0-py3-none-any.whl |
Total release size: 49.0 kB
Release files / vcti_shader_pick-2.0.0.tar.gz
| Download URL | vcti_shader_pick-2.0.0.tar.gz |
|---|---|
| Size | 34.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
29e1f09af7ab54a2c1e88e0392406d08d00311618aeb10b4627cfa4ad70c2dfe
|
|
BLAKE2b-256 checksum How to use checksums |
0bff9dda5510c152ed5ef0a0b0dac2cf3192f4c6242c5d977746dc27236fbcdb
|
| 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 19, 2026.
Transparency logRelease files / vcti_shader_pick-2.0.0-py3-none-any.whl
| Download URL | vcti_shader_pick-2.0.0-py3-none-any.whl |
|---|---|
| Size | 14.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
501a73a35e1b6f66ba3af6301c74db90fd6f7aa839f36992136682f9cb173765
|
|
BLAKE2b-256 checksum How to use checksums |
0c43f0e6a9c50abd8ebb76897c1ccb3f4296617eb184933f92a1963481f87123
|
| 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 19, 2026.
Transparency logSecurity for vcti-shader-pick 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_pick-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 19, 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.