chore: refactor shader types (#2250) (#2250)

docs/README.mdx

@@ -52,20 +52,20 @@ Docs for older versions are available on github:
 
 luma.gl is a modern GPU toolkit for the Web, created to facilitate processing and visualization of big data.
 
-- **Portable GPU API** - for working with GPUs in JavaScript.
-- **TypeScript** - All APIs are rigorously typed.
-- **Pluggable backends** - for WebGPU and WebGL .
+- **Rendering and Compute** - for computing and rendering with GPUs in JavaScript.
+- **WebGPU and WebGL2** - support one or both via luma's pluggable backends.
 - **Engine-level classes** - `Model`, `Transform` and `AnimationLoop`, as well as scenegraph support.
-- **glTF** support.
-- **Shader management system** - supports shader modules, dependencies, injection etc.
+- **glTF and PBR** support for glTF models and physically based rendering.
+- **Shader management system** - supports shader modules, dependencies, injection, transpilation etc.
 - **Shader module library** - Pre-optimized moduls for compute, visual effects and post processing.
+- **TypeScript** - All APIs are rigorously typed.
 
-For 3D math and data loading, luma.gl uses companion framworks:
+luma.gl offers extensive support for 3D math and data loading through companion vis.gl framworks:
 
 - [**loaders.gl**](https://loaders.gl) - wide range of 3D and geospatial data format standards.
 - [**math.gl**](https://uber-web.github.io/math.gl/docs) - a variety of high precision geospatial and 3D math logic.
 
-luma.gl is intended to be a foundation on top of which to build higher-level GPU frameworks. The primary example is
+luma.gl is a great foundation for building higher-level GPU frameworks. The primary example is
 
 - [**deck.gl**](https://deck.gl) - geospatial GPU visualization and compute via a high-performance functional programming API.
 

examples/api/animation/app.ts

@@ -1,4 +1,4 @@
-import {UniformStore, ShaderUniformType} from '@luma.gl/core';
+import {UniformStore, VariableShaderType} from '@luma.gl/core';
 import {
   AnimationLoopTemplate,
   AnimationProps,
@@ -24,7 +24,7 @@ type AppUniforms = {
   uProjection: number[];
 };
 
-const app: {uniformTypes: Record<string, ShaderUniformType>} = {
+const app: {uniformTypes: Record<string, VariableShaderType>} = {
   uniformTypes: {
     uColor: 'vec3<f32>',
     uModel: 'mat4x4<f32>',

examples/showcase/persistence/app.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {NumberArray, ShaderUniformType} from '@luma.gl/core';
+import type {NumberArray, VariableShaderType} from '@luma.gl/core';
 import {UniformStore, Framebuffer} from '@luma.gl/core';
 import type {AnimationProps} from '@luma.gl/engine';
 import {
@@ -26,7 +26,7 @@ type SphereUniforms = {
   projectionMatrix: NumberArray;
 };
 
-const sphere: {uniformTypes: Record<keyof SphereUniforms, ShaderUniformType>} = {
+const sphere: {uniformTypes: Record<keyof SphereUniforms, VariableShaderType>} = {
   uniformTypes: {
     // TODO make sure order doesn't matter
     color: 'vec3<f32>',
@@ -133,7 +133,7 @@ type ScreenQuadUniforms = {
   resolution: NumberArray;
 };
 
-const screenQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, ShaderUniformType>} = {
+const screenQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, VariableShaderType>} = {
   uniformTypes: {
     resolution: 'vec2<f32>'
   }
@@ -216,7 +216,7 @@ type PersistenceQuadUniforms = {
   resolution: NumberArray;
 };
 
-const persistenceQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, ShaderUniformType>} = {
+const persistenceQuad: {uniformTypes: Record<keyof ScreenQuadUniforms, VariableShaderType>} = {
   uniformTypes: {
     resolution: 'vec2<f32>'
   }

examples/tutorials/hello-cube/app.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {NumberArray, ShaderUniformType} from '@luma.gl/core';
+import type {NumberArray, VariableShaderType} from '@luma.gl/core';
 import {Texture, UniformStore} from '@luma.gl/core';
 import type {AnimationProps} from '@luma.gl/engine';
 import {AnimationLoopTemplate, Model, CubeGeometry, loadImageBitmap, AsyncTexture} from '@luma.gl/engine';
@@ -97,7 +97,7 @@ type AppUniforms = {
   mvpMatrix: NumberArray;
 };
 
-const app: {uniformTypes: Record<keyof AppUniforms, ShaderUniformType>} = {
+const app: {uniformTypes: Record<keyof AppUniforms, VariableShaderType>} = {
   uniformTypes: {
     mvpMatrix: 'mat4x4<f32>'
   }

modules/constants/src/index.ts

@@ -16,7 +16,6 @@ export type {
   GLPixelType,
   GLUniformType,
   GLSamplerType,
-  GLCompositeType,
   GLFunction,
   GLBlendEquation,
   GLBlendFunction,

modules/constants/src/webgl-types.ts

@@ -98,9 +98,6 @@ export type GLPixelType =
   | GL.UNSIGNED_INT_24_8
   | GL.FLOAT_32_UNSIGNED_INT_24_8_REV;
 
-/** Uniform Type */
-export type GLUniformType = GLSamplerType | GLCompositeType;
-
 /**
  * Sampler uniform type
  * @note These are all the valid sampler types used with `gl.uniform1i((location, value)`
@@ -127,7 +124,7 @@ export type GLSamplerType =
  * @note These are all the valid non-sampler uniform types,
  * Different `gl.uniformXXX(location, value)` functions must be used depending on which composite type is being set.
  */
-export type GLCompositeType =
+export type GLUniformType =
   | GL.FLOAT
   | GL.FLOAT_VEC2
   | GL.FLOAT_VEC3

modules/core/src/adapter-utils/get-attribute-from-layouts.ts

@@ -3,12 +3,16 @@
 // Copyright (c) vis.gl contributors
 
 import {log} from '../utils/log';
+import type {PrimitiveDataType, NormalizedDataType} from '../shadertypes/data-types';
+import type {AttributeShaderType} from '../shadertypes/shader-types';
+import type {VertexFormat} from '../shadertypes/vertex-formats';
+import {getAttributeShaderTypeInfo} from '../shadertypes/utils/decode-shader-types';
+import {
+  getVertexFormatInfo,
+  getCompatibleVertexFormat
+} from '../shadertypes/utils/decode-vertex-format';
 import type {ShaderLayout, AttributeDeclaration} from '../adapter/types/shader-layout';
 import type {BufferLayout} from '../adapter/types/buffer-layout';
-import type {ShaderDataType, ShaderAttributeType} from '../gpu-type-utils/shader-types';
-import {decodeShaderAttributeType} from '../gpu-type-utils/decode-attribute-type';
-import type {VertexFormat, VertexType} from '../gpu-type-utils/vertex-formats';
-import {decodeVertexFormat} from '../gpu-type-utils/decode-vertex-format';
 
 /** Resolved info for a buffer / attribute combination to help backend configure it correctly */
 export type AttributeInfo = {
@@ -17,9 +21,9 @@ export type AttributeInfo = {
   /** Location in shader */
   location: number;
   /** Type / precision used in shader (buffer values may be converted) */
-  shaderType: ShaderAttributeType;
+  shaderType: AttributeShaderType;
   /** Calculations are done in this type in the shader's attribute declaration */
-  shaderDataType: ShaderDataType;
+  primitiveType: PrimitiveDataType;
   /** Components refer to the number of components in the shader's attribute declaration */
   shaderComponents: 1 | 2 | 3 | 4;
   /** It is the shader attribute declaration that determines whether GPU will process as integer or float */
@@ -30,7 +34,7 @@ export type AttributeInfo = {
   /** Format of buffer data */
   vertexFormat: VertexFormat;
   /** Memory data type refers to the data type in the buffer */
-  bufferDataType: VertexType;
+  bufferDataType: NormalizedDataType;
   /** Components refer to the number of components in the buffer's vertex format */
   bufferComponents: 1 | 2 | 3 | 4;
   /** Normalization is encoded in the buffer layout's vertex format... */
@@ -108,16 +112,17 @@ function getAttributeInfoFromLayouts(
     return null;
   }
 
-  const attributeTypeInfo = decodeShaderAttributeType(shaderDeclaration.type);
-  const vertexFormat = bufferMapping?.vertexFormat || attributeTypeInfo.defaultVertexFormat;
-  const vertexFormatInfo = decodeVertexFormat(vertexFormat);
+  const attributeTypeInfo = getAttributeShaderTypeInfo(shaderDeclaration.type);
+  const defaultVertexFormat = getCompatibleVertexFormat(attributeTypeInfo);
+  const vertexFormat = bufferMapping?.vertexFormat || defaultVertexFormat;
+  const vertexFormatInfo = getVertexFormatInfo(vertexFormat);
 
   return {
     attributeName: bufferMapping?.attributeName || shaderDeclaration.name,
     bufferName: bufferMapping?.bufferName || shaderDeclaration.name,
     location: shaderDeclaration.location,
     shaderType: shaderDeclaration.type,
-    shaderDataType: attributeTypeInfo.dataType,
+    primitiveType: attributeTypeInfo.primitiveType,
     shaderComponents: attributeTypeInfo.components,
     vertexFormat,
     bufferDataType: vertexFormatInfo.type,
@@ -212,7 +217,7 @@ function getAttributeFromAttributesList(
     // Calculate a default byte stride if not provided
     if (typeof bufferLayout.byteStride !== 'number') {
       for (const attributeMapping of bufferLayout.attributes || []) {
-        const info = decodeVertexFormat(attributeMapping.format);
+        const info = getVertexFormatInfo(attributeMapping.format);
         // @ts-ignore
         byteStride += info.byteLength;
       }

modules/core/src/adapter/canvas-context.ts

@@ -7,7 +7,7 @@ import type {Device} from './device';
 import type {Framebuffer} from './resources/framebuffer';
 import {log} from '../utils/log';
 import {uid} from '../utils/uid';
-import type {DepthStencilTextureFormat} from '../gpu-type-utils/texture-formats';
+import type {DepthStencilTextureFormat} from '../shadertypes/texture-formats';
 
 /** Properties for a CanvasContext */
 export type CanvasContextProps = {

modules/core/src/adapter/device.ts

@@ -5,7 +5,7 @@
 import {StatsManager, lumaStats} from '../utils/stats-manager';
 import {log} from '../utils/log';
 import {uid} from '../utils/uid';
-import type {TextureFormat} from '../gpu-type-utils/texture-formats';
+import type {TextureFormat, TextureFormatInfo} from '../shadertypes/texture-formats';
 import type {CanvasContext, CanvasContextProps} from './canvas-context';
 import type {BufferProps} from './resources/buffer';
 import {Buffer} from './resources/buffer';
@@ -23,14 +23,14 @@ import type {VertexArray, VertexArrayProps} from './resources/vertex-array';
 import type {TransformFeedback, TransformFeedbackProps} from './resources/transform-feedback';
 import type {QuerySet, QuerySetProps} from './resources/query-set';
 
-import type {ExternalImage} from '../image-utils/image-types';
-import {isExternalImage, getExternalImageSize} from '../image-utils/image-types';
 import {
   isTextureFormatCompressed,
-  decodeTextureFormat
-} from '../gpu-type-utils/decode-texture-format';
-import {getTextureFormatCapabilities} from '../gpu-type-utils/texture-format-capabilities';
-import type {TextureFormatInfo} from '../gpu-type-utils/texture-format-info';
+  getTextureFormatInfo,
+  getTextureFormatCapabilities
+} from '../shadertypes/utils/decode-texture-format';
+
+import type {ExternalImage} from '../image-utils/image-types';
+import {isExternalImage, getExternalImageSize} from '../image-utils/image-types';
 
 /**
  * Identifies the GPU vendor and driver.
@@ -395,7 +395,7 @@ export abstract class Device {
 
   /** Returns information about a texture format, such as data type, channels, bits per channel, compression etc */
   getTextureFormatInfo(format: TextureFormat): TextureFormatInfo {
-    return decodeTextureFormat(format);
+    return getTextureFormatInfo(format);
   }
 
   /** Determines what operations are supported on a texture format on this particular device (checks against supported device features) */

modules/core/src/adapter/resources/framebuffer.ts

@@ -6,7 +6,7 @@ import type {
   ColorTextureFormat,
   DepthStencilTextureFormat,
   TextureFormat
-} from '../../gpu-type-utils/texture-formats';
+} from '../../shadertypes/texture-formats';
 import type {Device} from '../device';
 import {Resource, ResourceProps} from './resource';
 import {Texture} from './texture';

modules/core/src/adapter/resources/render-pipeline.ts

@@ -10,7 +10,7 @@ import type {BufferLayout} from '../types/buffer-layout';
 import type {
   ColorTextureFormat,
   DepthStencilTextureFormat
-} from '@luma.gl/core/gpu-type-utils/texture-formats';
+} from '@luma.gl/core/shadertypes/texture-formats';
 import type {Shader} from './shader';
 import type {RenderPass} from './render-pass';
 import {Resource, ResourceProps} from './resource';

modules/core/src/adapter/resources/texture-view.ts

@@ -4,7 +4,7 @@
 
 import type {Device} from '../device';
 import type {Texture} from './texture';
-import type {TextureFormat} from '../../gpu-type-utils/texture-formats';
+import type {TextureFormat} from '../../shadertypes/texture-formats';
 import {Resource, ResourceProps} from './resource';
 
 /** Properties for initializing a texture view */

modules/core/src/adapter/resources/texture.ts

@@ -4,7 +4,7 @@
 
 import {TypedArray} from '@math.gl/types';
 import type {Device} from '../device';
-import type {TextureFormat} from '../../gpu-type-utils/texture-formats';
+import type {TextureFormat} from '../../shadertypes/texture-formats';
 import type {TextureView, TextureViewProps} from './texture-view';
 import {Resource, ResourceProps} from './resource';
 import {Sampler, SamplerProps} from './sampler';

modules/core/src/adapter/types/attachments.ts

@@ -6,7 +6,7 @@ import type {
   ColorTextureFormat,
   DepthStencilTextureFormat,
   TextureFormat
-} from '../../gpu-type-utils/texture-formats';
+} from '../../shadertypes/texture-formats';
 import type {Texture} from '../resources/texture'; // TextureView...
 import type {TextureView} from '../resources/texture-view'; // TextureView...
 

modules/core/src/adapter/types/buffer-layout.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {VertexFormat} from '../../gpu-type-utils/vertex-formats';
+import type {VertexFormat} from '../../shadertypes/vertex-formats';
 
 /**
  * Provides specific details about the memory layout of the actual buffers

modules/core/src/adapter/types/parameters.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 import {NumberArray4, NumberArray6} from '@math.gl/types';
-import {DepthStencilTextureFormat} from '../../gpu-type-utils/texture-formats';
+import {DepthStencilTextureFormat} from '../../shadertypes/texture-formats';
 
 export type CompareFunction =
   | 'never'

modules/core/src/adapter/types/shader-layout.ts

@@ -2,8 +2,8 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {TextureFormat} from '../../gpu-type-utils/texture-formats';
-import type {ShaderUniformType, ShaderAttributeType} from '../../gpu-type-utils/shader-types';
+import type {TextureFormat} from '../../shadertypes/texture-formats';
+import type {VariableShaderType, AttributeShaderType} from '../../shadertypes/shader-types';
 import type {Buffer} from '../resources/buffer';
 import type {Sampler} from '../resources/sampler';
 import type {Texture} from '../resources/texture';
@@ -56,7 +56,7 @@ export type AttributeDeclaration = {
   /** The index into the GPU's vertex array buffer bank (usually between 0-15) */
   location: number;
   /** WebGPU-style shader type. The declared format of the attribute in the shader code. Buffer's vertex format needs to map to this. */
-  type: ShaderAttributeType;
+  type: AttributeShaderType;
   /** Inferred from attribute name. @note Technically not part of static structure of shader */
   stepMode?: 'vertex' | 'instance';
 };
@@ -89,7 +89,7 @@ export type UniformBufferBindingLayout = {
 
 export type UniformInfo = {
   name: string;
-  format: ShaderUniformType;
+  format: VariableShaderType;
   type?: string;
   arrayLength: number;
   byteOffset: number;
@@ -172,7 +172,7 @@ export type Binding =
 export type VaryingBinding = {
   location: number;
   name: string;
-  type: number; // glType
+  type: AttributeShaderType;
   size: number;
 };