@luma.gl/core 9.0.0-alpha.9 → 9.0.0-beta.2

package/src/adapter/types/accessor.ts

@@ -0,0 +1,34 @@
+// luma.gl, MIT license
+import type {Buffer} from '../resources/buffer';
+// import type {VertexFormat} from './data-formats';
+
+// ACCESSORS
+
+/**
+ * Attribute descriptor object
+ * @deprecated Use ShaderLayout
+ */
+export interface AccessorObject {
+  buffer?: Buffer;
+  // format: VertexFormat;
+  offset?: number;
+  // can now be described with single WebGPU-style `format` string
+
+  // 
+  stride?: number;
+
+  /** @deprecated - Use accessor.stepMode */
+  divisor?: number;
+
+  /** @deprecated - Infer from format */
+  type?: number;
+  /** @deprecated - Infer from format */
+  size?: number;
+  /** @deprecated - Infer from format */
+  normalized?: boolean;
+  /** @deprecated - Infer from format */
+  integer?: boolean;
+
+  /** @deprecated */
+  index?: number;
+}

package/src/adapter/types/buffer-layout.ts

@@ -0,0 +1,62 @@
+import type {VertexFormat} from './vertex-formats';
+
+/** 
+ * Provides specific details about the memory layout of the actual buffers 
+ * that will be provided to a `RenderPipeline`.
+ *  
+ * BufferLayout lets the application describe whether
+ * - A single buffer can be used for multiple attributes (using interleaving or offsets), 
+ * - The data format of the memory being supplied to a specific shader attribute.
+ * 
+ * `BufferLayout` complements the "static" attribute declarations in a ShaderLayout 
+ * with information about the "dynamic" memory layout of each buffer that will be bound 
+ * to the render pipeline.
+ */
+
+/** 
+ * Specify memory layout for one buffer, describing how it is used by one or more attribute
+ * @note Specifies format, stride, offset and step mode
+ * @note The buffer can be set using the buffer name:`.setAttributes({[bufferName]: buffer})`.
+ * @note Needs to match type/components of the ShaderLayout ('f32', 'i32', 's32')
+ *
+ * A buffer layout is used to specify "non-standard" buffer layouts (buffers with offsets, interleaved buffers etc)
+ *
+ * @example
+ * ```
+  device.createRenderPipeline({
+    ...
+    shaderLayout,
+    bufferLayout: [
+      {name: 'positions', stepMode: 'vertex', format: 'float32x3'},
+      // interleaved bindings, auto offset
+      {name: 'particles', stepMode: 'instance', byteStride: 32, attributes: [
+        {name: 'instancePositions', format: 'float32x4', byteOffset: 0},
+        {name: 'instanceVelocities', format: 'float32x4', byteOffset: 16}
+      ]},
+    ]
+  ];
+  ```
+  */
+export type BufferLayout = {
+  /** Name of buffer */
+  name: string;
+  /** Is the attribute is instanced. Default: auto-deduced from shader name. */
+  stepMode?: 'vertex' | 'instance';
+  /** bytes between successive elements. If omitted, stride is set to reflect a "packed" buffer */
+  byteStride?: number;
+  /** Option 1: interleaved attributes that read from this buffer */
+  attributes?: BufferAttributeLayout[];
+  /** Option 2: Single attribute with same name as buffer. */
+  format?: VertexFormat;
+};
+
+/** Specifies how the GPU should read one specific attribute from a buffer.  */
+export type BufferAttributeLayout = {
+  /** Name of attribute that maps to a "view" of this buffer */
+  attribute: string;
+  /** Data format of the memory in the buffer that is mapped to this attribute */
+  format: VertexFormat;
+  /** Sum up any the "global" offset (or 0) and the offset each stride (for interleaved data). */
+  byteOffset: number;
+};
+

package/src/adapter/types/parameters.ts

@@ -0,0 +1,250 @@
+import {DepthStencilTextureFormat} from './texture-formats';
+
+export type CompareFunction =
+  'never' |
+  'less' |
+  'equal' |
+  'less-equal' |
+  'greater' |
+  'not-equal' |
+  'greater-equal' |
+  'always';
+
+// Primitive state
+
+export type PrimitiveTopology =
+  'point-list' |
+  'line-list' |
+  'line-strip' |
+  /** @deprecated */
+  'line-loop-webgl' |
+  'triangle-list' |
+  'triangle-strip' |
+  /** @deprecated */
+  'triangle-fan-webgl';
+
+export type IndexFormat = 'uint16' | 'uint32';
+
+export type CullMode = 'none' | 'front' | 'back';
+export type FrontFace = 'ccw' | 'cw';
+
+// Rasterization Parameters
+
+type _RenderParameters = {
+  /** Defines which polygon orientation will be culled, if any. Only applies to triangle topologies/ */
+  cullMode?: CullMode;
+  /** Defines which polygons are considered front-facing. Only applies to triangle topologies. Default to "ccw" */
+  frontFace?: FrontFace;
+  /** TBD */
+  depthClamp?: boolean;
+  /** Constant depth bias (polygon offset) added to each fragment. */
+  depthBias?: number;
+  /** Depth bias (polygon offset) that scales with the fragment’s slope. */
+  depthBiasSlopeScale?: number;
+  /** Maximum depth bias of a fragment. */
+  depthBiasClamp?: number;
+}
+
+export type RasterizationParameters = _RenderParameters & {
+  /** The type of primitive to be constructed from the vertex inputs. Defaults to "triangle-list". */
+  topology?: PrimitiveTopology;
+  /** For pipelines with strip topologies ("line-strip" or "triangle-strip"), this determines the index buffer format and primitive restart value ("uint16"/0xFFFF or "uint32"/0xFFFFFFFF). It is not allowed on pipelines with non-strip topologies. */
+  stripIndexFormat?: IndexFormat; // WebGPU only
+}
+
+// Depth Stencil Parameters
+
+/** Types of operations that can be performed on stencil buffers when various tests pass */
+export type StencilOperation =
+  'keep' |
+  'zero' |
+  'replace' |
+  'invert' |
+  'increment-clamp' |
+  'decrement-clamp' |
+  'increment-wrap' |
+  'decrement-wrap';
+
+export type DepthStencilParameters = {
+  /** Whether this GPURenderPipeline can modify depthStencilAttachment depth values. */
+  depthWriteEnabled?: boolean;
+  /** The comparison operation used to test fragment depths against existing depthStencilAttachment depth values. */
+  depthCompare?: CompareFunction;
+  /** The format of depthStencilAttachment this GPURenderPipeline will be compatible with. */
+  depthFormat?: DepthStencilTextureFormat;
+
+  /** Bitmask controlling which depthStencilAttachment stencil value bits are read when performing stencil comparison tests. */
+  stencilReadMask?: number;
+  /** Bitmask controlling which depthStencilAttachment stencil value bits are written to when performing stencil operations. */
+  stencilWriteMask?: number;
+
+  /** The CompareFunction used when testing fragments against depthStencilAttachment stencil values. */
+  stencilCompare?: CompareFunction;
+  /** The StencilOperation performed if the fragment stencil comparison test described by compare fails. */
+  stencilPassOperation?: StencilOperation;
+  /** The GPUStencilOperation performed if the fragment depth comparison described by depthCompare fails. */
+  stencilFailOperation?: StencilOperation;
+  /** The GPUStencilOperation performed if the fragment stencil comparison test described by compare passes. */
+  stencilDepthFailOperation?: StencilOperation;
+}
+
+// Color Parameters
+
+/** BlendFactor defines how either a source or destination blend factors is calculated */
+export type BlendFactor =
+  'zero' |
+  'one' |
+  'src-color' |
+  'one-minus-src-color' |
+  'src-alpha' |
+  'one-minus-src-alpha' |
+  'dst-color' |
+  'one-minus-dst-color' |
+  'dst-alpha' |
+  'one-minus-dst-alpha' |
+  'src-alpha-saturated' |
+  'blend-color' |
+  'one-minus-blend-color';
+
+/** BlendOperation defines the algorithm used to combine source and destination blend factors: */
+export type BlendOperation =
+  'add' |
+  'subtract' |
+  'reverse-subtract' |
+  'min' |
+  'max';
+
+/*
+export const ColorWrite = {
+  RED: 0x1,
+  GREEN: 0x2,
+  BLUE: 0x4,
+  ALPHA: 0x8,
+  ALL: 0xF
+};
+
+blend: {
+  color: {operation, srcFactor, dstFactor}
+  alpha: {operation, srcFactor, dstFactor}
+}
+colorWriteMask
+
+rgba
+rgb
+rga
+rba
+gba
+rg
+rb
+ra
+gb
+ga
+ba
+r
+g
+b
+a
+none
+*/
+
+/* Color parameters are set on the RenderPipeline */
+export type ColorParameters = {
+  /** Defines the operation used to calculate the values written to the target attachment components. */
+  blendColorOperation?: BlendOperation;
+  /** Defines the operation to be performed on values from the fragment shader. */
+  blendColorSrcFactor?: BlendFactor;
+  /** Defines the operation to be performed on values from the target attachment. */
+  blendColorDstFactor?: BlendFactor;
+
+  /** Defines the operation used to calculate the values written to the target attachment components. */
+  blendAlphaOperation?: BlendOperation;
+  /** Defines the operation to be performed on values from the fragment shader. */
+  blendAlphaSrcFactor?: BlendFactor;
+  /** Defines the operation to be performed on values from the target attachment. */
+  blendAlphaDstFactor?: BlendFactor;
+
+  /** Bitmask controlling which channels are are written to when drawing to this color target. defaulting to 0xF */
+  colorMask?: number;
+}
+
+/** Multisample */
+export type MultisampleParameters = {
+  /** Number of samples per pixel. RenderPipeline will be compatible only with attachment textures with matching sampleCounts. */
+  sampleCount?: number; //  = 1;
+  /** Mask determining which samples are written to. defaulting to 0xFFFFFFFF */
+  sampleMask?: number; 
+  /** When true indicates that a fragment’s alpha channel should be used to generate a sample coverage mask. */
+  sampleAlphaToCoverageEnabled?: boolean; //  = false;
+};
+
+/** These parameters are set on the render pass and are thus easy to change frequently */
+export type RenderPassParameters = {
+  /** Linear map from normalized device coordinates to viewport coordinates [x, y, width, height, minDepth, maxDepth] */
+  viewport?: number[]; 
+  /** Sets scissor rectangle used during rasterization. Discards fragments outside viewport coords [x, y, width, height]. */
+  scissorRect?: number[]; // ;
+  /** Sets constant blend color and alpha values used with "constant" and "one-minus-constant" blend factors. */
+  blendConstant?: number[]; // GPUColor
+  /** Stencil operation "replace" sets the value to stencilReference */
+  stencilReference?: number; // GPUStencilValue
+};
+
+export type RenderPipelineParameters =
+  RasterizationParameters &
+  DepthStencilParameters &
+  ColorParameters &
+  MultisampleParameters;
+
+export type Parameters =
+  _RenderParameters &
+  DepthStencilParameters &
+  ColorParameters &
+  MultisampleParameters;
+
+// export const DEFAULT_PARAMETERS: Parameters;
+
+export const DEFAULT_PARAMETERS: Required<Parameters> = {
+
+  // Rasterization Parameters
+
+  cullMode: 'none',
+  frontFace: 'ccw',
+
+  // Depth Parameters
+
+  depthWriteEnabled: false,
+  depthCompare: 'always',
+  depthFormat: 'depth24plus',
+
+  depthClamp: false,
+  depthBias: 0,
+  depthBiasSlopeScale: 0,
+  depthBiasClamp: 0,
+
+  // Stencil parameters
+
+  stencilReadMask: 0xFFFFFFFF,
+  stencilWriteMask: 0xFFFFFFFF,
+
+  stencilCompare: 'always',
+  stencilPassOperation: 'keep',
+  stencilFailOperation: 'keep',
+  stencilDepthFailOperation: 'keep',
+
+  // Multisample parameters
+  sampleCount: 0,
+  sampleMask: 0xFFFFFFFF,
+  sampleAlphaToCoverageEnabled: false,
+
+  // Color and blend parameters
+
+  blendColorOperation: 'add',
+  blendColorSrcFactor: 'one',
+  blendColorDstFactor: 'zero',
+
+  blendAlphaOperation: 'add',
+  blendAlphaSrcFactor: 'one',
+  blendAlphaDstFactor: 'zero',
+
+  colorMask: 0xF
+};

package/src/adapter/types/shader-layout.ts

@@ -0,0 +1,193 @@
+// luma.gl, MIT license
+import type {TextureFormat} from '../types/texture-formats';
+import type {ShaderUniformType, ShaderAttributeType} from './shader-types';
+import {AccessorObject} from '../types/accessor';
+import type {Buffer} from '../resources/buffer';
+import type {Sampler} from '../resources/sampler';
+import type {Texture} from '../resources/texture';
+
+/**
+ * Describes all shader binding points for a `RenderPipeline` or `ComputePipeline`
+ * A ShaderLayout describes the static structure of a shader pipeline.
+ * It also allows the numeric locations in the shader to accessed with the same variable names
+ * used in the shader.
+ * @note A ShaderLayout needs to be complemented by a BufferLayout that describes 
+ * the actual memory layout of the buffers that will be used with the pipeline.
+ * 
+ * @example
+ * ```
+  device.createRenderPipeline({
+    shaderLayout: [
+      attributes: [
+        {name: 'instancePositions', location: 0, format: 'vec3<f32>', stepMode: 'instance'},
+        {name: 'instanceVelocities', location: 1, format: 'vec3<f32>', stepMode: 'instance'},
+        {name: 'vertexPositions', location: 2, format: 'vec3<f32>', stepMode: 'vertex'}
+      ],
+      bindings: [...]
+    ]
+  })
+ * ```
+ */
+export type ShaderLayout = {
+  /** All attributes, their locations, and basic type information. Also an auto-deduced step mode */
+  attributes: AttributeDeclaration[];
+  /** All bidning points (textures, samplers, uniform buffers) with their locations and type */
+  bindings: BindingDeclaration[];
+  /** WebGL only (WebGPU use bindings and uniform buffers) */
+  uniforms?: any[];
+  /** WebGL2 only (WebGPU use compute shaders) */
+  varyings?: VaryingBinding[];
+};
+
+/**
+ * Declares one for attributes
+ */
+export type AttributeDeclaration = {
+  /** The name of this attribute in the shader */
+  name: string;
+  /** 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;
+  /** Inferred from attribute name. @note Technically not part of static structure of shader */
+  stepMode?: 'vertex' | 'instance';
+};
+
+// BINDING LAYOUTS
+
+/*
+type Binding = {
+  binding: number;
+  visibility: number;
+
+  buffer?: {
+    type?: 'uniform' | 'storage' | 'read-only-storage';
+    hasDynamicOffset?: false;
+    minBindingSize?: number;
+  };
+
+  // type = sampler
+  samplerType?: 'filtering' | 'non-filtering' | 'comparison';
+
+  // type = texture
+  viewDimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
+  sampleType?: 'float' | 'unfilterable-float' | 'depth' | 'sint' | 'uint';
+  multisampled?: boolean;
+
+  // type = storage
+  viewDimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
+  access: 'read-only' | 'write-only';
+  format: string;
+};
+*/
+
+/** ShaderLayout for bindings */
+export type BindingDeclaration =
+  | UniformBufferBindingLayout
+  | BufferBindingLayout
+  | TextureBindingLayout
+  | SamplerBindingLayout
+  | StorageTextureBindingLayout;
+
+export type UniformBufferBindingLayout = {
+  type: 'uniform';
+  name: string;
+  location: number;
+  visibility?: number;
+  hasDynamicOffset?: boolean;
+  minBindingSize?: number;
+  uniforms?: UniformInfo[];
+};
+
+export type UniformInfo = {
+  name: string;
+  format: ShaderUniformType;
+  type?: string;
+  arrayLength: number;
+  byteOffset: number;
+  byteStride: number;
+};
+
+export type BufferBindingLayout = {
+  type: 'uniform' | 'storage' | 'read-only-storage';
+  name: string;
+  location: number;
+  visibility?: number;
+  hasDynamicOffset?: boolean;
+  minBindingSize?: number;
+};
+
+type TextureBindingLayout = {
+  type: 'texture';
+  name: string;
+  location: number;
+  visibility?: number;
+  viewDimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d'; // default: '2d'
+  sampleType?: 'float' | 'unfilterable-float' | 'depth' | 'sint' | 'uint'; // default: 'float'
+  multisampled?: boolean;
+};
+
+type SamplerBindingLayout = {
+  type: 'sampler';
+  name: string;
+  location: number;
+  visibility?: number;
+  samplerType?: 'filtering' | 'non-filtering' | 'comparison'; // default: filtering
+};
+
+type StorageTextureBindingLayout = {
+  type: 'storage';
+  name: string;
+  location: number;
+  visibility?: number;
+  access?: 'write-only';
+  format: TextureFormat;
+  viewDimension?: '1d' | '2d' | '2d-array' | 'cube' | 'cube-array' | '3d';
+};
+
+// BINDINGS
+
+/** Binding value */
+export type Binding = Texture | Sampler | Buffer | {buffer: Buffer; offset?: number; size?: number};
+
+// SHADER LAYOUTS
+
+/**
+ * Describes a varying binding for a program
+ * @deprecated Varyings are WebGL-only
+ */
+export type VaryingBinding = {
+  location: number;
+  name: string;
+  accessor: AccessorObject;
+};
+
+// Uniform bindings
+
+/** Describes a uniform block binding for a program */
+export type UniformBlockBinding = {
+  location: number;
+  name: string;
+  byteLength: number;
+  vertex: boolean;
+  fragment: boolean;
+  uniformCount: number;
+  uniformIndices?: number[];
+  uniforms: UniformInfo[];
+};
+
+/** Describes a uniform (sampler etc) binding for a program */
+export type UniformBinding = {
+  location: number;
+  name: string;
+  size: number;
+  type: number;
+  isArray: boolean;
+};
+
+/** @deprecated */
+export type AttributeBinding = {
+  name: string;
+  location: number;
+  accessor: AccessorObject;
+};

package/src/adapter/types/shader-types.ts

@@ -0,0 +1,77 @@
+// luma.gl, MIT license
+// Copyright (c) vis.gl contributors
+
+/**
+ * Primitive data types understood by shaders
+ * @note These types describe the type used in shader calculations, but for attribute inputs these can be populated from a different in-memory type.
+ * @note bindings (like textures, samplers, and uniform buffers) are considered "bindings", not types
+ * @note `f16` requires the `f16` extension
+ */
+export type ShaderDataType = 'u32' | 'i32' | 'f32' | 'f16';
+
+/**
+ * Describes the type of an attribute as defined in the shader source code.
+ * @note Buffers with various `VertexFormat`s can be supplied for each type, and the GPU will convert them at runtime,
+ * but there are limitations, see documentation for details.
+ */
+export type ShaderAttributeType =
+  | 'f32'
+  | 'vec2<f32>'
+  | 'vec3<f32>'
+  | 'vec4<f32>'
+  | 'i32'
+  | 'vec2<i32>'
+  | 'vec3<i32>'
+  | 'vec4<i32>'
+  | 'u32'
+  | 'vec2<u32>'
+  | 'vec3<u32>'
+  | 'vec4<u32>'
+  // requires `f16` extension
+  | 'f16'
+  | 'vec2<f16>'
+  | 'vec3<f16>'
+  | 'vec4<f16>';
+
+/**
+ * Describes the type of a uniform as described in the shader source code.
+ * Uniforms can be of a wider range of types than attributes.
+ */
+export type ShaderUniformType =
+  | 'f32'
+  | 'i32'
+  | 'u32'
+  | 'vec2<f32>'
+  | 'vec3<f32>'
+  | 'vec4<f32>'
+  | 'vec2<i32>'
+  | 'vec3<i32>'
+  | 'vec4<i32>'
+  | 'vec2<u32>'
+  | 'vec3<u32>'
+  | 'vec4<u32>'
+  | 'mat2x2<f32>'
+  | 'mat2x3<f32>'
+  | 'mat2x4<f32>'
+  | 'mat3x2<f32>'
+  | 'mat3x3<f32>'
+  | 'mat3x4<f32>'
+  | 'mat4x2<f32>'
+  | 'mat4x3<f32>'
+  | 'mat4x4<f32>';
+
+/** Shorthand type aliases recognized by WGSL */
+export type ShaderTypeAlias =
+  | 'vec2i'
+  | 'vec3i'
+  | 'vec4i'
+  | 'vec2u'
+  | 'vec3u'
+  | 'vec4u'
+  | 'vec2f'
+  | 'vec3f'
+  | 'vec4f'
+  // Requires the f16 extension.
+  | 'vec2h'
+  | 'vec3h'
+  | 'vec4h';