@luma.gl/core 9.2.5 → 9.3.0-alpha.2

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

@@ -9,77 +9,132 @@ import type {
   TextureFormatCompressed,
   TextureFormatInfo,
   TextureFormatCapabilities,
-  TextureFormatColor
+  TextureFormatColor,
+  TextureMemoryLayout,
+  TextureFormatDepthStencil
 } from './texture-formats';
 import {getTextureFormatDefinition} from './texture-format-table';
 
+const RGB_FORMAT_REGEX = /^(r|rg|rgb|rgba|bgra)([0-9]*)([a-z]*)(-srgb)?(-webgl)?$/;
+const COLOR_FORMAT_PREFIXES = ['rgb', 'rgba', 'bgra'];
+const DEPTH_FORMAT_PREFIXES = ['depth', 'stencil'];
 // prettier-ignore
 const COMPRESSED_TEXTURE_FORMAT_PREFIXES = [
   'bc1', 'bc2', 'bc3', 'bc4', 'bc5', 'bc6', 'bc7', 'etc1', 'etc2', 'eac', 'atc', 'astc', 'pvrtc'
 ];
 
-const RGB_FORMAT_REGEX = /^(r|rg|rgb|rgba|bgra)([0-9]*)([a-z]*)(-srgb)?(-webgl)?$/;
-
+// HELPERS - MEMORY LAYOUT
+
+/** Options to calculate a texture layout */
+export type TextureMemoryLayoutOptions = {
+  /** Number of bytes per pixel */
+  format: TextureFormat;
+  /** Width of the texture in pixels */
+  width: number;
+  /** Height of the texture in pixels */
+  height: number;
+  /** Number of images in the texture */
+  depth: number;
+  /** Alignment of each row */
+  byteAlignment: number;
+};
+
+/** Class that helps applications work with texture formats */
 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');
+    return COLOR_FORMAT_PREFIXES.some(prefix => format.startsWith(prefix));
   }
 
   /** Checks if a texture format is depth or stencil */
-  isDepthStencil(format: TextureFormat): boolean {
-    return format.startsWith('depth') || format.startsWith('stencil');
+  isDepthStencil(format: TextureFormat): format is TextureFormatDepthStencil {
+    return DEPTH_FORMAT_PREFIXES.some(prefix => format.startsWith(prefix));
   }
 
   /** 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));
+    return COMPRESSED_TEXTURE_FORMAT_PREFIXES.some(prefix => format.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;
+  /** Returns information about a texture format, e.g. attachment type, components, byte length and flags (integer, signed, normalized) */
+  getInfo(format: TextureFormat): TextureFormatInfo {
+    return getTextureFormatInfo(format);
+  }
 
-    // signed formats are not renderable
-    formatCapabilities.render &&= !isSigned;
-    // signed and integer formats are not filterable
-    formatCapabilities.filter &&= !isDepthStencil && !isSigned && !isInteger && !isWebGLSpecific;
+  /**  "static" capabilities of a texture format. @note Needs to be adjusted against current device */
+  getCapabilities(format: TextureFormat): TextureFormatCapabilities {
+    return getTextureFormatCapabilities(format);
+  }
 
-    return formatCapabilities;
+  /** Computes the memory layout for a texture, in particular including row byte alignment */
+  computeMemoryLayout(opts: TextureMemoryLayoutOptions): TextureMemoryLayout {
+    return computeTextureMemoryLayout(opts);
   }
 }
 
 export const textureFormatDecoder = new TextureFormatDecoder();
 
-// HELPERS
+// HELPERS - MEMORY LAYOUT
+
+/** Get the memory layout of a texture */
+function computeTextureMemoryLayout({
+  format,
+  width,
+  height,
+  depth,
+  byteAlignment
+}: TextureMemoryLayoutOptions): TextureMemoryLayout {
+  const {bytesPerPixel} = textureFormatDecoder.getInfo(format);
+  // WebGPU requires bytesPerRow to be a multiple of 256.
+  const unpaddedBytesPerRow = width * bytesPerPixel;
+  const bytesPerRow = Math.ceil(unpaddedBytesPerRow / byteAlignment) * byteAlignment;
+  const rowsPerImage = height;
+  const byteLength = bytesPerRow * rowsPerImage * depth;
+
+  return {
+    bytesPerPixel,
+    bytesPerRow,
+    rowsPerImage,
+    depthOrArrayLayers: depth,
+    bytesPerImage: bytesPerRow * rowsPerImage,
+    byteLength
+  };
+}
+
+// HELPERS - CAPABILITIES
+
+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;
+}
+
+// HELPER - FORMAT INFO
 
 /**
  * Decodes a texture format, returning e.g. attatchment type, components, byte length and flags (integer, signed, normalized)
  */
-function getTextureFormatInfo(format: TextureFormat): TextureFormatInfo {
+export function getTextureFormatInfo(format: TextureFormat): TextureFormatInfo {
   let formatInfo: TextureFormatInfo = getTextureFormatInfoUsingTable(format);
 
   if (textureFormatDecoder.isCompressed(format)) {

package/src/shadertypes/textures/texture-formats.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-import {NormalizedDataType} from '../data-types/data-types';
+import {NormalizedDataType, DataTypeArray, NormalizedDataTypeArray} from '../data-types/data-types';
 
 /** Information about the structure of a texture format */
 export type TextureFormatInfo = {
@@ -58,6 +58,33 @@ export type TextureFormatCapabilities = {
   store: TextureFeature | boolean;
 };
 
+/**
+ * Memory layout for reading/writing data to a texture's memory.
+ *
+ * @note Due to alignment, GPU texture data is typically not contiguous.
+ *
+ * @note  GPU texure data must be accessed according to this layout.
+ * - On CPU, only the range of rows that are actually read or written need to be allocated.
+ * - However, space for the full, padded/aligned rows must be allocated in the buffer,
+ *   even if just a partial horizontal range `{x, width}` is actually read or written.
+ *
+ * @note byteLength = bytesPerRow * rowsPerImage * depthOrArrayLayers.
+ */
+export type TextureMemoryLayout = {
+  /** Total length in bytes */
+  byteLength: number;
+  /** Number of images */
+  depthOrArrayLayers: number;
+  /** Stride between successive images (Use when depthOrArrayLayers > 1) */
+  bytesPerImage: number;
+  /** Number of rows per image */
+  rowsPerImage: number;
+  /** Number of bytes per row (padded) */
+  bytesPerRow: number;
+  /** Number of bytes per pixel */
+  bytesPerPixel: number;
+};
+
 /**
  * These represent the main compressed texture formats
  * Each format typically has a number of more specific subformats
@@ -133,7 +160,7 @@ export type TextureFormatColorUncompressed =
   | TextureFormatPacked16
   | TextureFormatPacked32;
 
-type TextureFormatUnorm8 =
+export type TextureFormatUnorm8 =
   | 'r8unorm'
   | 'rg8unorm'
   | 'rgb8unorm-webgl'
@@ -142,32 +169,36 @@ type TextureFormatUnorm8 =
   | 'bgra8unorm'
   | 'bgra8unorm-srgb';
 
-type TextureFormatSnorm8 = 'r8snorm' | 'rg8snorm' | 'rgb8snorm-webgl' | 'rgba8snorm';
+export type TextureFormatSnorm8 = 'r8snorm' | 'rg8snorm' | 'rgb8snorm-webgl' | 'rgba8snorm';
 
-type TextureFormatUint8 = 'r8uint' | 'rg8uint' | 'rgba8uint';
+export type TextureFormatUint8 = 'r8uint' | 'rg8uint' | 'rgba8uint';
 
-type TextureFormatSint8 = 'r8sint' | 'rg8sint' | 'rgba8sint';
+export type TextureFormatSint8 = 'r8sint' | 'rg8sint' | 'rgba8sint';
 
-type TextureFormatUnorm16 = 'r16unorm' | 'rg16unorm' | 'rgb16unorm-webgl' | 'rgba16unorm';
+export type TextureFormatUnorm16 = 'r16unorm' | 'rg16unorm' | 'rgb16unorm-webgl' | 'rgba16unorm';
 
-type TextureFormatSnorm16 = 'r16snorm' | 'rg16snorm' | 'rgb16snorm-webgl' | 'rgba16snorm';
+export type TextureFormatSnorm16 = 'r16snorm' | 'rg16snorm' | 'rgb16snorm-webgl' | 'rgba16snorm';
 
-type TextureFormatUint16 = 'r16uint' | 'rg16uint' | 'rgba16uint';
+export type TextureFormatUint16 = 'r16uint' | 'rg16uint' | 'rgba16uint';
 
-type TextureFormatSint16 = 'r16sint' | 'rg16sint' | 'rgba16sint';
+export type TextureFormatSint16 = 'r16sint' | 'rg16sint' | 'rgba16sint';
 
-type TextureFormatFloat16 = 'r16float' | 'rg16float' | 'rgba16float';
+export type TextureFormatFloat16 = 'r16float' | 'rg16float' | 'rgba16float';
 
 // 96-bit formats (deprecated!)
-type TextureFormatUint32 = 'r32uint' | 'rg32uint' | 'rgba32uint';
+export type TextureFormatUint32 = 'r32uint' | 'rg32uint' | 'rgba32uint';
 
-type TextureFormatSint32 = 'r32sint' | 'rg32sint' | 'rgba32sint';
+export type TextureFormatSint32 = 'r32sint' | 'rg32sint' | 'rgba32sint';
 
-type TextureFormatFloat32 = 'r32float' | 'rg32float' | 'rgb32float-webgl' | 'rgba32float';
+export type TextureFormatFloat32 = 'r32float' | 'rg32float' | 'rgb32float-webgl' | 'rgba32float';
 
-type TextureFormatPacked16 = 'rgba4unorm-webgl' | 'rgb565unorm-webgl' | 'rgb5a1unorm-webgl';
+export type TextureFormatPacked16 = 'rgba4unorm-webgl' | 'rgb565unorm-webgl' | 'rgb5a1unorm-webgl';
 
-type TextureFormatPacked32 = 'rgb9e5ufloat' | 'rg11b10ufloat' | 'rgb10a2unorm' | 'rgb10a2uint';
+export type TextureFormatPacked32 =
+  | 'rgb9e5ufloat'
+  | 'rg11b10ufloat'
+  | 'rgb10a2unorm'
+  | 'rgb10a2uint';
 
 export type TextureFormatCompressed =
   | 'bc1-rgb-unorm-webgl'
@@ -245,6 +276,14 @@ export type TextureFormatCompressed =
 
 // Texture format helper types
 
+export type TextureFormatTypedArray<T extends TextureFormat> = DataTypeArray<
+  TextureFormatDataType<T>
+>;
+
+export type TextureFormatNormalizedTypedArray<T extends TextureFormat> = NormalizedDataTypeArray<
+  TextureFormatDataType<T>
+>;
+
 export type TextureFormatDataType<T extends TextureFormat> = T extends TextureFormatUint8
   ? 'uint8'
   : T extends TextureFormatSint8

package/src/shadertypes/textures/texture-layout.ts

@@ -0,0 +1,60 @@
+// luma.gl
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {TypedArray} from '@math.gl/types';
+import {type TextureFormat, type TextureMemoryLayout} from './texture-formats';
+import {textureFormatDecoder} from './texture-format-decoder';
+
+export function getTextureImageView<T extends TextureFormat>(
+  arrayBuffer: ArrayBuffer,
+  memoryLayout: TextureMemoryLayout,
+  format: T,
+  image = 0
+) {
+  const formatInfo = textureFormatDecoder.getInfo(format);
+  const bytesPerComponent = formatInfo.bytesPerPixel / formatInfo.components;
+  const {bytesPerImage} = memoryLayout;
+  const offset = bytesPerImage * image;
+  const totalPixels = memoryLayout.bytesPerImage / bytesPerComponent;
+
+  switch (format) {
+    case 'rgba8unorm':
+    case 'bgra8unorm':
+    case 'rgba8uint':
+      return new Uint8Array(arrayBuffer, offset, totalPixels);
+    case 'r8unorm':
+      return new Uint8Array(arrayBuffer, offset, totalPixels);
+    case 'r16uint':
+    case 'rgba16uint':
+      return new Uint16Array(arrayBuffer, offset, totalPixels);
+    case 'r32uint':
+    case 'rgba32uint':
+      return new Uint32Array(arrayBuffer, offset, totalPixels);
+    case 'r32float':
+      return new Float32Array(arrayBuffer, offset, totalPixels);
+    case 'rgba16float':
+      return new Uint16Array(arrayBuffer, offset, totalPixels); // 4 channels
+    case 'rgba32float':
+      return new Float32Array(arrayBuffer, offset, totalPixels);
+    default:
+      throw new Error(`Unsupported format: ${format}`);
+  }
+}
+
+export function setTextureImageData<T extends TextureFormat>(
+  arrayBuffer: ArrayBuffer,
+  memoryLayout: TextureMemoryLayout,
+  format: T,
+  data: TypedArray,
+  image = 0
+): void {
+  const offset = 0; // memoryLayout.bytesPerImage * image;
+
+  const totalPixels = memoryLayout.bytesPerImage / memoryLayout.bytesPerPixel;
+  const subArray = data.subarray(0, totalPixels);
+
+  const typedArray = getTextureImageView(arrayBuffer, memoryLayout, format, image);
+
+  typedArray.set(subArray, offset);
+}