feat(engine): model cleanup (#1779)

docs/api-reference/debug/README.md → docs-wip/debug/README.md

@@ -10,7 +10,6 @@ To use debug support, first import the debug tools, then call `createGLContext`
 
 ```typescript
 import {createGLContext} from '@luma.gl/gltools';
-import '@luma.gl/debug';
 const gl = createGLContext(gl, {debug: true});
 ```
 

docs/README.mdx

@@ -1,4 +1,4 @@
-# Introduction
+# Overview
 
 <p/>
 <p>
@@ -48,21 +48,21 @@
 
 luma.gl is a modern GPU toolkit for the Web, created to facilitate processing and visualization of big data on GPUs, that offers:
 
-- A "closer-to-the-metal" API for working with GPUs in JavaScript.
-- WebGPU, WebGL2 and WebGL backends.
-- A GLSL shader system supporting modules, dependencies, injection, transpilation etc.
-- A minimal set of higher-level classes such as `Model`, `Transform` and `AnimationLoop` and basic scenegraph support.
+- A "close-to-the-metal" API for working with GPUs in TypeScript and JavaScript.
+- Offers WebGPU, WebGL2 and WebGL backends.
+- A minimal set of engine-level classes such as `Model`, `Transform` and `AnimationLoop` and basic scenegraph support.
 - glTF support.
-- Shader modules for compute, visual effects and post processing.
+- A shader management system supporting shader modules, dependencies, injection, transpilation etc.
+- Pre-optimized shader modules for compute, visual effects and post processing.
 
-Instead of including limited support for math and data loading, luma.gl integrates seamlessly with dedicated companion framworks such as:
+Unlike some other GPU frameworks, luma.gl does not include support for prerequisites such math and data loading. Instead luma.gl integrates seamlessly with dedicated companion framworks such as:
 
-- [loaders.gl](https://loaders.gl) - a long list of 3D and geospatial data format standards are supported out of the box.
+- [loaders.gl](https://loaders.gl) - wide range of 3D and geospatial data format standards.
 - [math.gl](https://uber-web.github.io/math.gl/docs) - a variety of high precision geospatial and 3D math logic.
 
-luma.gl is a small framework that can be used to build other GPU frameworks. The canonical example is
+luma.gl is intended to be a foundation on top of which to build higher-level GPU frameworks. The primary example is
 
-- [deck.gl](https://deck.gl) - an extensive geospatial GPU framework that even supports functional programming paradigms, built on top of luma.gl.
+- [deck.gl](https://deck.gl) - geospatial GPU visualization and compute via a high-performance functional programming API.
 
 ## Philosophy
 

docs/developer-guide/debugging.md

@@ -64,14 +64,17 @@ Buffers will also have their first values checked to ensure that they are not Na
 
 ## Resource Leak Detection
 
-See the chapter on Profiling for some tools that can help spot resource leaks.
+See the chapter on Profiling for tools that can help spot resource leaks.
 
-## Khronos WebGL developer tools integration (WebGL only)
+## WebGL API tracing integration (WebGL only)
 
-luma.gl is pre-integrated with the Khronos group's WebGL developer tools (the [WebGLDeveloperTools](https://github.com/KhronosGroup/WebGLDeveloperTools)) and luma.gl use these tools to "instrument" the `WebGLRenderingContext` which enabled:
+luma.gl is pre-integrated with the Khronos group's WebGL developer tools (the [WebGLDeveloperTools](https://github.com/KhronosGroup/WebGLDeveloperTools)) which provide the following features:
 
-- **Inline WebGL Error Detections** - Check the WebGL error status after each WebGL call and throws an exception if an error was detected, breaking the debugger at the correct place, and also extract helpful information about the error. 
-- **WebGL Parameters Checking** - Ensure that WebGL parameters are set to valid values.
+- **WebGL API tracing** - Logs each call to the WebGL context with parameters.
+- **Synchronous WebGL Error Detections** - Checks the WebGL error status after each WebGL call and throws an exception if an error was detected, breaking the debugger at the correct place, and also extract helpful information about the error. 
+- **WebGL Parameters Checking** - Checks that WebGL parameters are set to valid values.
+
+The most flexible way to enable WebGL API tracing is by typing the following command into the browser developer tools console:
 
 Note that the developer tools module is loaded dynamically when a device is created with the debug flag set, so the developer tools can be activated in production code by opening the browser console and typing:
 
@@ -93,12 +96,23 @@ const device = luma.createDevice({type: 'webgl', debug: true});
 
 luma.gl integrates with [Spector.js](https://spector.babylonjs.com/), a powerful debug tool created by the BabylonJS team.
 
-To avoid performance impact, luma.gl doesn't load or start spector.js by default. 
+The most flexible way to enable Spector.js is by typing the following command into the browser developer tools console:
+
+```
+luma.log.set('spector', true);
+```
 
-- Add the `spector: true` option when creating a device.
+And then restarting the application (e.g. via Command-R on MacOS),
+
+
+You can also enable spector when creating a device  by adding the `spector: true` option.
 
 To display Spector.js stats when loaded.
 
 ```
 luma.spector.displayUI()
 ```
+
+:::info
+Spector.js is dynamically loaded into your application, so there is no bundle size penalty.
+:::

docs/sidebar.json

@@ -1,17 +1,6 @@
 [
   "README",
   "whats-new", 
-  "public-review",
-  {
-    "type": "category",
-    "label": "Upgrade Guide",
-    "items": [
-      "upgrade-guide/README",
-      "upgrade-guide/api-philosophy",
-      "upgrade-guide/upgrade-v9",
-      "upgrade-guide/upgrade-v9-parameters"
-    ]
-  },
   {
     "type": "category",
     "label": "Tutorials",
@@ -30,18 +19,6 @@
       "tutorials/whats-next"
     ]
   },
-  {
-    "type": "category",
-    "label": "Developer Guide",
-    "items": [
-      "developer-guide/installing",
-      "developer-guide/debugging",
-      "developer-guide/testing",
-      "developer-guide/profiling",
-      "developer-guide/bundling",
-      "developer-guide/contributing"
-    ]
-  },
   {
     "type": "category",
     "label": "API Guide",
@@ -54,6 +31,7 @@
           "api-guide/background/webgpu-vs-webgl"
         ]
       },
+      "public-review",
       "api-guide/README",
       "api-guide/device",
       "api-guide/resources",
@@ -210,14 +188,29 @@
         "items": [
           "api-reference/webgpu/README"
         ]
-      },
-      {
-        "type": "category",
-        "label": "@luma.gl/debug",
-        "items": [
-          "api-reference/debug/README"
-        ]
       }
     ]
+  },  
+  {
+    "type": "category",
+    "label": "Developer Guide",
+    "items": [
+      "developer-guide/installing",
+      "developer-guide/debugging",
+      "developer-guide/testing",
+      "developer-guide/profiling",
+      "developer-guide/bundling",
+      "developer-guide/contributing"
+    ]
+  },
+  {
+    "type": "category",
+    "label": "Upgrade Guide",
+    "items": [
+      "upgrade-guide/README",
+      "upgrade-guide/api-philosophy",
+      "upgrade-guide/upgrade-v9",
+      "upgrade-guide/upgrade-v9-parameters"
+    ]
   }
 ]

docs/tutorials/transform.mdx

@@ -1,4 +1,5 @@
 import {DeviceTabs} from '@site/src/react-luma';
+import {TransformExample} from '@site';
 
 # Transform
 
@@ -9,6 +10,7 @@ TransformFeedback based examples are temporarily disabled until `Transform` clas
 :::
 
 <DeviceTabs />
+<TransformExample />
 
 In this tutorial, we'll learn how to use [transform feedback](https://www.khronos.org/opengl/wiki/Transform_Feedback) using luma.gl's high-level API. Transform feedback allows us to capture vertex shader results from one pass and use them in subsequent passes. It is a powerful tool that can be used to set up massively parrallelized animations or data transformations. Note that transform feedback can only be used with WebGL 2.
 

docs/upgrade-guide/README.md

@@ -1,14 +1,20 @@
 # Upgrade Guide
 
-This upgrade guide focuses on breaking changes in the APIs.
+This upgrade guide calls out any breaking changes in the luma.gl API. It covers all releases, and includes information on how to update affected applications.
 
-> Upgrade instructions assume that you are upgrading from the immediately previous release.
-> If you are upgrading across multiple releases you will want to consider the release notes for all
-> intermediary releases.
+:::info
+luma.gl largely follows [**semantic versioning**](https://semver.org) conventions: breaking changes are done in major versions only, minor version bumps  bring new functionality but no breaking changes, and patch releases contain only low-risk fixes. However luma.gl is a big framework and there are cases where maintainers decide that it is reasonable to make a small breaking change in a minor releases for some infrequently used part of the API. 
+:::
+
+:::caution
+Upgrade instructions assume that you are upgrading from the immediately previous release.
+If you are upgrading across multiple releases you will want to consider the release notes for all
+intermediary releases.
+:::
 
 ## Upgrading to v9.0
 
-luma.gl v9 represents a major API changes and a substantial amount of documentation is provided:
+luma.gl v9 represents a major, "once in a generation" API change and separate documentation is provided:
 - [v9 upgrade guide](./upgrade-to-v9).
 - [v9 GPU parameter upgrade guide](./upgrade-v9-parameters.md)
 - [v9 API philosophy](./api-philosophy).

examples-wip/api-v8/program-management/package.json

@@ -1,17 +1,17 @@
 {
   "name": "luma.gl-examples-program-management",
-  "version": "9.0.0-alpha.21",
+  "version": "9.0.0-alpha.27",
   "private": true,
   "scripts": {
     "start": "vite",
     "build": "tsc && vite build",
     "serve": "vite preview"
   },
   "dependencies": {
-    "@luma.gl/core": "9.0.0-alpha.21",
-    "@luma.gl/engine": "9.0.0-alpha.21",
-    "@luma.gl/shadertools": "9.0.0-alpha.21",
-    "@luma.gl/webgl": "9.0.0-alpha.21",
+    "@luma.gl/core": "9.0.0-alpha.27",
+    "@luma.gl/engine": "9.0.0-alpha.27",
+    "@luma.gl/shadertools": "9.0.0-alpha.27",
+    "@luma.gl/webgl": "9.0.0-alpha.27",
     "@math.gl/core": "4.0.0-alpha.4"
   },
   "devDependencies": {

examples-wip/api-v8/program-management/vite.config.ts

@@ -4,7 +4,6 @@ const alias = {
   '@luma.gl/api': `${__dirname}/../../../modules/api/src`,
   '@luma.gl/constants': `${__dirname}/../../../modules/constants/src`,
   '@luma.gl/core': `${__dirname}/../../../modules/core/src`,
-  '@luma.gl/debug': `${__dirname}/../../../modules/debug/src`,
   '@luma.gl/engine': `${__dirname}/../../../modules/engine/src`,
   '@luma.gl/experimental': `${__dirname}/../../../modules/experimental/src`,
   '@luma.gl/webgl-legacy': `${__dirname}/../../../modules/webgl-legacy/src`,

examples-wip/api-v8/stress-test/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luma.gl-example-stress-test",
-  "version": "9.0.0-alpha.21",
+  "version": "9.0.0-alpha.27",
   "private": true,
   "description": "A stress test for luma.gl.",
   "contributors": [
@@ -12,10 +12,10 @@
     "serve": "vite preview"
   },
   "dependencies": {
-    "@luma.gl/constants": "9.0.0-alpha.21",
-    "@luma.gl/engine": "9.0.0-alpha.21",
-    "@luma.gl/shadertools": "9.0.0-alpha.21",
-    "@luma.gl/webgl": "9.0.0-alpha.21",
+    "@luma.gl/constants": "9.0.0-alpha.27",
+    "@luma.gl/engine": "9.0.0-alpha.27",
+    "@luma.gl/shadertools": "9.0.0-alpha.27",
+    "@luma.gl/webgl": "9.0.0-alpha.27",
     "@math.gl/core": "4.0.0-alpha.4",
     "@probe.gl/stats-widget": "^4.0.0"
   },

examples-wip/notready/dof/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luma.gl-examples-dof",
-  "version": "9.0.0-alpha.21",
+  "version": "9.0.0-alpha.27",
   "private": true,
   "description": "An es6 Depth of Field example for luma.gl.",
   "contributors": [
@@ -12,11 +12,11 @@
     "serve": "vite preview"
   },
   "dependencies": {
-    "@luma.gl/constants": "9.0.0-alpha.21",
-    "@luma.gl/core": "9.0.0-alpha.21",
-    "@luma.gl/engine": "9.0.0-alpha.21",
-    "@luma.gl/webgl": "9.0.0-alpha.21",
-    "@luma.gl/webgl-legacy": "9.0.0-alpha.21",
+    "@luma.gl/constants": "9.0.0-alpha.27",
+    "@luma.gl/core": "9.0.0-alpha.27",
+    "@luma.gl/engine": "9.0.0-alpha.27",
+    "@luma.gl/webgl": "9.0.0-alpha.27",
+    "@luma.gl/webgl-legacy": "9.0.0-alpha.27",
     "@math.gl/core": "4.0.0-alpha.4"
   },
   "devDependencies": {

examples-wip/notready/dof/vite.config.ts

@@ -4,7 +4,6 @@ const alias = {
   '@luma.gl/api': `${__dirname}/../../../modules/api/src`,
   '@luma.gl/constants': `${__dirname}/../../../modules/constants/src`,
   '@luma.gl/core': `${__dirname}/../../../modules/core/src`,
-  '@luma.gl/debug': `${__dirname}/../../../modules/debug/src`,
   '@luma.gl/engine': `${__dirname}/../../../modules/engine/src`,
   '@luma.gl/experimental': `${__dirname}/../../../modules/experimental/src`,
   '@luma.gl/webgl-legacy': `${__dirname}/../../../modules/webgl-legacy/src`,

examples-wip/notready/geospatial/package.json

@@ -1,16 +1,16 @@
 {
   "name": "luma.gl-examples-geospatial",
-  "version": "9.0.0-alpha.21",
+  "version": "9.0.0-alpha.27",
   "private": true,
   "scripts": {
     "start": "vite",
     "build": "tsc && vite build",
     "serve": "vite preview"
   },
   "dependencies": {
-    "@luma.gl/engine": "9.0.0-alpha.21",
-    "@luma.gl/webgl": "9.0.0-alpha.21",
-    "@luma.gl/webgl-legacy": "9.0.0-alpha.21",
+    "@luma.gl/engine": "9.0.0-alpha.27",
+    "@luma.gl/webgl": "9.0.0-alpha.27",
+    "@luma.gl/webgl-legacy": "9.0.0-alpha.27",
     "mapbox-gl": "^1.2.1"
   },
   "devDependencies": {

examples-wip/notready/geospatial/vite.config.ts

@@ -4,7 +4,6 @@ const alias = {
   '@luma.gl/api': `${__dirname}/../../../modules/api/src`,
   '@luma.gl/constants': `${__dirname}/../../../modules/constants/src`,
   '@luma.gl/core': `${__dirname}/../../../modules/core/src`,
-  '@luma.gl/debug': `${__dirname}/../../../modules/debug/src`,
   '@luma.gl/engine': `${__dirname}/../../../modules/engine/src`,
   '@luma.gl/experimental': `${__dirname}/../../../modules/experimental/src`,
   '@luma.gl/webgl-legacy': `${__dirname}/../../../modules/webgl-legacy/src`,

examples-wip/notready/gltf/package.json

@@ -1,6 +1,6 @@
 {
   "name": "luma.gl-examples-gltf",
-  "version": "9.0.0-alpha.21",
+  "version": "9.0.0-alpha.27",
   "private": true,
   "description": "glTF loader using luma.gl for rendering.",
   "contributors": [
@@ -15,11 +15,11 @@
     "@loaders.gl/core": "^3.2.12",
     "@loaders.gl/gltf": "^3.2.12",
     "@loaders.gl/polyfills": "^3.2.12",
-    "@luma.gl/constants": "9.0.0-alpha.21",
-    "@luma.gl/engine": "9.0.0-alpha.21",
-    "@luma.gl/experimental": "9.0.0-alpha.21",
-    "@luma.gl/webgl": "9.0.0-alpha.21",
-    "@luma.gl/webgl-legacy": "9.0.0-alpha.21",
+    "@luma.gl/constants": "9.0.0-alpha.27",
+    "@luma.gl/engine": "9.0.0-alpha.27",
+    "@luma.gl/experimental": "9.0.0-alpha.27",
+    "@luma.gl/webgl": "9.0.0-alpha.27",
+    "@luma.gl/webgl-legacy": "9.0.0-alpha.27",
     "@math.gl/core": "4.0.0-alpha.4"
   },
   "devDependencies": {

examples-wip/notready/gltf/vite.config.ts

@@ -4,7 +4,6 @@ const alias = {
   '@luma.gl/api': `${__dirname}/../../../modules/api/src`,
   '@luma.gl/constants': `${__dirname}/../../../modules/constants/src`,
   '@luma.gl/core': `${__dirname}/../../../modules/core/src`,
-  '@luma.gl/debug': `${__dirname}/../../../modules/debug/src`,
   '@luma.gl/engine': `${__dirname}/../../../modules/engine/src`,
   '@luma.gl/experimental': `${__dirname}/../../../modules/experimental/src`,
   '@luma.gl/webgl-legacy': `${__dirname}/../../../modules/webgl-legacy/src`,

examples-wip/notready/instanced-transform/package.json

@@ -1,17 +1,17 @@
 {
   "name": "luma.gl-examples-instanced-transform",
-  "version": "9.0.0-alpha.21",
+  "version": "9.0.0-alpha.27",
   "private": true,
   "scripts": {
     "start": "vite",
     "build": "tsc && vite build",
     "serve": "vite preview"
   },
   "dependencies": {
-    "@luma.gl/engine": "9.0.0-alpha.21",
-    "@luma.gl/shadertools": "9.0.0-alpha.21",
-    "@luma.gl/webgl": "9.0.0-alpha.21",
-    "@luma.gl/webgl-legacy": "9.0.0-alpha.21",
+    "@luma.gl/engine": "9.0.0-alpha.27",
+    "@luma.gl/shadertools": "9.0.0-alpha.27",
+    "@luma.gl/webgl": "9.0.0-alpha.27",
+    "@luma.gl/webgl-legacy": "9.0.0-alpha.27",
     "@math.gl/core": "4.0.0-alpha.4"
   },
   "devDependencies": {

examples-wip/notready/instanced-transform/vite.config.ts

@@ -4,7 +4,6 @@ const alias = {
   '@luma.gl/api': `${__dirname}/../../../modules/api/src`,
   '@luma.gl/constants': `${__dirname}/../../../modules/constants/src`,
   '@luma.gl/core': `${__dirname}/../../../modules/core/src`,
-  '@luma.gl/debug': `${__dirname}/../../../modules/debug/src`,
   '@luma.gl/engine': `${__dirname}/../../../modules/engine/src`,
   '@luma.gl/experimental': `${__dirname}/../../../modules/experimental/src`,
   '@luma.gl/webgl-legacy': `${__dirname}/../../../modules/webgl-legacy/src`,