@deck.gl-community/layers 9.2.8 → 9.3.0-beta.2

package/src/skybox-layer/cubemap-utils.ts

@@ -0,0 +1,105 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import type {TextureCubeManifest, TextureCubeLoaderOptions} from '@loaders.gl/textures';
+import type {TextureCubeData, TextureCubeFace} from '@luma.gl/engine';
+
+const CUBE_FACES: TextureCubeFace[] = ['+X', '-X', '+Y', '-Y', '+Z', '-Z'];
+
+type LoadedTextureLevel = {
+  /** Browser-native bitmap representation for a mip level. */
+  imageBitmap?: ImageBitmap;
+  /** Explicit WebGPU texture format name. */
+  textureFormat?: string;
+  /** Legacy format field returned by some loaders.gl code paths. */
+  format?: string;
+  /** Raw pixel data for CPU-side texture uploads. */
+  data?: Uint8Array;
+  /** Width in pixels for raw pixel data uploads. */
+  width?: number;
+  /** Height in pixels for raw pixel data uploads. */
+  height?: number;
+};
+
+type LoadedCubemapTexture = {
+  type: 'cube';
+  data: unknown[];
+};
+
+/**
+ * Normalizes loaders.gl cubemap load options so in-memory manifests can still
+ * resolve relative face URLs through `core.baseUrl`.
+ */
+export function createCubemapLoadOptions(
+  cubemap: string | TextureCubeManifest,
+  loadOptions?: TextureCubeLoaderOptions | null
+): TextureCubeLoaderOptions | undefined {
+  if (!loadOptions) {
+    return undefined;
+  }
+
+  if (typeof cubemap === 'string' || loadOptions.core?.baseUrl || !loadOptions.baseUrl) {
+    return loadOptions;
+  }
+
+  return {
+    ...loadOptions,
+    core: {
+      ...loadOptions.core,
+      baseUrl: loadOptions.baseUrl
+    }
+  };
+}
+
+/** Converts a loaders.gl cubemap result into luma.gl `TextureCubeData`. */
+export function convertLoadedCubemapToTextureData(texture: LoadedCubemapTexture): TextureCubeData {
+  if (texture.type !== 'cube' || !Array.isArray(texture.data) || texture.data.length !== 6) {
+    throw new Error('SkyboxLayer expected a cubemap texture with six faces.');
+  }
+
+  return Object.fromEntries(
+    CUBE_FACES.map((face, index) => [face, normalizeTextureSlice(texture.data[index], face)])
+  ) as TextureCubeData;
+}
+
+/** Normalizes a cubemap face that may contain one or more mip levels. */
+function normalizeTextureSlice(faceData: unknown, face: TextureCubeFace): any {
+  if (Array.isArray(faceData)) {
+    if (faceData.length === 0) {
+      throw new Error(`SkyboxLayer received an empty mip chain for face ${face}.`);
+    }
+    return faceData.map((level, mipLevel) => normalizeTextureLevel(level, face, mipLevel));
+  }
+
+  return normalizeTextureLevel(faceData, face, 0);
+}
+
+/** Normalizes a single cubemap face mip level into luma.gl upload data. */
+function normalizeTextureLevel(faceData: unknown, face: TextureCubeFace, mipLevel: number) {
+  if (typeof ImageBitmap !== 'undefined' && faceData instanceof ImageBitmap) {
+    return faceData;
+  }
+
+  const level = faceData as LoadedTextureLevel | null | undefined;
+
+  if (level?.imageBitmap) {
+    return level.imageBitmap;
+  }
+
+  if (level && ArrayBuffer.isView(level.data) && level.width && level.height) {
+    return {
+      data: level.data,
+      width: level.width,
+      height: level.height,
+      format:
+        typeof level.textureFormat === 'string'
+          ? level.textureFormat
+          : typeof level.format === 'string'
+            ? level.format
+            : 'rgba8unorm'
+    };
+  }
+
+  throw new Error(`SkyboxLayer could not normalize cubemap face ${face} mip ${mipLevel}.`);
+}

package/src/skybox-layer/skybox-layer.ts

@@ -0,0 +1,344 @@
+// deck.gl-community
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {load} from '@loaders.gl/core';
+import {
+  TextureCubeLoader,
+  type TextureCubeLoaderOptions,
+  type TextureCubeManifest
+} from '@loaders.gl/textures';
+import {Layer} from '@deck.gl/core';
+import type {DefaultProps, LayerProps, UpdateParameters, Viewport} from '@deck.gl/core';
+import {Matrix4} from '@math.gl/core';
+import type {Device, RenderPipelineParameters} from '@luma.gl/core';
+import {CubeGeometry, DynamicTexture, Model, ShaderInputs} from '@luma.gl/engine';
+import type {TextureCubeData} from '@luma.gl/engine';
+import type {ShaderModule} from '@luma.gl/shadertools';
+import {convertLoadedCubemapToTextureData, createCubemapLoadOptions} from './cubemap-utils';
+
+type AppUniforms = {
+  /** World transform for the unit cube used to draw the skybox. */
+  modelMatrix: any;
+  /** View transform with translation removed so the skybox stays camera-centered. */
+  viewMatrix: any;
+  /** Projection transform for the active viewport. */
+  projectionMatrix: any;
+};
+
+const app: ShaderModule<AppUniforms, AppUniforms> = {
+  name: 'app',
+  uniformTypes: {
+    modelMatrix: 'mat4x4<f32>',
+    viewMatrix: 'mat4x4<f32>',
+    projectionMatrix: 'mat4x4<f32>'
+  }
+} as any;
+
+const SKYBOX_PARAMETERS: RenderPipelineParameters = {
+  cullMode: 'front',
+  depthWriteEnabled: false,
+  depthCompare: 'less-equal'
+};
+
+const SKYBOX_SCALE = new Matrix4().scale([2, 2, 2]);
+
+const defaultProps: DefaultProps<SkyboxLayerProps> = {
+  cubemap: null,
+  loadOptions: null,
+  orientation: 'default'
+};
+
+type _SkyboxLayerProps = {
+  /** Cubemap manifest URL or manifest object to load and render. */
+  cubemap: string | TextureCubeManifest | null;
+  /** Optional loaders.gl texture-cube load options. */
+  loadOptions?: TextureCubeLoaderOptions | null;
+  /**
+   * Declares how the cubemap faces are oriented relative to deck.gl's Z-up
+   * world. Use `y-up` for cubemaps authored for Y-up scenes, such as the
+   * Tycho star map faces from the luma.gl globe showcase.
+   */
+  orientation?: 'default' | 'y-up';
+};
+
+export type SkyboxLayerProps = _SkyboxLayerProps & LayerProps;
+
+type LoadedCubemapTexture = {
+  type: 'cube';
+  data: unknown[];
+};
+
+type SkyboxLayerState = {
+  /** Active GPU cubemap texture, if one has been loaded successfully. */
+  cubemapTexture: DynamicTexture | null;
+  /** Monotonic load token used to discard stale async cubemap loads. */
+  loadCount: number;
+  /** Backing model that renders the cube geometry. */
+  model?: Model;
+  /** Shader input manager for the skybox uniforms. */
+  shaderInputs?: ShaderInputs<any>;
+};
+
+/**
+ * Renders a camera-centered cubemap background for `MapView`, `GlobeView`,
+ * `FirstPersonView`, and other 3D-capable deck.gl views.
+ */
+export class SkyboxLayer<
+  ExtraProps extends Record<string, unknown> = Record<string, unknown>
+> extends Layer<Required<_SkyboxLayerProps> & ExtraProps> {
+  static defaultProps = defaultProps;
+  static layerName = 'SkyboxLayer';
+
+  state: SkyboxLayerState = undefined!;
+
+  /** Initializes the cube model and starts loading the cubemap texture. */
+  initializeState(): void {
+    const attributeManager = this.getAttributeManager();
+    attributeManager?.remove(['instancePickingColors']);
+
+    const shaderInputs = new ShaderInputs(
+      createShaderInputModules(this.context.defaultShaderModules),
+      {
+        disableWarnings: true
+      }
+    );
+    const model = this._getModel(shaderInputs);
+
+    this.setState({
+      cubemapTexture: null,
+      loadCount: 0,
+      model,
+      shaderInputs
+    });
+
+    this._loadCubemap().catch(() => {});
+  }
+
+  /** Reloads the cubemap when its source manifest or load options change. */
+  updateState({props, oldProps}: UpdateParameters<this>): void {
+    if (props.cubemap !== oldProps.cubemap || props.loadOptions !== oldProps.loadOptions) {
+      this._loadCubemap().catch(() => {});
+    }
+  }
+
+  /** Releases GPU resources owned by the layer. */
+  finalizeState(): void {
+    this.state.cubemapTexture?.destroy();
+    this.state.model?.destroy();
+  }
+
+  /** Draws the skybox cube for the current viewport. */
+  draw(): void {
+    const {model, cubemapTexture, shaderInputs} = this.state;
+    if (!model || !cubemapTexture || !shaderInputs) {
+      return;
+    }
+
+    const viewport = this.context.viewport;
+    shaderInputs.setProps({
+      app: {
+        modelMatrix: getSkyboxModelMatrix(this.props.orientation),
+        viewMatrix: getSkyboxViewMatrix(viewport),
+        projectionMatrix: viewport.projectionMatrix
+      }
+    });
+
+    model.draw(this.context.renderPass);
+  }
+
+  /** Creates the luma.gl model used to render the skybox cube. */
+  protected _getModel(shaderInputs: ShaderInputs<any>): Model {
+    return new Model(this.context.device, {
+      ...this.getShaders(),
+      id: this.props.id,
+      bufferLayout: this.getAttributeManager()?.getBufferLayouts() || [],
+      geometry: new CubeGeometry({indices: true}),
+      shaderInputs,
+      isInstanced: false,
+      parameters: SKYBOX_PARAMETERS
+    });
+  }
+
+  /** Returns the WGSL/GLSL shader pair used by the layer. */
+  getShaders() {
+    return {
+      source: SKYBOX_WGSL,
+      vs: SKYBOX_VS,
+      fs: SKYBOX_FS
+    };
+  }
+
+  /** Starts an asynchronous cubemap load for the current props. */
+  private async _loadCubemap(): Promise<void> {
+    const {cubemap, loadOptions} = this.props;
+    const nextLoadCount = this.state.loadCount + 1;
+    this.setState({loadCount: nextLoadCount});
+
+    if (!cubemap) {
+      this._setCubemapTexture(null);
+      return;
+    }
+
+    try {
+      const loadedTexture = await loadCubemapSource(cubemap, loadOptions);
+      if (this.state.loadCount !== nextLoadCount || !this.state.model) {
+        return;
+      }
+
+      const cubemapData = convertLoadedCubemapToTextureData(loadedTexture);
+      this._setCubemapTexture(createCubemapTexture(this.context.device, cubemapData));
+    } catch (error) {
+      if (this.state.loadCount === nextLoadCount) {
+        this.raiseError(error as Error, 'SkyboxLayer failed to load cubemap');
+      }
+    }
+  }
+
+  /** Swaps the active GPU cubemap texture and updates model bindings. */
+  private _setCubemapTexture(texture: DynamicTexture | null): void {
+    const {cubemapTexture, model} = this.state;
+    if (cubemapTexture === texture) {
+      return;
+    }
+
+    cubemapTexture?.destroy();
+    this.setState({cubemapTexture: texture});
+
+    if (texture && model) {
+      model.setBindings({cubeTexture: texture});
+    }
+
+    this.setNeedsRedraw();
+  }
+}
+
+/** Loads a cubemap manifest or manifest URL through loaders.gl. */
+async function loadCubemapSource(
+  cubemap: string | TextureCubeManifest,
+  loadOptions?: TextureCubeLoaderOptions | null
+): Promise<LoadedCubemapTexture> {
+  const normalizedLoadOptions = createCubemapLoadOptions(cubemap, loadOptions);
+
+  if (typeof cubemap === 'string') {
+    return (await load(cubemap, TextureCubeLoader, normalizedLoadOptions)) as LoadedCubemapTexture;
+  }
+
+  return (await TextureCubeLoader.parseText(
+    JSON.stringify(cubemap),
+    normalizedLoadOptions
+  )) as LoadedCubemapTexture;
+}
+
+/** Creates the runtime `DynamicTexture` instance used by the skybox model. */
+function createCubemapTexture(device: Device, data: TextureCubeData): DynamicTexture {
+  return new DynamicTexture(device, {
+    dimension: 'cube',
+    data,
+    mipmaps: true,
+    sampler: {
+      addressModeU: 'clamp-to-edge',
+      addressModeV: 'clamp-to-edge',
+      addressModeW: 'clamp-to-edge',
+      magFilter: 'linear',
+      minFilter: 'linear',
+      mipmapFilter: 'linear'
+    }
+  });
+}
+
+/** Removes camera translation from the active view matrix for skybox rendering. */
+function getSkyboxViewMatrix(viewport: Viewport): Matrix4 {
+  const viewMatrix = new Matrix4(viewport.viewMatrixUncentered || viewport.viewMatrix);
+  viewMatrix[12] = 0;
+  viewMatrix[13] = 0;
+  viewMatrix[14] = 0;
+  return viewMatrix;
+}
+
+/** Returns the skybox cube transform for the requested cubemap orientation. */
+function getSkyboxModelMatrix(orientation: 'default' | 'y-up' = 'default'): Matrix4 {
+  if (orientation === 'y-up') {
+    return new Matrix4().rotateX(Math.PI / 2).scale([2, 2, 2]);
+  }
+
+  return new Matrix4(SKYBOX_SCALE);
+}
+
+/** Converts the current shader module list into a name-indexed dictionary. */
+function createShaderInputModules(defaultShaderModules: ShaderModule[]): {
+  [moduleName: string]: ShaderModule;
+} {
+  return Object.fromEntries([app, ...defaultShaderModules].map((module) => [module.name, module]));
+}
+
+const SKYBOX_WGSL = /* wgsl */ `
+struct appUniforms {
+  modelMatrix: mat4x4<f32>,
+  viewMatrix: mat4x4<f32>,
+  projectionMatrix: mat4x4<f32>,
+};
+
+@group(0) @binding(auto) var<uniform> app : appUniforms;
+@group(0) @binding(auto) var cubeTexture : texture_cube<f32>;
+@group(0) @binding(auto) var cubeTextureSampler : sampler;
+
+struct VertexInputs {
+  @location(0) positions : vec3<f32>,
+};
+
+struct VertexOutputs {
+  @builtin(position) position : vec4<f32>,
+  @location(0) direction : vec3<f32>,
+};
+
+@vertex
+fn vertexMain(inputs: VertexInputs) -> VertexOutputs {
+  var outputs : VertexOutputs;
+  let clipPosition =
+    app.projectionMatrix *
+    app.viewMatrix *
+    app.modelMatrix *
+    vec4<f32>(inputs.positions, 1.0);
+  outputs.position = vec4<f32>(clipPosition.x, clipPosition.y, clipPosition.w, clipPosition.w);
+  outputs.direction = inputs.positions;
+  return outputs;
+}
+
+@fragment
+fn fragmentMain(inputs: VertexOutputs) -> @location(0) vec4<f32> {
+  return textureSample(cubeTexture, cubeTextureSampler, normalize(inputs.direction));
+}
+`;
+
+const SKYBOX_VS = /* glsl */ `#version 300 es
+in vec3 positions;
+
+uniform appUniforms {
+  mat4 modelMatrix;
+  mat4 viewMatrix;
+  mat4 projectionMatrix;
+} app;
+
+out vec3 vDirection;
+
+void main(void) {
+  vec4 clipPosition =
+    app.projectionMatrix * app.viewMatrix * app.modelMatrix * vec4(positions, 1.0);
+  gl_Position = clipPosition.xyww;
+  vDirection = positions;
+}
+`;
+
+const SKYBOX_FS = /* glsl */ `#version 300 es
+precision highp float;
+
+uniform samplerCube cubeTexture;
+
+in vec3 vDirection;
+out vec4 fragColor;
+
+void main(void) {
+  fragColor = texture(cubeTexture, normalize(vDirection));
+}
+`;