@luma.gl/shaders 0.0.0-stage → 10.0.0-alpha.5

package/dist/lib/wgsl-shader-assembler.js

@@ -0,0 +1,84 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+import { ShaderAssembler } from "./shader-assembler-base.js";
+import { assembleWGSLSource } from "./shader-assembly/assemble-wgsl-shaders.js";
+import { getShaderBindingDebugRowsFromWGSL } from "./shader-assembly/wgsl-binding-debug.js";
+import { preprocess } from "./preprocessor/preprocessor.js";
+import { scanWGSLInterface } from "./shader-assembly/wgsl-interface-scan.js";
+/** Stateful assembler for unified WGSL shaders. */
+export class WGSLShaderAssembler extends ShaderAssembler {
+    shaderLanguage = 'wgsl';
+    /** Stable per-run WGSL auto-binding assignments keyed by group/module/binding. */
+    _wgslBindingRegistry = new Map();
+    /**
+     * Assemble a WGSL unified shader.
+     * @param props WGSL source, platform information, shader modules, defines, and injections.
+     * @returns Assembled WGSL source, resolved modules, uniforms, and binding debug metadata.
+     */
+    assembleWGSLShader(props) {
+        const modules = this._getModuleList(props.modules); // Combine with default modules
+        const hookFunctions = this._hookFunctions; // TODO - combine with default hook functions
+        const translated = this._transpileShader(props, modules, props.source, props.shaderStage ?? (props.computeEntryPoint ? 'compute' : undefined));
+        const entryPoints = {
+            vertex: translated.entryPoints?.vertex ?? props.vertexEntryPoint,
+            fragment: translated.entryPoints?.fragment ?? props.fragmentEntryPoint,
+            compute: translated.entryPoints?.compute ?? props.computeEntryPoint
+        };
+        const defines = WGSLShaderAssembler.getShaderPreprocessorDefines(props, modules);
+        const preprocessedApplicationSource = props.platformInfo.shaderLanguage === 'wgsl' && translated.code
+            ? preprocess(translated.code, { defines })
+            : translated.code;
+        const { source: assembledSource, getUniforms, bindingAssignments } = assembleWGSLSource({
+            ...props,
+            source: preprocessedApplicationSource,
+            vertexEntryPoint: entryPoints.vertex,
+            fragmentEntryPoint: entryPoints.fragment,
+            defines,
+            _bindingRegistry: this._wgslBindingRegistry,
+            modules: translated.modules,
+            hookFunctions
+        });
+        // WGSL does not have built-in preprocessing support (just compile time constants)
+        const preprocessedSource = props.platformInfo.shaderLanguage === 'wgsl'
+            ? preprocess(assembledSource, { defines })
+            : assembledSource;
+        return {
+            source: preprocessedSource,
+            entryPoints,
+            getUniforms,
+            modules,
+            bindingAssignments,
+            bindingTable: getShaderBindingDebugRowsFromWGSL(preprocessedSource, bindingAssignments),
+            shaderLayout: scanWGSLInterface(preprocessedSource, {
+                vertexEntryPoint: entryPoints.vertex,
+                scanVertexAttributes: props.scanVertexAttributes
+            })
+        };
+    }
+    static getShaderPreprocessorDefines(props, modules) {
+        return {
+            ...WGSLShaderAssembler.getPlatformPreprocessorDefines(props.platformInfo),
+            ...modules.reduce((accumulator, module) => {
+                Object.assign(accumulator, module.defines);
+                return accumulator;
+            }, {}),
+            ...props.defines
+        };
+    }
+    static getPlatformPreprocessorDefines(platformInfo) {
+        const limits = platformInfo.limits || {};
+        return {
+            LUMA_SUPPORTS_VERTEX_STORAGE_BUFFERS: platformInfo.type === 'webgpu' && (limits['maxStorageBuffersInVertexStage'] || 0) > 0,
+            // Native tan() does not provide enough precision on all WebGPU implementations.
+            LUMA_FP32_TAN_PRECISION_WORKAROUND: platformInfo.type === 'webgpu' &&
+                platformInfo.gpu.toLowerCase() !== 'nvidia' &&
+                platformInfo.gpu.toLowerCase() !== 'amd',
+            // Metal may reassociate the floating-point transforms used by classic
+            // double-single arithmetic. The integer path makes each rounding point
+            // explicit while preserving the public vec2<f32> representation.
+            LUMA_FP64_INTEGER_ARITHMETIC: platformInfo.type === 'webgpu' && platformInfo.gpu.toLowerCase() === 'apple'
+        };
+    }
+}
+//# sourceMappingURL=wgsl-shader-assembler.js.map

package/dist/lib/wgsl-shader-assembler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wgsl-shader-assembler.js","sourceRoot":"","sources":["../../src/lib/wgsl-shader-assembler.ts"],"names":[],"mappings":"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"}

package/dist/module-injectors.cjs

@@ -0,0 +1,59 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var module_injectors_exports = {};
+__export(module_injectors_exports, {
+  MODULE_INJECTORS_FS: () => MODULE_INJECTORS_FS,
+  MODULE_INJECTORS_VS: () => MODULE_INJECTORS_VS
+});
+module.exports = __toCommonJS(module_injectors_exports);
+const MODULE_INJECTORS_VS = (
+  /* glsl */
+  `#ifdef MODULE_LOGDEPTH
+  logdepth_adjustPosition(gl_Position);
+#endif
+`
+);
+const MODULE_INJECTORS_FS = (
+  /* glsl */
+  `#ifdef MODULE_MATERIAL
+  fragColor = material_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_LIGHTING
+  fragColor = lighting_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_FOG
+  fragColor = fog_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_PICKING
+  fragColor = picking_filterHighlightColor(fragColor);
+  fragColor = picking_filterPickingColor(fragColor);
+#endif
+
+#ifdef MODULE_LOGDEPTH
+  logdepth_setFragDepth();
+#endif
+`
+);
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MODULE_INJECTORS_FS,
+  MODULE_INJECTORS_VS
+});

package/dist/module-injectors.d.ts

@@ -0,0 +1,3 @@
+export declare const MODULE_INJECTORS_VS = "#ifdef MODULE_LOGDEPTH\n  logdepth_adjustPosition(gl_Position);\n#endif\n";
+export declare const MODULE_INJECTORS_FS = "#ifdef MODULE_MATERIAL\n  fragColor = material_filterColor(fragColor);\n#endif\n\n#ifdef MODULE_LIGHTING\n  fragColor = lighting_filterColor(fragColor);\n#endif\n\n#ifdef MODULE_FOG\n  fragColor = fog_filterColor(fragColor);\n#endif\n\n#ifdef MODULE_PICKING\n  fragColor = picking_filterHighlightColor(fragColor);\n  fragColor = picking_filterPickingColor(fragColor);\n#endif\n\n#ifdef MODULE_LOGDEPTH\n  logdepth_setFragDepth();\n#endif\n";
+//# sourceMappingURL=module-injectors.d.ts.map

package/dist/module-injectors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-injectors.d.ts","sourceRoot":"","sources":["../src/module-injectors.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mBAAmB,8EAI/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,4bAqB/B,CAAC"}

package/dist/module-injectors.js

@@ -0,0 +1,31 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+export const MODULE_INJECTORS_VS = /* glsl */ `\
+#ifdef MODULE_LOGDEPTH
+  logdepth_adjustPosition(gl_Position);
+#endif
+`;
+export const MODULE_INJECTORS_FS = /* glsl */ `\
+#ifdef MODULE_MATERIAL
+  fragColor = material_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_LIGHTING
+  fragColor = lighting_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_FOG
+  fragColor = fog_filterColor(fragColor);
+#endif
+
+#ifdef MODULE_PICKING
+  fragColor = picking_filterHighlightColor(fragColor);
+  fragColor = picking_filterPickingColor(fragColor);
+#endif
+
+#ifdef MODULE_LOGDEPTH
+  logdepth_setFragDepth();
+#endif
+`;
+//# sourceMappingURL=module-injectors.js.map

package/dist/module-injectors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-injectors.js","sourceRoot":"","sources":["../src/module-injectors.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,+BAA+B;AAC/B,4DAA4D;AAE5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;;;;CAI7C,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;CAqB7C,CAAC"}

package/dist/modules/color/float-colors.cjs

@@ -0,0 +1,275 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var float_colors_exports = {};
+__export(float_colors_exports, {
+  STORAGE_COLOR_DEFAULT_BYTE_STRIDES: () => STORAGE_COLOR_DEFAULT_BYTE_STRIDES,
+  STORAGE_COLOR_FORMAT: () => STORAGE_COLOR_FORMAT,
+  STORAGE_COLOR_FORMAT_BYTE_LENGTHS: () => STORAGE_COLOR_FORMAT_BYTE_LENGTHS,
+  colors: () => colors,
+  floatColors: () => floatColors,
+  storageColors: () => storageColors
+});
+module.exports = __toCommonJS(float_colors_exports);
+const STORAGE_COLOR_FORMAT = {
+  RGBA8UNORM: 0,
+  RGBA16FLOAT: 1,
+  RGBA32FLOAT: 2
+};
+const STORAGE_COLOR_FORMAT_BYTE_LENGTHS = {
+  rgba8unorm: 4,
+  rgba16float: 8,
+  rgba32float: 16
+};
+const STORAGE_COLOR_DEFAULT_BYTE_STRIDES = {
+  ...STORAGE_COLOR_FORMAT_BYTE_LENGTHS
+};
+const STORAGE_COLOR_FORMAT_BY_NAME = {
+  rgba8unorm: STORAGE_COLOR_FORMAT.RGBA8UNORM,
+  rgba16float: STORAGE_COLOR_FORMAT.RGBA16FLOAT,
+  rgba32float: STORAGE_COLOR_FORMAT.RGBA32FLOAT
+};
+const STORAGE_COLOR_FORMAT_NAME_BY_VALUE = {
+  [STORAGE_COLOR_FORMAT.RGBA8UNORM]: "rgba8unorm",
+  [STORAGE_COLOR_FORMAT.RGBA16FLOAT]: "rgba16float",
+  [STORAGE_COLOR_FORMAT.RGBA32FLOAT]: "rgba32float"
+};
+const COLORS_UNIFORM_TYPES = {
+  useByteColors: "f32"
+};
+const COLORS_DEFAULT_UNIFORMS = {
+  useByteColors: true
+};
+const STORAGE_COLORS_UNIFORM_TYPES = {
+  format: "u32",
+  wordStride: "u32",
+  wordOffset: "u32",
+  _padding: "u32"
+};
+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
+};
+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) {
+  return (
+    /* glsl */
+    `layout(std140) uniform ${primaryPrefix}Uniforms {
+  float useByteColors;
+} ${primaryPrefix};
+
+vec3 ${primaryPrefix}_normalize(vec3 inputColor) {
+  return ${primaryPrefix}.useByteColors > 0.5 ? inputColor / 255.0 : inputColor;
+}
+
+vec4 ${primaryPrefix}_normalize(vec4 inputColor) {
+  return ${primaryPrefix}.useByteColors > 0.5 ? inputColor / 255.0 : inputColor;
+}
+
+vec4 ${primaryPrefix}_premultiplyAlpha(vec4 inputColor) {
+  return vec4(inputColor.rgb * inputColor.a, inputColor.a);
+}
+
+vec4 ${primaryPrefix}_unpremultiplyAlpha(vec4 inputColor) {
+  return inputColor.a > 0.0 ? vec4(inputColor.rgb / inputColor.a, inputColor.a) : vec4(0.0);
+}
+
+vec4 ${primaryPrefix}_premultiply_alpha(vec4 inputColor) {
+  return ${primaryPrefix}_premultiplyAlpha(inputColor);
+}
+
+vec4 ${primaryPrefix}_unpremultiply_alpha(vec4 inputColor) {
+  return ${primaryPrefix}_unpremultiplyAlpha(inputColor);
+}
+`
+  );
+}
+function buildWGSLColorModuleSource(primaryPrefix) {
+  return (
+    /* wgsl */
+    `struct ${primaryPrefix}Uniforms {
+  useByteColors: f32
+};
+
+@group(0) @binding(auto) var<uniform> ${primaryPrefix} : ${primaryPrefix}Uniforms;
+
+fn ${primaryPrefix}_normalize(inputColor: vec3<f32>) -> vec3<f32> {
+  return select(inputColor, inputColor / 255.0, ${primaryPrefix}.useByteColors > 0.5);
+}
+
+fn ${primaryPrefix}_normalize4(inputColor: vec4<f32>) -> vec4<f32> {
+  return select(inputColor, inputColor / 255.0, ${primaryPrefix}.useByteColors > 0.5);
+}
+
+fn ${primaryPrefix}_premultiplyAlpha(inputColor: vec4<f32>) -> vec4<f32> {
+  return vec4<f32>(inputColor.rgb * inputColor.a, inputColor.a);
+}
+
+fn ${primaryPrefix}_unpremultiplyAlpha(inputColor: vec4<f32>) -> vec4<f32> {
+  return select(
+    vec4<f32>(0.0),
+    vec4<f32>(inputColor.rgb / inputColor.a, inputColor.a),
+    inputColor.a > 0.0
+  );
+}
+
+fn ${primaryPrefix}_premultiply_alpha(inputColor: vec4<f32>) -> vec4<f32> {
+  return ${primaryPrefix}_premultiplyAlpha(inputColor);
+}
+
+fn ${primaryPrefix}_unpremultiply_alpha(inputColor: vec4<f32>) -> vec4<f32> {
+  return ${primaryPrefix}_unpremultiplyAlpha(inputColor);
+}
+`
+  );
+}
+function getStorageColorsUniforms(props = {}) {
+  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 = "rgba8unorm") {
+  if (typeof format === "number") {
+    if (format in STORAGE_COLOR_FORMAT_NAME_BY_VALUE) {
+      return format;
+    }
+  } 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, value) {
+  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`);
+  }
+}
+const colors = {
+  name: "colors",
+  props: {},
+  uniforms: {},
+  vs: COLORS_GLSL,
+  fs: COLORS_GLSL,
+  source: COLORS_WGSL,
+  uniformTypes: COLORS_UNIFORM_TYPES,
+  defaultUniforms: COLORS_DEFAULT_UNIFORMS
+};
+const floatColors = {
+  name: "floatColors",
+  props: {},
+  uniforms: {},
+  vs: FLOAT_COLORS_GLSL,
+  fs: FLOAT_COLORS_GLSL,
+  source: FLOAT_COLORS_WGSL,
+  uniformTypes: COLORS_UNIFORM_TYPES,
+  defaultUniforms: COLORS_DEFAULT_UNIFORMS
+};
+const storageColors = {
+  name: "storageColors",
+  props: {},
+  uniforms: {},
+  bindings: {},
+  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 = {}) {
+    return {
+      ...getStorageColorsUniforms(props),
+      ...props.colorBuffer ? { storageColorsBuffer: props.colorBuffer } : {}
+    };
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  STORAGE_COLOR_DEFAULT_BYTE_STRIDES,
+  STORAGE_COLOR_FORMAT,
+  STORAGE_COLOR_FORMAT_BYTE_LENGTHS,
+  colors,
+  floatColors,
+  storageColors
+});

package/dist/modules/color/float-colors.d.ts

@@ -0,0 +1,132 @@
+import type { ShaderBinding as Binding } from "../../types.js";
+/** 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.
+     */
+    useByteColors?: boolean;
+};
+/** Uniforms consumed by semantic color normalization helpers. */
+export type ColorsUniforms = {
+    /** Controls whether shader helpers normalize semantic colors from byte space. */
+    useByteColors: boolean;
+};
+/** 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 declare const STORAGE_COLOR_FORMAT: {
+    readonly RGBA8UNORM: 0;
+    readonly RGBA16FLOAT: 1;
+    readonly RGBA32FLOAT: 2;
+};
+/** 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 declare const STORAGE_COLOR_FORMAT_BYTE_LENGTHS: Record<StorageColorFormat, number>;
+/** Default byte stride for one tightly packed storage color row. */
+export declare const STORAGE_COLOR_DEFAULT_BYTE_STRIDES: Record<StorageColorFormat, number>;
+/** 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;
+};
+/** Semantic color normalization helpers named `colors_*`. */
+export declare const colors: {
+    readonly name: "colors";
+    readonly props: ColorsProps;
+    readonly uniforms: ColorsUniforms;
+    readonly vs: string;
+    readonly fs: string;
+    readonly source: string;
+    readonly uniformTypes: {
+        readonly useByteColors: "f32";
+    };
+    readonly defaultUniforms: {
+        readonly useByteColors: true;
+    };
+};
+/** Legacy semantic color normalization helpers named `floatColors_*`. */
+export declare const floatColors: {
+    readonly name: "floatColors";
+    readonly props: FloatColorsProps;
+    readonly uniforms: FloatColorsUniforms;
+    readonly vs: string;
+    readonly fs: string;
+    readonly source: string;
+    readonly uniformTypes: {
+        readonly useByteColors: "f32";
+    };
+    readonly defaultUniforms: {
+        readonly useByteColors: true;
+    };
+};
+/**
+ * WGSL reader for packed RGBA storage rows.
+ *
+ * Include {@link colors} separately when semantic color normalization helpers are also needed.
+ */
+export declare const storageColors: {
+    readonly name: "storageColors";
+    readonly props: StorageColorsProps;
+    readonly uniforms: StorageColorsUniforms;
+    readonly bindings: StorageColorsBindings;
+    readonly source: string;
+    readonly uniformTypes: {
+        readonly format: "u32";
+        readonly wordStride: "u32";
+        readonly wordOffset: "u32";
+        readonly _padding: "u32";
+    };
+    readonly defaultUniforms: {
+        readonly format: 0;
+        readonly wordStride: number;
+        readonly wordOffset: 0;
+        readonly _padding: 0;
+    };
+    readonly bindingLayout: readonly [{
+        readonly name: "storageColors";
+        readonly group: 0;
+    }, {
+        readonly name: "storageColorsBuffer";
+        readonly group: 0;
+    }];
+    readonly getUniforms: (props?: StorageColorsProps) => {
+        storageColorsBuffer?: {} | undefined;
+        /** 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;
+    };
+};
+//# sourceMappingURL=float-colors.d.ts.map

package/dist/modules/color/float-colors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"float-colors.d.ts","sourceRoot":"","sources":["../../../src/modules/color/float-colors.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,aAAa,IAAI,OAAO,EAAC,uBAAoB;AAG1D,sDAAsD;AACtD,MAAM,MAAM,WAAW,GAAG;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,cAAc,GAAG;IAC3B,iFAAiF;IACjF,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAC3C,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,cAAc,CAAC;AAEjD,+DAA+D;AAC/D,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,aAAa,GAAG,aAAa,CAAC;AAE9E,2DAA2D;AAC3D,eAAO,MAAM,oBAAoB;;;;CAIvB,CAAC;AAEX,4DAA4D;AAC5D,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,OAAO,oBAAoB,CAAC,CAAC;AAEnE,8DAA8D;AAC9D,eAAO,MAAM,iCAAiC,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAIhF,CAAC;AAEF,oEAAoE;AACpE,eAAO,MAAM,kCAAkC,EAAE,MAAM,CAAC,kBAAkB,EAAE,MAAM,CAEjF,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG;IAC/B,wDAAwD;IACxD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sEAAsE;IACtE,MAAM,CAAC,EAAE,kBAAkB,GAAG,uBAAuB,CAAC;IACtD,+EAA+E;IAC/E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,qBAAqB,GAAG;IAClC,uDAAuD;IACvD,MAAM,EAAE,uBAAuB,CAAC;IAChC,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,qBAAqB,GAAG;IAClC,+DAA+D;IAC/D,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B,CAAC;AA6MF,6DAA6D;AAC7D,eAAO,MAAM,MAAM;;oBAEJ,WAAW;uBACR,cAAc;;;;;;;;;;CAM8B,CAAC;AAE/D,yEAAyE;AACzE,eAAO,MAAM,WAAW;;oBAET,gBAAgB;uBACb,mBAAmB;;;;;;;;;;CAMmC,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,aAAa;;oBAEX,kBAAkB;uBACf,qBAAqB;uBACrB,qBAAqB;;;;;;;;;;;;;;;;;;;;;mCAQlB,kBAAkB;;QApQrC,uDAAuD;gBAC/C,uBAAuB;QAC/B,+CAA+C;oBACnC,MAAM;QAClB,yDAAyD;oBAC7C,MAAM;QAClB,wDAAwD;kBAC9C,MAAM;;CAmQiF,CAAC"}