Skip to main content

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)

Source distribution for vcti-shader-pick 2.0.0
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)

Table of built distributions (wheels) for vcti-shader-pick 2.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

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

Select from 2 files

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