Visitar URL original
Migrate shader hooks and plugins to luma.gl alpha.9 by ibgreen · Pull Request #11022 · visgl/deck.gl · GitHub
Skip to content

Migrate shader hooks and plugins to luma.gl alpha.9 - #11022

Merged
ibgreen merged 3 commits into
masterfrom
codex/bump-luma-alpha-9
Nov 3, 2026
Merged

ibgreen merged 3 commits into
masterfrom
codex/bump-luma-alpha-9

Conversation

@ibgreen

@ibgreen ibgreen commented Nov 3, 2026 •

Copy link
Copy Markdown
Collaborator

Background

These are upstream improvements to simplify the open PRs for arrow layer support and WebGPU extensions. They are breaking luma API changes but simplify deck.gl significantly.

Luma.gl alpha.9 replaces module injections with shader plugins. Deck’s hooks, effects, and extensions need migration to preserve rendering.

Change List

  • Upgrade luma.gl packages to alpha.9
  • Migrate shader hooks and injection-bearing features to native plugins
  • Preserve picking order and effect plugin lifecycles
  • Migrate TripsLayer WGSL inputs, varyings, and named hooks
  • Update custom-layer examples and shader documentation
  • Unit tests: migrate existing assertions and fixtures
  • Upgrade guide: document plugin migration

Verified root install, full/private builds, lint, and gallery build (upstream chunk warnings); commit hook automatically ran 31 passing tests. All five CI jobs and coverage pass (84.465% overall, 97.561% patch); Greptile/Bugbot clear, Codex review unavailable due quota.


Note

Medium Risk
Touches core shader compilation and effect pipelines across multiple layers and extensions to adapt to upstream luma.gl alpha.9 API changes.

Overview
Updates @luma.gl dependencies to 10.0.0-alpha.9 and migrates shader injections across core, extensions, and layers to use luma's native ShaderPlugin architecture instead of module-level inject properties.

Key changes include:

  • Plugin Architecture: Introduces ShaderPlugin descriptors (e.g., pickingPlugin, shadowPlugin) and transitions hook injections to language-qualified keys (glsl:... and wgsl:...).
  • Core and Effects Management: Adds _addDefaultShaderPlugin and _removeDefaultShaderPlugin to Deck and LayerManager to manage effect plugins and preserve module lifecycles.
  • Extensions and Layers: Updates extensions (brushing, clip, collision-filter, data-filter, fill-style, mask, path-style, terrain) and layers (TripsLayer, PathLayer) to return plugins from getShaders(), including WGSL-native hook and varying definitions.
  • Documentation and Tests: Updates upgrade guide, custom layer docs, and test fixtures to reflect plugin-based shader customization.

Reviewed by Cursor Bugbot for commit 9023741. Bugbot is set up for automated code reviews on this repo. Configure here.

@ibgreen ibgreen changed the title WIP: Migrate shader APIs to luma.gl alpha.9 Migrate shader hooks and plugins to luma.gl alpha.9 Nov 3, 2026
@ibgreen
ibgreen marked this pull request as ready for review November 3, 2026 23:34
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ⚠️ Failed 2026-11-03T23:34:11.534288Z
We couldn’t complete this review. Comment @codex review to try again.
18289a2 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector

Copy link
Copy Markdown

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 18289a2. Configure here.

@greptile-apps

greptile-apps Bot commented Nov 3, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[High impact] The PR appears safe to merge; the previous aggregation filter finding is addressed.

Summary

Migrates shader hooks and extensions to luma.gl alpha.9 plugins.

  • Layers combine shader plugins with modules for rendering.
  • Shader extensions keep their hooks with the modules they use.
  • TripsLayer uses named WGSL hooks to fade and filter paths by time.

Reviews (2) · Last reviewed commit: "Forward shader plugins to GPU aggregatio..." · Reviewed by Greptile

@coveralls

coveralls commented Nov 3, 2026 •

Copy link
Copy Markdown

Coverage Status

coverage: 84.465% (-0.007%) from 84.472% — codex/bump-luma-alpha-9 into master

@ibgreen
ibgreen merged commit 7ca2523 into master Nov 3, 2026
9 checks passed
@ibgreen
ibgreen deleted the codex/bump-luma-alpha-9 branch November 3, 2026 23:56

@chrisgervang chrisgervang left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed 9023741 after merge; follow-ups below. One P1: the RedFilter example in layer-extensions.md throws. The upgrade-guide entry for this breaking change needs the "This applies if you…" form with Before code.

Labels: P1 settle before this is merged, P2 can follow, Non-blocking optional.

Comment on lines 224 to +225
const shaders = super.getShaders();
shaders.inject = {
// Standard injection hook - see "Writing Shaders"
'fs:DECKGL_FILTER_COLOR': `
shaders.plugins = [...(shaders.plugins || []), {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1: This example throws TypeError: Cannot read properties of null (reading 'plugins'). In an extension, super.getShaders() calls LayerExtension.getShaders, which returns null (layer-extension.ts:38-40).

  • Running this getShaders against the built LayerExtension threw that error.
  • The super call predates this PR. The rewrite kept it.

Could the extension return its plugin directly, as the WebGPU section at the end of the page already says? This also fixes the comment on line 229 from #11023.

class RedFilter extends LayerExtension {
  getShaders() {
    return {
      plugins: [{
        name: 'highlight',
        module: highlightUniforms,
        injections: {
          // Standard injection target - see "Writing Shaders"
          'glsl:fs:DECKGL_FILTER_COLOR': `
          if (highlight.enabled) {
            if (color.r / max(color.g, 0.001) > 2. && color.r / max(color.b, 0.001) > 2.) {
              // is red
              color = vec4(1.0, 0.0, 0.0, 1.0);
            } else {
              discard;
            }
          }
        `
        }
      }]
    };
  }

Comment thread docs/upgrade-guide.md
Comment on lines +36 to +58
Shader injections move from `inject` on modules or model options into native
`ShaderPlugin` descriptors passed in `plugins`. Keep reusable shader source, uniforms,
and dependencies in a `ShaderModule`; attach it as the plugin's `module` when it also
contributes injections. Preserve inherited plugins when extending a layer:

```ts
const shaders = super.getShaders();
return {
...shaders,
plugins: [...(shaders.plugins || []), {
name: 'customFilter',
injections: {'glsl:fs:DECKGL_FILTER_COLOR': 'color.a *= 0.5;'}
}]
};
```

`addShaderHook` now takes `{name, stage, glsl: {parameters}}` instead of a GLSL
signature string. Use explicit `ShaderInjection` arrays for ordered injections and
language-qualified keys for GLSL-only plugins. `Layer.getShaders` still installs
picking hooks when its `modules` includes deck's `picking` module. Custom models
constructed outside that method must pass `plugins: [pickingPlugin]` from
`@deck.gl/core` to install the picking module and its hooks. Similarly, use
`shadowPlugin` instead of adding `shadow` alone to a custom model.

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2: This breaks every custom layer, extension and shader module that injects code. The entry has no "This applies if you…" line and no Before code. It also doesn't say that an inject field on a ShaderModule is now dropped without a warning.

  • With luma.gl alpha.10, a module's inject was missing from the assembled shader. Top-level inject and plugin injections were present.
  • The alpha.11 assembler has no read of module inject either.

Could these paragraphs (master lines 44-68, including the #11023 rename) become three entries like these?

#### Shader injections

This applies if a custom layer, extension or shader module uses `inject`. Move the injections into a `ShaderPlugin` in `plugins`. An `inject` field on a `ShaderModule` is now ignored without a warning.

```ts
// Before
const myModule = {name: 'myFilter', fs, inject: {'fs:DECKGL_FILTER_COLOR': 'color.a *= 0.5;'}};
const shaders = super.getShaders();
return {...shaders, modules: [...shaders.modules, myModule]};

// After
const myModule = {name: 'myFilter', fs};
const shaders = super.getShaders();
return {
  ...shaders,
  plugins: [...(shaders.plugins || []), {
    name: 'myFilter',
    module: myModule,
    injections: {'glsl:fs:DECKGL_FILTER_COLOR': 'color.a *= 0.5;'}
  }]
};
```

#### `addShaderHook`

This applies if you register your own injection targets. Call `addShaderInjectionTarget` with a descriptor.

```ts
// Before
ShaderAssembler.getDefaultShaderAssembler().addShaderHook('fs:MY_FILTER(inout vec4 color)');

// After
getShaderAssembler('glsl').addShaderInjectionTarget({
  name: 'MY_FILTER',
  stage: 'fragment',
  glsl: {parameters: 'inout vec4 color'}
});
```

#### Picking and shadows in custom models

This applies if you create a `Model` without `this.getShaders()` and add the `picking` or `shadow` module. Pass `pickingPlugin` or `shadowPlugin` from `@deck.gl/core` in `plugins` instead.

```ts
// Before
new Model(device, {vs, fs, modules: [picking]});

// After
new Model(device, {vs, fs, plugins: [pickingPlugin]});
```

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants