Update docs for luma.gl v9 and API changes

Revised documentation to reflect luma.gl v9 updates, including changes to GPU parameter handling, device initialization, and usage of string constants over WebGL constants.

Author: chrisgervang

docs/api-reference/core/deck.md

@@ -147,35 +147,40 @@ Note:
 
 #### `parameters` (object) {#parameters}
 
-Expects an object with GPU parameters. Before each frame is rendered, this object will be passed to luma.gl's `setParameters` function to reset the GPU context parameters, e.g. to disable depth testing, change blending modes etc. The default parameters set by `Deck` on initialization are the following:
+Expects an object with GPU parameters. Before each frame is rendered, this object will be passed to luma.gl's `RenderPass` to reset the GPU context parameters, e.g. to disable depth testing, change blending modes etc. The default parameters set by `Deck` on initialization are the following:
 
 ```js
 {
   blend: true,
-  blendFunc: [GL.SRC_ALPHA, GL.ONE_MINUS_SRC_ALPHA, GL.ONE, GL.ONE_MINUS_SRC_ALPHA],
+  blendColorSrcFactor: 'src-alpha',
+  blendColorDstFactor: 'one-minus-src-alpha',  
+  blendAlphaSrcFactor: 'one',
+  blendAlphaDstFactor: 'one-minus-src-alpha'
   polygonOffsetFill: true,
-  depthTest: true,
-  depthFunc: GL.LEQUAL
+  depthWriteEnabled: true,
+  depthCompare: 'less-equal'
 }
 ```
 
-Refer to the luma.gl [setParameters](https://github.com/visgl/luma.gl/blob/8.5-release/modules/gltools/docs/api-reference/parameter-setting.md) API for documentation on supported parameters and values.
+Refer to the luma.gl [GPU parameters](https://luma.gl/docs/api-reference/core/parameters) API for documentation on supported parameters and values.
 
 ```js
-import GL from '@luma.gl/constants';
 new Deck({
   // ...
   parameters: {
-    blendFunc: [GL.ONE, GL.ONE, GL.ONE, GL.ONE],
-    depthTest: false
+    blendColorSrcFactor: 'one',
+    blendColorDstFactor: 'one',
+    blendAlphaSrcFactor: 'one',
+    blendAlphaDstFactor: 'one'
+    depthWriteEnabled: false
   }
 });
 ```
 
 Notes:
 
 - Any GPU `parameters` prop supplied to individual layers will still override the global `parameters` when that layer is rendered.
-- An alternative way to set `parameters`  is to instead define the `onWebGLInitialized` callback (it receives the `gl` context as parameter) and call the luma.gl `setParameters` method inside it.
+- An alternative way to set `parameters`  is to instead define the `onDeviceInitialized` callback (it receives the `device.handle` context as parameter) and call the luma.gl `setParameters` method inside it.
 
 #### `layers` (LayersList) {#layers}
 

docs/api-reference/mesh-layers/simple-mesh-layer.md

@@ -16,7 +16,7 @@ import TabItem from '@theme/TabItem';
 ```js
 import {Deck} from '@deck.gl/core';
 import {SimpleMeshLayer} from '@deck.gl/mesh-layers';
-import {OBJLoader} from '@deck.gl/obj';
+import {OBJLoader} from '@loaders.gl/obj';
 
 const layer = new SimpleMeshLayer({
   id: 'SimpleMeshLayer',
@@ -49,7 +49,7 @@ new Deck({
 ```ts
 import {Deck, PickingInfo} from '@deck.gl/core';
 import {SimpleMeshLayer} from '@deck.gl/mesh-layers';
-import {OBJLoader} from '@deck.gl/obj';
+import {OBJLoader} from '@loaders.gl/obj';
 
 type BartStation = {
   name: string;
@@ -90,7 +90,7 @@ new Deck({
 import React from 'react';
 import {DeckGL} from '@deck.gl/react';
 import {SimpleMeshLayer} from '@deck.gl/mesh-layers';
-import {OBJLoader} from '@deck.gl/obj';
+import {OBJLoader} from '@loaders.gl/obj';
 import type {PickingInfo} from '@deck.gl/core';
 
 type BartStation = {

docs/upgrade-guide.md

@@ -72,19 +72,122 @@ The following issues are known and can be expected to resolve in a 9.0 patch:
 
 ### Typescript
 
-Typescript is now enabled on all modules. The `'@deck.gl/xxx/typed'` packages are removed. 
+Typescript is now enabled on all modules. The `'@deck.gl/xxx/typed'` packages are removed.
+
+```ts
+// deck.gl v9
+import {Deck} from '@deck.gl/core'
+
+// deck.gl v8
+import {Deck} from '@deck.gl/core/typed'
+```
 
 ### luma.gl v9 Updates
 
 The biggest changes in deck.gl v9 are due to the upgrade to the luma.gl v9 API. Fortunately, deck.gl encapsulates most of the luma.gl API so the changes to deck.gl applications should be limited, in particular if the application does not directly interact with GPU resources.
 
+For more information read the [luma v9 porting guide](https://luma.gl/docs/legacy/porting-guide)
+
 Quick summary:
 
 - `DeckProps.gl (WebGLRenderingContext)` should be replaced with `device`: [Device](https://luma.gl/docs/api-reference/core/device).
-- `DeckProps.glOptions (WebGLContextAttributes)` should be replaced with `DeckProps.deviceProps.webgl`: `deviceProps: {type: 'webgl', webgl: ...glOptions}`: [WebGLDeviceProps](https://luma.gl/docs/api-reference/webgl/#webgldeviceprops)
+
+```ts
+// deck.gl v9
+import {Deck} from '@deck.gl/core'
+import {luma} from '@luma.gl/core'
+import {webgl2Adapter}'@luma.gl/webgl'
+
+new Deck({ 
+  device: await luma.createDevice({adapters: [webgl2Adapter]})
+});
+
+// deck.gl v8
+import {Deck} from '@deck.gl/core/typed'
+
+const canvas = document.getElementById('myCanvas');
+
+new Deck({ 
+  gl: canvas.getContext('webgl2')
+});
+```
+
+- `DeckProps.glOptions (WebGLContextAttributes)` should be replaced with `DeckProps.deviceProps.webgl`: [WebGLContextAttributes](https://luma.gl/docs/api-reference/core/device#webglcontextattributes)
 - `DeckProps.glOptions.preserveDrawingBuffers` is now set by default, and does not need to be overridden.
+- `DeckProps.glOptions.powerPreference` is now set to `'high-performance'` by default, and does not need to be overridden.
 - `DeckProps.onWebGLInitialized` callback is now `DeckProps.onDeviceInitialized`.
-- `LayerProps.parameters` and `LayerProps.textureParameters` no longer use WebGL constants, but instead use (WebGPU style) [string constants](https://luma.gl/docs/api-reference/core/parameters/).
+
+```ts
+// deck.gl v9
+import {Deck} from '@deck.gl/core'
+
+new Deck({
+  deviceProps: {
+    type: 'webgl', 
+    // powerPreference: 'high-performance' is now set by default
+    webgl: {
+      stencil: true
+      // preserveDrawingBuffers: true is now set by default
+    }
+  },
+  onDeviceInitialized: (device) => {
+    const gl = device.handle // WebGL2RenderingContext when using a webgl device
+  }
+});
+
+// deck.gl v8
+import {Deck} from '@deck.gl/core/typed'
+
+new Deck({
+  glOptions: {
+    stencil: true,
+    preserveDrawingBuffers: true,
+    powerPreference: 'high-performance'
+  },
+  onWebGLInitialized: (gl) => {}
+});
+```
+
+- `DeckProps.parameters`, `LayerProps.parameters`, and `LayerProps.textureParameters` no longer use WebGL constants, but instead use (WebGPU style) [string constants](https://luma.gl/docs/api-reference/core/parameters/).
+
+```ts
+// deck.gl v9 using string constants
+import {Deck} from '@deck.gl/core'
+new Deck({
+  parameters: {
+    blendColorOperation: 'add',
+    blendColorSrcFactor: 'src-alpha',
+    blendColorDstFactor: 'one',
+    blendAlphaOperation: 'add',
+    blendAlphaSrcFactor: 'one-minus-dst-alpha',
+    blendAlphaDstFactor: 'one'
+  }
+})
+
+// deck.gl v9 using GL constants
+// The constant module remains but is now considered an internal luma.gl module, and is no longer intended to be imported by applications.
+import {Deck} from '@deck.gl/core'
+import {GL} from '@luma.gl/constants' // Note the ESM import
+
+new Deck({
+  parameters: {
+    blendEquation: [GL.ADD, GL.ADD],
+    blendFunc: [GL.ONE, GL.ONE, GL.ONE, GL.ONE],
+  }
+})
+
+// deck.gl v8
+import {Deck} from '@deck.gl/core/typed'
+import GL from '@luma.gl/constants';
+
+new Deck({
+  parameters: {
+    blendEquation: [GL.ADD, GL.ADD],
+    blendFunc: [GL.ONE, GL.ONE, GL.ONE, GL.ONE],
+  }
+})
+```
+
 - When providing [binary data attributes](./api-reference/core/layer.md#data), `type` is now a WebGPU-style [string format](https://luma.gl/docs/api-guide/gpu/gpu-attributes#vertexformat) instead of a GL constant.
 - GPU resources should no longer be created by directly instantiating classes. For example, instead of `new Buffer(gl)` use `device.createBuffer()`, instead of `new Texture()` use `device.createTexture()`. See [Device methods](https://luma.gl/docs/api-reference/core/device#methods).