docs: Update release notes for 9.1 (#2251)

docs/api-reference/core/README.md

@@ -7,42 +7,32 @@ which provides methods for creating GPU resources such as `Buffer`, `Texture`, `
 ## Installing adapters
 
 The `@luma.gl/core` module is not usable on its own. A device adapter module must
-be imported and registered.
+be imported and provided during device creation.
 
 ```typescript
 import {luma} from '@luma.gl/core';
-import {WebGPUAdapter} from '@luma.gl/webgpu';
+import {webgpuAdapter} from '@luma.gl/webgpu';
 
-luma.registerDevice([WebGPUAdapter])
-const device = await luma.createDevice({type: 'webgpu', createCanvasContext: ...});
+const device = await luma.createDevice({type: 'webgpu', adapters: [webgpuAdapter], createCanvasContext: ...});
 ```
 
-It is possible to register more than one device adapter to create an application
+It is possible to supply more than one device adapter to create an application
 that can work in both WebGL and WebGPU environments.
 
 ```typescript
-luma.registerDevice([WebGPUAdapter])
 import {luma} from '@luma.gl/core';
-import {WebGPUAdapter} from '@luma.gl/webgpu';
-import {WebGLAdapter} '@luma.gl/webgl';
+import {webgpuAdapter} from '@luma.gl/webgpu';
+import {webglAdapter} '@luma.gl/webgl';
 
-const webgpuDevice = luma.createDevice({type: 'best-available', createCanvasContext: ...});
+const webgpuDevice = luma.createDevice({type: 'best-available', adapters: [webgpuAdapter, webglAdapter], createCanvasContext: ...});
 ```
 
 ## Creating GPU Resources
 
 Once the application has created a `Device`, GPU resources can be created:
 
 ```typescript
-const buffer = device.createBuffer(...)
+const buffer = device.createBuffer(...);
+const texture = device.createTexture(...);
+const renderPass = device.beginRenderPass(...);
 ```
-
-## Accessing the CanvasContext
-
-A `Device` may (optinally) be used to render in one or more canvases (HTML canvas elements).
-The connection between a Device and a canvas is managed by the `CanvasContext` class.
-
-:::info
-In WebGL there is always exactly one canvas associated with the device and it is not
-possible to create a canvas-less context or render into multiple contexts.
-:::

docs/api-reference/core/adapter.md

@@ -4,16 +4,29 @@
   <img src="https://img.shields.io/badge/From-v9.1-blue.svg?style=flat-square" alt="From-v9.1" />
 </p>
 
-An `Adapter` is a factory for `Device` instances for a specific backend (e.g. WebGPU or WebGL).
+An `Adapter` is a factory that creates [`Device`](./device) instances for a specific backend (e.g. WebGPU or WebGL).
+Each GPU backend exports a singleton adapter instance that is used to create devices for that GPU backend.
 
-Each GPU backend exports a singleton adapter instance.
+Adapters can be used directly to create and attach devices, but they are usually imported and used via the [`luma`](./luma) API through 
+methods like [`luma.createDevice`].
 
-Methods on adapters are normally not called directly, they are imported and passed to 
-methods like [`luma.createDevice`] that select the appropriate adapter before calling it.
+Note: an adapter may perform asynchronous loading of adapter code, debug libraries, etc before creating the `Device`.
+
+## Usage 
+
+Register the WebGL backend, then create a WebGL2 context, auto creating a canvas
+
+```typescript
+import {luma} from '@luma.gl/core';
+import {webgl2Adapter} from '@luma.gl/webgl';
+luma.registerAdapters([webgl2Adapter]);
+const webglDevice = await luma.createDevice({type: 'webgl', createCanvasContext: ...});
+```
 
 ## Members
 
 ### `type`
+
 ```ts
 type: string;
 ```
@@ -43,4 +56,3 @@ Attaches a device to a GPU device handle from this backend.
 ```ts
 attach?(handle: unknown): Promise<Device>;
 ```
-}

docs/api-reference/shadertools/shader-assembler.md

@@ -23,7 +23,7 @@ For shader pair compilation
 Common options
 - `prologue`=`true` (Boolean) - Will inject platform prologue (see below)
 - `defines`=`{}` (Object) - a map of key/value pairs representing custom `#define`s to be injected into the shader source
-- `modules`=`[]` (Array) - list of shader modules (either objects defining the module, or names of previously registered modules)
+- `modules`=`[]` (Array) - list of shader modules
 - `inject`=`{}` (Object) - map of substituions,
 - `hookFunctions`=`[]` Array of hook functions descriptions. Descriptions can simply be the hook function signature (with a prefix `vs` for vertex shader, or `fs` for fragment shader) or an object with the hook signature, and a header and footer that will always appear in the hook function.
 
@@ -44,7 +44,7 @@ Example of hook function
 
 ### `getDefaultShaderAssembler()`
 
-Most applications that register default modules and hooks will want to use a single `Shader`
+Most applications that register default modules and hooks will want to use a single `ShaderAssembler`
 
 ## Methods
 

docs/upgrade-guide.md

@@ -12,45 +12,47 @@ luma.gl largely follows [SEMVER](https://semver.org) conventions. Breaking chang
 
 ## Upgrading to v9.2
 
+v9.2 brings full WebGPU support. Some additional deprecations and breaking changes have been necessary, but apart from the `Texture` -> `AsyncTexture` split, impact on most applications should be minimal. 
+
+**Major change: Texture and AsyncTextures**
 - `device.createTexture()` no longer accepts `props.mipmaps`: Use `AsyncTexture` or call texture.generateMipmapsWebGL()`
 
+**Minor changes**
+- The shader type system has been refactored, some shader type names have changed. These are typically not used directly by applications.
+
 ## Upgrading to v9.1
 
 v9.1 continues to build out WebGPU support. Some additional deprecations and breaking changes have been necessary, but impact on most applications should be minimal.
 
-**Notable change: Adapters**
-
-When initializing luma.gl, applications now import an `Adapter` singleton from either the WebGPU or the WebGL module, and pass the adapter object to `luma.createDevice()`, `makeAnimationLoop` etc. 
+**Major change: Adapters**
 
-`luma.registerDevices()` is replaced with `luma.registerAdapters()` if global registration work best.
+- When initializing luma.gl, applications now import an `Adapter` singleton from the WebGPU and/or the WebGL module, and passes the adapter object(s) to `luma.createDevice()`, `makeAnimationLoop` etc. 
+- `luma.registerDevices()` can be replaced with `luma.registerAdapters()` if global registration is still desired.
 
-**Notable change: Textures**
+**Major change: Texture and AsyncTextures**
 
 - The texture API is being streamlined to work symmetrically across WebGPU and WebGL.
 - `Texture.copyExternalImage()` and `Texture.copyImageData()` replaces `Texture.setImageData()` when initializing texture memory with image data.
-
-**Notable change: AsyncTextures**
-
 - `Textures` no longer accept promises when setting data (e.g. from `loadImageBitmap(url)`. 
 - Instead, a new `AsyncTexture` class does accept promises and creates actual `Textures` once the promise resolves and data is available.
 - The `Model` class now accepts `AsyncTextures` as bindings and defers rendering until the underlying texture has been created.
 
 **@luma.gl/core**
 
-| Updated API                    | Status     | Replacement                                  | Comment                                                         |
-| ------------------------------ | ---------- | -------------------------------------------- | --------------------------------------------------------------- |
-| `luma.registerDevices()`       | Deprecated | [`luma.registerAdapters()`][adapters].       | Adapters provide a cleaner way to work with GPU backends.       |
-| `DeviceProps` for canvas       | Moved      | [`DeviceProps.createCanvasContext`][canvas]. | Move canvas related props to `props.createCanvasContext: {}`.   |
-| `DeviceProps` for webgl        | Moved      | [`DeviceProps.webgl`][webgl].                | Move canvas related props to `props.webgl: {}`.                 |
-| `DeviceProps.break`            | Removed    |                                              | Use an alterative [debugger][debugging]                         |
-| `TextureProps.data` (Promise) | Removed    | `AsyncTexture` class                         | Textures no longer accept promises.                             |
-| `Parameters.blend`             | New        |                                              | Explicit activation of color blending                           |
-| `triangle-fan-webgl` topology  | Removed    | `triangle-strip`.                            | Reorganize your geometries                                      |
-| `line-loop-webgl` topology     | Removed    | `line-list`.                                 | Reorganize your geometries                                      |
-| `glsl` shader template string  | Removed    | `/* glsl */` comment                         | Enable syntax highlighting in vscode using before shader string |
-| `depth24unorm-stencil8`        | Removed    | `depth24plus-stencil8`                       | The `TextureFormat` was removed from the WebGPU spec            |
-| `rgb8unorm-unsized`            | Removed    | `rgb8unorm`                                  | No longer support unsized WebGL1 `TextureFormat`                |
-| `rgba8unorm-unsized`           | Removed    | `rgb8aunorm`                                 | No longer support unsized WebGL1 `TextureFormat`                |
+| Updated API                   | Status     | Replacement                                  | Comment                                                         |
+| ----------------------------- | ---------- | -------------------------------------------- | --------------------------------------------------------------- |
+| `luma.registerDevices()`      | Deprecated | [`luma.registerAdapters()`][adapters].       | Adapters provide a cleaner way to work with GPU backends.       |
+| `DeviceProps.canvas`          | Moved      | [`DeviceProps.createCanvasContext`][canvas]. | Move canvas related props to `props.createCanvasContext: {}`.   |
+| `DeviceProps.<webgl options>` | Moved      | [`DeviceProps.webgl.<options>`][webgl].      | Move canvas related props to `props.webgl: {}`.                 |
+| `DeviceProps.break`           | Removed    |                                              | Use an alterative [debugger][debugging]                         |
+| `TextureProps.data` (Promise) | Removed    | `AsyncTexture` class                         | `Texture` no longer accept promises. Use `AsyncTexture`         |
+| `Parameters.blend`            | New        |                                              | Explicit activation of color blending                           |
+| `triangle-fan-webgl` topology | Removed    | `triangle-strip`.                            | Reorganize your geometries                                      |
+| `line-loop-webgl` topology    | Removed    | `line-list`.                                 | Reorganize your geometries                                      |
+| `glsl` shader template string | Removed    | `/* glsl */` comment                         | Enable syntax highlighting in vscode using before shader string |
+| `depth24unorm-stencil8`       | Removed    | `depth24plus-stencil8`                       | The `TextureFormat` was dropped from the WebGPU spec            |
+| `rgb8unorm-unsized`           | Removed    | `rgb8unorm`                                  | Drop support for unsized WebGL1 `TextureFormat`                 |
+| `rgba8unorm-unsized`          | Removed    | `rgb8aunorm`                                 | Drop support for unsized WebGL1 `TextureFormat`                 |
 
 [adapters]: /docs/api-reference/core/luma#lumaregisteradapters
 [canvas]: /docs/api-reference/core/canvas-context#canvascontextprops
@@ -67,10 +69,9 @@ When initializing luma.gl, applications now import an `Adapter` singleton from e
 | `getDependencyGraph()`               | Removed | `getShaderModuleDependencies(module)` . | Interact directly with the shader module           |
 | `glsl` template string               | Removed | `/* glsl */` comment                    | Enable syntax highlighting in vscode using comment |
 
-
 **@luma.gl/webgl**
 
-- `WebGLDeviceContext` - Note that luma.gl v9.1 and onwards set `DeviceProps.webgl.preserveDrawingBuffers` to `true` by default. This can be disabled for some memory savings and a minor performance boost on resource limited devices, such as mobile phones, at the cost of not being able to take screenshots or rendering to screen without clearing it.
+- `WebGLDeviceContext` - Note that luma.gl v9.1 and onwards set `DeviceProps.webgl.preserveDrawingBuffers` to `true` by default. This can be disabled for some (potential) memory savings and a (potential) minor performance boost on resource limited devices, such as mobile phones, at the cost of not being able to take screenshots or rendering to the screen without clearing it.
 
 ## Upgrading to v9.0
 

docs/whats-new.md

@@ -16,34 +16,40 @@ Improvements focused on enhancing WebGPU support.
 
 **@luma.gl/core**
 
-- `luma`
-  - `luma.createDevice()` Accepts a new `props.adapters` prop to avoid need for global registration of adapters.
-  - [`luma.registerAdapters()`](/docs/api-reference/core/luma#lumaregisteradapters) New method for global registration of adapters in case it still desired.
 - [`Adapter`](/docs/api-reference/core/adapter)
   - New class representing a pluggable GPU backend.
-  - Singleton `Adapter` objects are exported by `@luma.gl/webgpu` and `@luma.gl/webgl` notes below.
+  - Singleton `Adapter` objects are exported by `@luma.gl/webgpu` and `@luma.gl/webgl`.
+- `luma`
+  - Now relies on `Adapter` instances to define which GPU backends are available.
+  - Adapter can be supplied during device creation, avoiding the need for global registration of GPU backends.
+  -  `CreateDeviceProps.adapters` prop to supply list of GPU backend adapters to `luma.createDevice()`. 
+  - [`luma.registerAdapters()`](/docs/api-reference/core/luma#lumaregisteradapters) New method for global registration of adapters (in case it still desired).
 - `Device`
   - `DeviceProps.createCanvasContext` - New prop for creating a default `CanvasContext`.
-  - `DeviceProps.onResize` - New callback tracking size changes to a `CanvasContext`.
-  - `DeviceProps.onVisibilityChange` - New callback tracking visibility changes to a `CanvasContext`.
-  - `DeviceProps.onDevicePixelRatioChange` - New callback tracking DPR changes to a `CanvasContext`.
-  - `DeviceProps.debug*` - Debug option improvements, please refer to `DeviceProps` documentation.
+  - `DeviceProps.onResize` - New callback tracking size changes to `CanvasContext`s.
+  - `DeviceProps.onVisibilityChange` - New callback tracking visibility to `CanvasContext`s.
+  - `DeviceProps.onDevicePixelRatioChange` - New callback tracking device pixel resolution (DPR) changes to `CanvasContext`s.
+  - `DeviceProps.debug*` - New debug options, please refer to `DeviceProps` documentation.
 - `CanvasContext`
-  - Now calculates exact "device pixel content box" size.
-  - Now tracks size, visibility and DPR changes (see new `DeviceProps` callbacks).
+  - Now calculates exact "device pixel content box" size enabling pixel perfect sized drawing buffers (no moire etc).
+  - Now tracks size, visibility and DPR changes (see the new `DeviceProps` callbacks).
 - `Texture`
+  - Textures are now immutable and synchronous. See upgrade guide, and the new `AsyncTexture` class in `@luma.gl/engine`.
   - `Texture.copyExternalImage()` New function that works on both WebGPU and WebGL.
+  - `Texture.copyImageData()` New function that works on both WebGPU and WebGL.
+- `Sampler`
+  - `SamplerProps.mipmapFilter` New value `'none'` providing more explicit control over mipmap filtering.
 - `RenderPipeline`
   - `Parameters.blend` - New parameter that provides more explicit control over color blending activation.
--  `Sampler`
-  - `SamplerProps.mipmapFilter` has a new value `'none'` providing more explicit control over mipmap filtering.
+- `RenderPass`
+  - `RenderPassProps.clearColors` - New prop enables specification of clear colors for multiple color attachments.
 
 **@luma.gl/engine**
 
 - `makeAnimationLoopTemplate`
-  - Accepts a new `props.adapters` prop. (Avoids need for global registration of adapters).
+  - Accepts a new `.adapters` prop. (Avoids need for global registration of adapters).
 - `AsyncTexture`](/docs/api-reference/engine/async-texture)
-  - New class allows that applications to create textures from a Promise.
+  - New class allows that applications to work withcreate textures from a Promise.
 - `ShaderPassRenderer` 
   - New class that helps applications apply a `ShaderPass` list to a texture.
 
@@ -57,9 +63,14 @@ Improvements focused on enhancing WebGPU support.
 
 **@luma.gl/webgl**
 
-- `webglAdapter` New object representing the WebGL backend
+- `webglAdapter` 
+  - New object representing the WebGL backend
   - New: adds mock WEBGL1 extensions to WebGL2 contexts for better compatibility with old WebGL libraries
   - Big texture refactor to align WebGL implementation with WebGPU APIs
+- `RenderPipeline`
+  - WebGL render pipelines now support frame buffers with multiple color attachments.
+- `RenderPass`
+  - Now supports framebuffers with multiple color attachments.
 
 **@luma.gl/webgpu**