chore(core): Rename api to core (#1783)

visgl · Aug 18, 2023 · b1b1ba3 · b1b1ba3
1 parent f3eb206
commit b1b1ba3
Show file tree

Hide file tree

Showing 374 changed files with 989 additions and 737 deletions.
diff --git a/docs/api-guide/README.md b/docs/api-guide/README.md
@@ -15,10 +15,10 @@ Core responsibilities for any GPU library are to enable applications to perform:
 
 luma.gl enables the creation of portable applications that can run on top of either WebGPU, WebGL 2, or WebGL.
 
-The `@luma.gl/api` module provides an abstract API for writing application code
+The `@luma.gl/core` module provides an abstract API for writing application code
 that works with both WebGPU and WebGL.
 
-The `@luma.gl/api` module cannot be used on its own: it relies on being backed up by another module
+The `@luma.gl/core` module cannot be used on its own: it relies on being backed up by another module
 that implements the API. luma.gl provides adapters (implementations of the abstract API)
 through the `@luma.gl/webgl` and `@luma.gl/webgpu` modules.
 

diff --git a/docs/api-guide/device.md b/docs/api-guide/device.md
@@ -12,7 +12,7 @@ Each `CanvasContext` provides a connection between a `Device` and an `HTMLCanvas
 
 ## Registering Device Types
 
-The `@luma.gl/api` module defines abstract API interfaces such as `Device`, `Buffer` etc and is not usable on its own. 
+The `@luma.gl/core` module defines abstract API interfaces such as `Device`, `Buffer` etc and is not usable on its own. 
 
 One or more device types must be also be imported from a corresponding GPU API backend module
 (`@luma.gl/webgl` and/or `@luma.gl/webgpu`) and then registered with luma.gl.
@@ -25,7 +25,7 @@ yarn add @luma.gl/webgpu
 ```
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import {WebGPUDevice} from '@luma.gl/webgpu';
 
 luma.registerDevices([WebGPUDevice]);
@@ -43,7 +43,7 @@ yarn add @luma.gl/webgpu
 ```
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import {WebGLDevice} from '@luma.gl/webgl';
 import {WebGPUDevice} from '@luma.gl/webgpu';
 
@@ -57,7 +57,7 @@ const webgpuDevice = luma.createDevice({type: 'best-available', canvas: ...});
 Create a WebGL2 or WebGL context, auto creating a canvas
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import {WebGLDevice} from '@luma.gl/webgl';
 
 luma.registerDevices([WebGLDevice]);
@@ -67,7 +67,7 @@ const webgpuDevice = luma.createDevice({type: 'webgl', canvas: ...});
 Create a WebGL 2 context (throws if WebGL2 not supported)
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import {WebGLDevice} from '@luma.gl/webgl';
 
 luma.registerDevices([WebGLDevice]);

diff --git a/docs/api-reference-v8/webgl-legacy/engine/README.md b/docs/api-reference-v8/webgl-legacy/engine/README.md
@@ -5,5 +5,5 @@ to facilitate application development.
 
 ## Remarks
 
-- The engine classes are built on top of the abstract API in `@luma.gl/api` module
+- The engine classes are built on top of the abstract API in `@luma.gl/core` module
 and are thus portable between GPUs. 
diff --git a/docs/api-reference/README.md b/docs/api-reference/README.md
@@ -4,10 +4,10 @@ luma.gl is packaged and published as a suite of composable npm modules, so that
 
 | Module                                  | Usage       | Description                                                                                          |
 | --------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------- |
-| [`@luma.gl/api`][api]                   | Required    | The "Abstract" `Device` API (implemented by both the `webgpu` and `webgl` modules).                  |
+| [`@luma.gl/core`][api]                   | Required    | The "Abstract" `Device` API (implemented by both the `webgpu` and `webgl` modules).                  |
 | [`@luma.gl/webgl`][webgl]               | Required \* | `Device` adapter implemented using the WebGPU API. Enables creation of WebGPU resources              |
 | [`@luma.gl/webgpu`][webgpu]             | Required \* | `Device` adapter implemented using the WebGL API. Enables creation of WebGL resources.               |
-| [`@luma.gl/core`][core]                 | Recommended | A set of WebGPU/WebGL independent core 3D engine style classes built on top of `@luma.gl/api`.       |
+| [`@luma.gl/core`][core]                 | Recommended | A set of WebGPU/WebGL independent core 3D engine style classes built on top of `@luma.gl/core`.       |
 | [`@luma.gl/shadertools`][shadertools]   | Recommended | System for modularizing and composing shader code, shader module system, transpiler, shader modules. |
 | [`@luma.gl/experimental`][experimental] | Optional    | Contains Scenegraph, glTF loader, GPU algorithms, VR classes etc.                                    |
 | [`@luma.gl/test-utils`][test-utils]     | Optional    | Test setups, in particular support for rendering and comparing images.                               |

diff --git a/docs/api-reference/api/README.md b/docs/api-reference/api/README.md
diff --git a/docs/api-reference/core/README.md b/docs/api-reference/core/README.md
@@ -1,3 +1,48 @@
-# Core API
+# Overview
 
-The core module exports the `@luma.gl/api`.
+The `@luma.gl/core` module provides an abstract API that enables application code
+to portably work with both WebGPU and WebGL. The main export is the `Device` class
+which provides methods for creating GPU resources such as `Buffer`, `Texture`, `Shader` etc.
+
+## Installing adapters
+
+The `@luma.gl/core` module is not usable on its own. A device adapter module must
+be imported and registered.
+
+```typescript
+import {luma} from '@luma.gl/core';
+import {WebGPUAdapter} from '@luma.gl/webgpu';
+
+luma.registerDevice([WebGPUAdapter])
+const device = await luma.createDevice({type: 'webgpu', canvas: ...});
+```
+
+It is possible to register 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';
+
+const webgpuDevice = luma.createDevice({type: 'best-available', canvas: ...});
+```
+
+## Creating GPU Resources
+
+Once the application has created a `Device`, GPU resources can be created:
+
+```typescript
+const buffer = device.createBuffer(...)
+```
+
+## 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.
+:::
diff --git a/docs/api-reference/api/bindings.md → docs/api-reference/core/bindings.md b/docs/api-reference/api/bindings.md → docs/api-reference/core/bindings.md
diff --git a/docs/api-reference/api/buffer-mapping.md → docs/api-reference/core/buffer-mapping.md b/docs/api-reference/api/buffer-mapping.md → docs/api-reference/core/buffer-mapping.md
diff --git a/docs/api-reference/api/canvas-context.md → docs/api-reference/core/canvas-context.md b/docs/api-reference/api/canvas-context.md → docs/api-reference/core/canvas-context.md
diff --git a/docs/api-reference/api/device-features.mdx → docs/api-reference/core/device-features.mdx b/docs/api-reference/api/device-features.mdx → docs/api-reference/core/device-features.mdx
diff --git a/docs/api-reference/api/device-limits.mdx → docs/api-reference/core/device-limits.mdx b/docs/api-reference/api/device-limits.mdx → docs/api-reference/core/device-limits.mdx
@@ -16,8 +16,8 @@ The `device.limits` field contains limits object that indicates what the current
 ## Usage
 
 ```typescript
-import type {DeviceLimits} from '@luma.gl/api';
-import {Device} from '@luma.gl/api';
+import type {DeviceLimits} from '@luma.gl/core';
+import {Device} from '@luma.gl/core';
 
 const limits: DeviceLimits = device.limits;
 console.log(limits);

diff --git a/docs/api-reference/api/device.md → docs/api-reference/core/device.md b/docs/api-reference/api/device.md → docs/api-reference/core/device.md
@@ -22,14 +22,14 @@ based on what the run-time environment (ie. browser or Node.js) supports.
 Creates a WebGL2 or WebGL context, auto creating a canvas
 
 ```typescript
-import {Device} from '@luma.gl/api';
+import {Device} from '@luma.gl/core';
 const device = new Device(); // Prefers WebGL 2 but falls back to WebGL 1
 ```
 
 Creates a WebGL 2 context (throws if WebGL2 not supported)
 
 ```typescript
-import {Device} from '@luma.gl/api';
+import {Device} from '@luma.gl/core';
 const device = createGLContext({
   webgl1: false
 });
@@ -39,7 +39,7 @@ Attaching a Device to an externally created WebGLRendering context instruments i
 so that it works with other luma.gl classes.
 
 ```typescript
-import {Device} from '@luma.gl/api';
+import {Device} from '@luma.gl/core';
 import {Model} from '@luma.gl/engine';
 
 const device = Device.attach(gl); // "instruments" the external context

diff --git a/docs/api-reference/api/parameters.md → docs/api-reference/core/parameters.md b/docs/api-reference/api/parameters.md → docs/api-reference/core/parameters.md
diff --git a/docs/api-reference/api/resources/buffer.md → docs/api-reference/core/resources/buffer.md b/docs/api-reference/api/resources/buffer.md → docs/api-reference/core/resources/buffer.md
diff --git a/...eference/api/resources/command-encoder.md → ...ference/core/resources/command-encoder.md b/...eference/api/resources/command-encoder.md → ...ference/core/resources/command-encoder.md
diff --git a/...i-reference/api/resources/compute-pass.md → ...-reference/core/resources/compute-pass.md b/...i-reference/api/resources/compute-pass.md → ...-reference/core/resources/compute-pass.md
diff --git a/...ference/api/resources/compute-pipeline.md → ...erence/core/resources/compute-pipeline.md b/...ference/api/resources/compute-pipeline.md → ...erence/core/resources/compute-pipeline.md
diff --git a/...ference/api/resources/external-texture.md → ...erence/core/resources/external-texture.md b/...ference/api/resources/external-texture.md → ...erence/core/resources/external-texture.md
diff --git a/...pi-reference/api/resources/framebuffer.md → ...i-reference/core/resources/framebuffer.md b/...pi-reference/api/resources/framebuffer.md → ...i-reference/core/resources/framebuffer.md
diff --git a/docs/api-reference/api/resources/pipeline.md → .../api-reference/core/resources/pipeline.md b/docs/api-reference/api/resources/pipeline.md → .../api-reference/core/resources/pipeline.md
diff --git a/...pi-reference/api/resources/render-pass.md → ...i-reference/core/resources/render-pass.md b/...pi-reference/api/resources/render-pass.md → ...i-reference/core/resources/render-pass.md
diff --git a/...eference/api/resources/render-pipeline.md → ...ference/core/resources/render-pipeline.md b/...eference/api/resources/render-pipeline.md → ...ference/core/resources/render-pipeline.md
diff --git a/docs/api-reference/api/resources/sampler.md → docs/api-reference/core/resources/sampler.md b/docs/api-reference/api/resources/sampler.md → docs/api-reference/core/resources/sampler.md
@@ -23,7 +23,7 @@ Specifying the `type: 'comparison-sampler'` sampler property creates a compariso
 Create a new `Sampler`
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 const device = await luma.createDevice();
 const sampler = device.createSampler(gl, {
   addressModeU: 'clamp-to-edge'

diff --git a/docs/api-reference/api/resources/shader.md → docs/api-reference/core/resources/shader.md b/docs/api-reference/api/resources/shader.md → docs/api-reference/core/resources/shader.md
diff --git a/docs/api-reference/api/resources/texture.md → docs/api-reference/core/resources/texture.md b/docs/api-reference/api/resources/texture.md → docs/api-reference/core/resources/texture.md
diff --git a/...rence/api/resources/transform-feedback.md → ...ence/core/resources/transform-feedback.md b/...rence/api/resources/transform-feedback.md → ...ence/core/resources/transform-feedback.md
diff --git a/docs/api-reference/api/shader-layout.md → docs/api-reference/core/shader-layout.md b/docs/api-reference/api/shader-layout.md → docs/api-reference/core/shader-layout.md
diff --git a/docs/api-reference/api/texture-formats.mdx → docs/api-reference/core/texture-formats.mdx b/docs/api-reference/api/texture-formats.mdx → docs/api-reference/core/texture-formats.mdx
diff --git a/.../api-reference/api/types/shader-layout.md → ...api-reference/core/types/shader-layout.md b/.../api-reference/api/types/shader-layout.md → ...api-reference/core/types/shader-layout.md
diff --git a/docs/api-reference/engine/README.md b/docs/api-reference/engine/README.md
@@ -5,5 +5,5 @@ to facilitate application development.
 
 ## Remarks
 
-- The engine classes are built on top of the abstract API in `@luma.gl/api` module
+- The engine classes are built on top of the abstract API in `@luma.gl/core` module
 and are thus portable between GPUs. 
diff --git a/docs/api-reference/webgl/README.md b/docs/api-reference/webgl/README.md
@@ -2,13 +2,13 @@
 
 ## WebGL Device Adapter
 
-This module contains the WebGL adapter for the "abstract" luma.gl API (`@luma.gl/api`).
+This module contains the WebGL adapter for the "abstract" luma.gl API (`@luma.gl/core`).
 
 Simply importing `@luma.gl/webgl` installs the adapter and enables WebGL devices to
 be created using `luma.createDevice(...)`:
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import '@luma.gl/webgl'; // Installs the WebGLDevice adapter
 
 const device = await luma.createDevice({type: 'webgl', canvas: ...});
@@ -29,7 +29,7 @@ With a bit more work, typescript users can retrieve the `WebGLRenderingContext`
 without ignoring type errors:
 
 ```typescript
-import {cast} from '@luma.gl/api';
+import {cast} from '@luma.gl/core';
 import {WebGLDevice} from '@luma.gl/webgl'; // Installs the WebGLDevice adapter
 
 const webglDevice = cast<WebGPUDevice>(device);

diff --git a/docs/api-reference/webgpu/README.md b/docs/api-reference/webgpu/README.md
@@ -2,13 +2,13 @@
 
 ## WebGPU Device Adapter
 
-This module contains the WebGPU adapter for the "abstract" luma.gl API (`@luma.gl/api`).
+This module contains the WebGPU adapter for the "abstract" luma.gl API (`@luma.gl/core`).
 
 Simply importing `@luma.gl/webgpu` installs the adapter and enables WebGPU devices to
 be created using `luma.createDevice(...)`:
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import '@luma.gl/webgpu'; // Installs the WebGPUDevice adapter
 
 const device = await luma.createDevice({type: 'webgpu', canvas: ...});
@@ -29,7 +29,7 @@ With a bit more work, typescript users can retrieve the `WebGLRenderingContext`
 without ignoring type errors:
 
 ```typescript
-import {Device, cast} from '@luma.gl/api';
+import {Device, cast} from '@luma.gl/core';
 import {WebGPUDevice} from '@luma.gl/webgpu'; // Installs the WebGPUDevice adapter
 
 function f(device: Device) {

diff --git a/docs/developer-guide/debugging.md b/docs/developer-guide/debugging.md
@@ -91,7 +91,7 @@ then reload your browser tab.
 While usually not recommended, it is also possible to activate the developer tools manually. Call [`luma.createDevice`](/docs/api-reference-v8/webgl-legacy/context/context-api) with `debug: true` to create a WebGL context instrumented with the WebGL developer tools:
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 const device = luma.createDevice({type: 'webgl', debug: true});
 ```
 

diff --git a/docs/developer-guide/installing.md b/docs/developer-guide/installing.md
@@ -4,14 +4,14 @@
 
 ## A Minimal Install
 
-The most basic module is `@luma.gl/api` which provides an abstract API for writing application code
+The most basic module is `@luma.gl/core` which provides an abstract API for writing application code
 that works with both WebGPU and WebGL.
 
-However, the `@luma.gl/api` module cannot be used on its own: it relies on being backed up by another module
+However, the `@luma.gl/core` module cannot be used on its own: it relies on being backed up by another module
 that implements the API. luma.gl provides adapters (implementations of the abstract API)
 through the `@luma.gl/webgl` and `@luma.gl/webgpu` modules.
 
-The `@luma.gl/api` module is not usable on its own. A device adapter module must
+The `@luma.gl/core` module is not usable on its own. A device adapter module must
 be imported.
 
 ```bash
@@ -21,7 +21,7 @@ yarn add @luma.gl/webgpu
 ```
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import '@luma.gl/webgpu';
 
 const device = await luma.createDevice({type: 'webgpu', canvas: ...});
@@ -31,7 +31,7 @@ It is possible to register more than one device adapter to create an application
 that can work in both WebGL and WebGPU environments.
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 import '@luma.gl/webgpu';
 import '@luma.gl/webgl';
 

diff --git a/docs/developer-guide/profiling.md b/docs/developer-guide/profiling.md
@@ -12,7 +12,7 @@ as a "bag" of different stats (or performance measurements), and luma.gl itself
 automatically populates `Stats` objects that can be inspected by the application.
 
 ```typescript
-import {luma} from '@luma.gl/api';
+import {luma} from '@luma.gl/core';
 
 console.log(luma.stats.getTable());
 ```

diff --git a/docs/sidebar.json b/docs/sidebar.json
@@ -98,7 +98,7 @@
       "api-reference/README",
         {
         "type": "category",
-        "label": "@luma.gl/api",
+        "label": "@luma.gl/core",
         "items": [
           "api-reference/api/README",
           "api-reference/api/device",

diff --git a/docs/upgrade-guide/upgrade-v9.md b/docs/upgrade-guide/upgrade-v9.md
@@ -32,9 +32,9 @@ The ground-up focus on TypeScript and strong typing in luma.gl v9 should create
 
 | **Module**           | v8 Description                                  | v9 Replacement                                                                                                                   |
 | -------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `@luma.gl/core`      | The core module was re-exporting other modules. | Replace direct use of WebGL classes with `@luma.gl/api` device API. import directly from `@luma.gl/shadertools`.                 |
-| `@luma.gl/gltools`   | Contained WebGL context functionality.          | Removed. WebGL context is now handled by the  `@luma.gl/webgl` `WebGLDevice` and  `@luma.gl/api` `CanvasContext` classes.        |
-| `@luma.gl/webgl`     | Exported WebGL classes meant for direct usage.  | Now exports the WebGL backend for the `@luma.gl/api` module. `@luma.gl/webgl-legacy` now offers the legacy luma.gl v8 WebGL API. |
+| `@luma.gl/core`      | The core module was re-exporting other modules. | Replace direct use of WebGL classes with `@luma.gl/core` device API. import directly from `@luma.gl/shadertools`.                 |
+| `@luma.gl/gltools`   | Contained WebGL context functionality.          | Removed. WebGL context is now handled by the  `@luma.gl/webgl` `WebGLDevice` and  `@luma.gl/core` `CanvasContext` classes.        |
+| `@luma.gl/webgl`     | Exported WebGL classes meant for direct usage.  | Now exports the WebGL backend for the `@luma.gl/core` module. `@luma.gl/webgl-legacy` now offers the legacy luma.gl v8 WebGL API. |
 | `@luma.gl/constants` | Exported numeric OpenGL constants.              | Do not use. The luma.gl v9 API uses strictly typed WebGPU-style strings instead of numeric constants.                            |
 
 

diff --git a/docs/whats-new.md b/docs/whats-new.md
@@ -28,16 +28,16 @@ Note that adoption of the new v9 luma.gl API will require existing luma.gl v8 ap
 - The core module no longer exports the luma.gl v8 API. Update your applications to import from `@luma.gl/webgl-legacy`).
 - The core module still exports `@luma.gl/engine` classes.
 
-#### `@luma.gl/api` (new module)
+#### `@luma.gl/core` (new module)
 
 - The new cross-platform luma.gl API exported as a set of interfaces and abstract classes.
-- The core `Device` API that is exposed through the new `@luma.gl/api` module.
-- Applications written against `@luma.gl/api` can run on both WebGPU, WebGL2 and WebGL devices.
+- The core `Device` API that is exposed through the new `@luma.gl/core` module.
+- Applications written against `@luma.gl/core` can run on both WebGPU, WebGL2 and WebGL devices.
 
 #### `@luma.gl/engine` (breaking changes)
 
 - The `@luma.gl/engine` module still exports the classic luma.gl classes such as `Model` and `AnimationLoop`. 
-- However all engine classes are now implemented on top of `@luma.gl/api`, allowing them to work portably on both WebGPU and WebGL.
+- However all engine classes are now implemented on top of `@luma.gl/core`, allowing them to work portably on both WebGPU and WebGL.
 - For backwards compatibility, the `WebGLRenderingContext`-dependent versions have been moved to `@luma.gl/webgl-legacy`
 - Scenegraph classes (`ModelNode`, `GroupNode`, `ScenegraphNode`) are now exported from `@luma.gl/engine`.
 
@@ -47,12 +47,12 @@ Note that adoption of the new v9 luma.gl API will require existing luma.gl v8 ap
 
 #### `@luma.gl/webgpu` (new module)
 
-- Provides a WebGPU implementation of the luma.gl API (`@luma.gl/api`). 
+- Provides a WebGPU implementation of the luma.gl API (`@luma.gl/core`). 
 - Importing this module enables the application to create `Device`s of type `'webgpu'` (when run in a browser that supports WebGPU API).
 
 #### `@luma.gl/webgl` (breaking changes)
 
-- Exports `WebGLDevice`, a WebGL / WebGL 2 backend implementation of the luma.gl API (`@luma.gl/api`). 
+- Exports `WebGLDevice`, a WebGL / WebGL 2 backend implementation of the luma.gl API (`@luma.gl/core`). 
 - Importing this module enables the application to create `Device`s of type `'webgl2'` or `'webgl'`.
 
 #### `@luma.gl/constants` (breaking changes, deprecated)

diff --git a/examples-wip/api-v8/program-management/app.ts b/examples-wip/api-v8/program-management/app.ts
@@ -1,5 +1,5 @@
 
-import {getRandom, glsl} from '@luma.gl/api';
+import {getRandom, glsl} from '@luma.gl/core';
 import {dirlight as dirlightBase} from '@luma.gl/shadertools';
 import {AnimationLoopTemplate, AnimationProps, Model, PipelineFactory, CubeGeometry} from '@luma.gl/engine';
 import {Matrix4, radians} from '@math.gl/core';