chore: website and doc cleanup pass (#1944)

visgl · Feb 19, 2024 · b84c984 · b84c984
1 parent 4ac458b
commit b84c984
Show file tree

Hide file tree

Showing 58 changed files with 14,613 additions and 10,787 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1619,7 +1619,7 @@ Debug improvements
 
 - Un-deprecate `scenegraph` module (except `Scene`), merge with `core` module.
 - `shadertools` module no longer experimental
-- webgl2 uniform support
+- uniform support
 
 ## 4.0.0-alpha.12
 
@@ -1722,7 +1722,6 @@ Codebase/Build tooling improvements
 - Changed precommit hook from `husky` to `pre-commit`
 - `shader-modules`, `shader-tools`, `shaders` shader module system added to `/experimental`
 - `probe` moved to `/experimental`
-- `webgl` folder now contains both webgl1 and webgl2 classes
 
 Feature Improvements
 
@@ -1910,7 +1909,6 @@ precedence when using wildcard installs.
 
 - `shader-modules`, `shader-tools`, `shaders` shader module system added to `/experimental`
 - `probe` moved to `/experimental`
-- `webgl` folder now contains both webgl1 and webgl2 classes
 
 ### 3.0.0-alpha1
 

diff --git a/docs/api-guide/README.md b/docs/api-guide/README.md
@@ -1,34 +1,41 @@
 # API Overview
 
-The luma.gl API is designed to expose the capabilities of the GPU and shader programming to web applications.
+The luma.gl API enables the creation of portable GPU applications that can run on top of either WebGPU, or WebGL 2.
+luma.gl is divided into different sub-APIs: the core GPU API, the shader API and the engine API.
 
-Core responsibilities for any GPU library are to enable applications to perform:
+Most applications work with the engine API (`Model`, `AnimationLoop` and related classes), leveraging the core GPU API as necessary to obtain a `Device` and use it to create GPU resources such as `Buffer` and `Texture`. 
+The shader API is used to assemble shaders and define shader modules.
 
-- [GPU device access](/docs/api-guide/device) - Open a GPU device and query its capabilities 
-- [GPU memory management](/docs/api-guide/memory) - Create, upload memory to and read from [Buffers](/docs/api-guide/buffers), [Textures](/docs/api-guide/textures) etc.
-- [GPU resource management](/docs/api-guide/resources) - Create `Shader`, `Renderpipeline`, `RenderPass` etc objects.
-- [GPU binding management](/docs/api-guide/bindings) - Make attribute buffers, uniforms, textures, samplers available to GPU shaders.
-- [Shader execution / rendering](/docs/api-guide/rendering) - Drawing into textures, running compute shaders.
-- [GPU parameter management](/docs/api-guide/parameters) - Configuring blending, clipping, depth tests etc.
+Most luma.gl applications will:
 
-## Portability 
+1. Use the core API to create a `Device` class to access the GPU (either using WebGPU or WebGL).
+2. Upload data to the GPU via methods on the `Device`, using `Buffer` and `Texture` objects.
+3. Use tne engine API to create one or more `Model` instances from GLSL or WGSL shader code.
+4. Bind attribute buffers and bindings (textures, uniform buffers or uniforms).
+5. Start an engine API `AnimationLoop` loop, and draw each frame into a `RenderPass`.
 
-luma.gl enables the creation of portable applications that can run on top of either WebGPU, WebGL 2, or WebGL.
+## Core API
 
-The `@luma.gl/core` module provides an abstract API for writing application code
-that works with both WebGPU and WebGL.
+The core luma.gl API is designed to expose the capabilities of the GPU and shader programming to web applications.
+It is a portable API, in the sense that the `@luma.gl/core` module provides an abstract API for writing application code
+that works with both WebGPU and/or WebGL depending on which adapter modules are installed
+)`@luma.gl/webgl` and/or `@luma.gl/webgpu`).
 
-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.
+Core responsibilities for any GPU library are to enable applications to perform:
 
-## Usage
+- [GPU initialization](/docs/api-guide/gpu/gpu-initialization) - Open a GPU device and query its capabilities 
+- [GPU memory management](/docs/api-guide/gpu/gpu-memory) - Create, upload memory to and read from [Buffers](/docs/api-guide/gpu/gpu-buffers), [Textures](/docs/api-guide/gpu/gpu-textures) etc.
+- [GPU resource management](/docs/api-guide/gpu/gpu-resources) - Create `Shader`, `Renderpipeline`, `RenderPass` etc objects.
+- [GPU binding management](/docs/api-guide/gpu/gpu-bindings) - Make attribute buffers, uniforms, textures, samplers available to GPU shaders.
+- [Shader execution / rendering](/docs/api-guide/gpu/gpu-rendering) - Drawing into textures, running compute shaders.
+- [GPU parameter management](/docs/api-guide/gpu/gpu-parameters) - Configuring blending, clipping, depth tests etc.
 
-Most luma.gl applications will:
+## Shader API
 
-1. Create a `Device` class to access the GPU (either using WebGPU or WebGL).
-2. Use that device to upload data to the GPU in the form of `Buffer` and `Texture` objects.
-3. Create one or more `RenderingPipeline` objects from GLSL or WGSL shader code.
-4. Bind attribute buffers and bindings (textures, uniform buffers or uniforms).
-5. Start a render loop, and use a `RenderPass` to draw.
+The Shader API lets the application use a library of existing shader modules to create new customer shaders. 
+It is also possible for developers to create new reusable shader modules.
+
+## Engine API
 
+The engine API provides higher level classes like `Model`, `AnimationLoop` and `Transform`s.
+glTF support is available through `@luma.gl/gltxf`.
diff --git a/docs/api-guide/background/api-design.md b/docs/api-guide/background/api-design.md
@@ -9,7 +9,7 @@ Goals:
 - The luma.gl API is designed to expose the capabilities of the GPU and shader programming to web applications.
 - Avoid creating a thick abstraction layer hiding the underlying API.
 - Big data processing (thinking about the GPU as a parallel binary columnar table processor rather than a scenegraph rendering engine).
-- Cross platform support: backwards compatibility with WebGL 2 and WebGL on a "best effort" basis.
+- Cross platform support: backwards compatibility with WebGL 2.
 
 Non-goals:
 

diff --git a/docs/api-guide/transforms.md → docs/api-guide/engine/transforms.md b/docs/api-guide/transforms.md → docs/api-guide/engine/transforms.md
diff --git a/docs/api-guide/attributes.md → docs/api-guide/gpu/gpu-attributes.md b/docs/api-guide/attributes.md → docs/api-guide/gpu/gpu-attributes.md
diff --git a/docs/api-guide/bindings.md → docs/api-guide/gpu/gpu-bindings.md b/docs/api-guide/bindings.md → docs/api-guide/gpu/gpu-bindings.md
diff --git a/docs/api-guide/buffers.md → docs/api-guide/gpu/gpu-buffers.md b/docs/api-guide/buffers.md → docs/api-guide/gpu/gpu-buffers.md
diff --git a/docs/api-guide/device.md → docs/api-guide/gpu/gpu-initialization.md b/docs/api-guide/device.md → docs/api-guide/gpu/gpu-initialization.md
@@ -1,4 +1,4 @@
-# GPU Access
+# GPU Initialization
 
 ## Device
 
@@ -24,24 +24,26 @@ A `CanvasContext` takes care of:
 
 ## Usage
 
-Create a WebGL2 context, auto creating a canvas
+Create a `Device` using the best available registered backend, 
+specifying an existing canvas to initialize the default `CanvasContext`.
 
 ```typescript
 import {luma} from '@luma.gl/core';
 import {WebGLDevice} from '@luma.gl/webgl';
+import {WebGPUDevice} from '@luma.gl/webgpu';
 
 luma.registerDevices([WebGLDevice]);
-const webgpuDevice = luma.createDevice({type: 'webgl', canvas: ...});
+const device = luma.createDevice({canvas: ...});
 ```
 
-Create a WebGL 2 context (throws if WebGL2 not supported)
+Create a WebGL 2 device, auto creating a canvas.
 
 ```typescript
 import {luma} from '@luma.gl/core';
 import {WebGLDevice} from '@luma.gl/webgl';
 
 luma.registerDevices([WebGLDevice]);
-const webgpuDevice = luma.createDevice({type: 'webgl', canvas: ...});
+const webglDevice = luma.createDevice({type: 'webgl'});
 ```
 
 ## Registering Device Backends

diff --git a/docs/api-guide/memory.md → docs/api-guide/gpu/gpu-memory.md b/docs/api-guide/memory.md → docs/api-guide/gpu/gpu-memory.md
@@ -1,6 +1,6 @@
-# GPU Memory Management
+# GPU Memory
 
-Memory on GPU is managed through [Buffer](/docs/api-guide/buffers) and [Texture](/docs/api-guide/textures) resources.
+Memory on GPU is managed through [Buffer](/docs/api-guide/gpu/gpu-buffers) and [Texture](/docs/api-guide/gpu/gpu-textures) resources.
 
 This article provides some background information on how GPU memory works that can be helpful in understanding limitations and performance characteristics.
 

diff --git a/docs/api-guide/parameters.md → docs/api-guide/gpu/gpu-parameters.md b/docs/api-guide/parameters.md → docs/api-guide/gpu/gpu-parameters.md