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

package/src/index.ts

@@ -0,0 +1,259 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+// shaders exports
+
+/**
+ * Marks GLSL shaders for syntax highlighting: glsl`...`
+ * Install https://marketplace.visualstudio.com/items?itemName=boyswan.glsl-literal
+ */
+export type {PlatformInfo} from './lib/shader-assembly/platform-info';
+export type {ShaderBindingDebugRow} from './lib/shader-assembly/wgsl-binding-debug';
+export {
+  scanWGSLInterface,
+  type ScanWGSLInterfaceOptions
+} from './lib/shader-assembly/wgsl-interface-scan';
+
+// ShaderModules
+
+export type {ShaderModule} from './lib/shader-module/shader-module';
+export type {
+  ResolvedShaderPlugins,
+  ResolvedShaderPluginVarying,
+  ShaderPlugin,
+  ShaderPluginInjection,
+  ShaderPluginInjectionTarget,
+  ShaderPluginVarying,
+  ShaderPluginVaryingInterpolation,
+  ShaderPluginVariant
+} from './lib/shader-plugin';
+export type {
+  ShaderPass,
+  ShaderPassInputSource,
+  ShaderPassRenderTarget,
+  ShaderSubPass
+} from './lib/shader-module/shader-pass';
+export type {
+  CompositeShaderPassComputeOptimization,
+  CompositeShaderPass,
+  CompositeShaderPassStep
+} from './lib/shader-module/composite-shader-pass';
+export type {ShaderModuleUniformValue, UniformTypes} from './lib/utils/uniform-types';
+
+export {initializeShaderModule, initializeShaderModules} from './lib/shader-module/shader-module';
+export {getShaderModuleUniforms} from './lib/shader-module/shader-module';
+export {getShaderModuleDependencies} from './lib/shader-module/shader-module-dependencies';
+export {checkShaderModuleDeprecations} from './lib/shader-module/shader-module';
+export {mergeShaderPluginModules, resolveShaderPlugins} from './lib/shader-plugin';
+export type {
+  GLSLUniformBlockInfo,
+  ShaderModuleUniformLayoutStage,
+  ShaderModuleUniformLayoutValidationResult
+} from './lib/shader-module/shader-module-uniform-layout';
+export {
+  getGLSLUniformBlocks,
+  getShaderModuleUniformBlockFields,
+  getShaderModuleUniformBlockName,
+  getShaderModuleUniformLayoutValidationResult,
+  validateShaderModuleUniformLayout,
+  warnIfGLSLUniformBlocksAreNotStd140
+} from './lib/shader-module/shader-module-uniform-layout';
+
+export {getShaderModuleSource} from './lib/shader-assembly/assemble-shaders';
+
+export {resolveModules as _resolveModules} from './lib/shader-module/shader-module-dependencies';
+
+// ShaderAssembler
+export {ShaderAssembler, GLSLShaderAssembler, WGSLShaderAssembler} from './lib/shader-assembler';
+export type {ShaderHook, ShaderHookOptions} from './lib/shader-assembly/shader-hooks';
+export type {ShaderInjection} from './lib/shader-assembly/shader-injections';
+
+// SHADER HELPERS
+
+// Shader source introspection
+export {getShaderInfo} from './lib/glsl-utils/get-shader-info';
+export {
+  getQualifierDetails,
+  getPassthroughFS,
+  typeToChannelSuffix,
+  typeToChannelCount,
+  convertToVec4
+} from './lib/glsl-utils/shader-utils';
+
+// EXPERIMENTAL - Do not use in production applications
+export type {ShaderGenerationOptions} from './lib/shader-generator/generate-shader';
+export {generateShaderForModule} from './lib/shader-generator/generate-shader';
+export {capitalize} from './lib/shader-generator/utils/capitalize';
+
+// TEST EXPORTS - Do not use in production applications
+export {preprocess} from './lib/preprocessor/preprocessor';
+export {assembleGLSLShaderPair} from './lib/shader-assembly/assemble-shaders';
+export {combineInjects} from './lib/shader-assembly/shader-injections';
+
+// data utils
+export {toHalfFloat, fromHalfFloat} from './modules/math/fp16/fp16-utils';
+export {fp64ify, fp64LowPart, fp64ifyMatrix4} from './modules/math/fp64/fp64-utils';
+export {
+  normalizeByteColor3,
+  normalizeByteColor4,
+  resolveUseByteColors
+} from './lib/color/normalize-byte-colors';
+
+export {sketchStroke, type SketchStrokeProps} from './modules/geometry/sketch-stroke/sketch-stroke';
+export {
+  pathDash,
+  type PathDashProps,
+  type PathDashUniforms
+} from './modules/geometry/path-dash/path-dash';
+
+// math libraries
+export {random} from './modules/math/random/random';
+export {volumeRaymarch} from './modules/volume/volume-raymarch';
+
+export {fp32} from './modules/math/fp32/fp32';
+export {fp64, fp64arithmetic} from './modules/math/fp64/fp64';
+export {dggs} from './modules/geospatial/dggs/dggs';
+export type {
+  ColorsProps,
+  ColorsUniforms,
+  FloatColorsProps,
+  FloatColorsUniforms,
+  StorageColorFormat,
+  StorageColorFormatValue,
+  StorageColorsBindings,
+  StorageColorsProps,
+  StorageColorsUniforms
+} from './modules/color/float-colors';
+export {
+  colors,
+  floatColors,
+  STORAGE_COLOR_DEFAULT_BYTE_STRIDES,
+  STORAGE_COLOR_FORMAT,
+  STORAGE_COLOR_FORMAT_BYTE_LENGTHS,
+  storageColors
+} from './modules/color/float-colors';
+
+// engine shader modules
+
+//  projection
+// export type {ProjectionUniforms} from './modules/engine/project/project';
+// export {projection} from './modules/engine/project/project';
+export type {PickingProps, PickingUniforms} from './modules/engine/picking/picking';
+export {picking} from './modules/engine/picking/picking';
+export type {FilterShaderPluginProps} from './modules/engine/filter/filter';
+export {filterShaderPlugin} from './modules/engine/filter/filter';
+export type {ClipShaderPluginProps} from './modules/engine/clip/clip';
+export {clipShaderPlugin} from './modules/engine/clip/clip';
+export type {SkinProps, SkinUniforms} from './modules/engine/skin/skin';
+export {skin, SKIN_MAX_JOINTS} from './modules/engine/skin/skin';
+export type {
+  GPUAnimationBindings,
+  GPUAnimationProps
+} from './modules/engine/gpu-animation/gpu-animation';
+export {gpuAnimation} from './modules/engine/gpu-animation/gpu-animation';
+
+// lighting
+export {
+  type Light,
+  type AmbientLight,
+  type PointLight,
+  type SpotLight,
+  type DirectionalLight,
+  type LightingLightUniform
+} from './modules/lighting/lights/lighting';
+
+export type {LightingProps, LightingUniforms} from './modules/lighting/lights/lighting';
+export {lighting} from './modules/lighting/lights/lighting';
+export type {IBLBindings} from './modules/lighting/ibl/ibl';
+export {ibl} from './modules/lighting/ibl/ibl';
+export {dirlight} from './modules/lighting/no-material/dirlight';
+export type {LambertMaterialProps} from './modules/lighting/lambert-material/lambert-material';
+export {lambertMaterial} from './modules/lighting/lambert-material/lambert-material';
+export type {GouraudMaterialProps} from './modules/lighting/gouraud-material/gouraud-material';
+export {gouraudMaterial} from './modules/lighting/gouraud-material/gouraud-material';
+export type {PhongMaterialProps} from './modules/lighting/phong-material/phong-material';
+export {phongMaterial} from './modules/lighting/phong-material/phong-material';
+export type {
+  WaterMaterialProps,
+  WaterMaterialUniforms
+} from './modules/lighting/water-material/water-material';
+export {waterMaterial} from './modules/lighting/water-material/water-material';
+export type {
+  RiverWaterMaterialProps,
+  RiverWaterMaterialUniforms
+} from './modules/lighting/water-material/river-water-material';
+export {riverWaterMaterial} from './modules/lighting/water-material/river-water-material';
+export type {
+  PBRMaterialBindings,
+  PBRMaterialProps,
+  PBRMaterialUniforms
+} from './modules/lighting/pbr-material/pbr-material';
+export type {
+  PBRSceneBindings,
+  PBRSceneProps,
+  PBRSceneUniforms,
+  PBRToneMapMode
+} from './modules/lighting/pbr-material/pbr-scene';
+export type {PBRProjectionProps} from './modules/lighting/pbr-material/pbr-projection';
+
+export {pbrMaterial} from './modules/lighting/pbr-material/pbr-material';
+export {pbrScene, PBR_TONE_MAP_MODE} from './modules/lighting/pbr-material/pbr-scene';
+
+export {heightFog} from './modules/lighting/height-fog/height-fog';
+export {heightFogFunctions} from './modules/lighting/height-fog/height-fog-functions';
+export type {HeightFogProps, HeightFogUniforms} from './modules/lighting/height-fog/height-fog';
+export {
+  patternFill,
+  type PatternFillProps,
+  type PatternFillUniforms
+} from './modules/geometry/pattern-fill/pattern-fill';
+export {
+  pointGlow,
+  type PointGlowProps,
+  type PointGlowUniforms
+} from './modules/geometry/point-glow/point-glow';
+
+export {precipitation} from './modules/geometry/precipitation/precipitation';
+export type {
+  PrecipitationProps,
+  PrecipitationUniforms
+} from './modules/geometry/precipitation/precipitation';
+
+export type {
+  ShaderTranspiler,
+  ShaderTranspileProps,
+  ShaderTranspileResult,
+  ShaderTranspilerEntryPoints
+} from './lib/shader-transpiler/shader-transpiler';
+
+export {valueNoise} from './modules/math/value-noise/value-noise';
+export {clouds, type CloudProps, type CloudUniforms} from './modules/lighting/clouds/clouds';
+
+export {
+  atmosphere,
+  type AtmosphereProps,
+  type AtmosphereUniforms
+} from './modules/lighting/atmosphere/atmosphere';
+export {
+  surfaceWeather,
+  integrateSurfaceWeather,
+  type SurfaceWeatherProps,
+  type SurfaceWeatherUniforms,
+  type SurfaceWeatherState,
+  type SurfaceWeatherRates
+} from './modules/lighting/surface-weather/surface-weather';
+
+export {firefly, type FireflyProps, type FireflyUniforms} from './modules/lighting/firefly/firefly';
+
+export {
+  globeClouds,
+  type GlobeCloudProps,
+  type GlobeCloudUniforms
+} from './modules/lighting/globe-clouds/globe-clouds';
+
+export {
+  areaLighting,
+  type AreaLight,
+  type AreaLightingProps
+} from './modules/lighting/area-lighting/area-lighting';

package/src/lib/color/normalize-byte-colors.ts

@@ -0,0 +1,57 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {NumberArray3, NumberArray4} from '@math.gl/core';
+
+/**
+ * Resolves whether semantic colors should be interpreted as byte-style `0..255` values.
+ * @param useByteColors - Explicit color interpretation flag.
+ * @param defaultUseByteColors - Fallback value when `useByteColors` is omitted.
+ * @returns `true` when semantic colors should be normalized from bytes, otherwise `false`.
+ */
+export function resolveUseByteColors(
+  useByteColors?: boolean,
+  defaultUseByteColors: boolean = true
+): boolean {
+  return useByteColors ?? defaultUseByteColors;
+}
+
+/**
+ * Normalizes an RGB semantic color to float space when byte-style colors are enabled.
+ * @param color - Input RGB semantic color.
+ * @param useByteColors - When `true`, divide components by `255`.
+ * @returns The normalized RGB color.
+ */
+export function normalizeByteColor3(
+  color: Readonly<NumberArray3> = [0, 0, 0],
+  useByteColors: boolean = true
+): NumberArray3 {
+  if (!useByteColors) {
+    return [...color] as NumberArray3;
+  }
+
+  return color.map(component => component / 255) as NumberArray3;
+}
+
+/**
+ * Normalizes an RGBA semantic color to float space when byte-style colors are enabled.
+ * @param color - Input RGB or RGBA semantic color.
+ * @param useByteColors - When `true`, divide components by `255`.
+ * @returns The normalized RGBA color, adding an opaque alpha channel when needed.
+ */
+export function normalizeByteColor4(
+  color: Readonly<NumberArray4> | Readonly<NumberArray3>,
+  useByteColors: boolean = true
+): NumberArray4 {
+  const normalizedColor = normalizeByteColor3(color.slice(0, 3) as NumberArray3, useByteColors);
+  const hasAlpha = Number.isFinite(color[3]);
+  const alpha = hasAlpha ? (color[3] as number) : 1;
+
+  return [
+    normalizedColor[0],
+    normalizedColor[1],
+    normalizedColor[2],
+    useByteColors && hasAlpha ? alpha / 255 : alpha
+  ] as NumberArray4;
+}

package/src/lib/filters/prop-types.ts

@@ -0,0 +1,150 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {assert} from '../utils/assert';
+
+/**
+ * For use by shader module and shader pass writers to describe the types of the
+ * properties they expose (properties ultimately map to uniforms).
+ */
+export type PropType =
+  | {
+      type?: string;
+      value?: unknown;
+      max?: number;
+      min?: number;
+      softMax?: number;
+      softMin?: number;
+      hint?: string;
+      /** @deprecated internal uniform */
+      private?: boolean;
+    }
+  | number;
+
+/**
+ * Internal property validators generated by processing the prop types ,
+ * The `validate()` method can be used to validate the type of properties passed in to
+ * shader module or shader pass
+ */
+export type PropValidator = {
+  type: string;
+  value?: unknown;
+  max?: number;
+  min?: number;
+  private?: boolean;
+  validate?(value: unknown, propDef: PropValidator): boolean;
+};
+
+/** Minimal validators for number and array types */
+const DEFAULT_PROP_VALIDATORS: Record<string, PropValidator> = {
+  number: {
+    type: 'number',
+    validate(value: unknown, propType: PropType) {
+      return (
+        Number.isFinite(value) &&
+        typeof propType === 'object' &&
+        (propType.max === undefined || (value as number) <= propType.max) &&
+        (propType.min === undefined || (value as number) >= propType.min)
+      );
+    }
+  },
+  array: {
+    type: 'array',
+    validate(value: unknown, propType: PropType) {
+      return Array.isArray(value) || ArrayBuffer.isView(value);
+    }
+  }
+};
+
+/**
+ * Parse a list of property types into property definitions that can be used to validate
+ * values passed in by applications.
+ * @param propTypes
+ * @returns
+ */
+export function makePropValidators(
+  propTypes: Record<string, PropType>
+): Record<string, PropValidator> {
+  const propValidators: Record<string, PropValidator> = {};
+  for (const [name, propType] of Object.entries(propTypes)) {
+    propValidators[name] = makePropValidator(propType);
+  }
+  return propValidators;
+}
+
+/**
+ * Validate a map of user supplied properties against a map of validators
+ * Inject default values when user doesn't supply a property
+ * @param properties
+ * @param propValidators
+ * @returns
+ */
+export function getValidatedProperties(
+  properties: Record<string, unknown>,
+  propValidators: Record<string, PropValidator>,
+  errorMessage: string
+): Record<string, unknown> {
+  const validated: Record<string, unknown> = {};
+
+  for (const [key, propsValidator] of Object.entries(propValidators)) {
+    if (properties && key in properties && !propsValidator.private) {
+      if (propsValidator.validate) {
+        assert(
+          propsValidator.validate(properties[key], propsValidator),
+          `${errorMessage}: invalid ${key}`
+        );
+      }
+      validated[key] = properties[key];
+    } else {
+      // property not supplied - use default value
+      validated[key] = propsValidator.value;
+    }
+  }
+
+  // TODO - warn for unused properties that don't match a validator?
+
+  return validated;
+}
+
+/**
+ * Creates a property validator for a prop type. Either contains:
+ * - a valid prop type object ({type, ...})
+ * - or just a default value, in which case type and name inference is used
+ */
+function makePropValidator(propType: PropType): PropValidator {
+  let type = getTypeOf(propType);
+
+  if (type !== 'object') {
+    return {value: propType, ...DEFAULT_PROP_VALIDATORS[type], type};
+  }
+
+  // Special handling for objects
+  if (typeof propType === 'object') {
+    if (!propType) {
+      return {type: 'object', value: null};
+    }
+    if (propType.type !== undefined) {
+      return {...propType, ...DEFAULT_PROP_VALIDATORS[propType.type], type: propType.type};
+    }
+    // If no type and value this object is likely the value
+    if (propType.value === undefined) {
+      return {type: 'object', value: propType};
+    }
+
+    type = getTypeOf(propType.value);
+    return {...propType, ...DEFAULT_PROP_VALIDATORS[type], type};
+  }
+
+  throw new Error('props');
+}
+
+/**
+ * "improved" version of javascript typeof that can distinguish arrays and null values
+ */
+function getTypeOf(value: unknown): string {
+  if (Array.isArray(value) || ArrayBuffer.isView(value)) {
+    return 'array';
+  }
+  return typeof value;
+}

package/src/lib/glsl-shader-assembler.ts

@@ -0,0 +1,39 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {ShaderAssembler} from './shader-assembler-base';
+import type {ShaderModule} from './shader-module/shader-module';
+import type {AssembleShaderProps, GetUniformsFunc} from './shader-assembly/shader-assembly-types';
+import {assembleGLSLShaderPair} from './shader-assembly/assemble-glsl-shaders';
+
+/** Stateful assembler for GLSL vertex and fragment shaders. */
+export class GLSLShaderAssembler extends ShaderAssembler {
+  readonly shaderLanguage: 'glsl' = 'glsl';
+
+  /**
+   * Assemble a pair of shaders into a single shader program.
+   * @param props GLSL vertex and fragment source, platform information, shader modules, defines, and injections.
+   * @returns Assembled GLSL source, resolved modules, and combined uniform getter.
+   */
+  assembleGLSLShaderPair(props: AssembleShaderProps): {
+    vs: string;
+    fs: string;
+    getUniforms: GetUniformsFunc;
+    modules: ShaderModule[];
+  } {
+    const modules = this._getModuleList(props.modules); // Combine with default modules
+    const hookFunctions = this._hookFunctions; // TODO - combine with default hook functions
+    const vertex = this._transpileShader(props, modules, props.vs, 'vertex');
+    const fragment = this._transpileShader(props, modules, props.fs, 'fragment');
+    const assembled = assembleGLSLShaderPair({
+      ...props,
+      vs: vertex.code,
+      fs: props.fs == null ? undefined : fragment.code,
+      modules: vertex.modules,
+      hookFunctions
+    });
+
+    return {...assembled, modules};
+  }
+}

package/src/lib/glsl-utils/get-shader-info.ts

@@ -0,0 +1,42 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+/** Information extracted from shader source code */
+export type ShaderInfo = {
+  name: string;
+  language: 'glsl' | 'wgsl';
+  version: number;
+};
+
+/** Extracts information from shader source code */
+export function getShaderInfo(source: string, defaultName?: string): ShaderInfo {
+  return {
+    name: getShaderName(source, defaultName),
+    language: 'glsl',
+    version: getShaderVersion(source)
+  };
+}
+
+/** Extracts GLSLIFY style naming of shaders: `#define SHADER_NAME ...` */
+function getShaderName(shader: string, defaultName: string = 'unnamed'): string {
+  const SHADER_NAME_REGEXP = /#define[^\S\r\n]*SHADER_NAME[^\S\r\n]*([A-Za-z0-9_-]+)\s*/;
+  const match = SHADER_NAME_REGEXP.exec(shader);
+  return match ? match[1] : defaultName;
+}
+
+/** returns GLSL shader version of given shader string */
+function getShaderVersion(source: string): 100 | 300 {
+  let version = 100;
+  const words = source.match(/[^\s]+/g);
+  if (words && words.length >= 2 && words[0] === '#version') {
+    const parsedVersion = parseInt(words[1], 10);
+    if (Number.isFinite(parsedVersion)) {
+      version = parsedVersion;
+    }
+  }
+  if (version !== 100 && version !== 300) {
+    throw new Error(`Invalid GLSL version ${version}`);
+  }
+  return version;
+}

package/src/lib/glsl-utils/shader-utils.ts

@@ -0,0 +1,110 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+const FS_GLES = /* glsl */ `\
+out vec4 transform_output;
+void main() {
+  transform_output = vec4(0);
+}`;
+const FS300 = `#version 300 es\n${FS_GLES}`;
+
+type QualifierInfo = {
+  qualifier: string;
+  type: string;
+  name: string;
+};
+
+// Prase given glsl line and return qualifier details or null
+export function getQualifierDetails(
+  line: string,
+  qualifiers: string | string[]
+): QualifierInfo | null {
+  qualifiers = Array.isArray(qualifiers) ? qualifiers : [qualifiers];
+  const words = line.replace(/^\s+/, '').split(/\s+/);
+  // TODO add support for precession qualifiers (highp, mediump and lowp)
+  const [qualifier, type, definition] = words;
+  if (!qualifiers.includes(qualifier) || !type || !definition) {
+    return null;
+  }
+  const name = definition.split(';')[0];
+  return {qualifier, type, name};
+}
+
+/**
+ * Given the shader input and output variable names,
+ * builds and return a pass through fragment shader.
+ */
+export function getPassthroughFS(options?: {
+  input?: string;
+  inputChannels?: 1 | 2 | 3 | 4;
+  output?: string;
+}): string {
+  const {input, inputChannels, output} = options || {};
+  if (!input) {
+    // Default shader
+    return FS300;
+  }
+  if (!inputChannels) {
+    throw new Error('inputChannels');
+  }
+  const inputType = channelCountToType(inputChannels);
+  const outputValue = convertToVec4(input, inputChannels);
+  return `\
+#version 300 es
+in ${inputType} ${input};
+out vec4 ${output};
+void main() {
+  ${output} = ${outputValue};
+}`;
+}
+
+/** convert glsl type to suffix */
+export function typeToChannelSuffix(type: string): 'x' | 'xy' | 'xyz' | 'xyzw' {
+  // biome-ignore format: preserve layout
+  switch (type) {
+    case 'float': return 'x';
+    case 'vec2': return 'xy';
+    case 'vec3': return 'xyz';
+    case 'vec4': return 'xyzw';
+    default:
+      throw new Error(type);
+  }
+}
+
+/** convert glsl type to channel count */
+export function typeToChannelCount(type: string): 1 | 2 | 3 | 4 {
+  // biome-ignore format: preserve layout
+  switch (type) {
+    case 'float': return 1;
+    case 'vec2': return 2;
+    case 'vec3': return 3;
+    case 'vec4': return 4;
+    default:
+      throw new Error(type);
+  }
+}
+function channelCountToType(channels: 1 | 2 | 3 | 4): 'float' | 'vec2' | 'vec3' | 'vec4' {
+  // biome-ignore format: preserve layout
+  switch (channels) {
+    case 1: return 'float';
+    case 2: return 'vec2';
+    case 3: return 'vec3';
+    case 4: return 'vec4';
+    default:
+      throw new Error(`invalid channels: ${channels}`);
+  }
+}
+
+/** Returns glsl instruction for converting to vec4 */
+export function convertToVec4(variable: string, channels: 1 | 2 | 3 | 4): string {
+  // biome-ignore format: preserve layout
+  switch (channels) {
+    case 1: return `vec4(${variable}, 0.0, 0.0, 1.0)`;
+    case 2: return `vec4(${variable}, 0.0, 1.0)`;
+    case 3: return `vec4(${variable}, 1.0)`;
+    case 4: return variable;
+    default:
+      throw new Error(`invalid channels: ${channels}`);
+  }
+}