feat(core): Add blend parameter (#2061)

visgl · May 23, 2024 · a999dc6 · a999dc6
1 parent 0ab7e1e
commit a999dc6
Show file tree

Hide file tree

Showing 7 changed files with 26 additions and 8 deletions.
diff --git a/docs/api-reference/core/parameters.md b/docs/api-reference/core/parameters.md
@@ -15,6 +15,7 @@ All parameters listed in a single table
 | `scissor`                   | `RenderPass.setParameters()`   | Specifying scissor rect size                                         |                                   | `gl.scissor()`             |
 | `clearColor`                | `RenderPass(colorAttachments)` |                                                                      |                                   | `gl.clearColor()`          |
 | **Blending**                |
+| `blend`                     | `RenderPipeline(targets)`      | Enabled blending                                                     | `true`, `false`, `undefined`      | `gl.enable(GL.BLEND)`      |
 | `blendConstant`             |                                | Color used by blend factors `constant`, `one-minus-constant`         |
 | `blendColor`                | `RenderPass.setParameters()`   |
 | `blendEquation`             | `RenderPipeline(targets})`     |

diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md
@@ -23,16 +23,17 @@ Some deprectations and minor breaking changes are necessary as WebGPU support is
 | `triangle-fan-webgl`           | Removed    | Rebuild your geometries using `triangle-strip`.                                              |
 | `line-loop-webgl`              | Removed    | Rebuild your geometries`line-list`.                                                          |
 | `glsl` template string         | Removed    | Enable syntax highlighting in vscode using `/* glsl */` comment instead                      |
+| `Parameters.blend`             | New        | Explicit control over color blending                                                         |
 
 **@luma.gl/shadertools**
 
-| Updated API                          | Status   | Replacement                                                             |
-| ------------------------------------ | -------- | ----------------------------------------------------------------------- |
-| `ShaderModuleInstance`               | Removed  | Type has been removed. Use `ShaderModule` instead.                      |
-| `initializeShaderModule()`           | Changed  | Stores initialized information on the original shader module object.    |
+| Updated API                          | Status  | Replacement                                                             |
+| ------------------------------------ | ------- | ----------------------------------------------------------------------- |
+| `ShaderModuleInstance`               | Removed | Type has been removed. Use `ShaderModule` instead.                      |
+| `initializeShaderModule()`           | Changed | Stores initialized information on the original shader module object.    |
 | `ShaderModuleInstance.getUniforms()` | Removed | Use `getShaderModuleUniforms(module, ...)` instead.                     |
-| `getDependencyGraph()`               | Removed  | Use `getShaderModuleDependencies(module)` instead.                      |
-| `glsl` template string               | Removed  | Enable syntax highlighting in vscode using `/* glsl */` comment instead |
+| `getDependencyGraph()`               | Removed | Use `getShaderModuleDependencies(module)` instead.                      |
+| `glsl` template string               | Removed | Enable syntax highlighting in vscode using `/* glsl */` comment instead |
 
 ## Upgrading to v9.0
 

diff --git a/docs/whats-new.md b/docs/whats-new.md
@@ -11,6 +11,7 @@ Target Date: Q2 2024
 **@luma.gl/core**
 
 - New [`luma.registerAdapters()`](/docs/api-reference/core/luma#lumaregisteradapters) method - Register adapters for WebGL and WebGPU.
+- New `Parameters.blend` - Provides explicit control over color blending activation.
 
 **@luma.gl/engine**
 

diff --git a/modules/core/src/adapter/types/parameters.ts b/modules/core/src/adapter/types/parameters.ts
@@ -142,6 +142,9 @@ export type BlendOperation = 'add' | 'subtract' | 'reverse-subtract' | 'min' | '
 
 /* Color parameters are set on the RenderPipeline */
 export type ColorParameters = {
+  /** Enable blending */
+  blend?: boolean;
+
   /** Defines the operation used to calculate the values written to the target attachment components. */
   blendColorOperation?: BlendOperation;
   /** Defines the operation to be performed on values from the fragment shader. */
@@ -229,6 +232,7 @@ export const DEFAULT_PARAMETERS: Required<Parameters> = {
   sampleAlphaToCoverageEnabled: false,
 
   // Color and blend parameters
+  blend: false,
 
   blendColorOperation: 'add',
   blendColorSrcFactor: 'one',

diff --git a/modules/engine/test/transform/texture-transform.spec.ts b/modules/engine/test/transform/texture-transform.spec.ts
@@ -48,6 +48,7 @@ test('TextureTransform#attribute', async t => {
     vertexCount: 6,
     parameters: {
       depthCompare: 'always',
+      blend: true,
       blendColorOperation: 'add',
       blendColorSrcFactor: 'one',
       blendColorDstFactor: 'one'
@@ -96,6 +97,7 @@ test('TextureTransform#texture', async t => {
     bindings: {uSampler: inputTexture},
     parameters: {
       depthCompare: 'always',
+      blend: true,
       blendColorOperation: 'add',
       blendColorSrcFactor: 'one',
       blendColorDstFactor: 'one'

diff --git a/modules/test-utils/tsconfig.json b/modules/test-utils/tsconfig.json
@@ -10,6 +10,7 @@
   },
   "references": [
     {"path": "../core"},
+    {"path": "../engine"},
     {"path": "../webgl"},
     {"path": "../webgpu"}
   ]

diff --git a/modules/webgl/src/adapter/converters/device-parameters.ts b/modules/webgl/src/adapter/converters/device-parameters.ts
@@ -278,10 +278,18 @@ export function setDeviceParameters(device: Device, parameters: Parameters) {
   // },
 
   // COLOR STATE
+  switch (parameters.blend) {
+    case true:
+      gl.enable(GL.BLEND);
+      break;
+    case false:
+      gl.disable(GL.BLEND);
+      break;
+    default:
+    // leave WebGL blend state unchanged if `parameters.blend` is not set
+  }
 
   if (parameters.blendColorOperation || parameters.blendAlphaOperation) {
-    gl.enable(GL.BLEND);
-
     const colorEquation = convertBlendOperationToEquation(
       'blendColorOperation',
       parameters.blendColorOperation || 'add'