@luma.gl/core 9.1.9 → 9.2.0-alpha.3

package/src/shadertypes/data-types/decode-data-types.ts

@@ -0,0 +1,91 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TypedArray, TypedArrayConstructor} from '../../types';
+import {PrimitiveDataType, SignedDataType, NormalizedDataType, DataTypeInfo} from './data-types';
+
+/**
+ * Gets info about a data type constant (signed or normalized)
+ * @returns underlying primitive / signed types, byte length, normalization, integer, signed flags
+ */
+export function getDataTypeInfo(type: NormalizedDataType): DataTypeInfo {
+  const [signedType, primitiveType, byteLength] = NORMALIZED_TYPE_MAP[type];
+  const normalized: boolean = type.includes('norm');
+  const integer: boolean = !normalized && !type.startsWith('float');
+  const signed: boolean = type.startsWith('s');
+  return {
+    signedType,
+    primitiveType,
+    byteLength,
+    normalized,
+    integer,
+    signed
+  };
+}
+
+/** Build a vertex format from a signed data type and a component */
+export function getNormalizedDataType(signedDataType: SignedDataType): NormalizedDataType {
+  const dataType: NormalizedDataType = signedDataType;
+  // prettier-ignore
+  switch (dataType) {
+    case 'uint8': return 'unorm8';
+    case 'sint8': return 'snorm8';
+    case 'uint16': return 'unorm16';
+    case 'sint16': return 'snorm16';
+    default: return dataType;
+  }
+}
+
+/** Align offset to 1, 2 or 4 elements (4, 8 or 16 bytes) */
+export function alignTo(size: number, count: number): number {
+  // prettier-ignore
+  switch (count) {
+    case 1: return size; // Pad upwards to even multiple of 2
+    case 2: return size + (size % 2); // Pad upwards to even multiple of 2
+    default: return size + ((4 - (size % 4)) % 4); // Pad upwards to even multiple of 4
+  }
+}
+
+/** Returns the VariableShaderType that corresponds to a typed array */
+export function getDataType(arrayOrType: TypedArray | TypedArrayConstructor): SignedDataType {
+  const Constructor = ArrayBuffer.isView(arrayOrType) ? arrayOrType.constructor : arrayOrType;
+  if (Constructor === Uint8ClampedArray) {
+    return 'uint8';
+  }
+  const info = Object.values(NORMALIZED_TYPE_MAP).find(entry => Constructor === entry[4]);
+  if (!info) {
+    throw new Error(Constructor.name);
+  }
+  return info[0];
+}
+
+/** Returns the TypedArray that corresponds to a shader data type */
+export function getTypedArrayConstructor(type: NormalizedDataType): TypedArrayConstructor {
+  const [, , , , Constructor] = NORMALIZED_TYPE_MAP[type];
+  return Constructor;
+}
+
+const NORMALIZED_TYPE_MAP: Record<
+  NormalizedDataType,
+  [
+    SignedDataType,
+    PrimitiveDataType,
+    bytes: 1 | 2 | 4,
+    normalized: boolean,
+    arrayConstructor: TypedArrayConstructor
+  ]
+> = {
+  uint8: ['uint8', 'u32', 1, false, Uint8Array],
+  sint8: ['sint8', 'i32', 1, false, Int8Array],
+  unorm8: ['uint8', 'f32', 1, true, Uint8Array],
+  snorm8: ['sint8', 'f32', 1, true, Int8Array],
+  uint16: ['uint16', 'u32', 2, false, Uint16Array],
+  sint16: ['sint16', 'i32', 2, false, Int16Array],
+  unorm16: ['uint16', 'u32', 2, true, Uint16Array],
+  snorm16: ['sint16', 'i32', 2, true, Int16Array],
+  float16: ['float16', 'f16', 2, false, Uint16Array],
+  float32: ['float32', 'f32', 4, false, Float32Array],
+  uint32: ['uint32', 'u32', 4, false, Uint32Array],
+  sint32: ['sint32', 'i32', 4, false, Int32Array]
+};

package/src/shadertypes/data-types/decode-shader-types.ts

@@ -0,0 +1,211 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {PrimitiveDataType} from './data-types';
+import type {
+  VariableShaderType,
+  AttributeShaderType,
+  AttributeShaderTypeInfo,
+  VariableShaderTypeAlias,
+  AttributeShaderTypeAlias
+} from './shader-types';
+
+/** Split a uniform type string into type and components */
+export function getVariableShaderTypeInfo(format: VariableShaderType): {
+  type: PrimitiveDataType;
+  components: number;
+} {
+  const decoded = UNIFORM_FORMATS[format];
+  return decoded;
+}
+
+/** Decodes a vertex type, returning byte length and flags (integer, signed, normalized) */
+export function getAttributeShaderTypeInfo(
+  attributeType: AttributeShaderType
+): AttributeShaderTypeInfo {
+  const [primitiveType, components] = TYPE_INFO[attributeType];
+  const integer: boolean = primitiveType === 'i32' || primitiveType === 'u32';
+  const signed: boolean = primitiveType !== 'u32';
+
+  const byteLength = PRIMITIVE_TYPE_SIZES[primitiveType] * components;
+  return {
+    primitiveType,
+    components,
+    byteLength,
+    integer,
+    signed
+  };
+}
+
+export function makeShaderAttributeType(
+  primitiveType: PrimitiveDataType,
+  components: 1 | 2 | 3 | 4
+): AttributeShaderType {
+  return components === 1 ? primitiveType : `vec${components}<${primitiveType}>`;
+}
+
+export function resolveAttributeShaderTypeAlias(
+  alias: AttributeShaderTypeAlias | AttributeShaderType
+): AttributeShaderType {
+  return WGSL_ATTRIBUTE_TYPE_ALIAS_MAP[alias as AttributeShaderTypeAlias] || alias;
+}
+
+export function resolveVariableShaderTypeAlias(
+  alias: VariableShaderTypeAlias | VariableShaderType
+): VariableShaderType {
+  return WGSL_VARIABLE_TYPE_ALIAS_MAP[alias as VariableShaderTypeAlias] || alias;
+}
+
+// TABLES
+
+const PRIMITIVE_TYPE_SIZES: Record<PrimitiveDataType, 2 | 4> = {
+  f32: 4,
+  f16: 2,
+  i32: 4,
+  u32: 4
+  // 'bool-webgl': 4,
+};
+
+/** All valid shader attribute types. A table guarantees exhaustive list and fast execution */
+const TYPE_INFO: Record<AttributeShaderType, [PrimitiveDataType, components: 1 | 2 | 3 | 4]> = {
+  f32: ['f32', 1],
+  'vec2<f32>': ['f32', 2],
+  'vec3<f32>': ['f32', 3],
+  'vec4<f32>': ['f32', 4],
+  f16: ['f16', 1],
+  'vec2<f16>': ['f16', 2],
+  'vec3<f16>': ['f16', 3],
+  'vec4<f16>': ['f16', 4],
+  i32: ['i32', 1],
+  'vec2<i32>': ['i32', 2],
+  'vec3<i32>': ['i32', 3],
+  'vec4<i32>': ['i32', 4],
+  u32: ['u32', 1],
+  'vec2<u32>': ['u32', 2],
+  'vec3<u32>': ['u32', 3],
+  'vec4<u32>': ['u32', 4]
+};
+
+/** @todo These tables are quite big, consider parsing type strings instead */
+const UNIFORM_FORMATS: Record<VariableShaderType, {type: PrimitiveDataType; components: number}> = {
+  f32: {type: 'f32', components: 1},
+  f16: {type: 'f16', components: 1},
+  i32: {type: 'i32', components: 1},
+  u32: {type: 'u32', components: 1},
+  // 'bool-webgl': {type: 'bool-webgl', components: 1},
+  'vec2<f32>': {type: 'f32', components: 2},
+  'vec3<f32>': {type: 'f32', components: 3},
+  'vec4<f32>': {type: 'f32', components: 4},
+  'vec2<f16>': {type: 'f16', components: 2},
+  'vec3<f16>': {type: 'f16', components: 3},
+  'vec4<f16>': {type: 'f16', components: 4},
+  'vec2<i32>': {type: 'i32', components: 2},
+  'vec3<i32>': {type: 'i32', components: 3},
+  'vec4<i32>': {type: 'i32', components: 4},
+  'vec2<u32>': {type: 'u32', components: 2},
+  'vec3<u32>': {type: 'u32', components: 3},
+  'vec4<u32>': {type: 'u32', components: 4},
+
+  'mat2x2<f32>': {type: 'f32', components: 4},
+  'mat2x3<f32>': {type: 'f32', components: 6},
+  'mat2x4<f32>': {type: 'f32', components: 8},
+  'mat3x2<f32>': {type: 'f32', components: 6},
+  'mat3x3<f32>': {type: 'f32', components: 9},
+  'mat3x4<f32>': {type: 'f32', components: 12},
+  'mat4x2<f32>': {type: 'f32', components: 8},
+  'mat4x3<f32>': {type: 'f32', components: 12},
+  'mat4x4<f32>': {type: 'f32', components: 16},
+
+  'mat2x2<f16>': {type: 'f16', components: 4},
+  'mat2x3<f16>': {type: 'f16', components: 6},
+  'mat2x4<f16>': {type: 'f16', components: 8},
+  'mat3x2<f16>': {type: 'f16', components: 6},
+  'mat3x3<f16>': {type: 'f16', components: 9},
+  'mat3x4<f16>': {type: 'f16', components: 12},
+  'mat4x2<f16>': {type: 'f16', components: 8},
+  'mat4x3<f16>': {type: 'f16', components: 12},
+  'mat4x4<f16>': {type: 'f16', components: 16},
+
+  'mat2x2<i32>': {type: 'i32', components: 4},
+  'mat2x3<i32>': {type: 'i32', components: 6},
+  'mat2x4<i32>': {type: 'i32', components: 8},
+  'mat3x2<i32>': {type: 'i32', components: 6},
+  'mat3x3<i32>': {type: 'i32', components: 9},
+  'mat3x4<i32>': {type: 'i32', components: 12},
+  'mat4x2<i32>': {type: 'i32', components: 8},
+  'mat4x3<i32>': {type: 'i32', components: 12},
+  'mat4x4<i32>': {type: 'i32', components: 16},
+
+  'mat2x2<u32>': {type: 'u32', components: 4},
+  'mat2x3<u32>': {type: 'u32', components: 6},
+  'mat2x4<u32>': {type: 'u32', components: 8},
+  'mat3x2<u32>': {type: 'u32', components: 6},
+  'mat3x3<u32>': {type: 'u32', components: 9},
+  'mat3x4<u32>': {type: 'u32', components: 12},
+  'mat4x2<u32>': {type: 'u32', components: 8},
+  'mat4x3<u32>': {type: 'u32', components: 12},
+  'mat4x4<u32>': {type: 'u32', components: 16}
+};
+
+/**  Predeclared aliases @see https://www.w3.org/TR/WGSL/#vector-types */
+export const WGSL_ATTRIBUTE_TYPE_ALIAS_MAP: Record<AttributeShaderTypeAlias, AttributeShaderType> =
+  {
+    vec2i: 'vec2<i32>',
+    vec3i: 'vec3<i32>',
+    vec4i: 'vec4<i32>',
+    vec2u: 'vec2<u32>',
+    vec3u: 'vec3<u32>',
+    vec4u: 'vec4<u32>',
+    vec2f: 'vec2<f32>',
+    vec3f: 'vec3<f32>',
+    vec4f: 'vec4<f32>',
+    // Requires the f16 extension.
+    vec2h: 'vec2<f16>',
+    vec3h: 'vec3<f16>',
+    vec4h: 'vec4<f16>'
+  };
+
+/** @todo These tables are quite big, consider parsing alias strings instead */
+export const WGSL_VARIABLE_TYPE_ALIAS_MAP: Record<VariableShaderTypeAlias, VariableShaderType> = {
+  ...WGSL_ATTRIBUTE_TYPE_ALIAS_MAP,
+  mat2x2f: 'mat2x2<f32>',
+  mat2x3f: 'mat2x3<f32>',
+  mat2x4f: 'mat2x4<f32>',
+  mat3x2f: 'mat3x2<f32>',
+  mat3x3f: 'mat3x3<f32>',
+  mat3x4f: 'mat3x4<f32>',
+  mat4x2f: 'mat4x2<f32>',
+  mat4x3f: 'mat4x3<f32>',
+  mat4x4f: 'mat4x4<f32>',
+
+  mat2x2i: 'mat2x2<i32>',
+  mat2x3i: 'mat2x3<i32>',
+  mat2x4i: 'mat2x4<i32>',
+  mat3x2i: 'mat3x2<i32>',
+  mat3x3i: 'mat3x3<i32>',
+  mat3x4i: 'mat3x4<i32>',
+  mat4x2i: 'mat4x2<i32>',
+  mat4x3i: 'mat4x3<i32>',
+  mat4x4i: 'mat4x4<i32>',
+
+  mat2x2u: 'mat2x2<u32>',
+  mat2x3u: 'mat2x3<u32>',
+  mat2x4u: 'mat2x4<u32>',
+  mat3x2u: 'mat3x2<u32>',
+  mat3x3u: 'mat3x3<u32>',
+  mat3x4u: 'mat3x4<u32>',
+  mat4x2u: 'mat4x2<u32>',
+  mat4x3u: 'mat4x3<u32>',
+  mat4x4u: 'mat4x4<u32>',
+
+  mat2x2h: 'mat2x2<f16>',
+  mat2x3h: 'mat2x3<f16>',
+  mat2x4h: 'mat2x4<f16>',
+  mat3x2h: 'mat3x2<f16>',
+  mat3x3h: 'mat3x3<f16>',
+  mat3x4h: 'mat3x4<f16>',
+  mat4x2h: 'mat4x2<f16>',
+  mat4x3h: 'mat4x3<f16>',
+  mat4x4h: 'mat4x4<f16>'
+};

package/src/shadertypes/data-types/shader-types.ts

@@ -0,0 +1,87 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {PrimitiveDataType} from './data-types';
+
+/**
+ * Describes the type of an attribute as defined in the shader source code.
+ * @note This is a subset of shader variable types
+ * @note Buffers with various `VertexFormat`s can be supplied for each type, GPU will convert them at runtime/
+ */
+export type AttributeShaderType =
+  | PrimitiveDataType
+  | `vec2<${PrimitiveDataType}>`
+  | `vec3<${PrimitiveDataType}>`
+  | `vec4<${PrimitiveDataType}>`;
+
+/**
+ * Describes the type of a variable that can declared in shader source code.
+ * @note Uniforms can be declared using these types
+ * @note Uniforms can be of a wider range of types than attributes.
+ * @note to WebGL users: "bindings" (textures, samplers, and uniform buffers) are considered "bindings", not shader variables/uniforms
+ */
+export type VariableShaderType =
+  | PrimitiveDataType
+  | `vec2<${PrimitiveDataType}>`
+  | `vec3<${PrimitiveDataType}>`
+  | `vec4<${PrimitiveDataType}>`
+  | `mat2x2<${PrimitiveDataType}>`
+  | `mat2x3<${PrimitiveDataType}>`
+  | `mat2x4<${PrimitiveDataType}>`
+  | `mat3x2<${PrimitiveDataType}>`
+  | `mat3x3<${PrimitiveDataType}>`
+  | `mat3x4<${PrimitiveDataType}>`
+  | `mat4x2<${PrimitiveDataType}>`
+  | `mat4x3<${PrimitiveDataType}>`
+  | `mat4x4<${PrimitiveDataType}>`;
+
+/* Suffixes used by WGSL alias types */
+type ShaderTypeAliasSuffix = 'f' | 'i' | 'u' | 'h';
+
+/** Shorthand type aliases recognized by WGSL */
+export type AttributeShaderTypeAlias =
+  | `vec2${ShaderTypeAliasSuffix}`
+  | `vec3${ShaderTypeAliasSuffix}`
+  | `vec4${ShaderTypeAliasSuffix}`;
+
+/** Shorthand type aliases recognized by WGSL */
+export type VariableShaderTypeAlias =
+  | AttributeShaderTypeAlias
+  | `mat2x2${ShaderTypeAliasSuffix}`
+  | `mat2x3${ShaderTypeAliasSuffix}`
+  | `mat2x4${ShaderTypeAliasSuffix}`
+  | `mat3x2${ShaderTypeAliasSuffix}`
+  | `mat3x3${ShaderTypeAliasSuffix}`
+  | `mat3x4${ShaderTypeAliasSuffix}`
+  | `mat4x2${ShaderTypeAliasSuffix}`
+  | `mat4x3${ShaderTypeAliasSuffix}`
+  | `mat4x4${ShaderTypeAliasSuffix}`;
+
+/** A composite shader type can include structs and arrays, recursively */
+export type CompositeShaderType = VariableShaderType | StructShaderType | ArrayShaderType;
+
+/** Represents a struct in WGSL */
+export type StructShaderType = {
+  members: Record<string, CompositeShaderType>;
+};
+
+/** Represents an array in WGSL */
+export type ArrayShaderType = {
+  type: CompositeShaderType;
+  length: number;
+};
+
+/** Information extracted from a AttributeShaderType constant */
+export type AttributeShaderTypeInfo = {
+  /** WGSL-style primitive data type, f32, i32, u32 */
+  primitiveType: PrimitiveDataType;
+  /** Whether this is a normalized integer (that must be used as float) */
+  components: 1 | 2 | 3 | 4;
+  /** Length in bytes of the data for one vertex */
+  byteLength?: number;
+  /** Whether this is for integer or float vert */
+  integer: boolean;
+  /** Whether this data type is signed */
+  signed: boolean;
+};

package/src/shadertypes/textures/pixel-utils.ts

@@ -0,0 +1,239 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+export type ImageData = {
+  /** Offset into the data (in addition to any offset built-in to the ArrayBufferView) */
+  byteOffset?: number;
+  /** The stride, in bytes, between the beginning of each texel block row and the subsequent texel block row. Required if there are multiple texel block rows (i.e. the copy height or depth is more than one block). */
+  bytesPerRow?: number;
+  /** Number or rows per image (needed if multiple images are being set) */
+  rowsPerImage?: number;
+  /** Bits per channel */
+  bitsPerChannel: [number, number, number, number];
+};
+
+export type PixelData = {
+  arrayBuffer: ArrayBuffer;
+  width: number;
+  height: number;
+  /** Bytes per pixel */
+  bytesPerPixel: number;
+  bytesPerRow: number;
+  bitsPerChannel: [number, number, number, number];
+};
+
+/**
+ * Extracts a single RGBA pixel value from PixelData at the given (x, y) coordinate.
+ *
+ * The pixel's data is assumed to be packed according to pixelData.bitsPerChannel.
+ * The pixel data for a given row is padded to pixelData.bytesPerRow.
+ *
+ * @param pixelData - The metadata and data for the pixel buffer.
+ * @param x - The x coordinate (0-based).
+ * @param y - The y coordinate (0-based).
+ * @returns A tuple [r, g, b, a] where each channel is the extracted numeric value.
+ *
+* @example
+
+Assume you obtained an ArrayBuffer from copyTextureToBuffer and have the following metadata:
+
+  const pixelData: PixelData = {
+    bitsPerChannel: [5, 6, 5, 0], // For example, a 16-bit RGB565 format (no alpha)
+    width: 800,
+    height: 600,
+    bytesPerPixel: 2,           // 16 bits per pixel
+    bytesPerRow: 1600,          // Assuming no extra padding
+    arrayBuffer: myTextureBuffer, // Obtained from copyTextureToBuffer
+  };
+
+You can then extract the pixel at (x, y) like so:
+
+  const rgba = extractPixel(pixelData, x, y);
+  console.log("Extracted RGBA:", rgba);
+
+For RGBA formats where all channels are present (e.g. [8, 8, 8, 8]), the function will extract a 4-channel pixel value.
+*/
+
+export function readPixel(
+  pixelData: PixelData,
+  x: number,
+  y: number,
+  bitsPerChannel: [number, number, number, number]
+): [number, number, number, number] {
+  if (x < 0 || x >= pixelData.width || y < 0 || y >= pixelData.height) {
+    throw new Error('Coordinates out of bounds.');
+  }
+
+  // Compute the byte offset of the pixel in the buffer.
+  const byteOffset = y * pixelData.bytesPerRow + x * pixelData.bytesPerPixel;
+
+  // Create a Uint8Array view for this pixel's bytes.
+  // We only need to view pixelData.bytesPerPixel bytes.
+  const pixelDataView = new DataView(pixelData.arrayBuffer, byteOffset, pixelData.bytesPerPixel);
+
+  let bitOffsetWithinPixel = 0;
+  const channels: number[] = [];
+
+  // Extract each of the four channels.
+  for (let i = 0; i < 4; i++) {
+    const bits = bitsPerChannel[i];
+    // If a channel's bit width is zero or negative, consider it not present.
+    if (bits <= 0) {
+      channels.push(0);
+    } else {
+      const channelValue = readBitsFromDataView(pixelDataView, bitOffsetWithinPixel, bits);
+      channels.push(channelValue);
+      bitOffsetWithinPixel += bits;
+    }
+  }
+
+  return [channels[0], channels[1], channels[2], channels[3]];
+}
+
+/**
+ * Encodes an RGBA pixel into a DataView at a given bit offset according to a specified bit layout.
+ *
+ * The channels are written sequentially in the order R, G, B, A. For each channel, the number
+ * of bits is taken from the bitsPerChannel array. Channel values are masked to fit within the specified width.
+ *
+ * @param dataView - The DataView into which the pixel will be encoded.
+ * @param bitOffset - The bit offset in the DataView where the pixel should be written.
+ * @param bitsPerChannel - A tuple specifying the number of bits for each channel: [R, G, B, A].
+ * @param pixel - A tuple [r, g, b, a] containing the channel values (as numbers).
+ *
+ * @example
+
+Assume you want to encode a pixel into a packed format where:
+  - Red uses 5 bits
+  - Green uses 6 bits
+  - Blue uses 5 bits
+  - Alpha is not used (0 bits)
+And the pixel format is packed into 16 bits total.
+
+You might have:
+  const bitsPerChannel: [number, number, number, number] = [5, 6, 5, 0];
+  const pixel: [number, number, number, number] = [15, 31, 15, 0]; // Example values
+  const buffer = new ArrayBuffer(2); // 16 bits = 2 bytes
+  const dataView = new DataView(buffer);
+
+Now encode the pixel at bit offset 0:
+  encodePixel(dataView, 0, bitsPerChannel, pixel);
+
+The dataView now contains the 16-bit packed pixel value in big-endian order.
+*/
+export function writePixel(
+  dataView: DataView,
+  bitOffset: number,
+  bitsPerChannel: [number, number, number, number],
+  pixel: [number, number, number, number]
+): void {
+  let currentBitOffset = bitOffset;
+  for (let channel = 0; channel < 4; channel++) {
+    const bits = bitsPerChannel[channel];
+    // Clamp the channel value to the maximum allowed by the bit width.
+    const maxValue = (1 << bits) - 1;
+    const channelValue = pixel[channel] & maxValue;
+    writeBitsToDataView(dataView, currentBitOffset, bits, channelValue);
+    currentBitOffset += bits;
+  }
+}
+
+/**
+ * Reads a specified number of bits from a DataView starting at a given bit offset.
+ *
+ * For channels with a bit width of 8, 16, or 32 bits and when the bitOffset is byte-aligned,
+ * this function uses DataView methods for fast extraction.
+ *
+ * Bits are assumed to be stored in big-endian order (i.e. the most-significant bit is at position 7 in each byte).
+ *
+ * @param dataView - The DataView containing the data.
+ * @param bitOffset - The offset (in bits) within the data from which to start reading.
+ * @param bitCount - The number of bits to read (supported range: 1 to 32).
+ * @returns The extracted value as a number.
+ */
+export function readBitsFromDataView(
+  dataView: DataView,
+  bitOffset: number,
+  bitCount: number
+): number {
+  // Check if we can optimize when bitOffset is byte-aligned.
+  if (bitOffset % 8 === 0) {
+    const byteOffset = bitOffset / 8;
+    if (bitCount === 8 && byteOffset + 1 <= dataView.byteLength) {
+      return dataView.getUint8(byteOffset);
+    } else if (bitCount === 16 && byteOffset + 2 <= dataView.byteLength) {
+      // false for big-endian reading.
+      return dataView.getUint16(byteOffset, false);
+    } else if (bitCount === 32 && byteOffset + 4 <= dataView.byteLength) {
+      return dataView.getUint32(byteOffset, false);
+    }
+  }
+
+  // Fallback: bit-level extraction for non-aligned or non-standard bit widths.
+  let value = 0;
+  for (let i = 0; i < bitCount; i++) {
+    const overallBitIndex = bitOffset + i;
+    const byteIndex = Math.floor(overallBitIndex / 8);
+    const bitIndex = overallBitIndex % 8;
+    // Read the byte and extract the bit at position (7 - bitIndex).
+    const byteValue = dataView.getUint8(byteIndex);
+    const bit = (byteValue >> (7 - bitIndex)) & 1;
+    value = (value << 1) | bit;
+  }
+  return value;
+}
+
+/**
+ * Writes a specified number of bits from a value into a DataView at a given bit offset.
+ *
+ * For channels with a bit width of 8, 16, or 32 bits and when the bit offset is byte-aligned,
+ * this function uses DataView methods for fast writing.
+ *
+ * Bits are assumed to be stored in big-endian order (i.e. the most-significant bit is at position 7 in each byte).
+ *
+ * @param dataView - The DataView to write into.
+ * @param bitOffset - The bit offset at which to begin writing.
+ * @param bitCount - The number of bits to write (supported range: 1 to 32).
+ * @param value - The numeric value whose lower bitCount bits will be written.
+ */
+export function writeBitsToDataView(
+  dataView: DataView,
+  bitOffset: number,
+  bitCount: number,
+  value: number
+): void {
+  // If the bitOffset is byte-aligned, we may optimize for common bit widths.
+  if (bitOffset % 8 === 0) {
+    const byteOffset = bitOffset / 8;
+    if (bitCount === 8 && byteOffset + 1 <= dataView.byteLength) {
+      dataView.setUint8(byteOffset, value & 0xff);
+      return;
+    } else if (bitCount === 16 && byteOffset + 2 <= dataView.byteLength) {
+      dataView.setUint16(byteOffset, value & 0xffff, false); // big-endian
+      return;
+    } else if (bitCount === 32 && byteOffset + 4 <= dataView.byteLength) {
+      dataView.setUint32(byteOffset, value, false); // big-endian
+      return;
+    }
+  }
+
+  // Fallback: write bit-by-bit.
+  for (let i = 0; i < bitCount; i++) {
+    const overallBitIndex = bitOffset + i;
+    const byteIndex = Math.floor(overallBitIndex / 8);
+    const bitIndex = overallBitIndex % 8;
+    const mask = 1 << (7 - bitIndex);
+    // Extract the i-th bit from value (starting from the most-significant bit)
+    const bitValue = (value >> (bitCount - 1 - i)) & 1;
+    // Read the current byte.
+    let currentByte = dataView.getUint8(byteIndex);
+    // Clear the target bit.
+    currentByte &= ~mask;
+    // Set the target bit if bitValue is 1.
+    if (bitValue) {
+      currentByte |= mask;
+    }
+    dataView.setUint8(byteIndex, currentByte);
+  }
+}