@luma.gl/core 9.2.0-alpha.1 → 9.2.0-alpha.5

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);
+  }
+}

package/src/shadertypes/{utils/decode-texture-format.ts → textures/texture-format-decoder.ts}

@@ -2,14 +2,15 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import type {NormalizedDataType} from '../data-types';
+import type {NormalizedDataType} from '../data-types/data-types';
+import {getDataTypeInfo} from '../data-types/decode-data-types';
 import type {
   TextureFormat,
-  CompressedTextureFormat,
+  TextureFormatCompressed,
   TextureFormatInfo,
-  TextureFormatCapabilities
-} from '../texture-formats';
-import {getDataTypeInfo} from './decode-data-types';
+  TextureFormatCapabilities,
+  TextureFormatColor
+} from './texture-formats';
 import {getTextureFormatDefinition} from './texture-format-table';
 
 // prettier-ignore
@@ -19,22 +20,69 @@ const COMPRESSED_TEXTURE_FORMAT_PREFIXES = [
 
 const RGB_FORMAT_REGEX = /^(r|rg|rgb|rgba|bgra)([0-9]*)([a-z]*)(-srgb)?(-webgl)?$/;
 
-/**
- * Returns true if a texture format is GPU compressed
- */
-export function isTextureFormatCompressed(
-  format: TextureFormat
-): format is CompressedTextureFormat {
-  return COMPRESSED_TEXTURE_FORMAT_PREFIXES.some(prefix => (format as string).startsWith(prefix));
+export class TextureFormatDecoder {
+  /** Returns information about a texture format, e.g. attatchment type, components, byte length and flags (integer, signed, normalized) */
+  getInfo(format: TextureFormat): TextureFormatInfo {
+    return getTextureFormatInfo(format);
+  }
+
+  /** Checks if a texture format is color */
+  isColor(format: TextureFormat): format is TextureFormatColor {
+    return format.startsWith('rgba') || format.startsWith('bgra') || format.startsWith('rgb');
+  }
+
+  /** Checks if a texture format is depth or stencil */
+  isDepthStencil(format: TextureFormat): boolean {
+    return format.startsWith('depth') || format.startsWith('stencil');
+  }
+
+  /** Checks if a texture format is compressed */
+  isCompressed(format: TextureFormat): format is TextureFormatCompressed {
+    return COMPRESSED_TEXTURE_FORMAT_PREFIXES.some(prefix => (format as string).startsWith(prefix));
+  }
+
+  /**
+   * Returns the "static" capabilities of a texture format.
+   * @note Needs to be checked against current device
+   */
+  getCapabilities(format: TextureFormat): TextureFormatCapabilities {
+    const info = getTextureFormatDefinition(format);
+
+    const formatCapabilities: Required<TextureFormatCapabilities> = {
+      format,
+      create: info.f ?? true,
+      render: info.render ?? true,
+      filter: info.filter ?? true,
+      blend: info.blend ?? true,
+      store: info.store ?? true
+    };
+
+    const formatInfo = getTextureFormatInfo(format);
+    const isDepthStencil = format.startsWith('depth') || format.startsWith('stencil');
+    const isSigned = formatInfo?.signed;
+    const isInteger = formatInfo?.integer;
+    const isWebGLSpecific = formatInfo?.webgl;
+
+    // signed formats are not renderable
+    formatCapabilities.render &&= !isSigned;
+    // signed and integer formats are not filterable
+    formatCapabilities.filter &&= !isDepthStencil && !isSigned && !isInteger && !isWebGLSpecific;
+
+    return formatCapabilities;
+  }
 }
 
+export const textureFormatDecoder = new TextureFormatDecoder();
+
+// HELPERS
+
 /**
  * Decodes a texture format, returning e.g. attatchment type, components, byte length and flags (integer, signed, normalized)
  */
-export function getTextureFormatInfo(format: TextureFormat): TextureFormatInfo {
+function getTextureFormatInfo(format: TextureFormat): TextureFormatInfo {
   let formatInfo: TextureFormatInfo = getTextureFormatInfoUsingTable(format);
 
-  if (isTextureFormatCompressed(format)) {
+  if (textureFormatDecoder.isCompressed(format)) {
     formatInfo.channels = 'rgb';
     formatInfo.components = 3;
     formatInfo.bytesPerPixel = 1;
@@ -97,38 +145,6 @@ export function getTextureFormatInfo(format: TextureFormat): TextureFormatInfo {
   return formatInfo;
 }
 
-/**
- * Returns the "static" capabilities of a texture format.
- * @note Needs to be checked against current device
- */
-export function getTextureFormatCapabilities(format: TextureFormat): TextureFormatCapabilities {
-  const info = getTextureFormatDefinition(format);
-
-  const formatCapabilities: Required<TextureFormatCapabilities> = {
-    format,
-    create: info.f ?? true,
-    render: info.render ?? true,
-    filter: info.filter ?? true,
-    blend: info.blend ?? true,
-    store: info.store ?? true
-  };
-
-  const formatInfo = getTextureFormatInfo(format);
-  const isDepthStencil = format.startsWith('depth') || format.startsWith('stencil');
-  const isSigned = formatInfo?.signed;
-  const isInteger = formatInfo?.integer;
-  const isWebGLSpecific = formatInfo?.webgl;
-
-  // signed formats are not renderable
-  formatCapabilities.render &&= !isSigned;
-  // signed and integer formats are not filterable
-  formatCapabilities.filter &&= !isDepthStencil && !isSigned && !isInteger && !isWebGLSpecific;
-
-  return formatCapabilities;
-}
-
-// HELPERS
-
 /** Decode texture format info from the table */
 function getTextureFormatInfoUsingTable(format: TextureFormat): TextureFormatInfo {
   const info = getTextureFormatDefinition(format);
@@ -166,7 +182,7 @@ function getTextureFormatInfoUsingTable(format: TextureFormat): TextureFormatInf
 
 /** Parses ASTC block widths from format string */
 function getCompressedTextureBlockSize(
-  format: CompressedTextureFormat
+  format: TextureFormatCompressed
 ): {blockWidth: number; blockHeight: number} | null {
   const REGEX = /.*-(\d+)x(\d+)-.*/;
   const matches = REGEX.exec(format as string);

package/src/shadertypes/textures/texture-format-generics.ts

@@ -0,0 +1,190 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {
+  type TextureFormat,
+  type TextureFormatDepthStencil,
+  type TextureFormatCompressed
+} from './texture-formats';
+
+import {type DataTypeArray, NormalizedDataTypeArray} from '../data-types/data-types';
+
+export type TextureFormatTypedArray<T extends TextureFormat> = DataTypeArray<
+  TextureFormatDataType<T>
+>;
+
+export type TextureFormatNormalizedTypedArray<T extends TextureFormat> = NormalizedDataTypeArray<
+  TextureFormatDataType<T>
+>;
+
+/** A numeric array of length matching the number of components in the texture format */
+export type TextureFormatPixel<T extends TextureFormat> =
+  TextureFormatPackedComponents<T> extends 1
+    ? [number]
+    : TextureFormatPackedComponents<T> extends 2
+      ? [number, number]
+      : TextureFormatPackedComponents<T> extends 3
+        ? [number, number, number]
+        : TextureFormatPackedComponents<T> extends 4
+          ? [number, number, number, number]
+          : never;
+
+/** @note packed formats have only one component. Use TextureFormatPackedComponents */
+export type TextureFormatComponents<T extends TextureFormat> = T extends
+  | TextureFormatR
+  | TextureFormatPackedRGB
+  | TextureFormatPackedRGBA
+  ? 1
+  : T extends TextureFormatRG
+    ? 2
+    : T extends TextureFormatRGB
+      ? 3
+      : T extends TextureFormatRGBA
+        ? 4
+        : never;
+
+export type TextureFormatPackedComponents<T extends TextureFormat> = T extends TextureFormatR
+  ? 1
+  : T extends TextureFormatRG
+    ? 2
+    : T extends TextureFormatRGB | TextureFormatPackedRGB
+      ? 3
+      : T extends TextureFormatRGBA | TextureFormatPackedRGBA
+        ? 4
+        : never;
+
+/** Get the data type for a texture format */
+export type TextureFormatDataType<T extends TextureFormat> = T extends TextureFormatUint8
+  ? 'uint8'
+  : T extends TextureFormatSint8
+    ? 'sint8'
+    : T extends TextureFormatUnorm8
+      ? 'unorm8'
+      : T extends TextureFormatSnorm8
+        ? 'snorm8'
+        : T extends TextureFormatUint16
+          ? 'uint16'
+          : T extends TextureFormatSint16
+            ? 'sint16'
+            : T extends TextureFormatUnorm16
+              ? 'unorm16'
+              : T extends TextureFormatSnorm16
+                ? 'snorm16'
+                : T extends TextureFormatUint32
+                  ? 'uint32'
+                  : T extends TextureFormatSint32
+                    ? 'sint32'
+                    : T extends TextureFormatFloat16
+                      ? 'float16'
+                      : T extends TextureFormatFloat32
+                        ? 'float32'
+                        : T extends TextureFormatDepthStencil
+                          ? 'uint32'
+                          : T extends TextureFormatCompressed
+                            ? 'uint8'
+                            : T extends TextureFormatPacked16
+                              ? 'uint16'
+                              : T extends TextureFormatPacked32
+                                ? 'uint32'
+                                : never;
+
+// Component groups
+
+type TextureFormatR =
+  | 'r8uint'
+  | 'r8sint'
+  | 'r8unorm'
+  | 'r8snorm'
+  | 'r16unorm'
+  | 'r16snorm'
+  | 'r16uint'
+  | 'r16sint'
+  | 'r16float'
+  | 'r32uint'
+  | 'r32sint'
+  | 'r32float';
+
+type TextureFormatRG =
+  | 'rg8unorm'
+  | 'rg8snorm'
+  | 'rg8uint'
+  | 'rg8sint'
+  | 'rg16unorm'
+  | 'rg16snorm'
+  | 'rg16uint'
+  | 'rg16sint'
+  | 'rg16float'
+  | 'rg32uint'
+  | 'rg32sint'
+  | 'rg32float';
+
+type TextureFormatRGB =
+  | 'rgb8unorm-webgl'
+  | 'rgb8snorm-webgl'
+  | 'rgb16unorm-webgl'
+  | 'rgb16snorm-webgl'
+  | 'rgb32float-webgl';
+
+type TextureFormatRGBA =
+  | 'rgba8uint'
+  | 'rgba8unorm'
+  | 'rgba8unorm-srgb'
+  | 'rgba8snorm'
+  | 'bgra8unorm'
+  | 'bgra8unorm-srgb'
+  | 'rgba8sint'
+  | 'rgba16unorm'
+  | 'rgba16snorm'
+  | 'rgba16uint'
+  | 'rgba16sint'
+  | 'rgba16float'
+  | 'rgba32uint'
+  | 'rgba32sint'
+  | 'rgba32float';
+
+type TextureFormatPackedRGB = 'rgb565unorm-webgl' | 'rgb9e5ufloat' | 'rg11b10ufloat';
+
+type TextureFormatPackedRGBA =
+  | 'rgba4unorm-webgl'
+  | 'rgb5a1unorm-webgl'
+  | 'rgb10a2unorm'
+  | 'rgb10a2uint';
+
+// Data type groups
+
+type TextureFormatUnorm8 =
+  | 'r8unorm'
+  | 'rg8unorm'
+  | 'rgb8unorm-webgl'
+  | 'rgba8unorm'
+  | 'rgba8unorm-srgb'
+  | 'bgra8unorm'
+  | 'bgra8unorm-srgb';
+
+type TextureFormatSnorm8 = 'r8snorm' | 'rg8snorm' | 'rgb8snorm-webgl' | 'rgba8snorm';
+
+type TextureFormatUint8 = 'r8uint' | 'rg8uint' | 'rgba8uint';
+
+type TextureFormatSint8 = 'r8sint' | 'rg8sint' | 'rgba8sint';
+
+type TextureFormatUnorm16 = 'r16unorm' | 'rg16unorm' | 'rgb16unorm-webgl' | 'rgba16unorm';
+
+type TextureFormatSnorm16 = 'r16snorm' | 'rg16snorm' | 'rgb16snorm-webgl' | 'rgba16snorm';
+
+type TextureFormatUint16 = 'r16uint' | 'rg16uint' | 'rgba16uint';
+
+type TextureFormatSint16 = 'r16sint' | 'rg16sint' | 'rgba16sint';
+
+type TextureFormatFloat16 = 'r16float' | 'rg16float' | 'rgba16float';
+
+// 96-bit formats (deprecated!)
+type TextureFormatUint32 = 'r32uint' | 'rg32uint' | 'rgba32uint';
+
+type TextureFormatSint32 = 'r32sint' | 'rg32sint' | 'rgba32sint';
+
+type TextureFormatFloat32 = 'r32float' | 'rg32float' | 'rgb32float-webgl' | 'rgba32float';
+
+type TextureFormatPacked16 = 'rgba4unorm-webgl' | 'rgb565unorm-webgl' | 'rgb5a1unorm-webgl';
+
+type TextureFormatPacked32 = 'rgb9e5ufloat' | 'rg11b10ufloat' | 'rgb10a2unorm' | 'rgb10a2uint';