@luma.gl/shadertools 9.3.5 → 9.4.0-alpha.1

package/src/modules/color/float-colors.ts

@@ -2,9 +2,11 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
+import type {Binding} from '@luma.gl/core';
 import {ShaderModule} from '../../lib/shader-module/shader-module';
 
-export type FloatColorsProps = {
+/** Props for semantic color normalization helpers. */
+export type ColorsProps = {
   /**
    * When true, semantic colors are interpreted as 0-255 byte-style values and normalized in shader code.
    * When false, semantic colors are interpreted directly as floats.
@@ -12,61 +14,214 @@ export type FloatColorsProps = {
   useByteColors?: boolean;
 };
 
-export type FloatColorsUniforms = {
+/** Uniforms consumed by semantic color normalization helpers. */
+export type ColorsUniforms = {
   /** Controls whether shader helpers normalize semantic colors from byte space. */
   useByteColors: boolean;
 };
 
-const GLSL_UNIFORMS = /* glsl */ `\
-layout(std140) uniform floatColorsUniforms {
+/** Backward-compatible props alias for shaders that import `floatColors`. */
+export type FloatColorsProps = ColorsProps;
+/** Backward-compatible uniform alias for shaders that import `floatColors`. */
+export type FloatColorsUniforms = ColorsUniforms;
+
+/** Packed storage color formats decoded by `storageColors`. */
+export type StorageColorFormat = 'rgba8unorm' | 'rgba16float' | 'rgba32float';
+
+/** Numeric WGSL tags written to `storageColors.format`. */
+export const STORAGE_COLOR_FORMAT = {
+  RGBA8UNORM: 0,
+  RGBA16FLOAT: 1,
+  RGBA32FLOAT: 2
+} as const;
+
+/** Numeric WGSL tag for one packed storage color format. */
+export type StorageColorFormatValue =
+  (typeof STORAGE_COLOR_FORMAT)[keyof typeof STORAGE_COLOR_FORMAT];
+
+/** Bytes occupied by one tightly packed storage color row. */
+export const STORAGE_COLOR_FORMAT_BYTE_LENGTHS: Record<StorageColorFormat, number> = {
+  rgba8unorm: 4,
+  rgba16float: 8,
+  rgba32float: 16
+};
+
+/** Default byte stride for one tightly packed storage color row. */
+export const STORAGE_COLOR_DEFAULT_BYTE_STRIDES: Record<StorageColorFormat, number> = {
+  ...STORAGE_COLOR_FORMAT_BYTE_LENGTHS
+};
+
+/** Props for reading packed color rows from a read-only storage buffer. */
+export type StorageColorsProps = {
+  /** Storage buffer containing raw packed color words. */
+  colorBuffer?: Binding;
+  /** Per-row storage color representation. Defaults to `rgba8unorm`. */
+  format?: StorageColorFormat | StorageColorFormatValue;
+  /** Byte offset to the first color. Must be 4-byte aligned. Defaults to `0`. */
+  byteOffset?: number;
+  /** Bytes between color rows. Must be 4-byte aligned. Defaults to the packed format size. */
+  byteStride?: number;
+};
+
+/** Uniforms consumed by the packed storage color reader. */
+export type StorageColorsUniforms = {
+  /** Numeric `STORAGE_COLOR_FORMAT` tag used by WGSL. */
+  format: StorageColorFormatValue;
+  /** Uint32 words between storage color rows. */
+  wordStride: number;
+  /** Uint32 word offset to the first storage color row. */
+  wordOffset: number;
+  /** Reserved field retaining a 16-byte uniform block. */
+  _padding: number;
+};
+
+/** Bindings consumed by the packed storage color reader. */
+export type StorageColorsBindings = {
+  /** Raw packed storage color buffer exposed as `array<u32>`. */
+  storageColorsBuffer?: Binding;
+};
+
+const STORAGE_COLOR_FORMAT_BY_NAME: Record<StorageColorFormat, StorageColorFormatValue> = {
+  rgba8unorm: STORAGE_COLOR_FORMAT.RGBA8UNORM,
+  rgba16float: STORAGE_COLOR_FORMAT.RGBA16FLOAT,
+  rgba32float: STORAGE_COLOR_FORMAT.RGBA32FLOAT
+};
+
+const STORAGE_COLOR_FORMAT_NAME_BY_VALUE: Record<StorageColorFormatValue, StorageColorFormat> = {
+  [STORAGE_COLOR_FORMAT.RGBA8UNORM]: 'rgba8unorm',
+  [STORAGE_COLOR_FORMAT.RGBA16FLOAT]: 'rgba16float',
+  [STORAGE_COLOR_FORMAT.RGBA32FLOAT]: 'rgba32float'
+};
+
+const COLORS_UNIFORM_TYPES = {
+  useByteColors: 'f32'
+} as const;
+
+const COLORS_DEFAULT_UNIFORMS = {
+  useByteColors: true
+} as const;
+
+const STORAGE_COLORS_UNIFORM_TYPES = {
+  format: 'u32',
+  wordStride: 'u32',
+  wordOffset: 'u32',
+  _padding: 'u32'
+} as const;
+
+const STORAGE_COLORS_DEFAULT_UNIFORMS = {
+  format: STORAGE_COLOR_FORMAT.RGBA8UNORM,
+  wordStride: STORAGE_COLOR_DEFAULT_BYTE_STRIDES.rgba8unorm / Uint32Array.BYTES_PER_ELEMENT,
+  wordOffset: 0,
+  _padding: 0
+} as const satisfies StorageColorsUniforms;
+
+const COLORS_GLSL = buildGLSLColorModuleSource('colors');
+const FLOAT_COLORS_GLSL = buildGLSLColorModuleSource('floatColors');
+const COLORS_WGSL = buildWGSLColorModuleSource('colors');
+const FLOAT_COLORS_WGSL = buildWGSLColorModuleSource('floatColors');
+
+const STORAGE_COLORS_WGSL = /* wgsl */ `\
+struct storageColorsUniforms {
+  format: u32,
+  wordStride: u32,
+  wordOffset: u32,
+  _padding: u32
+};
+
+@group(0) @binding(auto) var<uniform> storageColors : storageColorsUniforms;
+@group(0) @binding(auto) var<storage, read> storageColorsBuffer : array<u32>;
+
+const STORAGE_COLOR_FORMAT_RGBA8UNORM : u32 = ${STORAGE_COLOR_FORMAT.RGBA8UNORM}u;
+const STORAGE_COLOR_FORMAT_RGBA16FLOAT : u32 = ${STORAGE_COLOR_FORMAT.RGBA16FLOAT}u;
+
+fn storageColors_getWordIndex(rowIndex: u32) -> u32 {
+  return storageColors.wordOffset + rowIndex * storageColors.wordStride;
+}
+
+fn storageColors_readRgba8UnormColor(wordIndex: u32) -> vec4<f32> {
+  return unpack4x8unorm(storageColorsBuffer[wordIndex]);
+}
+
+fn storageColors_readRgba16FloatColor(wordIndex: u32) -> vec4<f32> {
+  let redGreen = unpack2x16float(storageColorsBuffer[wordIndex]);
+  let blueAlpha = unpack2x16float(storageColorsBuffer[wordIndex + 1u]);
+  return vec4<f32>(redGreen.x, redGreen.y, blueAlpha.x, blueAlpha.y);
+}
+
+fn storageColors_readRgba32FloatColor(wordIndex: u32) -> vec4<f32> {
+  return vec4<f32>(
+    bitcast<f32>(storageColorsBuffer[wordIndex]),
+    bitcast<f32>(storageColorsBuffer[wordIndex + 1u]),
+    bitcast<f32>(storageColorsBuffer[wordIndex + 2u]),
+    bitcast<f32>(storageColorsBuffer[wordIndex + 3u])
+  );
+}
+
+fn storageColors_readColor(rowIndex: u32) -> vec4<f32> {
+  let wordIndex = storageColors_getWordIndex(rowIndex);
+  if (storageColors.format == STORAGE_COLOR_FORMAT_RGBA8UNORM) {
+    return storageColors_readRgba8UnormColor(wordIndex);
+  }
+  if (storageColors.format == STORAGE_COLOR_FORMAT_RGBA16FLOAT) {
+    return storageColors_readRgba16FloatColor(wordIndex);
+  }
+  return storageColors_readRgba32FloatColor(wordIndex);
+}
+`;
+
+function buildGLSLColorModuleSource(primaryPrefix: string): string {
+  return /* glsl */ `\
+layout(std140) uniform ${primaryPrefix}Uniforms {
   float useByteColors;
-} floatColors;
+} ${primaryPrefix};
 
-vec3 floatColors_normalize(vec3 inputColor) {
-  return floatColors.useByteColors > 0.5 ? inputColor / 255.0 : inputColor;
+vec3 ${primaryPrefix}_normalize(vec3 inputColor) {
+  return ${primaryPrefix}.useByteColors > 0.5 ? inputColor / 255.0 : inputColor;
 }
 
-vec4 floatColors_normalize(vec4 inputColor) {
-  return floatColors.useByteColors > 0.5 ? inputColor / 255.0 : inputColor;
+vec4 ${primaryPrefix}_normalize(vec4 inputColor) {
+  return ${primaryPrefix}.useByteColors > 0.5 ? inputColor / 255.0 : inputColor;
 }
 
-vec4 floatColors_premultiplyAlpha(vec4 inputColor) {
+vec4 ${primaryPrefix}_premultiplyAlpha(vec4 inputColor) {
   return vec4(inputColor.rgb * inputColor.a, inputColor.a);
 }
 
-vec4 floatColors_unpremultiplyAlpha(vec4 inputColor) {
+vec4 ${primaryPrefix}_unpremultiplyAlpha(vec4 inputColor) {
   return inputColor.a > 0.0 ? vec4(inputColor.rgb / inputColor.a, inputColor.a) : vec4(0.0);
 }
 
-vec4 floatColors_premultiply_alpha(vec4 inputColor) {
-  return floatColors_premultiplyAlpha(inputColor);
+vec4 ${primaryPrefix}_premultiply_alpha(vec4 inputColor) {
+  return ${primaryPrefix}_premultiplyAlpha(inputColor);
 }
 
-vec4 floatColors_unpremultiply_alpha(vec4 inputColor) {
-  return floatColors_unpremultiplyAlpha(inputColor);
+vec4 ${primaryPrefix}_unpremultiply_alpha(vec4 inputColor) {
+  return ${primaryPrefix}_unpremultiplyAlpha(inputColor);
 }
 `;
+}
 
-const WGSL_UNIFORMS = /* wgsl */ `\
-struct floatColorsUniforms {
+function buildWGSLColorModuleSource(primaryPrefix: string): string {
+  return /* wgsl */ `\
+struct ${primaryPrefix}Uniforms {
   useByteColors: f32
 };
 
-@group(0) @binding(auto) var<uniform> floatColors : floatColorsUniforms;
+@group(0) @binding(auto) var<uniform> ${primaryPrefix} : ${primaryPrefix}Uniforms;
 
-fn floatColors_normalize(inputColor: vec3<f32>) -> vec3<f32> {
-  return select(inputColor, inputColor / 255.0, floatColors.useByteColors > 0.5);
+fn ${primaryPrefix}_normalize(inputColor: vec3<f32>) -> vec3<f32> {
+  return select(inputColor, inputColor / 255.0, ${primaryPrefix}.useByteColors > 0.5);
 }
 
-fn floatColors_normalize4(inputColor: vec4<f32>) -> vec4<f32> {
-  return select(inputColor, inputColor / 255.0, floatColors.useByteColors > 0.5);
+fn ${primaryPrefix}_normalize4(inputColor: vec4<f32>) -> vec4<f32> {
+  return select(inputColor, inputColor / 255.0, ${primaryPrefix}.useByteColors > 0.5);
 }
 
-fn floatColors_premultiplyAlpha(inputColor: vec4<f32>) -> vec4<f32> {
+fn ${primaryPrefix}_premultiplyAlpha(inputColor: vec4<f32>) -> vec4<f32> {
   return vec4<f32>(inputColor.rgb * inputColor.a, inputColor.a);
 }
 
-fn floatColors_unpremultiplyAlpha(inputColor: vec4<f32>) -> vec4<f32> {
+fn ${primaryPrefix}_unpremultiplyAlpha(inputColor: vec4<f32>) -> vec4<f32> {
   return select(
     vec4<f32>(0.0),
     vec4<f32>(inputColor.rgb / inputColor.a, inputColor.a),
@@ -74,26 +229,106 @@ fn floatColors_unpremultiplyAlpha(inputColor: vec4<f32>) -> vec4<f32> {
   );
 }
 
-fn floatColors_premultiply_alpha(inputColor: vec4<f32>) -> vec4<f32> {
-  return floatColors_premultiplyAlpha(inputColor);
+fn ${primaryPrefix}_premultiply_alpha(inputColor: vec4<f32>) -> vec4<f32> {
+  return ${primaryPrefix}_premultiplyAlpha(inputColor);
 }
 
-fn floatColors_unpremultiply_alpha(inputColor: vec4<f32>) -> vec4<f32> {
-  return floatColors_unpremultiplyAlpha(inputColor);
+fn ${primaryPrefix}_unpremultiply_alpha(inputColor: vec4<f32>) -> vec4<f32> {
+  return ${primaryPrefix}_unpremultiplyAlpha(inputColor);
 }
 `;
+}
+
+function getStorageColorsUniforms(props: StorageColorsProps = {}): StorageColorsUniforms {
+  const format = resolveStorageColorFormat(props.format);
+  const formatName = STORAGE_COLOR_FORMAT_NAME_BY_VALUE[format];
+  const byteStride = props.byteStride ?? STORAGE_COLOR_DEFAULT_BYTE_STRIDES[formatName];
+  const byteOffset = props.byteOffset ?? 0;
+  const minimumByteStride = STORAGE_COLOR_FORMAT_BYTE_LENGTHS[formatName];
+
+  validateStorageColorByteAlignment('byteStride', byteStride);
+  validateStorageColorByteAlignment('byteOffset', byteOffset);
+  if (byteStride < minimumByteStride) {
+    throw new Error(
+      `storageColors byteStride must be at least ${minimumByteStride} for ${formatName}`
+    );
+  }
+
+  return {
+    format,
+    wordStride: byteStride / Uint32Array.BYTES_PER_ELEMENT,
+    wordOffset: byteOffset / Uint32Array.BYTES_PER_ELEMENT,
+    _padding: 0
+  };
+}
+
+function resolveStorageColorFormat(
+  format: StorageColorsProps['format'] = 'rgba8unorm'
+): StorageColorFormatValue {
+  if (typeof format === 'number') {
+    if (format in STORAGE_COLOR_FORMAT_NAME_BY_VALUE) {
+      return format as StorageColorFormatValue;
+    }
+  } else if (format in STORAGE_COLOR_FORMAT_BY_NAME) {
+    return STORAGE_COLOR_FORMAT_BY_NAME[format];
+  }
+
+  throw new Error(
+    `storageColors format must be one of ${Object.keys(STORAGE_COLOR_FORMAT_BY_NAME).join(', ')}`
+  );
+}
 
+function validateStorageColorByteAlignment(name: string, value: number): void {
+  if (!Number.isInteger(value) || value < 0 || value % Uint32Array.BYTES_PER_ELEMENT !== 0) {
+    throw new Error(`storageColors ${name} must be a non-negative 4-byte aligned integer`);
+  }
+}
+
+/** Semantic color normalization helpers named `colors_*`. */
+export const colors = {
+  name: 'colors',
+  props: {} as ColorsProps,
+  uniforms: {} as ColorsUniforms,
+  vs: COLORS_GLSL,
+  fs: COLORS_GLSL,
+  source: COLORS_WGSL,
+  uniformTypes: COLORS_UNIFORM_TYPES,
+  defaultUniforms: COLORS_DEFAULT_UNIFORMS
+} as const satisfies ShaderModule<ColorsProps, ColorsUniforms>;
+
+/** Legacy semantic color normalization helpers named `floatColors_*`. */
 export const floatColors = {
   name: 'floatColors',
   props: {} as FloatColorsProps,
   uniforms: {} as FloatColorsUniforms,
-  vs: GLSL_UNIFORMS,
-  fs: GLSL_UNIFORMS,
-  source: WGSL_UNIFORMS,
-  uniformTypes: {
-    useByteColors: 'f32'
-  },
-  defaultUniforms: {
-    useByteColors: true
-  }
+  vs: FLOAT_COLORS_GLSL,
+  fs: FLOAT_COLORS_GLSL,
+  source: FLOAT_COLORS_WGSL,
+  uniformTypes: COLORS_UNIFORM_TYPES,
+  defaultUniforms: COLORS_DEFAULT_UNIFORMS
 } as const satisfies ShaderModule<FloatColorsProps, FloatColorsUniforms>;
+
+/**
+ * WGSL reader for packed RGBA storage rows.
+ *
+ * Include {@link colors} separately when semantic color normalization helpers are also needed.
+ */
+export const storageColors = {
+  name: 'storageColors',
+  props: {} as StorageColorsProps,
+  uniforms: {} as StorageColorsUniforms,
+  bindings: {} as StorageColorsBindings,
+  source: STORAGE_COLORS_WGSL,
+  uniformTypes: STORAGE_COLORS_UNIFORM_TYPES,
+  defaultUniforms: STORAGE_COLORS_DEFAULT_UNIFORMS,
+  bindingLayout: [
+    {name: 'storageColors', group: 0},
+    {name: 'storageColorsBuffer', group: 0}
+  ],
+  getUniforms(props: StorageColorsProps = {}) {
+    return {
+      ...getStorageColorsUniforms(props),
+      ...(props.colorBuffer ? {storageColorsBuffer: props.colorBuffer} : {})
+    };
+  }
+} as const satisfies ShaderModule<StorageColorsProps, StorageColorsUniforms, StorageColorsBindings>;

package/src/modules/engine/clip/clip.ts

@@ -0,0 +1,149 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+import type {ShaderPlugin} from '../../../lib/shader-plugin';
+
+export type ClipShaderPluginProps = {
+  /** Enables clipping. Defaults to true. */
+  enabled?: boolean;
+  /** Inclusive lower and exclusive upper bounds. Defaults to [0, 0, 1, 1]. */
+  bounds?: readonly [number, number, number, number];
+  /** Clips whole instances by their anchor or individual fragments. Defaults to geometry. */
+  mode?: 'instance' | 'geometry';
+};
+
+type ClipUniforms = {
+  enabled: number;
+  mode: number;
+  bounds: readonly [number, number, number, number];
+};
+
+const CLIP_MODE_GEOMETRY = 0;
+const CLIP_MODE_INSTANCE = 1;
+
+const clipShaderModule = {
+  name: 'clip',
+  props: {} as ClipShaderPluginProps,
+  uniforms: {} as ClipUniforms,
+  bindingLayout: [{name: 'clip', group: 2}],
+  uniformTypes: {
+    enabled: 'i32',
+    mode: 'i32',
+    bounds: 'vec4<f32>'
+  },
+  defaultUniforms: {
+    enabled: 1,
+    mode: CLIP_MODE_GEOMETRY,
+    bounds: [0, 0, 1, 1]
+  },
+  vs: /* glsl */ `\
+layout(std140) uniform clipUniforms {
+  highp int enabled;
+  highp int mode;
+  highp vec4 bounds;
+} clipState;
+
+bool clip_isInBounds(vec2 coordinates) {
+  return coordinates.x >= clipState.bounds.x &&
+    coordinates.y >= clipState.bounds.y &&
+    coordinates.x < clipState.bounds.z &&
+    coordinates.y < clipState.bounds.w;
+}
+`,
+  fs: /* glsl */ `\
+layout(std140) uniform clipUniforms {
+  highp int enabled;
+  highp int mode;
+  highp vec4 bounds;
+} clipState;
+
+bool clip_isInBounds(vec2 coordinates) {
+  return coordinates.x >= clipState.bounds.x &&
+    coordinates.y >= clipState.bounds.y &&
+    coordinates.x < clipState.bounds.z &&
+    coordinates.y < clipState.bounds.w;
+}
+`,
+  source: /* wgsl */ `\
+struct ClipUniforms {
+  enabled: i32,
+  mode: i32,
+  bounds: vec4<f32>,
+};
+
+@group(2) @binding(auto) var<uniform> clipUniforms: ClipUniforms;
+
+fn clip_isInBounds(coordinates: vec2<f32>) -> bool {
+  return coordinates.x >= clipUniforms.bounds.x &&
+    coordinates.y >= clipUniforms.bounds.y &&
+    coordinates.x < clipUniforms.bounds.z &&
+    coordinates.y < clipUniforms.bounds.w;
+}
+`,
+  getUniforms(props: ClipShaderPluginProps = {}): Partial<ClipUniforms> {
+    const uniforms: Partial<ClipUniforms> = {};
+    if (props.enabled !== undefined) {
+      uniforms.enabled = Number(props.enabled);
+    }
+    if (props.mode !== undefined) {
+      uniforms.mode = props.mode === 'instance' ? CLIP_MODE_INSTANCE : CLIP_MODE_GEOMETRY;
+    }
+    if (props.bounds !== undefined) {
+      uniforms.bounds = props.bounds;
+    }
+    return uniforms;
+  }
+} as const satisfies ShaderModule<ClipShaderPluginProps, ClipUniforms, {}>;
+
+/** Coordinate-system-neutral instance and geometry clipping. */
+export const clipShaderPlugin: ShaderPlugin = {
+  name: 'clip',
+  modules: [clipShaderModule],
+  varyings: {
+    clipCoordinates: {type: 'vec2<f32>', interpolation: 'smooth'}
+  },
+  glsl: {
+    injections: [
+      {
+        target: 'vs:CLIP_POSITION',
+        injection: `\
+clipCoordinates = geometryCoordinates;
+if (clipState.enabled != 0 && clipState.mode == ${CLIP_MODE_INSTANCE} &&
+    !clip_isInBounds(instanceCoordinates)) {
+  position = vec4(2.0, 2.0, 2.0, 1.0);
+}`
+      },
+      {
+        target: 'fs:CLIP_COLOR',
+        injection: `\
+if (clipState.enabled != 0 && clipState.mode == ${CLIP_MODE_GEOMETRY} &&
+    !clip_isInBounds(clipCoordinates)) {
+  discard;
+}`
+      }
+    ]
+  },
+  wgsl: {
+    injections: [
+      {
+        target: 'vs:CLIP_POSITION',
+        injection: `\
+clipCoordinates = geometryCoordinates;
+if (clipUniforms.enabled != 0 && clipUniforms.mode == ${CLIP_MODE_INSTANCE} &&
+    !clip_isInBounds(instanceCoordinates)) {
+  *position = vec4<f32>(2.0, 2.0, 2.0, 1.0);
+}`
+      },
+      {
+        target: 'fs:CLIP_COLOR',
+        injection: `\
+if (clipUniforms.enabled != 0 && clipUniforms.mode == ${CLIP_MODE_GEOMETRY} &&
+    !clip_isInBounds(clipCoordinates)) {
+  discard;
+}`
+      }
+    ]
+  }
+};

package/src/modules/engine/filter/filter.ts

@@ -0,0 +1,107 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {ShaderModule} from '../../../lib/shader-module/shader-module';
+import type {ShaderPlugin} from '../../../lib/shader-plugin';
+
+export type FilterShaderPluginProps = {
+  /** Enables range filtering. Defaults to true. */
+  enabled?: boolean;
+  /** Inclusive minimum accepted value. Defaults to 0. */
+  min?: number;
+  /** Inclusive maximum accepted value. Defaults to 1. */
+  max?: number;
+};
+
+type FilterUniforms = {
+  enabled: number;
+  min: number;
+  max: number;
+};
+
+const filterShaderModule = {
+  name: 'filter',
+  props: {} as FilterShaderPluginProps,
+  uniforms: {} as FilterUniforms,
+  bindingLayout: [{name: 'filter', group: 2}],
+  uniformTypes: {
+    enabled: 'i32',
+    min: 'f32',
+    max: 'f32'
+  },
+  defaultUniforms: {
+    enabled: 1,
+    min: 0,
+    max: 1
+  },
+  vs: /* glsl */ `\
+layout(std140) uniform filterUniforms {
+  int enabled;
+  float min;
+  float max;
+} filterState;
+
+bool filter_isVisible(float value) {
+  return filterState.enabled == 0 || (value >= filterState.min && value <= filterState.max);
+}
+`,
+  source: /* wgsl */ `\
+struct FilterUniforms {
+  enabled: i32,
+  min: f32,
+  max: f32,
+};
+
+@group(2) @binding(auto) var<uniform> filterUniforms: FilterUniforms;
+
+fn filter_isVisible(value: f32) -> bool {
+  return filterUniforms.enabled == 0 ||
+    (value >= filterUniforms.min && value <= filterUniforms.max);
+}
+`,
+  getUniforms(props: FilterShaderPluginProps = {}): Partial<FilterUniforms> {
+    const uniforms: Partial<FilterUniforms> = {};
+    if (props.enabled !== undefined) {
+      uniforms.enabled = Number(props.enabled);
+    }
+    if (props.min !== undefined) {
+      uniforms.min = props.min;
+    }
+    if (props.max !== undefined) {
+      uniforms.max = props.max;
+    }
+    return uniforms;
+  }
+} as const satisfies ShaderModule<FilterShaderPluginProps, FilterUniforms>;
+
+/** Scalar inclusive-range filtering for shaders that expose the `FILTER_POSITION` vertex hook. */
+export const filterShaderPlugin: ShaderPlugin = {
+  name: 'filter',
+  modules: [filterShaderModule],
+  vertexInputs: {
+    filterValues: 'f32'
+  },
+  glsl: {
+    injections: [
+      {
+        target: 'vs:FILTER_POSITION',
+        injection: `\
+if (!filter_isVisible(filterValues)) {
+  position = vec4(2.0, 2.0, 2.0, 1.0);
+}`
+      }
+    ]
+  },
+  wgsl: {
+    injections: [
+      {
+        target: 'vs:FILTER_POSITION',
+        injection: `\
+if (!filter_isVisible(filterValues)) {
+  *position = vec4<f32>(2.0, 2.0, 2.0, 1.0);
+}`
+      }
+    ]
+  }
+};