archive-gh-me/luma.gl
1
0
Fork 0
mirror of https://github.com/visgl/luma.gl.git synced 2026-02-01 14:33:49 +00:00
Code Issues Projects Releases Wiki Activity

feat(docs): Pass on resource docs (#1620)

Browse Source
This commit is contained in:
Ib Green 2022-02-06 13:21:32 -08:00 committed by GitHub
parent 8b7fa9a482
commit 00a2cb5b30
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
72 changed files with 2357 additions and 1334 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
dev-docs/DOCUMENTATION-GUIDELINES.md
View File

@ -1,6 +0,0 @@
# Documentation Guidelines
## URLs to other markdown documents
In all markdown pages, when referring to other documents, we use actual file path and then during website generation these paths are replaced with correct website urls. This way links can work both by browsing the docs using the Github explorer and on the website.

1
dev-docs/tech-docs-wip/README.md
View File

@ -1 +0,0 @@
Various unfinished docs

63
dev-docs/tech-docs-wip/program-configuration.md
View File

@ -1,63 +0,0 @@
### uniformBlockBinding
* `blockIndex` (`GLuint`) - uniform block index
* `blockBinding` (`GLuint`) - binding point
Binds a uniform block (`blockIndex`) to a specific binding point (`blockBinding`)
### varyings
* `program` (`WebGLProgram?`) - program
* `varyings` (`sequence<DOMString>`) -
* `bufferMode` (`GLenum`) -
returns (`TransformFeedback`) - returns self to enable chaining
WebGL APIs [gl.transformFeedbackVaryings](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/transformFeedbackVaryings)
### getVarying(program, index)
* `program` (`WebGLProgram?`) - program
* `index` (`GLuint`) - index
returns (`WebGLActiveInfo`) - object with {`name`, `size`, `type`} fields.
WebGL APIs [gl.getTransformFeedbackVarying](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/getTransformFeedbackVarying)
### getUniformCount
Gets number of active uniforms
### getUniformInfo
Gets {name, type, size} for uniform at index
### getUniformLocation
Gets uniform's location (`WebGLUniformLocation`)
### getUniformValue
Gets the value of a uniform variable at a given location
### getActiveUniforms
Gets the requested information (size, offset etc) of uniforms
### getVarying (WebGL2)
Gets the information {name, size, type} of a varying
### getUniformBlockIndex (WebGL2)
Gets the index of a uniform block
### getActiveUniformBlockParameter (WebGL2)
Gets the information about an active uniform block
### getFragDataLocation (WebGL2)
Gets the binding of color numbers to user-defined varying out variables

43
dev-docs/tech-docs-wip/roadmap-ideas.md
View File

@ -1,43 +0,0 @@
# WebGL Feature Ideas
A scratchpad for roadmap ideas...
## Resource Management
### Stats
The Resource class will track allocations and initializations of resources, making it easy to see when your application is not reusing resources.
### Context Loss
The typical life cycle of a WebGL resource looks something like this:
1) Creating a handle
2) Initializing a handle
3) Using the handle
4) Destroying a handle (either explicitly or by letting it be garbage collected)
Context loss can happen at any time between 1 and 4, at which time resources will be invalidated and handles will have to be recreated and reinitialized.
The subclasses will store initialization parameters so that the object can be automatically recreated in case of context loss.
## Implemented
### Vertex Attributes (v6.0)
Consolidates vertex attributes handling using VertexAttributeObjects
## Rejected
### Sharing Resources between WebGL contexts
> The `WEBGL_shared_resources` extension that underpinned this idea was rejected.
The `Resource` class could be extended (`SharedResource`?) to implement context sharing support as soon as the [`WEBGL_shared_resources`](https://www.khronos.org/registry/webgl/extensions/WEBGL_shared_resources/) extension becomes available in a major browser.
The assumption is that an async `aquire` method will be available that will change the gl context stored in the `Resource`.

71
docs/api-guide/README.md
View File

@ -1,4 +1,27 @@
# Overview
# API Overview
# luma.gl API
The luma.gl API is designed to expose the capabilities of the GPU and shader programming to web applications.
Naturally, core responsibilities for any GPU library:
- GPU resource management (create and destroy GPU resources like Buffers, Textures etc)
- GPU Bindings (making attribute buffers, uniform buffers, textures, samplers etc available to GPU shaders.
- Shader execution (draw, compute)
- Shader composition
- Cross platform support: backwards compatibility with WebGL 2 (WebGL on a "best effort" basis).
The luma.gl API is designed to allow the creation of portable applications that can
run on top of either WebGPU, WebGL 2, or WebGL.
Most luma.gl applications will:
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 `Model` objects from GLSL or WGSL shader code.
4. Bind attribute buffers and bindings (textures, uniform buffers or uniforms).
5. Start a render loop, often using the `AnimationLoop` class.
The `@luma.gl/api` module provides an abstract API for writing application code
that works with both WebGPU and WebGL.
@ -9,35 +32,27 @@ through the `@luma.gl/webgl` and `@luma.gl/webgpu` modules.
## A WebGPU-style API
From a high level, the luma.gl API is similar to the WebGPU API in a number of ways:
- the application must first obtain a "device" and then uses methods on this device to create GPU resource classes such as buffers, textures, shaders and pipelines.
- the API uses string constants and parameter option names that mirror those in the WebGPU API.
The luma.gl v9 API design stays fairly close to the WebGPU API, just as the luma.gl v8 API followed the WebGL 2 API. The idea is to let the users' build their knowledge of the WebGPU and luma.gl API in tandem,
rather than asking users to learn another abstraction.
The similarities are intentional. The idea is to let knowledge of the WebGPU API carry over to the luma.gl API and vice versa,
rather than asking developers to learn another set of arbitrary abstractions.
Some examples of similarities:
While it has similarities to WebGPU, the luma.gl API is streamlined to be less cumbersome to use and also has to make
the necessary allowances to still support WebGL.
- The application must first obtain a "device"
- The application then uses methods on this device to create GPU resource classes such as buffers, textures, shaders and pipelines.
- The API uses string constants and parameter option names that mirror those in the WebGPU API.
## Installing adapters
However there are differences. Compared to the raw WebGPU API, the luma.gl v9 API is somewhat streamlined to be easier to use and also makes necessary allowances to ensure that it can also run on top of WebGL.
The `@luma.gl/api` module is not usable on its own. A device adapter module must
be imported (it self registers on import).
## Modules
```typescript
import {luma} from '@luma.gl/api';
import '@luma.gl/webgpu';
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
import {luma} from '@luma.gl/api';
import '@luma.gl/webgpu';
import '@luma.gl/webgl';
const webgpuDevice = luma.createDevice({type: 'best-available', canvas: ...});
```
| Module | Description |
| ----------------------- | ------------------------------------------------------------------------------------ |
| `@luma.gl/api` | "Abstract" API that is implemented by both the WebGPU or WebGL. |
| `@luma.gl/engine` | A set of core classes that are independent from their engine. |
| `@luma.gl/shadertools` | Provides GLSL module system and transpiler as well as a selection of shader modules. |
| `@luma.gl/experimental` | Contains glTF loader, GPU algorithms, VR classes etc. |
| `@luma.gl/webgl` | Contains the WebGL 1 and 2 implementations of the `@luma.gl/api` |
| `@luma.gl/webgpu` | Contains the WebGPU implementation of the `@luma.gl/api` |
| `@luma.gl/test-utils` | Test setups, in particular support for rendering and comparing images. |
| `@luma.gl/gltools` | The deprecated luma.gl v8 API can now be imported from `@luma.gl/gltools`. |
| `@luma.gl/core` | A module that re-exports many of the symbols in the other modules. |

102
docs/api-guide/bindings.md
View File

@ -1,10 +1,10 @@
# Bindings
A key responsibility of any GPU API is to enable the application to
set up data so that it can be accessed by shaders. in luma.b
A key responsibility of luma.gl is to make it easy for the application to
set up data so that it can be accessed by shader code running on the GPU.
The terminology can be a little confusing. To make it easy to cross-reference other code and
documentation, luma.gl attempts to roughly follow WebGPU / WGLSL conventions. The following terms are used:
The terminology used to describe GPU bindings can vary somewhat between APIs and frameworks.
luma.gl attempts to roughly follow WebGPU / WGLSL conventions. The following terms are used:
- **layouts** - metadata for various shader connection points
- **attribute layout** - actual values for attributes
@ -110,7 +110,7 @@ new Model(device, {
})
```
WGLSL vertex shader
WGSL vertex shader
```rust
struct Uniforms {
@ -135,7 +135,7 @@ fn main([[location(0)]] position : vec4<f32>,
}
```
WGLS FRAGMENT SHADER
WGSL Fragment Shader
```rust
[[group(0), binding(1)]] var mySampler: sampler; // BINDING 1
@ -147,3 +147,93 @@ fn main([[location(0)]] fragUV: vec2<f32>,
return textureSample(myTexture, mySampler, fragUV) * fragPosition;
}
```
# Accessors
"Buffer accessor objects" (or "accessor objects", or just "accessors" for short) are used to describe the structure of data contained in WebGL buffers (for more information see [`Buffers`](/docs/api-reference/webgl/buffer)).
When using `Buffer`s as input to shader programs, applications must tell WebGL how the data in the buffer is formatted, so that the GPU knows how to access buffers' memory. To enable applications to specify how the buffer memory should be accessed, luma.gl APIs that set attribute buffers accept buffer "accessor objects".
## Accessor Object Fields
This is an overview of the object accessor fields that are available to applications to define format descriptions. These objects can contain the following fields, this is an excerpt from [`Accessor`](/docs/api-reference/webgl/accessor).
| Property | Auto Deduced | Default | Comment |
| ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `buffer` | No | An accessor can optionally reference a specific buffer. Multiple accessors can point to the same buffer, providing different views or "slices" of the buffer's memory. |
| `offset` | No | `0` | Byte offset to start of data in buffer |
| `stride` | No | `0` | Extra bytes between each successive data element |
| `type` | Yes | `GL.FLOAT` | Low level data type (`GL.BYTE`, `GL.SHORT`, ...) |
| `size` | Yes | `1` | Components per element (`1`-`4`) |
| `divisor` | Yes | `0` | Enables/disables instancing |
| `normalize` | N/A | `false` | Normalize integers to [-1,1], or [0,1] if unsigned |
| `integer` | N/A | `false` | Disable conversion of integer values to floats **WebGL 2** |
## Combining Accessors with Buffers
When setting attributes (e.g. using `Model.setProps({attributes: {attributeName: value, ...}}))`, each attribute value needs to contain both a buffer (a handle to the raw data uploaded to the GPU) and an accessor (describing how that data should be accessed).
luma.gl provides three methods to specify attribute values so that both a buffer and an accessor are provided:
- As a two-element array: `[buffer, accessor]`.
- As an accessor, in which case the accessor object's `buffer` field should be set to the matching `Buffer`.
- As a `Buffer`, in which case the `Buffer` objects `accessor` field should be set to the mathing `Accessor`.
All three methods have their uses: the first option gives the applications full freedom to dynamically select combinations of buffers and accessors, the second option is often the natural choice when working with interleaved buffers (see below), and the last choice is often the most convenient when just setting up an ad-hoc buffer for immediate use, as the accessor can be stored directly on the buffer, avoiding the need to manage separate objects.
## Accessor Class vs Accessor Objects
luma.gl provides the [`Accessor`](/docs/api-reference/webgl/accessor) helper class to help you work with accessor objects. For instance, the `Accessor` class supports merging of partial accessor objects, see below.
Note that it is not necessary to use the `Accessor` class, as plain old JavaScript objects with the appropriate fields are also accepted by the various APIs that accept accessors. Use the style that works best for your application.
### "Partial" Accessors
luma.gl allows "partial" accessors to be created, and later combined. Usually many accessor fields can be left undefined (e.g. because defaults are sufficient, or because accessor auto-deduction has already deduced the information, see below).
Partial accessors will be created automatically by `Program` when shaders are compiled and linked, and also by `Buffer` objects when they are created. Any application supplied accessors fields will then be merged in (override) these auto-deduceted fields, that can add any fine-tuning or override of parameters.
### Accessor Auto Deduction
luma.gl attempts to "auto deduce" as much accessor information as it can, for instance luma.gl can extract fields like `type` and `size` after shaders have been compiled.
This relieves applications from having to respecify the same thing multiple times. For instance if the application has already declared an attribute as `in vec2 size` in the vertex shader, it does not need to specify `size:2, type: GL.FLOAT` again in the accessor, when it sets the buffer in JavaScript, since this information will have been auto-deduced.
In many cases, when buffers are not shared between attributes (i.e. interleaved) and default behavior is desired, luma.gl applications often do not need to specify any `Accessor` at all.
### Merging (Resolving) Accessors
The `Accessor` API allows for accessors to be merged (or "resolved") into a new `Accessor`. Accessor mmerging is mainly used internally in luma.gl to implement support for partial accessors and accessor auto deduction, but can be used by applications if necessary.
### Data Interleaving
Using the`stride` and `offset` fields in accessor objects, it is possible to interleave two arrays so that the first two elements of one array are next to each other, then the next two elements etc.
```
const interleavedBuffer = new Buffer(gl, accessor: {stride: 12 + 4}}); // Creates a partial accessor with `stride` in buffer.
vertexArray.setAttributes({
// These accessors are merged with the `interleavedBuffer` accessor and any
// auto-deduced accessors
POSITIONS: new Accessor({offset: 0, buffer: interleavedBuffer})
COLORS: new Accessor({offset: 12, buffer: interleavedBuffer})
})
```
For more information see the article about attributes.
### Using Different Size in Buffers and Shaders
It is possible to use different size memory attributes than specified by the GLSL shader code, by specifying a different size in the accessor compared to the GLSL shader variable declaration. Extra components in the Buffer memory will be ignored, missing components will be filled in from `(0.0, 0.0, 0.0, 1.0)`
> Be aware that the headless gl integration does not support this feature due to limitations in headless gl.
### glTF Format Accessors
[glTF formatted files](https://www.khronos.org/gltf/). glTF files contain two JSON object arrays ("bufferViews" and "accessors") that describe how raw memory buffers are organized and should be interpreted.
The `Accessor` and `Buffer` class APIs have intentionally been designed to be a close representation when converting "accessors" and "bufferViews" stored in glTF files. Each glTF `accessor` can be mapped to a luma.gl `Accessor` and each glTF `bufferView` can be mapped to a luma.gl `Buffer`.
`For more details see [glTF mapping]().`

52
docs/api-guide/canvas-context.md
View File

@ -1,52 +0,0 @@
# CanvasContext
> This class is still experimental
A `CanvasContext` holds a connection between the GPU `Device` and an HTML `canvas` into which it can render.
A `CanvasContext` handles the following responsibilities:
- manages the "swap chain" (provides fresh texture view every frame on WebGPU)
- manages canvas resizing
- manages device pixel ratio
- can look up canvas elements in DOM, or create a new canvas elements if needed
Note that:
- A `WebGPUDevice` can have multiple associated `CanvasContext` instances, or none, if only used for compute.
- A `WebGLDevice` always has exactly one `CanvasContext` (and can thus only render into a single canvas). This is due to fundamental limitations of the WebGL API.
## CanvasContextProps
| Property | Type |
| --- | --- |
| `canvas?` | HTMLCanvasElement \| OffscreenCanvas \| string |
| `width?` | number |
| `height?` | number |
| `useDevicePixels?` | boolean \| number |
| `autoResize?` | boolean |
Remarks:
- `useDevicePixels` can accept a custom ratio (Number), instead of `true` or `false`. This allows rendering to a much smaller or higher resolutions. When using high value (usually more than device pixel ratio), it is possible it can get clamped down, this happens due to system memory limitation, in such cases a warning will be logged to the browser console. For additional details check device pixels [`document`](<(/docs/api-reference/gltools/device-pixels)>).
## Methods
### constructor
A `CanvasContext` can not be constructed directly. It must be created by instantiating a `WebGPUDevice` or a `WebGLDevice`, or through `WebGPUDevice.createCanvasContext()`.
### `getDevicePixelResolution(): [number, number]`
### `getPixelSize(): [number, number]`
Returns the size in pixels required to cover the canvas at the current device pixel resolution.
## Static Fields
### `CanvasContext.isPageLoaded: boolean`
### `CanvasContext.pageLoaded: Promise<void>`
## Fields
### `canvas: HMTLCanvas | OffscreenCanvas`
### `useDevicePixels: boolean | number`

116
docs/api-guide/device.md
View File

@ -1,4 +1,4 @@
# Device
# Device and CanvasContext
The `Device` class initializes, instruments a WebGL contexts.
@ -8,6 +8,29 @@ The `Device` API is similar to the WebGPU `GPUDevice` class.
- Polyfill a WebGL context integrating available extensions.
## Installing adapters
The `@luma.gl/api` module is not usable on its own. A device adapter module must
be imported (it self registers on import).
```typescript
import {luma} from '@luma.gl/api';
import '@luma.gl/webgpu';
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
import {luma} from '@luma.gl/api';
import '@luma.gl/webgpu';
import '@luma.gl/webgl';
const webgpuDevice = luma.createDevice({type: 'best-available', canvas: ...});
```
## Usage
Create a WebGL2 or WebGL context, auto creating a canvas
@ -50,82 +73,33 @@ const device = Device.attach(gl);
const vao = device.gl.createVertexArray();
```
## Fields
### isWebGL
# CanvasContext
Test if an object is a WebGL 1 or 2 context, including correctly identifying a luma.gl debug context (which is not a subclass of a `WebGLRendringContext`).
> This class is still experimental
`isWebGL(gl)`
A `CanvasContext` holds a connection between the GPU `Device` and an HTML `canvas` into which it can render.
- `gl` (Object) - Object to test.
Returns true if the context is a WebGL 1 or 2 Context.
A `CanvasContext` handles the following responsibilities:
- manages the "swap chain" (provides fresh texture view every frame on WebGPU)
- manages canvas resizing
- manages device pixel ratio
- can look up canvas elements in DOM, or create a new canvas elements if needed
### isWebGL2
Note that:
- A `WebGPUDevice` can have multiple associated `CanvasContext` instances, or none, if only used for compute.
- A `WebGLDevice` always has exactly one `CanvasContext` (and can thus only render into a single canvas). This is due to fundamental limitations of the WebGL API.
Test if an object is a WebGL 1 or 2 context, including correctly identifying a luma.gl debug context (which is not a subclass of a `WebGL2RendringContext`).
## CanvasContextProps
`isWebGL2(gl)`
| Property | Type |
| --- | --- |
| `canvas?` | HTMLCanvasElement \| OffscreenCanvas \| string |
| `width?` | number |
| `height?` | number |
| `useDevicePixels?` | boolean \| number |
| `autoResize?` | boolean |
- `gl` (Object) - Object to test.
Returns true if the context is a WebGL 2 Context.
Remarks:
- `useDevicePixels` can accept a custom ratio (Number), instead of `true` or `false`. This allows rendering to a much smaller or higher resolutions. When using high value (usually more than device pixel ratio), it is possible it can get clamped down, this happens due to system memory limitation, in such cases a warning will be logged to the browser console. For additional details check device pixels [`document`](<(/docs/api-reference/gltools/device-pixels)>).
### info
Get debug information about a WebGL context. Depends on `WEBGL_debug_renderer_info` extension.
Returns (Object):
- **vendor**: GPU vendor (unmasked if possible)
- **renderer**: Renderer (unmasked if possible)
- **vendorMasked**: Masked GPU vendor
- **rendererMasked**: Masked renderer
- **version**: WebGL version
- **shadingLanguageVersion**: shading language version
## Functions
### constructor(props?: WebGLDeviceProps)
Creates and returns a WebGL context, both in browsers and in Node.js.
```typescript
const device = new Device(props);
```
- `props` (_Object_) - key/value pairs containing context creation options
| Parameter | Default | Description |
| ------------------------------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `canvas` | `null` | A _string_ containing the `id` of an existing HTML element or a _DOMElement_ instance. If `null` or not provided, a new canvas will be created. |
| `webgl2?: boolean` | `true` | If `true`, will attempt to create a WebGL 2 context. Will silently fall back to WebGL 1 contexts unless `webgl1` is set to `false`. |
| `webgl1?: boolean` | `true` | If `true`, will attempt to create a WebGL 1 context. The `webgl2` flag has higher priority. |
| `debug?: boolean` | `false` | WebGL API calls will be logged to the console and WebGL errors will generate JavaScript exceptions. **NOTE:** requires importing [@luma.gl/debug](/docs/api-reference/debug). |
| `break?: string[]` | `[]` | Insert a break point (`debugger`) if one of the listed gl functions is called. |
| `manageState?: boolean` | `true` | Instrument the context to enable state caching and `withParameter` calls. Leave on unless you have special reasons not to. |
| `onContextLost?: Function` | `undefined` | A handler for webglcontextlost event that is fired if the user agent detects that the drawing buffer associated with a WebGLRenderingContext object has been lost. |
| `onContextRestored?: Function` | `undefined` | A handler for webglcontextrestored event that is fired if the user agent restores the drawing buffer for a WebGLRenderingContext object. |
| `alpha?: boolean` | `true` | Default render target has an alpha buffer. |
| `depth?: boolean` | `true` | Default render target has a depth buffer of at least 16 bits. |
| `stencil?` | `false` | Default render target has a stencil buffer of at least 8 bits. |
| `antialias?` | `true` | Boolean that indicates whether or not to perform anti-aliasing. |
| `premultipliedAlpha?` | `true` | Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha. |
| `preserveDrawingBuffer?` | `false` | Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten |
| `failIfMajorPerformanceCaveat?` | `false` | Do not create if the system performance is low. |
### resize
Resize the drawing surface.
```
resizeGLContext(gl, options);
```
- `gl` (_Object_) - A WebGL context.
- `options` (_Object_) - key/value pairs containing resize options.
- **width**: New drawing surface width.
- **height**: New drawing surface height.
- **useDevicePixels**: Whether to scale the drawing surface using the device pixel ratio.

30
docs/api-guide/parameters.md
View File

@ -1,26 +1,16 @@
# Parameters
> This section describes the experimental, work-in-progress v9 luma.gl API.
The luma.gl API provides a unified key/value API for GPU parameters enabling applications to control GPU pipeline features such as culling, depth and stencil buffers, blending, clipping etc.
1. Vertex Shader
2. Primitive assembly (`topology`)
3. Rasterization (multisampling parameters)
4. Fragment shader `Framebuffer`
5. Stencil test and operation (stencil parameters)
6. Depth test and write (depth parameters)
7. Output merging, controlled by `Framebuffer`
luma.gl provides a unified API for controlling GPU parameters providing control of GPU pipeline features such as culling, depth and stencil buffers, blending, clipping etc.
A number of parameters are set when certain GPU objects are created, and cannot be changed without creating a new object.
| Parameter "Type" | Comments |
| ---------------- | ------------------------------------------------------------------------------------------------------------- |
| `RenderPipeline` | `RenderPipeline` is created. |
| `RenderPass` | Render targets, clear colors etc. To vary these parameters, additional RenderPasses would need to be created. |
| Dynamic | (`viewport`, `scissor` and `blendConstant`) can be changed dynamically on a RenderPass between draw calls. |
| `RenderPipeline` constructor | `RenderPipeline` is created. |
| `RenderPass` constructor | Render targets, clear colors etc. To vary these parameters, additional RenderPasses would need to be created. |
| `RenderPass` method | (`viewport`, `scissor` and `blendConstant`) can be changed dynamically between draw calls in the same RenderPass. |
For completeness, there are certain types of parameters affecting GPU operation that are not
Note that there are certain types of parameters affecting GPU operation that are not handled by
| Parameters | Comments |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
@ -85,6 +75,16 @@ renderPass.draw();
Describes luma.gl setting names and values
1. Vertex Shader
2. Primitive assembly (`topology`)
3. Rasterization (multisampling parameters)
4. Fragment shader `Framebuffer`
5. Stencil test and operation (stencil parameters)
6. Depth test and write (depth parameters)
7. Output merging, controlled by `Framebuffer`
### Primitive Assembly Parameters (RenderPipeline)
Note: `topology` must be specified on a `RenderPipeline` to describe the layout of vertex buffers.

655
docs/api-guide/rendering.md Normal file
View File

@ -0,0 +1,655 @@
# Rendering
> Proposed luma.gl v9 API. Open for comments.
> This page is a work-in-progress
A major feature of any GPU API is the ability to issue GPU draw calls. luma.gl has been designed to offer developers full control over draw calls as outlined below.
## Tutorials
The luma.gl documentation includes a series of tutorials that show how to render
## Model
## RenderPipeline
## RenderPass
...
The luma.gl `Framebuffer` constructor enables the creation of a framebuffer with all the proper attachments in a single step and also the `resize` method makes it easy to efficiently resize a all the attachments of a `Framebuffer` with a single method.
When no attachments are provided during `Framebuffer` object creation, new resources are created and used as default attachments for enabled targets (color and depth).
For color, new `Texture2D` object is created with no mipmaps and following filtering parameters are set.
| Texture parameter | Value |
| ----------------- | --------------- |
| `minFilter` | `linear` |
| `magFilter` | `linear` |
| `addressModeU` | `clamp-to-edge` |
| `addressModeV` | `clamp-to-edge` |
A `Framebuffer` is a container object that holds textures that will be used as render targets for `RenderPipeline`s.
- one or more color textures
- optionally a depth / stencil buffer
An application can render into an (HTML or offscreen) canvas by obtaining a
`Framebuffer` object from a `CanvasContext` using `canvasContext.getDefaultFramebuffer()`.
Alternatively an application can create custom framebuffers for rendering directly into textures.
The application uses a `Framebuffer` by providing it as a parameter to `device.beginRenderPass()`.
All operations on that `RenderPass` instance will render into that framebuffer.
A `Framebuffer` is shallowly immutable (the list of attachments cannot be changed after creation),
however a Framebuffer can be "resized".
## Framebuffer Attachments
A `Framebuffer` holds:
- an array of "color attachments" (often just one) that store data (one or more color `Texture`s)
- an optional depth, stencil or combined depth-stencil `Texture`).
All attachments must be in the form of `Texture`s.
## Rendering into a canvas
To render into a canvas, a special `Framebuffer` should be obtained from a
`CanvasContext` using `canvasContext.getDefaultFramebuffer()`.
A device context `Framebuffer` and has a (single) special color attachment that is connected to the
current swap chain buffer, and also a depth buffer, and is automatically resized to match the size of the canvas
associated.
## Resizing Framebuffers
Resizing a framebuffer effectively destroys all current textures and creates new
textures with otherwise similar properties. All data stored in the previous textures are lost.
This data loss is usually a non-issue as resizes are usually performed between render passes,
(typically to match the size of an off screen render buffer with the new size of the output canvas).
A default Framebuffer should not be manually resized.
### Reading, copying or blitting data from a Framebuffer attachment.
- For reading data into CPU memory check [`readPixelsToArray`](/docs/api-reference/webgl/moving-data)
- For reading into a Buffer object (GPU memory), doesn't result in CPU and GPU sync, check [`readPixelsToBuffer`](/docs/api-reference/webgl/moving-data)
- For reading into a Texture object (GPU memory), doesn't result in CPU and GPU sync, check [`copyToTexture`](/docs/api-reference/webgl/moving-data)
- For blitting between framebuffers (WebGL 2), check [`blit`](/docs/api-reference/webgl/moving-data)
### Framebuffer Attachment Values (TBD)
The following values can be provided for each attachment point
- `Texture` - attaches at mipmapLevel 0 of the supplied `Texture2D`.
- [`Texture`, 0, mipmapLevel] - attaches the specified mipmapLevel from the supplied `Texture2D` (WebGL 2), or cubemap face. The second element in the array must be `0`. In WebGL 1, mipmapLevel must be 0.
- [`Texture` (cube), face (number), mipmapLevel=0 (number)] - attaches the specifed cubemap face from the `Texture`, at the specified mipmap level. In WebGL 1, mipmapLevel must be 0.
- [`Texture`, layer (number), mipmapLevel=0 (number)] - attaches the specifed layer from the `Texture2DArray`, at the specified mipmap level.
- [`Texture3D`, layer (number), mipmapLevel=0 (number)] - attaches the specifed layer from the `Texture3D`, at the specified mipmap level.
## Limitations
The maximum number of color attachments supported is at least `8` in WebGPU and `4` in WebGL2.
There is currently no portable API to query this limit.
## Usage
Creating a framebuffer with default color and depth attachments
```typescript
const framebuffer = device.createFramebuffer({
width: window.innerWidth,
height: window.innerHeight,
color: 'true',
depthStencil: true
});
```
Attaching textures and renderbuffers
```typescript
device.createFramebuffer({
depthStencil: device.createRenderbuffer({...}),
color0: device.createTexture({...}),
color1: [device.createTexture({dimension: 'cube', ...}), GL.TEXTURE_CUBE_MAP_POSITIVE_X],
color2: [device.createTextureArray2D({{dimension: '2d-array',...}), 0],
color3: [device.createTextureArray2D({{dimension: '2d-array',...}), 1],
color4: [device.createTexture3D({{dimension: '3d', ..., depth: 8}), 2]
});
framebuffer.checkStatus(); // optional
```
Resizing a framebuffer to the size of a window. Resizes (and possibly clears) all attachments.
```typescript
framebuffer.resize(window.innerWidth, window.innerHeight);
```
Specifying a framebuffer for rendering in each render calls
```typescript
const offScreenBuffer = device.createFramebuffer(...);
const offScreenRenderPass = device.beginRenderPass({framebuffer: offScreenFramebuffer});
model1.draw({
framebuffer: offScreenBuffer,
parameters: {}
});
model2.draw({
framebuffer: null, // the default drawing buffer
parameters: {}
});
```
Clearing a framebuffer
```typescript
framebuffer.clear();
framebuffer.clear({color: [0, 0, 0, 0], depth: 1, stencil: 0});
```
Binding a framebuffer for multiple render calls
```typescript
const framebuffer1 = device.createFramebuffer({...});
const framebuffer2 = device.createFramebuffer({...});
const renderPass1 = device.createRenderPass({framebuffer: framebuffer1});
program.draw(renderPass1);
renderPass1.endPass();
const renderPass2 = device.createRenderPass({framebuffer: framebuffer1});
program.draw(renderPass2);
renderPass2.endPass();
```
### Using Multiple Render Targets
Specify which framebuffer attachments the fragment shader will be writing to when assigning to `gl_FragData[]`
```typescript
framebuffer.update({
drawBuffers: [
GL.COLOR_ATTACHMENT0, // gl_FragData[0]
GL.COLOR_ATTACHMENT1, // gl_FragData[1]
GL.COLOR_ATTACHMENT2, // gl_FragData[2]
GL.COLOR_ATTACHMENT3 // gl_FragData[3]
]
});
```
Writing to multiple framebuffer attachments in GLSL fragment shader
```
#extension GL_EXT_draw_buffers : require
precision highp float;
void main(void) {
gl_FragData[0] = vec4(0.25);
gl_FragData[1] = vec4(0.5);
gl_FragData[2] = vec4(0.75);
gl_FragData[3] = vec4(1.0);
}
```
Clearing a specific draw buffer in a framebuffer (WebGL 2)
```typescript
framebuffer.clear({
[GL.COLOR]: [0, 0, 1, 1], // Blue
[GL.COLOR]: new Float32Array([0, 0, 0, 0]), // Black/transparent
[GL.DEPTH_BUFFER]: 1, // Infinity
[GL.STENCIL_BUFFER]: 0 // no stencil
});
framebuffer.clear({
[GL.DEPTH_STENCIL_BUFFER]: [1, 0] // Infinity, no stencil
});
```
# RenderPipeline
> Proposed luma.gl v9 API. Open for comments.
A `RenderPipeline` contains a matched pair of vertex and fragment [shaders](/docs/api-reference/webgl/shader) that can be exectued on the GPU by calling `RenderPipeline.draw()`. handle compilation and linking of shaders, and store uniform values. They provide `draw` call which allows the application to run the shaders on specified input data.
A RenderPipeline controls the vertex and fragment shader stages, and can be used in GPURenderPassEncoder as well as GPURenderBundleEncoder.
Render pipeline inputs are:
- bindings, according to the given bindingLayout
- vertex and index buffers
- the color attachments, Framebuffer
- the optional depth-stencil attachment, described by Framebuffer
- parameters
Render pipeline outputs are:
- buffer bindings with a type of "storage"
- storageTexture bindings with a access of "write-only"
- the color attachments, described by Framebuffer
- the depth-stencil optional attachment, described by Framebuffer
A render pipeline is comprised of the following render stages:
- Vertex fetch, from the buffers buffers
- Vertex shader, props.vs
- Primitive assembly, controlled by
- Rasterization controlled by parameters (GPUPrimitiveState, GPUDepthStencilState, and GPUMultisampleState)
- Fragment shader, controlled by props.fs
- Stencil test and operation, controlled by GPUDepthStencilState
- Depth test and write, controlled by GPUDepthStencilState
- Output merging, controlled by GPUFragmentState.targets
## Usage
Creating a pipeline
```js
const pipeline = device.createRenderPipeline({
id: 'my-pipeline',
vs: vertexShaderSourceString,
fs: fragmentShaderSourceString
});
```
Set or update uniforms, in this case world and projection matrices
```js
pipeline.setUniforms({
uMVMatrix: view,
uPMatrix: projection
});
```
Create a `VertexArray` to store buffer values for the vertices of a triangle and drawing
```js
const pipeline = device.createRenderPipeline({vs, fs});
const vertexArray = new VertexArray(gl, {pipeline});
vertexArray.setAttributes({
aVertexPosition: new Buffer(gl, {data: new Float32Array([0, 1, 0, -1, -1, 0, 1, -1, 0])})
});
pipeline.draw({vertexArray, ...});
```
Creating a pipeline for transform feedback, specifying which varyings to use
```js
const pipeline = device.createRenderPipeline({vs, fs, varyings: ['gl_Position']});
```
## Members
- `gl` : `WebGLRenderingContext`
- `handle` : `WebGLProgram` - The WebGL `WebGLProgram` instance.
- `id` : `String` - `id` string for debugging.
## Constructor
### RenderPipeline(gl : WebGLRenderingContext, props : Object)
Creates a new pipeline using the supplied vertex and fragment shaders. The shaders are compiled into WebGLShaders and is created and the shaders are linked.
```js
const pipeline = device.createRenderPipeline({
id: 'my-identifier',
vs: vertexShaderSource,
fs: fragmentShaderSource,
varyings: ['gl_Position', 'vColor']
});
```
- `id` (`string`, optional) - string id (to help indentify the pipeline during debugging).
- `vs` (`VertexShader`|`String`) - A vertex shader object, or source as a string.
- `fs` (`FragmentShader`|`String`) - A fragment shader object, or source as a string.
- `varyings` WebGL 2 (`String[]`) - a list of names of varyings.
- `bufferMode`=`GL.SEPARATE_ATTRIBS` WebGL 2 (`GLenum`) - Optional, specifies how transform feedback should store the varyings.
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | Description |
| ----------------------------------- | ---------------------------- |
| `GL.SEPARATE_ATTRIBS` | One varying per buffer |
| `GL.INTERLEAVED_ATTRIBS` | Multiple varyings per buffer |
WebGL References [WebGLProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram), [gl.createProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/createProgram)
### delete() : RenderPipeline
Deletes resources held by pipeline. Note: Does not currently delete shaders (to enable shader caching).
## Methods
### initialize(props : Object) : RenderPipeline
Relinks a pipeline. Takes the same options as the constructor
### setUniforms(uniforms : Object) : RenderPipeline
Sets named uniforms from a map, ignoring names
- `key` (_String_) - The name of the uniform to be set. The name of the uniform will be matched with the name of the uniform declared in the shader. You can set more uniforms on the RenderPipeline than its shaders use, the extra uniforms will simply be ignored.
- `value` (_mixed_) - The value to be set. Can be a float, an array of floats, a typed array, a boolean, `Texture` etc. The values must match the declarations in the shader.
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram)
### draw(opts) : RenderPipeline
`RenderPipeline.draw` is the entry point for running shaders, rendering and (optionally calculating data using transform feedback techniques).
```js
RenderPipeline.draw({
vertexArray,
uniforms = {},
transformFeedback = null,
samplers = {},
parameters = {},
drawMode = GL.TRIANGLES,
vertexCount,
offset = 0,
isIndexed = false,
indexType = GL.UNSIGNED_SHORT,
isInstanced = false,
instanceCount = 0,
start = 0,
end=
})
```
Main parameters
- `vertexArray` - a `VertexArray` object that will be bound and unbound before and after the draw call.
- `uniforms`=`{}` - a map of uniforms that will be set just before the draw call (and remain set after the call).
- `samplers`=`{}` - a map of texture `Sampler`s that will be bound before the draw call.
- `parameters` - temporary gl settings to be applied to this draw call.
- `transformFeedback`=`null` - optional `TransformFeedback` object containing buffers that will receive the output of the transform feedback operation.
Potentially autodeduced parameters
- `drawMode`=`GL.TRIANGLES` - geometry primitive format of vertex data
- `vertexCount` - number of vertices to draw
- `offset`=`0` - first vertex to draw
- `isIndexed`=`false` - use indices in the "elements" buffer
- `indexType`=`GL.UNSIGNED_SHORT` - must match the type of the "elements" buffer
- `isInstanced`=`false` - Set to enable instanced rendering.
- `instanceCount`=`0` - Number of instances
Parameters for drawing a limited range (WebGL 2 only)
- `start` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
- `end` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
Returns: `true` if successful, `false` if draw call is blocked due to missing resources.
Notes:
- Runs the shaders in the pipeline, on the attributes and uniforms.
- Indexed rendering uses the element buffer (`GL.ELEMENT_ARRAY_BUFFER`), make sure your attributes or `VertexArray` contains one.
- If a `TransformFeedback` object is supplied, `transformFeedback.begin()` and `transformFeedback.end()` will be called before and after the draw call.
- A `Sampler` will only be bound if there is a matching Texture with the same key in the supplied `uniforms` object.
- Once a uniform is set, it's size should not be changed. This is only a concern for array uniforms.
The following WebGL APIs are called in this function:
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram),
[gl.drawElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawElements),
[gl.drawRangeElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawRangeElements) (WebGL 2),
[gl.drawArrays](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawArrays),
[gl.drawElementsInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawElementsInstanced) (WebGL 2),
[gl.drawArraysInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawArraysInstanced) (WebGL 2),
[gl.getExtension](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getExtension), [ANGLE_instanced_arrays](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays),
[gl.drawElementsInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawElementsInstancedANGLE),
[gl.drawArraysInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawArraysInstancedANGLE)
## Constants
### Limits
| Limit | Value | Description |
| ---------------------------------------------------- | -------------- | ----------- |
| `GL.MAX_VERTEX_TEXTURE_IMAGE_UNITS` | >= 0 (GLint) | |
| `GL.MAX_RENDERBUFFER_SIZE` | >= 1 (GLint) | |
| `GL.MAX_VARYING_VECTORS` | >= 8 (GLint) | |
| `GL.MAX_VERTEX_ATTRIBS` | >= 8 (GLint) | |
| `GL.MAX_VERTEX_UNIFORM_VECTORS` | >= 128 (GLint) | |
| `GL.MAX_FRAGMENT_UNIFORM_VECTORS` | >= 16 (GLint) | |
| `GL.TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH` (WebGL 2) | - | - |
### Parameters
Use with `RenderPipeline.getParameter(parameter)`
| Parameter | Type | Description |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GL.DELETE_STATUS` | GLboolean | If true, pipeline has been flagged for deletion (by calling `RenderPipeline.delete()`), but the delete is pending because pipeline is still part of current rendering state |
| `GL.LINK_STATUS` | GLboolean | Indicates whether last link operation was successful. RenderPipeline linking is performed by luma on pipeline initialization |
| `GL.VALIDATE_STATUS` | GLboolean | Result of last `gl.validateProgram()` operation |
| `GL.ATTACHED_SHADERS` | GLint | Number of attached shaders (`0`, `1` or `2`) |
| `GL.ACTIVE_ATTRIBUTES` | GLint | Number of active attribute variables to a pipeline |
| `GL.ACTIVE_UNIFORMS` | GLint | Number of active attribute variables to a pipeline |
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | GLenum | (WebGL 2) Buffer capture mode, `GL.SEPARATE_ATTRIBS` or `GL.INTERLEAVED_ATTRIBS` |
| `GL.TRANSFORM_FEEDBACK_VARYINGS` | GLint | (WebGL 2) Number of varying variables to capture in transform feedback mode. |
| `GL.ACTIVE_UNIFORM_BLOCKS` | GLint | (WebGL 2) Number of uniform blocks containing active uniforms. |
# RenderPipeline
> Proposed luma.gl v9 API. Open for comments.
A `RenderPipeline` contains a matched pair of vertex and fragment [shaders](/docs/api-reference/webgl/shader) that can be exectued on the GPU by calling `RenderPipeline.draw()`. Programs handle compilation and linking of shaders, and store uniform values. They provide `draw` call which allows the application to run the shaders on specified input data.
## Usage
Creating a pipeline
```js
const pipeline = device.createRenderPipeline({
id: 'my-pipeline',
vs: vertexShaderSourceString,
fs: fragmentShaderSourceString
});
```
Set or update uniforms, in this case world and projection matrices
```js
pipeline.setUniforms({
uMVMatrix: view,
uPMatrix: projection
});
```
Create a `VertexArray` to store buffer values for the vertices of a triangle and drawing
```js
const pipeline = device.createRenderPipeline({vs, fs});
const vertexArray = new VertexArray(gl, {pipeline});
vertexArray.setAttributes({
aVertexPosition: new Buffer(gl, {data: new Float32Array([0, 1, 0, -1, -1, 0, 1, -1, 0])})
});
pipeline.draw({vertexArray, ...});
```
Creating a pipeline for transform feedback, specifying which varyings to use
```js
const pipeline = device.createRenderPipeline({vs, fs, varyings: ['gl_Position']});
```
## Members
- `device`: `Device` - holds a reference to the `Device` that created this `Buffer`.
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `BufferProps` - holds a copy of the `BufferProps` used to create this `Buffer`.
## Methods
### `constructor(props: BufferProps)`
`Buffer` is an abstract class and cannot be instantiated directly. Create with `device.createBuffer(...)`.
### `destroy(): void`
Free up any GPU resources associated with this buffer immediately (instead of waiting for garbage collection).
## Members
- `gl` : `WebGLRenderingContext`
- `handle` : `WebGLProgram` - The WebGL `WebGLProgram` instance.
- `id` : `String` - `id` string for debugging.
## Constructor
### RenderPipeline(gl : WebGLRenderingContext, props : Object)
Creates a new pipeline using the supplied vertex and fragment shaders. The shaders are compiled into WebGLShaders and is created and the shaders are linked.
```js
const pipeline = device.createRenderPipeline({
id: 'my-identifier',
vs: vertexShaderSource,
fs: fragmentShaderSource,
varyings: ['gl_Position', 'vColor']
});
```
- `id` (`string`, optional) - string id (to help indentify the pipeline during debugging).
- `vs` (`VertexShader`|`String`) - A vertex shader object, or source as a string.
- `fs` (`FragmentShader`|`String`) - A fragment shader object, or source as a string.
- `varyings` WebGL 2 (`String[]`) - a list of names of varyings.
- `bufferMode`=`GL.SEPARATE_ATTRIBS` WebGL 2 (`GLenum`) - Optional, specifies how transform feedback should store the varyings.
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | Description |
| ----------------------------------- | ---------------------------- |
| `GL.SEPARATE_ATTRIBS` | One varying per buffer |
| `GL.INTERLEAVED_ATTRIBS` | Multiple varyings per buffer |
WebGL References [WebGLProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram), [gl.createProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/createProgram)
### delete() : RenderPipeline
Deletes resources held by pipeline. Note: Does not currently delete shaders (to enable shader caching).
## Methods
### initialize(props : Object) : RenderPipeline
Relinks a pipeline. Takes the same options as the constructor
### setUniforms(uniforms : Object) : RenderPipeline
Sets named uniforms from a map, ignoring names
- `key` (_String_) - The name of the uniform to be set. The name of the uniform will be matched with the name of the uniform declared in the shader. You can set more uniforms on the RenderPipeline than its shaders use, the extra uniforms will simply be ignored.
- `value` (_mixed_) - The value to be set. Can be a float, an array of floats, a typed array, a boolean, `Texture` etc. The values must match the declarations in the shader.
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram)
### draw(opts) : RenderPipeline
`RenderPipeline.draw` is the entry point for running shaders, rendering and (optionally calculating data using transform feedback techniques).
```js
RenderPipeline.draw({
vertexArray,
uniforms = {},
transformFeedback = null,
samplers = {},
parameters = {},
drawMode = GL.TRIANGLES,
vertexCount,
offset = 0,
isIndexed = false,
indexType = GL.UNSIGNED_SHORT,
isInstanced = false,
instanceCount = 0,
start = 0,
end=
})
```
Main parameters
- `vertexArray` - a `VertexArray` object that will be bound and unbound before and after the draw call.
- `uniforms`=`{}` - a map of uniforms that will be set just before the draw call (and remain set after the call).
- `samplers`=`{}` - a map of texture `Sampler`s that will be bound before the draw call.
- `parameters` - temporary gl settings to be applied to this draw call.
- `transformFeedback`=`null` - optional `TransformFeedback` object containing buffers that will receive the output of the transform feedback operation.
Potentially autodeduced parameters
- `drawMode`=`GL.TRIANGLES` - geometry primitive format of vertex data
- `vertexCount` - number of vertices to draw
- `offset`=`0` - first vertex to draw
- `isIndexed`=`false` - use indices in the "elements" buffer
- `indexType`=`GL.UNSIGNED_SHORT` - must match the type of the "elements" buffer
- `isInstanced`=`false` - Set to enable instanced rendering.
- `instanceCount`=`0` - Number of instances
Parameters for drawing a limited range (WebGL 2 only)
- `start` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
- `end` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
Returns: `true` if successful, `false` if draw call is blocked due to missing resources.
Notes:
- Runs the shaders in the pipeline, on the attributes and uniforms.
- Indexed rendering uses the element buffer (`GL.ELEMENT_ARRAY_BUFFER`), make sure your attributes or `VertexArray` contains one.
- If a `TransformFeedback` object is supplied, `transformFeedback.begin()` and `transformFeedback.end()` will be called before and after the draw call.
- A `Sampler` will only be bound if there is a matching Texture with the same key in the supplied `uniforms` object.
- Once a uniform is set, it's size should not be changed. This is only a concern for array uniforms.
The following WebGL APIs are called in this function:
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram),
[gl.drawElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawElements),
[gl.drawRangeElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawRangeElements) (WebGL 2),
[gl.drawArrays](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawArrays),
[gl.drawElementsInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawElementsInstanced) (WebGL 2),
[gl.drawArraysInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawArraysInstanced) (WebGL 2),
[gl.getExtension](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getExtension), [ANGLE_instanced_arrays](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays),
[gl.drawElementsInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawElementsInstancedANGLE),
[gl.drawArraysInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawArraysInstancedANGLE)
## Constants
### Limits
| Limit | Value | Description |
| ---------------------------------------------------- | -------------- | ----------- |
| `GL.MAX_VERTEX_TEXTURE_IMAGE_UNITS` | >= 0 (GLint) | |
| `GL.MAX_RENDERBUFFER_SIZE` | >= 1 (GLint) | |
| `GL.MAX_VARYING_VECTORS` | >= 8 (GLint) | |
| `GL.MAX_VERTEX_ATTRIBS` | >= 8 (GLint) | |
| `GL.MAX_VERTEX_UNIFORM_VECTORS` | >= 128 (GLint) | |
| `GL.MAX_FRAGMENT_UNIFORM_VECTORS` | >= 16 (GLint) | |
| `GL.TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH` (WebGL 2) | - | - |
### Parameters
Use with `RenderPipeline.getParameter(parameter)`
| Parameter | Type | Description |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GL.DELETE_STATUS` | GLboolean | If true, pipeline has been flagged for deletion (by calling `RenderPipeline.delete()`), but the delete is pending because pipeline is still part of current rendering state |
| `GL.LINK_STATUS` | GLboolean | Indicates whether last link operation was successful. RenderPipeline linking is performed by luma on pipeline initialization |
| `GL.VALIDATE_STATUS` | GLboolean | Result of last `gl.validateProgram()` operation |
| `GL.ATTACHED_SHADERS` | GLint | Number of attached shaders (`0`, `1` or `2`) |
| `GL.ACTIVE_ATTRIBUTES` | GLint | Number of active attribute variables to a pipeline |
| `GL.ACTIVE_UNIFORMS` | GLint | Number of active attribute variables to a pipeline |
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | GLenum | (WebGL 2) Buffer capture mode, `GL.SEPARATE_ATTRIBS` or `GL.INTERLEAVED_ATTRIBS` |
| `GL.TRANSFORM_FEEDBACK_VARYINGS` | GLint | (WebGL 2) Number of varying variables to capture in transform feedback mode. |
| `GL.ACTIVE_UNIFORM_BLOCKS` | GLint | (WebGL 2) Number of uniform blocks containing active uniforms. |

27
docs/api-guide/resources.md Normal file
View File

@ -0,0 +1,27 @@
# GPU Resources
GPU resources come in a few different flavors
- Resources that represent actual memory uploaded to the GPU are `Buffer` and `Texture`.
- Resources that hold executable GPU code, such as `Shader`, `Renderpipeline` and `ComputePipeline`.
- Other GPU resources tend to hold validated settings or state (usually these are GPU driver objects rather)
## Creating GPU Resources
The [`Device`](../api-reference/device) class provides methods for creating GPU resources
luma.gl provides a consistent API
| Resource creation method | Description |
| --- | --- |
| `device.createBuffer(props: BufferProps | ArrayBuffer | ArrayBufferView): Buffer` | Create a buffer, Deduces `indexType` if usage. |
| `device.createTexture(props: TextureProps | Promise<TextureData> | string): Texture` | Create a [`Texture`](./resources/texture). |
| `device.createSampler(props: SamplerProps): Sampler` | Create a [`Sampler`](./resources/sampler). |
| `device.createFramebuffer(props: FramebufferProps): Framebuffer` | Create a [`Framebuffer`](./resources/framebuffer). |
| `device.createShader(props: ShaderProps): Shader` | Create a [`Shader`](./resources/shader). |
| `device.createRenderPipeline(props: RenderPipelineProps): RenderPipeline` | Create a [`RenderPipeline`](./resources/render-pipeline) (aka program) |
| `device.createComputePipeline(props: ComputePipelineProps): ComputePipeline` | Create a [`ComputePipeline`](./resources/compute-pipeline) (aka program) |
| `beginRenderPass(props: RenderPassProps): RenderPass` | Create a [`RenderPass`](./resources/render-pass). |
| `beginComputePass(props?: ComputePassProps): ComputePass` | Create a [`ComputePass`](./resources/compute-pass) which can be used to bind data and run compute operations using compute pipelines. |
| `getDefaultRenderPass(): RenderPass` | A default `RenderPass` is provided for applications that don't need to create multiple or specially configured render passes. |

2
docs/api-guide/shader-modules.md
View File

@ -2,7 +2,7 @@
## Overview
shadertools is a GLSL shader module system built around a GLSL "assembler" that allows you build modular shaders. It addresses the lack of a module/import system in the GLSL language and allows you to import chunks of reusable shader code from modules into your shader source code, and organize your shader code in reusable modules.
The `@luma.gl/shadertools` module provides a GLSL shader module system built around a GLSL "assembler" that allows you build modular shaders. It addresses the lack of a module/import system in the GLSL language and allows you to import chunks of reusable shader code from modules into your shader source code, and organize your shader code in reusable modules.
- Enables you to import and "inject" prepackaged modules of shader code into your shaders.
- Allows you to package up reusable GLSL code as shader modules.

26
docs/api-guide/textures.mdx Normal file
View File

@ -0,0 +1,26 @@
import {DeviceTabs, Format as Ft, Filter as L, Render as R} from '@luma.gl/react-website';
# Textures
GPUs support a wide range of texture formats. In luma.gl, each format is identified with a string (the `TextureFormat` type).
Support for a specific format generally has three levels. luma provides `Device` functions to help
applications determine the capabilities of a texture format.
| Texture Format Capability | Check using |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------ |
| Can textures with the format be **created and sampled** (using `nearest` filters)? | `Device.isTextureFormatSupported(format)` |
| Can textures with the format be sampled using **linear filtering**? | `Device.isTextureFormatFilterable(format)` |
| Can textures with the format be rendered into? I.e used as render targets / color attachments? | `Device.isTextureFormatRenderable(format)` |
| Can textures with the format be used for storage bindings? | N/A |
| Can textures with the format be blended? | Yes if sampler type 1float` is supported |
| Do textures with the format support multisampling? | N/A |
Remarks
- Mipmaps can only be auto created for formats that are both filterable and renderable.
- A renderable format is either a color renderable format, or a depth-or-stencil format
- All depth/stencil formats are renderable.
- Less than 4 components, sampler reads the missing red, green and blue components as 0.0, alpha is 1.0
- The capabilities reported by luma.gl represent the minimal specification of the underlying API. Occasionally a driver may provide additional capabilities, such as a WebGL2 device running on top of an OpenGL ES 3.2 driver. Use of non-standard capabilities is enabled but not portable.
- The WebGL 1 core does not provide sized formats. While sized formats offer more control, unsized formats do give the GPU freedom to select the most performant internal representation.

0
docs/api-guide/transform.md → docs/api-guide/transforms.md
View File

88
docs/api-guide/v9-api.md Normal file
View File

@ -0,0 +1,88 @@
# luma.gl v9 API
> Proposed luma.gl v9 API. Open for comments.
The v9 API represents a break with the luma.gl v8 API, which was designed around providing a set of classes explicitly designed for working with the WebGL2 API.
While there are breaking changes, the "spirit" and concepts of the classic luma.gl API have carried forward from the v8 API to the v9 API, and programmers should find themselves comfortably working on the same abstraction level as before with essentially the same classes, such as `Model`, `AnimationLoop`, `Buffer`, `Texture` etc.
But there are a number of important differences, more on that below.
luma.gl v9 is an abstract API, specified in terms of TypeScript interfaces (such as `Buffer`, `Texture` etc). A `Device` class provides concrete classes that implement these interfaces using the corresponding implementation API.
| Interface | Description |
| --- | --- |
| `Adapter` | luma.gl exposes GPU capabilities on the device in the form of one or more as `Adapter`s. |
| `Device` | Manages resources, and the device’s GPUQueues, which execute commands. |
| `Buffer` | The physical resources backed by GPU memory. A `Device` may have its own memory with high-speed access to the processing units. |
| `Texture` | Like buffer, but supports random access |
GPUCommandBuffer and GPURenderBundle are containers for user-recorded commands.
| `Shader` | Compiled shader code.
| `Sampler` | or GPUBindGroup, configure the way physical resources are used by the GPU. |
GPUs execute commands encoded in GPUCommandBuffers by feeding data through a pipeline, which is a mix of fixed-function and programmable stages. Programmable stages execute shaders, which are special programs designed to run on GPU hardware. Most of the state of a pipeline is defined by a GPURenderPipeline or a GPUComputePipeline object. The state not included in these pipeline objects is set during encoding with commands, such as beginRenderPass() or setBlendColor().
## Why a major breaking change?
There a couple of reasons why we decided to make breaking changes in the v9 API:
### A "WebGPU-first" API
Making luma.gl work both on WebGPU and WebGL was the top priority for luma.gl v9. Naturally, we initially considered keeping the existing WebGL2-centric API and providing a WebGPU implementation of it, but ultimately that did not make sense.
- The imminent completion of the WebGPU standard and launch of WebGPU support in the Chrome browser.
- Announcements that no further evolution of the WebGL standard is taking place.
- WebGPU essentially exposes the latest next-gen GPU APIs (Vulkan, Metal, DX12) in the browser. A primary characteristic of these APIs is that they are designed to ensure GPU usage can be optimized "to the bone" (by e.g. minimization CPU-side validation overhead, enabling multi-threading etc) and wrapping WebGPU APIs under a backwards-compatible WebGL-centric API does not make much sense.
- It made sense to make a breaking change now, and introduce
### A "TypeScript-first" API
Both luma.gl and the most of the surrounding vis.gl code base has now been migrated to TypeScript. While we have added TypeScript types to the v8 API, it has become clear that TypeScript enables us to provide cleaner, more intuitive APIs.
One example is that in TypeScript we can now safely specify that an argument must be one of a few specific strings. By using string values in types, we don't need to introduce lots of enumerations or exports, and the code becomes easier to debug as the string parameters are self explaining, typescript will catch any misspelled string inputs. As an example the `Sampler` `minFilter` property is now specified as either `'linear'` or `'nearest'`, rather than `GL.LINEAR` or `GL.NEAREST`.
This move to string constant values also allowed us to align string constants with the WebGPU standard.
### Community Maintainability
Another major reason is that the luma.gl API had grown quite large as it exposed all the functionality offered by WebGL2. However as the some core maintainers have moved on, and luma.gl is increasingly becomes a community project, we want to make sure the code base is accessible and easy to understand. The new WebGPU compatible API provided the just the lens we needed to decide if a piece of functionality could be cut.
For now we have kept all the old functionality (it has been moved into the `gltools` module which is now considered deprecated).
## v9 vs v8 API
- The API is now abstract, specified in terms of TypeScript interfaces, such as `Buffer`, `Texture` etc. A `Device` class provides concrete classes that implement these interfaces using the corresponding implementation API.
- Reading and writing buffers is now an async operation. While WebGL does not support async reads and writes on MacOS, the API is still async to ensure portability.
- Uniform buffers are now the standard way for the application to specify uniforms. Uniform buffers are "emulated" under WebGL.
- The v9 API no longer accepts/returns `GL` constants, but instead uses the corresponding string values from the WebGPU standard (mapping those transparently under WebGL).
- The parameter API has been updated to more closely match the WebGPU API. Also parameters are built into pipelines and not as easy to change in a draw call.
## Get Started
```js
import {GPU} from '@luma.gl/webgpu';
const device = GPU.getDevice({canvas});
const {Buffer, Model, AnimationLoop} = device;
const buffer = new Buffer(device, {});
const animationLoop = new AnimationLoop({
device,
onInitialize({device}) {
},
onFinalize({device}) {
},
onRender({device}) {
}
});
animationLoop.run();
```
## String constants (GL no longer used)

45
docs/api-guide/webgpu-vs-webgl.md Normal file
View File

@ -0,0 +1,45 @@
# WebGPU vs WebGL
This pages collects notes on some of the notable differences between WebGPU and WebGL. This is not intended to be a complete list but is essentially a set of author's notes, included because they may be useful to understanding why some of the breaking changes in the luma.gl v9 API were made, and provide more detail on the differences between the WebGPU and WebGL implementations.
**Decision: Convert luma.gl into a "WebGPU first" API**
## Background
WebGPU is the next generation GPU API for the browser, standardized by W3C. Given the high profile of the project and how WebGPU was designed to embrace all the proprietary next-gen APIs from the major manufacturers (Vulkan, Metal, DX12) it seems reasonable to assume that the WebGPU API will be widely adopted and represents the future of GPU programming on the Web.
## WebGL compatibility
The WebGPU designers had many noble goals, however backwards compatibility WebGL was very clearly not one of them. This lack of backwards is quite significant. And it is not just a simple matter of essentially the same APIs being arbitrarily renamed, but the structure of the API is quite different.
- It is more static, and objects tend to be immutable after creation
- and a range of WebGL features are no longer available (uniforms and transform feedback just to mention a few). There are of course good reasons for this (and In many cases these incompatibilities reflect choices made by the underlying next-gen APIs) but WebGPU does create quite an upgrade shock for existing WebGL based frameworks.
The luma.gl API with its focus on providing direct access to the GPU is perhaps impacted more by the incompatibilities compared to other major WebGL frameworks that tend to provide higher-level, game-engine type abstractions in their APIs (such as a "renderer" class). To be sure, there effort required to support WebGPU is big in both cases, but sometimes implementation changes in other frameworks can be hidden inside their abstractions.
## General comments
## WebGPU Device vs WebGL Context
A WebGL context is associated with a specific canvas.
- The default drawing buffer is associated with the canvas
- Rendering to other canvases either requires separate WebGL contexts (with duplicated GPU resources) or going through hoops with framebuffer rendering and image copies.
- A WebGPU device enables the application to render to multiple canvases using the same resources create separate swap chains for
## Parameters and State Management
In WebGL many parameters are set on the WebGL context using individual function calls.
- This does cause problems when trying to make different modules work together.
- But it does make it easier to change settings between draw calls.
## Programs
| WebGPU limitation | Alternatives |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| No GLSL support | 1) glslang project seems stale. 2) Use Naga (Rust) to build a WebAssembly transpiler. 3) write two sets of shaders. |
| No constant attributes | 1) Create dummy buffers 2) dynamically generate shaders with uniforms. |
| Interleaving specified at Pipeline creation | New `PipelineProps.bufferMap` concept |
| No transform feedback | Compute shaders (storage buffers) |
| No uniforms, only Uniform buffers | Add strong uniform buffer support to API, WebGL1 fallback? |

87
docs/api-guide/wip/accessors.md
View File

@ -1,87 +0,0 @@
# Accessors
"Buffer accessor objects" (or "accessor objects", or just "accessors" for short) are used to describe the structure of data contained in WebGL buffers (for more information see [`Buffers`](/docs/api-reference/webgl/buffer)).
When using `Buffer`s as input to shader programs, applications must tell WebGL how the data in the buffer is formatted, so that the GPU knows how to access buffers' memory. To enable applications to specify how the buffer memory should be accessed, luma.gl APIs that set attribute buffers accept buffer "accessor objects".
## Accessor Object Fields
This is an overview of the object accessor fields that are available to applications to define format descriptions. These objects can contain the following fields, this is an excerpt from [`Accessor`](/docs/api-reference/webgl/accessor).
| Property | Auto Deduced | Default | Comment |
| ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| `buffer` | No | An accessor can optionally reference a specific buffer. Multiple accessors can point to the same buffer, providing different views or "slices" of the buffer's memory. |
| `offset` | No | `0` | Byte offset to start of data in buffer |
| `stride` | No | `0` | Extra bytes between each successive data element |
| `type` | Yes | `GL.FLOAT` | Low level data type (`GL.BYTE`, `GL.SHORT`, ...) |
| `size` | Yes | `1` | Components per element (`1`-`4`) |
| `divisor` | Yes | `0` | Enables/disables instancing |
| `normalize` | N/A | `false` | Normalize integers to [-1,1], or [0,1] if unsigned |
| `integer` | N/A | `false` | Disable conversion of integer values to floats **WebGL 2** |
## Combining Accessors with Buffers
When setting attributes (e.g. using `Model.setProps({attributes: {attributeName: value, ...}}))`, each attribute value needs to contain both a buffer (a handle to the raw data uploaded to the GPU) and an accessor (describing how that data should be accessed).
luma.gl provides three methods to specify attribute values so that both a buffer and an accessor are provided:
- As a two-element array: `[buffer, accessor]`.
- As an accessor, in which case the accessor object's `buffer` field should be set to the matching `Buffer`.
- As a `Buffer`, in which case the `Buffer` objects `accessor` field should be set to the mathing `Accessor`.
All three methods have their uses: the first option gives the applications full freedom to dynamically select combinations of buffers and accessors, the second option is often the natural choice when working with interleaved buffers (see below), and the last choice is often the most convenient when just setting up an ad-hoc buffer for immediate use, as the accessor can be stored directly on the buffer, avoiding the need to manage separate objects.
## Accessor Class vs Accessor Objects
luma.gl provides the [`Accessor`](/docs/api-reference/webgl/accessor) helper class to help you work with accessor objects. For instance, the `Accessor` class supports merging of partial accessor objects, see below.
Note that it is not necessary to use the `Accessor` class, as plain old JavaScript objects with the appropriate fields are also accepted by the various APIs that accept accessors. Use the style that works best for your application.
### "Partial" Accessors
luma.gl allows "partial" accessors to be created, and later combined. Usually many accessor fields can be left undefined (e.g. because defaults are sufficient, or because accessor auto-deduction has already deduced the information, see below).
Partial accessors will be created automatically by `Program` when shaders are compiled and linked, and also by `Buffer` objects when they are created. Any application supplied accessors fields will then be merged in (override) these auto-deduceted fields, that can add any fine-tuning or override of parameters.
### Accessor Auto Deduction
luma.gl attempts to "auto deduce" as much accessor information as it can, for instance luma.gl can extract fields like `type` and `size` after shaders have been compiled.
This relieves applications from having to respecify the same thing multiple times. For instance if the application has already declared an attribute as `in vec2 size` in the vertex shader, it does not need to specify `size:2, type: GL.FLOAT` again in the accessor, when it sets the buffer in JavaScript, since this information will have been auto-deduced.
In many cases, when buffers are not shared between attributes (i.e. interleaved) and default behavior is desired, luma.gl applications often do not need to specify any `Accessor` at all.
### Merging (Resolving) Accessors
The `Accessor` API allows for accessors to be merged (or "resolved") into a new `Accessor`. Accessor mmerging is mainly used internally in luma.gl to implement support for partial accessors and accessor auto deduction, but can be used by applications if necessary.
### Data Interleaving
Using the`stride` and `offset` fields in accessor objects, it is possible to interleave two arrays so that the first two elements of one array are next to each other, then the next two elements etc.
```
const interleavedBuffer = new Buffer(gl, accessor: {stride: 12 + 4}}); // Creates a partial accessor with `stride` in buffer.
vertexArray.setAttributes({
// These accessors are merged with the `interleavedBuffer` accessor and any
// auto-deduced accessors
POSITIONS: new Accessor({offset: 0, buffer: interleavedBuffer})
COLORS: new Accessor({offset: 12, buffer: interleavedBuffer})
})
```
For more information see the article about attributes.
### Using Different Size in Buffers and Shaders
It is possible to use different size memory attributes than specified by the GLSL shader code, by specifying a different size in the accessor compared to the GLSL shader variable declaration. Extra components in the Buffer memory will be ignored, missing components will be filled in from `(0.0, 0.0, 0.0, 1.0)`
> Be aware that the headless gl integration does not support this feature due to limitations in headless gl.
### glTF Format Accessors
[glTF formatted files](https://www.khronos.org/gltf/). glTF files contain two JSON object arrays ("bufferViews" and "accessors") that describe how raw memory buffers are organized and should be interpreted.
The `Accessor` and `Buffer` class APIs have intentionally been designed to be a close representation when converting "accessors" and "bufferViews" stored in glTF files. Each glTF `accessor` can be mapped to a luma.gl `Accessor` and each glTF `bufferView` can be mapped to a luma.gl `Buffer`.
`For more details see [glTF mapping]().`

20
dev-docs/tech-docs-wip/README-WEBGL.md → docs/api-reference-legacy/README.md
View File

@ -1,16 +1,12 @@
# @luma.gl/gltools
Starting from luma.gl v9, the `@luma.gl/gltools` exports the now deprecated luma.gl v8 WebGL API.
The module provides WebGL context related functionality as well as WebGL API classes.
> These docs are work in progress
# WebGL Module Reference
luma.gl's WebGL classes are designed to offer a simple way to work with WebGL in JavaScript, without hiding or interfering with the WebGL API.
Highlights:
* luma.gl organizes the WebGL API in a set JavaScript classes that manage the underlying WebGL objects
* Instead of accessing all WebGL methods through the WebGL context, the methods that manipulate a certain WebGL object are collected in a class.
* This makes it easy see at a glance what classes WebGL offers, and allows you to quickly read up on what functionality is offered by each specific class.
## WebGL Resources
## WebGL Classes
luma.gl provides a set of JavaScript classes that wrap WebGL resource objects,
with the goal of making WebGL easier to work with and to learn.
@ -65,6 +61,6 @@ These objects all inherit from the [`Resource`](resource.html) class.
## General Comments
luma.gl provides JavaScript classes that manage core WebGL object types, with the intention of making these WebGL objects easier to work with in JavaScript, without adding an abstraction layer.
The `@luma.gl/gltools` module provides JavaScript classes that manage core WebGL object types, making these WebGL objects easier to work with in JavaScript without adding an abstraction layer.
The WebGL classes manage the resources that can be created in WebGL and naturally collect related functionality from the sprawling WebGL2 API into methods on classes. Each class provides methods that closely matches the operations supported by the underlying WebGL object, trying carefully not to alter semantics, while reducing the boilerplate often required by the verbose low-level WebGL functions (such as long, repeated argument lists, as well as the additional WebGL calls that are often necessary to bind and configure parameters before doing an actual operation), or automatically selecting the correct function among a family of similar overloaded functions.

66
docs/api-reference-legacy/classes/README.md Normal file
View File

@ -0,0 +1,66 @@
# @luma.gl/gltools
Starting from luma.gl v9, the `@luma.gl/gltools` exports the now deprecated luma.gl v8 WebGL API.
The module provides WebGL context related functionality as well as WebGL API classes.
> These docs are work in progress
## WebGL Classes
luma.gl provides a set of JavaScript classes that wrap WebGL resource objects,
with the goal of making WebGL easier to work with and to learn.
These objects all inherit from the [`Resource`](resource.html) class.
| ----------------------------------- | ============== | =============== |
| **Resource Class** | **WebGL Type** | **Description** |
| ----------------------------------- | ============== | =============== |
| [`Buffer`](/docs/api-reference/webgl/buffer.md) | [`WebGLBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLBuffer) | Holds memory on GPU |
| [`Framebuffer`](/docs/api-reference/webgl/framebuffer.md) | [`WebGLFrameBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLFrameBuffer) | Off-screen render target, Container for textures and renderbuffers. |
| [`Renderbuffer`](/docs/api-reference/webgl/renderbuffer.md) | [`WebGLRenderBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderBuffer) | Holds image data that is optimized for rendering but does not supporting sampling |
| [`Program`](/docs/api-reference/webgl/program.md) | [`WebGLProgram`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram) | Shaders, attributes and uniforms. |
| [`Shader`](/docs/api-reference/webgl/shader.md) | [`WebGLShader`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram) | Holds a compiled GLSL shader program. |
| [`Texture2D`](/docs/api-reference/webgl/texture-2d.md) | [`WebGLTexture(GL.TEXTURE_2D)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds a loaded texture in a format that supports sampling |
| [`TextureCube`](/docs/api-reference/webgl/texture-cube.md) | [`WebGLTexture(GL.TEXTURE_CUBE)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds 6 textures |
| [`WebGLTexture(GL.TEXTURE_2D_ARRAY)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds an array of textures |
| [`Texture3D`](/docs/api-reference/webgl/texture-3d.md) **WebGL2** | [`WebGLTexture(GL.TEXTURE_3D)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds a stack of textures |
| [`Query`](/docs/api-reference/webgl/query.md) **WebGL2/ext*** | [`WebGLQuery`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLQuery) | Occlusion, Tranform Feedback and Performance Queries |
| [`WebGLSampler`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLSampler) | Stores texture sampling params |
| [`Sync`](/#/documentation/api-reference/sync) **WebGL2** | [`WebGLSync`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLSync) | Synchronize GPU and app. |
| [`TransformFeedback`](/docs/api-reference/webgl/transform-feedback.md) **WebGL2** | [`WebGLTransformFeedback`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTransformFeedback) | Capture Vertex Shader output |
| [`VertexArrayObject`](/docs/api-reference/webgl/vertex-array.md) **WebGL2/ext** | [`WebGLVertexArrayObject`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLVertexArrayObject) | Save global vertex attribute array. |
| ----------------------------------- | ============== | =============== |
| **Class/Module** | **WebGL Type** | **Description** |
| ----------------------------------- | ============== | =============== |
| [`context`](/#/documentation/api-reference/webgl-context) | [`WebGLRenderingContext`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext) | The main GL context. |
| [`VertexAttributes`](vertex-attributes.html) | [`gl.vertexAttrib*`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/vertexAttribPointer) | Manipulates shader attributes (TBD merge with VAO?) |
| **Class/Module** | **WebGL Type** | **Description** |
| --- | --- | --- |
| [`createGLContext`](context.html#createGLContext) | [`WebGLRenderingContext`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext) | The main GL context. |
| [`Buffer`](buffer.html) | [`WebGLBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLBuffer) | Holds memory on GPU |
| [`FrameBuffer`](frame-buffer.html) | [`WebGLFrameBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLFrameBuffer) | Holds a framebuffer |
| [`RenderBuffer`](render-buffer.html) | [`WebGLRenderBuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderBuffer) | Holds a renderbuffer |
| [`Program`](program.html) | [`WebGLProgram`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram) | Shaders, attributes and uniforms.
| [`Shader`](shader.html) | [`WebGLShader`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram) | Shaders, attributes and uniforms.
| [`Texture2D`](texture.html) | [`WebGLTexture(GL.TEXTURE_2D)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds a loaded texture |
| [`TextureCube`](texture.html) | [`WebGLTexture(GL.TEXTURE_CUBE)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds a loaded texture |
| [`Texture2DArray`](texture.html) **`WebGL2`** | [`WebGLTexture(GL.TEXTURE_2D_ARRAY)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds a loaded texture |
| [`Texture3D`](texture.html) **`WebGL2`** | [`WebGLTexture(GL.TEXTURE_3D)`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTexture) | Holds a loaded texture |
| [`Query`](query.html) **`WebGL2`/`ext`** | [`WebGLQuery`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLQuery) | Occlusion, Tranform Feedback and Performance Queries |
| [`Sampler`](sampler.html) **`WebGL2`** | [`WebGLSampler`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLSampler) | Stores texture sampling params |
| [`Sync`](sync.html) **`WebGL2`** | [`WebGLSync`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLSync) | Synchronize GPU and app. |
| [`TransformFeedback`](transform-feedback.html) **`WebGL2`** | [`WebGLTransformFeedback`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLTransformFeedback) | Capture Vertex Shader output |
| [`VertexArrayObject`](vertex-array-object.html) **`WebGL2`/`ext`** | [`WebGLVertexArrayObject`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLVertexArrayObject) | Save global vertex attribute array. |
| [`VertexAttributes`](vertex-attributes.html) | [`gl.vertexAttrib*`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/vertexAttribPointer) | Manipulates shader attributes (TBD merge with VAO?) |
| [`VertexAttributes`](vertex-attributes.html) | [`gl.vertexAttrib*`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/vertexAttribPointer) | Manipulates shader attributes |
## General Comments
The `@luma.gl/gltools` module provides JavaScript classes that manage core WebGL object types, making these WebGL objects easier to work with in JavaScript without adding an abstraction layer.
The WebGL classes manage the resources that can be created in WebGL and naturally collect related functionality from the sprawling WebGL2 API into methods on classes. Each class provides methods that closely matches the operations supported by the underlying WebGL object, trying carefully not to alter semantics, while reducing the boilerplate often required by the verbose low-level WebGL functions (such as long, repeated argument lists, as well as the additional WebGL calls that are often necessary to bind and configure parameters before doing an actual operation), or automatically selecting the correct function among a family of similar overloaded functions.

2
docs/modules/webgl/legacy/accessor.md → docs/api-reference-legacy/classes/accessor.md
View File

@ -1,5 +1,7 @@
# Accessor
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
The `Accessor` class is a helper class that describes how a buffers memory is structured and should be accessed. Accessors are used.
The type of values, number of values per element, any offset and strides, etc. as well as some additional parameters relating to how the GPU should access buffer data (instance divisors, integer normalization etc).

2
docs/modules/webgl/legacy/buffer.md → docs/api-reference-legacy/classes/buffer.md
View File

@ -1,5 +1,7 @@
# Buffer
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
A `Buffer` is a WebGL object that stores an chunk of memory allocated by the GPU. This memory can be accessed directly by the GPU and is used to store things like vertex data, pixel data retrieved from images or the framebuffer, etc. The `Buffer` class provides mechanism for allocating such memory, together with facilities for copying data to and from the GPU (usually via JavaScript typed arrays).
For additional information, see [OpenGL Wiki](https://www.khronos.org/opengl/wiki/Buffer_Object).

2
docs/modules/webgl/legacy/framebuffer.md → docs/api-reference-legacy/classes/framebuffer.md
View File

@ -1,5 +1,7 @@
# Framebuffer
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
A `Framebuffer` is a WebGL container object that the application can use for "off screen" rendering. A framebuffer does not itself contain any image data but can optionally contain attachments (one or more color buffers, a depth buffer and a stencil buffer) that store data. Attachments must be in the form of `Texture`s and `Renderbuffer`s.
For additional information, see OpenGL Wiki [Framebuffer](https://www.khronos.org/opengl/wiki/Framebuffer) and [Framebuffer Object](https://www.khronos.org/opengl/wiki/Framebuffer_Object)

2
docs/modules/webgl/legacy/moving-data.md → docs/api-reference-legacy/classes/moving-data.md
View File

@ -1,5 +1,7 @@
# Moving Data
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
`luma.gl` offers a set of functions that copy or blit data from and to Texture and Framebuffer objects. Image data can also be copied into Buffer, TypedArray, Images or Urls.
## Readback Functions

2
docs/modules/webgl/legacy/program.md → docs/api-reference-legacy/classes/program.md
View File

@ -1,5 +1,7 @@
# Program
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
A `Program` contains a matched pair of vertex and fragment [shaders](/docs/api-reference/webgl/shader) that can be exectued on the GPU by calling `Program.draw()`. Programs handle compilation and linking of shaders, and store uniform values. They provide `draw` call which allows the application to run the shaders on specified input data.
## Usage

2
docs/modules/webgl/legacy/query.md → docs/api-reference-legacy/classes/query.md
View File

@ -1,5 +1,7 @@
# Query
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
A `Query` object provides single unified API for using WebGL asynchronus queries, which include query objects ('Occlusion' and 'Transform Feedback') and timer queries.
See also:

2
docs/modules/webgl/legacy/renderbuffer.md → docs/api-reference-legacy/classes/renderbuffer.md
View File

@ -1,5 +1,7 @@
# Renderbuffer
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
`Renderbuffer`s are WebGL Objects that contain textures. They are optimized for use as render targets, while vanilla `Texture`s may not be, and are the logical choice when you do not need to sample (i.e. in a post-pass shader) from the produced image. If you do need to sample (such as when reading depth back in a second shader pass), use [`Texture`](/docs/api-reference/webgl/texture) instead. In addition, in WebGL 2, `Renderbuffer` can do [Multisampling (MSAA)](https://www.khronos.org/opengl/wiki/Multisampling) just like standard framebuffer.
For additional information, see [OpenGL Wiki](https://www.opengl.org/wiki/Renderbuffer_Object)

2
docs/modules/webgl/legacy/resource.md → docs/api-reference-legacy/classes/resource.md
View File

@ -1,5 +1,7 @@
# Resource
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
## Overview
The `Resource` class is the base class of all WebGL resource classes (e.g. `Buffer`, `Texture`, etc.)

2
docs/modules/webgl/legacy/shader.md → docs/api-reference-legacy/classes/shader.md
View File

@ -1,5 +1,7 @@
# Shader
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
The `Shader` class are the base class for `VertexShader` class and `FragmentShader` class
## Usage

2
docs/modules/webgl/legacy/texture-2d.md → docs/api-reference-legacy/classes/texture-2d.md
View File

@ -1,5 +1,7 @@
# Texture2D
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
2D textures hold basic "single image" textures (although technically they can contain multiple mipmap levels). They hold image memory of a certain format and size, determined at initialization time. They can be read from using shaders and written to by attaching them to frame buffers.
Most texture related functionality is implemented by and documented on the [Texture](/docs/api-reference/webgl/texture) base class. For additional information, see [OpenGL Wiki](https://www.khronos.org/opengl/wiki/Texture).

2
docs/modules/webgl/legacy/texture-3d.md → docs/api-reference-legacy/classes/texture-3d.md
View File

@ -1,5 +1,7 @@
# Texture3D (WebGL 2)
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
3D textures hold basic volumetric textures and can be thought of 3-dimentional arrays with a width, height and depth. They hold image memory of a certain format and size, determined at initialization time. They can be sampled in shaders using the `texture` function with a 3D texture coordinate.
Most texture related functionality is implemented by and documented on the [Texture](/docs/api-reference/webgl/texture) base class. For additional information, see [OpenGL Wiki](https://www.khronos.org/opengl/wiki/Texture).

2
docs/modules/webgl/legacy/texture-cube.md → docs/api-reference-legacy/classes/texture-cube.md
View File

@ -1,5 +1,7 @@
# TextureCube
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
A texture cube holds six textures that represent faces of the cube. A main feature of `TextureCube`s are that they can be passed to shaders and sampled with a direction vector (looking out from the center of the cube) rather than a normal set of texture coordinates, see Usage below.
`TextureCube`s are typically used to store environment maps. As an example, by rendering an environment into a texture cube, reflections in objects can then be rendered efficiently.

2
docs/modules/webgl/legacy/texture.md → docs/api-reference-legacy/classes/texture.md
View File

@ -1,5 +1,7 @@
# Texture
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
A `Texture` is a WebGL object that contains one or more images that all have the same image format. Shaders can read from textures (through a sampler uniform) and they can be set up as render targets (by attaching them to a framebuffer).
Note: This section describes the `Texture` base class that implements functionality common to all four types of WebGL:

2
docs/modules/webgl/legacy/transform-feedback.md → docs/api-reference-legacy/classes/transform-feedback.md
View File

@ -1,5 +1,7 @@
# TransformFeedback (WebGL 2)
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
`TransformFeedback` objects holds state needed to perform transform feedback operations. They store the buffer bindings that are being recorded to. This makes it easy to switch between different sets of feedback buffer bindings (somewhat similar to how `VertexArrayObjects` hold input vertex buffers.
The state managed by `TransformFeedback` objects includes the buffers the GPU will use to record the requested varyings.

2
docs/modules/webgl/legacy/uniform-buffer-layout.md → docs/api-reference-legacy/classes/uniform-buffer-layout.md
View File

@ -1,5 +1,7 @@
# UniformBufferLayout (WebGL 2)
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
A helper class that lets the application describe the contents of a uniform block and then perform `setUniforms({uniform: value})` calls on it, manipulating individual values without concern for memory layout requirements.
## Usage

2
docs/modules/webgl/legacy/vertex-array-object.md → docs/api-reference-legacy/classes/vertex-array-object.md
View File

@ -1,5 +1,7 @@
# VertexArrayObject
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
The WebGL `VertexArrayObject` object holds a map of "buffers" that will be made available as input data to shaders during a draw call, similar to how a `TransformFeedback` object holds a set of `Buffer` instances that will receive output data from shaders.For `Buffer` objects, the `VertexArrayObject` also stores some additional information about how that data in the buffer should be accessed, such as offsets, strides, etc.
However, the use of `VertexArrayObject` is problematic in WebGL 1. While it is crucial for the operation of a program, its presence under WebGL 1 is dependent on an [extension](https://webglstats.com/webgl/extension/OES_vertex_array_object) that is fairly common, but not universally available. In particular it is not available in headless gl which is essential for running tests under Node.js.

2
docs/modules/webgl/legacy/vertex-array.md → docs/api-reference-legacy/classes/vertex-array.md
View File

@ -1,5 +1,7 @@
# VertexArray
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
The `VertexArray` class (like its lower level counterpart, the `VertexArrayObject`) manages an "array" of values ("buffers") that will be made available as input data to shaders during a draw call. For each WebGL `Buffer`, the `VertexArray` also stores some additional information about how that data in the buffer should be accessed, such as offsets, strides, etc, and whether the attribute is instanced.
The `VertexArray` class provides the following features on top of the lower level `VertexArrayObject` class:

2
docs/modules/webgl/context/context-api.md → docs/api-reference-legacy/context/context-api.md
View File

@ -1,5 +1,7 @@
# Context Management
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
Functions to initialize, instrument and manipulate WebGL contexts.
## Usage

2
docs/modules/webgl/context/context-properties.md → docs/api-reference-legacy/context/context-properties.md
View File

@ -1,5 +1,7 @@
# Context Properties
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
luma.gl provides several helper functions for testing properties of a WebGL context:
- `getContextLimits`: get resource limits for a context

2
docs/modules/webgl/context/device-pixels.md → docs/api-reference-legacy/context/device-pixels.md
View File

@ -1,5 +1,7 @@
# Device Pixels
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
Many modern devices support retina or UHD displays can render 2 or 4 times the number of pixels indicated by the CSS dimensions. By rendering to a drawing surface that matches the device and then down sampling it to the smaller (CSS) area, sharper images can be produced but at the cost of rendering more pixels.
The [resizeGLContext](/docs/api-reference/gltools/context) function takes a `useDevicePixels` option that can resize the drawing buffer without resizing the the canvas as displayed on the screen. The following functions are provided to simplify calculations between the display size and device size of the drawing buffer:

2
docs/modules/webgl/context/feature-checking.md → docs/api-reference-legacy/context/feature-checking.md
View File

@ -1,5 +1,7 @@
# Feature Checking
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
Provides WebGL feature detection.
WebGL capabilities can vary quite dramatically between browsers (from minimal WebGL 1 (e.g. headless-gl) to WebGL 1 with dozens of extensions to full WebGL 2, which also has a growing number of extensions). Unfortunately, the raw WebGL API sometimes expose the same functionalities through APIs that are slightly different and not exactly compatible.

2
docs/modules/webgl/context/parameter-setting.md → docs/api-reference-legacy/context/parameter-setting.md
View File

@ -1,5 +1,7 @@
# Parameter Setting
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
luma.gl simplifies the usage of WebGL parameters by providing a unified API for setting and getting values. Any GL parameter can be queried or set using `getParameters` and `setParameters` (no need to keep track of what underlying WebGL calls are required), and luma.gl also provide _setting names_ that allow the normal WebGL setter functions (like `gl.blendEquation` or `gl.clearColor`) to be specified as keys in a `setParameters` call.
In addition, state queries are done towards cached values and are thus much faster than working directly with the WebGL API, where synchronous WebGL queries can be a performance bottleneck.

71
docs/api-reference/canvas-context.md Normal file
View File

@ -0,0 +1,71 @@
# CanvasContext
> Proposed luma.gl v9 API. Open for comments.
A `CanvasContext` holds a connection between the GPU `Device` and an HTML `canvas` or `OffscreenCanvas` into which it can render.
Canvas contexts are created using `device.createCanvasContext()`. Depending on options passed, this either creates a new canvas element, or attaches the context to an existing canvas element (see [remarks](#remarks) below for WebGL limitations).
a `CanvasContext` handles the following responsibilities:
- manages the "swap chain" (provides a `Framebuffer` representing the display, with freshly updated and resized textures for every render frame)
- manages canvas resizing
- manages device pixel ratio
## Types
### `CanvasContextProps`
| Property | Type |
| ----------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------- |
| `canvas?` | `HTMLCanvasElement` \| `OffscreenCanvas` \| `string` | A new canvas will be created if not supplied. |
| `container?` | `HTMLElement` | Parent DOM element for new canvas. Defaults to first child of `document.body` |
| `width?` | `number` | Width in pixels of the canvas |
| `height?` | `number` | Height in pixels of the canvas |
| `useDevicePixels?` | `boolean` \| `number` | Device pixels scale factor (`true` uses browser DPI) |
| `autoResize?` | `boolean` | Whether to track resizes |
| `visible?` | `boolean` | Visibility (only used if new canvas is created). |
| `colorSpace?` | `'srgb'` | WebGPU only https://www.w3.org/TR/webgpu/#canvas-configuration |
| `compositingAlphaMode?` | `'opaque'` \| `'premultiplied'` | WebGPU only https://www.w3.org/TR/webgpu/#canvas-configuration |
## Static Fields
### `CanvasContext.isPageLoaded: boolean`
### `CanvasContext.pageLoaded: Promise<void>`
## Fields
### `canvas: HMTLCanvas | OffscreenCanvas`
### `useDevicePixels: boolean | number`
## Methods
### constructor
A `CanvasContext` can not be constructed directly. It must be created by instantiating a `WebGPUDevice` or a `WebGLDevice`, or through `WebGPUDevice.createCanvasContext()`.
### `getDevicePixelResolution(): [number, number]`
### `getPixelSize(): [number, number]`
Returns the size in pixels required to cover the canvas at the current device pixel resolution.
### `resize()`
Resize the drawing surface.
```
canvasContext.resize(options)
```
- **width**: New drawing surface width.
- **height**: New drawing surface height.
- **useDevicePixels**: Whether to scale the drawing surface using the device pixel ratio.
## Remarks
- Note that a WebGPU `Device` can have multiple associated `CanvasContext` instances (or none, if only used for compute). However a WebGL `Device` always has exactly one `CanvasContext` and can only render into that single canvas. (This is a fundamental limitation of the WebGL API.)
- `useDevicePixels` can accept a custom ratio (Number), instead of `true` or `false`. This allows rendering to a much smaller or higher resolutions. When using high value (usually more than device pixel ratio), it is possible it can get clamped down, this happens due to system memory limitation, in such cases a warning will be logged to the browser console. For additional details check device pixels [`document`](<(/docs/api-reference/gltools/device-pixels)>).

137
docs/api-guide/wip/features.mdx → docs/api-reference/device-features.mdx
View File

@ -1,4 +1,95 @@
import {Feature as F} from '@luma.gl/react-website';
import {
DeviceTabs,
Info,
Feature as F,
Limit as L,
WebGLLimit as WL,
WebGLExtensions
} from '@luma.gl/react-website';
# DeviceFeature
> Proposed luma.gl v9 API. Open for comments.
The luma.gl `Device` provides a range of fields and functions to help an application
determine the capabilities of the underlying platform and API.
The tables on this page use luma.gl Device APIs to display the capabilities of your current browser.
Open this page in different browsers to compare capabilities.
## Fields
### Device.info
A `DeviceInfo` object with fields that describe the devices.
<DeviceTabs />
| Field | This Browser | Description |
| ---------- | --------------------- | ------------------------------------- |
| `type` | <Info f="type" /> | `webgpu`, `webgl2` or `webgl` |
| `gpu` | <Info f="gpu" /> | `intel`, `nvidia`, `amd` or `unknown` |
| `renderer` | <Info f="renderer" /> | GPU Driver |
| `vendor` | <Info f="vendor" /> | GPU vendor |
| `version` | <Info f="version" /> | Driver version |
### Device.features
luma.gl provides a unified feature detection system across WebGPU, WebGL and GLSL.
Each device has a `device.features` field that holds a set of strings (`Set<DeviceFeature>`).
A substantial set of features are devoted to texture capabilites, however these can also
be queried on a per-texture basis
```typescript
if (device.features.has('instanced-rendering-webgl1')) {
// Will work both on WebGL 1 (via extension) and WebGL 2 via the standard API
program.draw({instanceCount: ..., ....});
}
```
<DeviceTabs />
| `luma.gl Feature` | This<br /> Browser | Description |
| -------------------------------------- | ---------------------------------------------- | ------------------------------ |
| **Features** |
| `depth-clip-control` | <F f="depth-clip-control"/> | Depth clamps instead of clips. |
| `indirect-first-instance` | <F f="indirect-first-instance"/> | Specify via GPU buffer |
| `timestamp-query` | <F f="timestamp-query"/> | |
| `timer-query-webgl` | <F f="timer-query-webgl"/> | GPU timer support |
| `instanced-rendering-webgl1` | <F f="instanced-rendering-webgl1"/> | Instanced rendering available |
| `multiple-render-targets-webgl1` | <F f="multiple-render-targets-webgl1"/> | Multiple render targets |
| `index-uint32-webgl1` | <F f="index-uint32-webgl1"/> | 32 bit indexing supported |
| `blend-minmax-webgl1` | <F f="blend-minmax-webgl1"/> | `min` and `max` blending |
| **Textures** |
| `depth24unorm-stencil8` | <F f="depth24unorm-stencil8"/> | `UNSIGNED_INT_24_8_WEBGL` |
| `depth32float-stencil8` | <F f="depth32float-stencil8"/> | WebGPU only |
| `texture-filter-anisotropic-webgl` | <F f="texture-filter-anisotropic-webgl"/> | anisotropic filtering, common |
| `texture-filter-linear-float32-webgl` | <F f="texture-filter-linear-float32-webgl"/> | float32 `linear` filtering |
| `texture-filter-linear-float16-webgl` | <F f="texture-filter-linear-float16-webgl`" /> | float16 `linear` filtering |
| `texture-renderable-float32-webgl` | <F f="texture-renderable-float32-webgl"/> | float32 textures renderable |
| `texture-renderable-float16-webgl` | <F f="texture-renderable-float16-webgl"/> | float16 textures renderable |
| `texture-renderable-rgba32float-webgl` | <F f="texture-renderable-rgba32float-webgl"/> | float32 textures renderable |
| `texture-blend-float-webgl1` | <F f="texture-blend-float-webgl1"/> | float texture blending |
| `texture-formats-float32-webgl1` | <F f="texture-formats-float32-webgl1"/> | float32 texture support |
| `texture-formats-float16-webgl1` | <F f="texture-formats-float16-webgl1"/> | float16 texture support |
| `texture-formats-srgb-webgl1` | <F f="texture-formats-srgb-webgl1"/> | SRGB format support |
| `texture-formats-depth-webgl1` | <F f="texture-formats-depth-webgl1"/> | depth texture supports |
| **Compressed Textures** |
| `texture-compression-bc5-webgl` | <F f="texture-compression-bc5-webgl"/> | DXT (BC1-BC5). Desktops. |
| `texture-compression-bc` | <F f="texture-compression-bc"/> | DXT (BC1-BC7). Desktops. |
| `texture-compression-etc2` | <F f="texture-compression-etc2"/> | Performance caveats. |
| `texture-compression-astc` | <F f="texture-compression-astc"/> | ASTC. |
| `texture-compression-etc1-webgl` | <F f="texture-compression-etc1-webgl"/> | Qualcomm Snapdragon. Android. |
| `texture-compression-pvrtc-webgl` | <F f="texture-compression-pvrtc-webgl"/> | PowerVR GPUs, iOS devices. |
| `texture-compression-atc-webgl` | <F f="texture-compression-atc-webgl"/> | Qualcomm Adreno GPUs. Android. |
| **GLSL** |
| `glsl-frag-data` | <F f="glsl-frag-data"/> | |
| `glsl-frag-depth` | <F f="glsl-frag-depth"/> | |
| `glsl-derivatives` | <F f="glsl-derivatives"/> | |
| `glsl-texture-lod` | <F f="glsl-texture-lod"/> | |
## Usage
@ -16,18 +107,33 @@ if (webglDevice.gl.getExtension('EXT_disjoint_timer_query') || webglDevice.gl.ge
}
```
## Alternative APIs
## WebGL
There are a few additional capability query functions in the luma.gl API. In particular,
some classes have a static `isSupported()` method that you can call instead of checking
for specific features.
If you know that you are running on WebGL, you don't need to go through
the luma.gl Device APIs. You can access "raw" WebGL extensions and limits directly.
### WebGL extensions
It is easy to get the list of actual WebGL extensions from `WebGLDevice`:
```typescript
import {Query} from '@luma.gl/webgl';
if (Query.isSupported(gl)) {
...
}
const webglDevice = device instanceof WebGLDevice ? (device as WebGLDevice) : null;
const extensions = webglDevice ? webglDevice.gl.getSupportedExtensions() : [];
console.log(extensions);
```
On your current browser, this would yield:
<DeviceTabs />
<WebGLExtensions />
> Caveat: WebGL extensions can be onerous to work with directly. They are very granular,
> and WebGL1 extensions are not listed as supported on WebGL2 contexts even though the
> corresponding features are supported.
# Features
| `FEATURE` | Description |
@ -47,13 +153,12 @@ if (Query.isSupported(gl)) {
| `texture-renderable-float32-webgl` | Floating point `Texture`s are renderable and readable, i.e. can be attached to `Framebuffer`s and written to from fragment shaders, and read from with `readPixels` etc. Note that the formats include `GL.RGBA32F`. [`EXT_color_buffer_float`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_color_buffer_float) |
| `texture-renderable-float16-webgl` | Half float format `Texture`s are renderable and readable[`EXT_color_buffer_half_float`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_color_buffer_half_float) |
| `float-blend-webgl1` | Blending with 32-bit floating point color buffers[`EXT_float_blend`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_float_blend) |
| [`WEBGL_depth_texture`][depth_url] |
| `epth_buffers` | Depth buffers can be stored in `Texture`s, e.g. for shadow map calculations |
| `TEXTURE_FILTER_LINEAR_FLOAT` | Linear texture filtering for floating point textures [`OES_texture_float_linear`](https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_float_linear) |
| `webgl-texture_filter_linear_half_float` | Linear texture filtering for half float textures [`OES_texture_half_float_linear`](https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_half_float_linear) |
| `webgl-texture_filter_anisotropic` | Anisotropic texture filtering [`EXT_texture_filter_anisotropic`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_texture_filter_anisotropic) |
| `depth_buffers` | Depth buffers can be stored in `Texture`s, e.g. for shadow map calculations [`WEBGL_depth_texture`][depth_url] |
| `texture-filter-linear-float` | Linear texture filtering for floating point textures [`OES_texture_float_linear`](https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_float_linear) |
| `webgl-texture-filter-linear-half-float` | Linear texture filtering for half float textures [`OES_texture_half_float_linear`](https://developer.mozilla.org/en-US/docs/Web/API/OES_texture_half_float_linear) |
| `webgl-texture_filter-anisotropic` | Anisotropic texture filtering [`EXT_texture_filter_anisotropic`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_texture_filter_anisotropic) |
| `texture-srgb-webgl` | sRGB encoded rendering is available [`EXT_sRGB`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_sRGB) |
| extensions\*\* | |
| \*\* GLSL extensions\*\* | |
| `webgl-shader_texture_lod` | Enables shader control of LOD [`EXT_shader_texture_lod`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_shader_texture_lod) |
| `webgl-fragment-shader-draw-buffers` | Fragment shader can draw to multiple render targets [`WEBGL_draw_buffers`](https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_draw_buffers) |
| `webgl-fragment-shader-depth` | Fragment shader can control fragment depth value [`EXT_frag_depth`](https://developer.mozilla.org/en-US/docs/Web/API/EXT_frag_depth) |
@ -128,3 +233,5 @@ A list of luma classes that can only be instantiated under WebGL 2:
- `Sync` -
The WebGL standard comes with an elaborate "extension" system allowing applications to check for the availability of features beyond the base WebGL 1 and WebGL 2 standards. These extensions tend to be rather technical, plus they have to be used differently in WebGL 1 and WebGL 2, so luma provides a simplified feature detection system. Following table lists all the available features, and their support under WebGL 1 and WebGL 2 , `NO` implies not supported, 'YES' implies supported and `*` implies supported through an extension.

116
docs/api-guide/device-properties.mdx → docs/api-reference/device-limits.mdx
View File

@ -1,104 +1,31 @@
import {
DeviceTabs,
Info,
Feature as F,
Limit as L,
WebGLLimit as WL,
WebGLExtensions
} from '@luma.gl/react-website';
# Device Properties
# Device Limits
> The tables on this page use luma.gl Device APIs to display the capabilities of your current browser.
> Open this page in different browsers to compare capabilities.
> Proposed luma.gl v9 API. Open for comments.
The luma.gl `Device` provides a range of fields and functions to help an application
determine the capabilities of the underlying platform and API.
The `device.limits` field contains limits object that indicates what the current platform supports.
## Fields
### Device.info
A `DeviceInfo` object with fields that describe the devices.
<DeviceTabs />
| Field | This Browser | Description |
| ---------- | --------------------- | ------------------------------------- |
| `type` | <Info f="type" /> | `webgpu`, `webgl2` or `webgl` |
| `gpu` | <Info f="gpu" /> | `intel`, `nvidia`, `amd` or `unknown` |
| `renderer` | <Info f="renderer" /> | GPU Driver |
| `vendor` | <Info f="vendor" /> | GPU vendor |
| `version` | <Info f="version" /> | Driver version |
### Device.features
luma.gl provides a unified feature detection system across WebGPU, WebGL and GLSL.
Each device has a `device.features` field that holds a set of strings (`Set<DeviceFeature>`).
A substantial set of features are devoted to texture capabilites, however these can also
be queried on a per-texture basis
```typescript
if (device.features.has('instanced-rendering-webgl1')) {
// Will work both on WebGL 1 (via extension) and WebGL 2 via the standard API
program.draw({instanceCount: ..., ....});
}
```
<DeviceTabs />
| `luma.gl Feature` | This<br /> Browser | Description |
| -------------------------------------- | ---------------------------------------------- | ------------------------------ |
| **Features** |
| `depth-clip-control` | <F f="depth-clip-control"/> | Depth clamps instead of clips. |
| `indirect-first-instance` | <F f="indirect-first-instance"/> | Specify via GPU buffer |
| `timestamp-query` | <F f="timestamp-query"/> | |
| `timer-query-webgl` | <F f="timer-query-webgl"/> | GPU timer support |
| `instanced-rendering-webgl1` | <F f="instanced-rendering-webgl1"/> | Instanced rendering available |
| `multiple-render-targets-webgl1` | <F f="multiple-render-targets-webgl1"/> | Multiple render targets |
| `index-uint32-webgl1` | <F f="index-uint32-webgl1"/> | 32 bit indexing supported |
| `blend-minmax-webgl1` | <F f="blend-minmax-webgl1"/> | `min` and `max` blending |
| **Textures** |
| `depth24unorm-stencil8` | <F f="depth24unorm-stencil8"/> | `UNSIGNED_INT_24_8_WEBGL` |
| `depth32float-stencil8` | <F f="depth32float-stencil8"/> | WebGPU only |
| `texture-filter-anisotropic-webgl` | <F f="texture-filter-anisotropic-webgl"/> | anisotropic filtering, common |
| `texture-filter-linear-float32-webgl` | <F f="texture-filter-linear-float32-webgl"/> | float32 `linear` filtering |
| `texture-filter-linear-float16-webgl` | <F f="texture-filter-linear-float16-webgl`" /> | float16 `linear` filtering |
| `texture-renderable-float32-webgl` | <F f="texture-renderable-float32-webgl"/> | float32 textures renderable |
| `texture-renderable-float16-webgl` | <F f="texture-renderable-float16-webgl"/> | float16 textures renderable |
| `texture-renderable-rgba32float-webgl` | <F f="texture-renderable-rgba32float-webgl"/> | float32 textures renderable |
| `texture-blend-float-webgl1` | <F f="texture-blend-float-webgl1"/> | float texture blending |
| `texture-formats-float32-webgl1` | <F f="texture-formats-float32-webgl1"/> | float32 texture support |
| `texture-formats-float16-webgl1` | <F f="texture-formats-float16-webgl1"/> | float16 texture support |
| `texture-formats-srgb-webgl1` | <F f="texture-formats-srgb-webgl1"/> | SRGB format support |
| `texture-formats-depth-webgl1` | <F f="texture-formats-depth-webgl1"/> | depth texture supports |
| **Compressed Textures** |
| `texture-compression-bc5-webgl` | <F f="texture-compression-bc5-webgl"/> | DXT (BC1-BC5). Desktops. |
| `texture-compression-bc` | <F f="texture-compression-bc"/> | DXT (BC1-BC7). Desktops. |
| `texture-compression-etc2` | <F f="texture-compression-etc2"/> | Performance caveats. |
| `texture-compression-astc` | <F f="texture-compression-astc"/> | ASTC. |
| `texture-compression-etc1-webgl` | <F f="texture-compression-etc1-webgl"/> | Qualcomm Snapdragon. Android. |
| `texture-compression-pvrtc-webgl` | <F f="texture-compression-pvrtc-webgl"/> | PowerVR GPUs, iOS devices. |
| `texture-compression-atc-webgl` | <F f="texture-compression-atc-webgl"/> | Qualcomm Adreno GPUs. Android. |
| **GLSL** |
| `glsl-frag-data` | <F f="glsl-frag-data"/> | |
| `glsl-frag-depth` | <F f="glsl-frag-depth"/> | |
| `glsl-derivatives` | <F f="glsl-derivatives"/> | |
| `glsl-texture-lod` | <F f="glsl-texture-lod"/> | |
### Device.limits
The `limits` object contains a "WebGPU style" limits object.
## Usage
```typescript
import type {DeviceLimits} from '@luma.gl/api';
import {Device} from '@luma.gl/api';
console.log(device.info);
if (device.limits.maxTextureDimension2D > 2048) {
const limits: DeviceLimits = device.limits;
console.log(limits);
if (limits.maxTextureDimension2D > 2048) {
...
}
```
## DeviceLimits
<DeviceTabs />
| Limit | Value | Comments |
@ -135,26 +62,6 @@ if (device.limits.maxTextureDimension2D > 2048) {
If you know that you are running on WebGL, you don't need to go through
the luma.gl Device APIs. You can access "raw" WebGL extensions and limits directly.
### WebGL extensions
It is easy to get the list of actual WebGL extensions from `WebGLDevice`:
```typescript
const webglDevice = device instanceof WebGLDevice ? (device as WebGLDevice) : null;
const extensions = webglDevice ? webglDevice.gl.getSupportedExtensions() : [];
console.log(extensions);
```
On your current browser, this would yield:
<DeviceTabs />
<WebGLExtensions />
> Caveat: WebGL extensions can be onerous to work with directly. They are very granular,
> and WebGL1 extensions are not listed as supported on WebGL2 contexts even though the
> corresponding features are supported.
### Device.webglLimits
A luma.gl `WebGLDevice` extracts an object that contains all "raw" WebGL limits.
@ -226,3 +133,4 @@ console.log(webglDevice ? webglDevice.webglLimits[GL.MAX_VERTEX_ATTRIBS]);
- Naturally, given that queries to driver and GPU are typically expensive in WebGL, the capabilities system will cache any queries.
['ext_texture_filter_anisotropic']: https://developer.mozilla.org/en-US/docs/Web/API/EXT_texture_filter_anisotropic

268
docs/api-reference/device.md Normal file
View File

@ -0,0 +1,268 @@
# Device
> This is the proposed new luma.gl v9 API, which is currently open for comments. It is available for testing using luma.gl v9 alpha releases.
The `Device` class manages the application's connection with the GPU,
providing methods to:
- create GPU resources
- query the capabilities of the GPU
- detect error conditions.
A `Device` is created through static `Device.create(...)` method.
Note that the actual `Device` returned by `Device.create()` will be either
a `WebGLDevice` wrapping a WebGL context or a `WebGPUDevice` wrapping a WebGPU device
based on what the run-time environment (ie. browser or Node.js) supports.
## Usage
Create a WebGL2 or WebGL context, auto creating a canvas
```typescript
import {Device} from '@luma.gl/api';
const device = new Device(); // Prefers WebGL 2 but falls back to WebGL 1
```
Create a WebGL 2 context (throws if WebGL2 not supported)
```typescript
import {Device} from '@luma.gl/api';
const device = createGLContext({
webgl1: false
});
```
Attaching a Device to an externally created WebGLRendering context instruments it
so that it works with other luma.gl classes.
```typescript
import {Device} from '@luma.gl/api';
import {Model} from '@luma.gl/engine';
const device = Device.attach(gl); // "instruments" the external context
// Instrumentation ensures the context works with higher-level classes.
const model = new Model(gl, options);
```
Attaching a device to a WebGL1 context adds WebGL2 "polyfills" to the WebGLRendering context
extends that context with a subset of WebGL2 APIs that are available via WebGL extensions.
```typescript
const gl = canvas.createContext('webgl'); // A WebGL 1 context
const device = Device.attach(gl);
// Can now use a subset of WebGL2 APIs on
const vao = device.gl.createVertexArray();
```
Handle GPU disconnections:
```typescript
if (!device.isLost) {
...
}
const {message} = await device.lost;
console.error(message);
```
## Types
### `DeviceProps`
| Parameter | Default | Description |
| ------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type` | `'best-available'` | `'webgpu`', `'webgl'`, `'webgl1'`, `'webgl2'` |
| `canvas` | N/A | A _string_ `id` of an existing HTML element or a _DOMElement_. If not provided, a new canvas will be created. |
| priority. |
| `debug?: boolean` | `false` | WebGL API calls will be logged to the console and WebGL errors will generate JavaScript exceptions. **NOTE:** requires importing [@luma.gl/debug](/docs/api-reference/debug). |
| `break?: string[]` | `[]` | Insert a break point (`debugger`) if one of the listed gl functions is called. |
| `alpha?: boolean` | `true` | Default render target has an alpha buffer. |
| `depth?: boolean` | `true` | Default render target has a depth buffer of at least `16` bits. |
| `stencil?` | `false` | Default render target has a stencil buffer of at least `8` bits. |
| `antialias?` | `true` | Boolean that indicates whether or not to perform anti-aliasing. |
| `premultipliedAlpha?` | `true` | Boolean that indicates that the page compositor will assume the drawing buffer contains colors with pre-multiplied alpha. |
| `preserveDrawingBuffer?` | `false` | Default render target buffers will not be automatically cleared and will preserve their values until cleared or overwritten |
| `failIfMajorPerformanceCaveat?` | `false` | Do not create if the system performance is low. |
## Static Methods
###` Device.create(props: DeviceProps): Promise<Device>`
Creating device is done with the static `Device.create()` method.
Creates and returns a WebGL context, both in browsers and in Node.js.
```typescript
const device = await Device.create(props);
```
- `props` (_Object_) - key/value pairs containing context creation options
## Fields
### `readonly id: string`
A string identifier, for debug purposes.
### `readonly statsManager: StatsManager`
Provides access to bags of stats containing information about resource usage and performance of the device.
### `readonly props: Required<DeviceProps>`
A readonly copy of the props that were used to create this device.
### `userData: Record<string, any>`
Reserved for the application.
### info: DeviceInfo
Information about the device (vendor, versions etc).
Get debug information about the device
| Field | Type | Description |
| ------------------------ | -------- | --------------------------------- |
| `vendor` | `string` | GPU vendor (unmasked if possible) |
| `renderer` | `string` | Renderer (unmasked if possible) |
| `version` | `string` | WebGL version |
| `shadingLanguageVersion` | `string` | shading language version |
Remarks:
- WebGPU Devices currently do not provide much information due to limitations in the WebGPU API.
- WebGL Devices can usually provide the full set of information (through the `WEBGL_debug_renderer_info` extension).
## Functions
### constructor
`Device` is an abstract class and the constructor can not be called directly.
Use the static `Device.create()` method to create classes.
### `features: Set<DeviceFeature>`
Determine whether the device implements an optional features by checking `device.features.has(...)`.
### `limits: DeviceLimits`
An object with various device limits. WebGPU style.
### `isTextureFormatSupported(format: TextureFormat): boolean`
Check if device supports a specific texture format (creation and `nearest` sampling).
### `isTextureFormatFilterable(format: TextureFormat): boolean`
Check if linear filtering (sampler interpolation) is supported for a specific texture format.
### `isTextureFormatRenderable(format: TextureFormat): boolean`
Check if device supports rendering to a specific texture format.
### `isLost: boolean`
True if the device is already lost (GPU is disconnected).
### `lost: Promise<{reason: 'destroyed', message: string}>`
Promise that resolves with an error message if the device is lost (GPU is disconnected).
GPU disconnections normally happen when the computer goes to sleep but it can also happen
when too many applications use the GPU, too many `Device` instances are created etc.
### `canvasContext: CanvasContext`
Returns the default [`CanvasContext`](./canvas-context).
Note that a WebGPU `Device` may not have a canvas context.
### `createCanvasContext(props?: CanvasContextProps): CanvasContext`
> WebGPU only. (WebGL devices can only render to the single canvas they were created for.)
Creates a new [`CanvasContext`](./canvas-context).
### `submit(): void`
Call after rendering a frame is complete.
### `createBuffer(props: BufferProps): Buffer`
### `createBuffer(data: ArrayBuffer | ArrayBufferView): Buffer`
Create a buffer,
Deduces `indexType` if usage.
### `createTexture(props: TextureProps): Texture`
### `createTexture(data: Promise<TextureData>): Texture`
### `createTexture(url: string): Texture`
Create a [`Texture`](./resources/sampler).
### `createSampler(props: SamplerProps): Sampler`
Create a [`Sampler`](./resources/sampler).
### `createFramebuffer(props: FramebufferProps): Framebuffer`
Create a [`Framebuffer`](./resources/framebuffer).
### `createShader(props: ShaderProps): Shader`
Create a [`Shader`](./resources/shader).
### `createRenderPipeline(props: RenderPipelineProps): RenderPipeline`
Create a [`RenderPipeline`](./resources/render-pipeline) (aka program)
### `createComputePipeline(props: ComputePipelineProps): ComputePipeline`
Create a [`ComputePipeline`](./resources/compute-pipeline) (aka program)
### `beginRenderPass(props: RenderPassProps): RenderPass`
Create a [`RenderPass`](./resources/render-pass).
### `beginComputePass(props?: ComputePassProps): ComputePass`
Create a [`ComputePass`](./resources/compute-pass) which can be used to bind data and run compute operations using compute pipelines.
### `getDefaultRenderPass(): RenderPass`
A default `RenderPass` is provided for applications that don't need to create
multiple or specially configured render passes.
Note that a new default `RenderPass` is returned every animation frame.
## Remarks
- Note that the actual `Device` returned by `Device.create()` will be either
a `WebGLDevice` wrapping a WebGL context or a `WebGPUDevice` wrapping a WebGPU device
based on what the run-time environment (ie. browser or Node.js) supports.
- The `Device` API is intentionally similar, but not identical, to the [WebGPU `GPUDevice`](https://www.w3.org/TR/webgpu/#gpu-device) class API.
## WebGL specifics
### isWebGL: boolean
True if the is a WebGL context. Both WebGL 1 and WebGL 2 contexts will be
`device.isWebGL`
Returns true if the context is a WebGL 1 or 2 Context.
### isWebGL2: boolean
Test if an object is a WebGL context.
`device.isWebGL2`
Returns true if the context is a WebGL 2 Context.

105
docs/api-reference/engine/model.md
View File

@ -1,8 +1,10 @@
# Model
`Model` is the primary class in luma.gl.
> Proposed luma.gl v9 API. Open for comments.
A `Model` holds all the data necessary to perform draw calls:
The `Model` is the primary class for most luma.gl applications.
A `Model` brings together a range of different luma.gl functions in one class. It holds all the data necessary to perform draw calls:
- **shaders** (via a [`Program`](/docs/api-reference/webgl/program) instance)
- **bindings** these can reference uniforms and textures.
@ -24,7 +26,7 @@ Create model object by passing shaders, uniforms, geometry and render it by pass
```typescript
// construct the model.
const model = new Model(gl, {
const model = new Model(device, {
vs: VERTEX_SHADER,
fs: FRAGMENT_SHADER,
uniforms: {uSampler: texture},
@ -46,23 +48,23 @@ When using `Buffer` objects, data remains on GPU and same `Buffer` object can be
```typescript
// construct the model.
const model = new Model(gl, {
const model = new Model(device, {
vs: VERTEX_SHADER,
fs: FRAGMENT_SHADER,
uniforms: {uSampler: texture},
topology: 'triangle-list',
vertexCount: 3,
attributes: {
attributeName1: bufferObject,
attributeName2: [new Buffer(gl, new Float32Array(...)), {size: 3, type: GL.FLOAT}]
}
drawMode: gl.TRIANGLE_FAN,
vertexCount: 3,
attributeName2: device.createBuffer(new Float32Array(...))
},
uniforms: {uSampler: texture},
})
// and on each frame update any uniforms (typically matrices) and call render.
model
.setUniforms({
uPMatrix: currentProjectionMatrix,
uMVMatrix: current ModelViewMatrix
uMVMatrix: currentModelViewMatrix
})
.draw();
```
@ -73,7 +75,7 @@ A `VertexArray` object can be build and passed to `Model.draw()` to provide attr
```typescript
// construct the model.
const model = new Model(gl, {
const model = new Model(device, {
vs: VERTEX_SHADER,
fs: FRAGMENT_SHADER,
uniforms: {uSampler: texture},
@ -83,13 +85,13 @@ const model = new Model(gl, {
const ATTRIBUTE1_LOCATION = 0;
const ATTRIBUTE2_LOCATION = 1;
const vertexArray1 = new VertexArray(gl, {
const vertexArray1 = device.createVertexArray({
buffers: {
[ATTRIBUTE1_LOCATION]: buffer1,
[ATTRIBUTE2_LOCATION]: buffer2
}
});
const vertexArray2 = new VertexArray(gl, {
const vertexArray2 = device.createVertexArray({
buffers: {
[ATTRIBUTE1_LOCATION]: buffer3,
[ATTRIBUTE2_LOCATION]: buffer4
@ -106,13 +108,12 @@ model.draw({
});
// Switch attribute data to vertexArray2
model.draw({
uniforms: {
uPMatrix: currentProjectionMatrix,
uMVMatrix: currentModelViewMatrix
},
vertexArray: vertexArray2
});
model.setUniforms({
uPMatrix: currentProjectionMatrix,
uMVMatrix: currentModelViewMatrix
})
model.setVertexArray(vertexArray2);
model.draw({...});
```
## Properties
@ -150,22 +151,16 @@ function to be called before every time this model is drawn.
function to be called after every time this model is drawn.
## Constructor
## Methods
### Model(gl: WebGLRenderingContext, props: object)
### Model(device: Device, props: ModelProps)
The constructor for the Model class. Use this to create a new Model.
### delete()
### destroy()
Free WebGL resources associated with this model
## Methods
### setProps(props: object); this
Updates properties
### isAnimated(): boolean
Returns `true` if the model is animated (i.e. needs to be redrawn every frame).
@ -232,55 +227,3 @@ model.transform({
discard: false
});
```
### clear(options: object); this
## Deprecated Methods in v7
### render(options: object): boolean
Use Model.setUniforms() and Model.draw()
### getDrawMode(): Enum
Gets the WebGL drawMode
### getVertexCount(): GLInt
Gets vertex count
Note: might be autocalculated from `Geometry`
### getInstanceCount(): GLInt
Defaults to 0
### getAttributes(): object
Get a map of named attributes
### setDrawMode(); this
Sets the WebGL `drawMode`.
`GL.POINTS` etc.
### setVertexCount(); this
Sets the number of vertices
### setInstanceCount(); this
How many instances will be rendered
### setGeometry(); this
Use a `Geometry` instance to define attribute buffers
### setAttributes(attributes: object); this
Sets map of attributes (passes through to [VertexArray.setAttributes](/docs/api-reference/webgl/vertex-array))
## Remarks
- The `Model` class is arguably the most useful class for typical applications. It manages the WebGL resources needed to perform draw calls and provide additional functionality as described below.

51
docs/api-reference/resources/buffer.md
View File

@ -1,3 +1,52 @@
# Buffer
> TBA
> Proposed luma.gl v9 API. Open for comments.
Holds a block of GPU memory. The length of a buffer cannot be changed after creation.
## Types
### `BufferProps`
| Property | Type | Description |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| `usage?` | `number` | Bit mask of Usage flags |
| `byteLength?` | `number` | Length of buffer (cannot be changed after creation). |
| `data?` | `ArrayBuffer \| ArrayBufferView` | Data to be copied into buffer. `byteLength` will be deduced if not supplied. |
| `byteOffset?` | `number` | Offset for `data` |
| `indexType?` | `'uint16' \| 'uint32'` | If props.usage & Buffer.INDEX |
### Usage
Usage expresses two things: The type of buffer and what operations can be performed on it.
Note that the allowed combinations are very limited, especially in WebGPU.
| Usage Flag | Value | Description |
| ---------------------- | ------ | -------------------------------------------------------- |
| `Buffer.INDEX` | 0x0010 | An index buffer (array of 16 or 32 bit unsigned integers |
| `Buffer.VERTEX` | 0x0020 | A vertex buffer (a binary column) |
| `Buffer.UNIFORM` | 0x0040 | A uniform buffer |
| `Buffer.STORAGE` | 0x0080 | A storage buffer |
| `Buffer.INDIRECT` | 0x0100 |
| `Buffer.QUERY_RESOLVE` | 0x0200 |
| `Buffer.MAP_READ` | 0x01 | Whether the buffer can be mapped for read |
| `Buffer.MAP_WRITE` | 0x02 | Whether the buffer can be mapped for write |
| `Buffer.COPY_SRC` | 0x0004 | Supports `commandEncoder.copyBufferTo...` |
| `Buffer.COPY_DST` | 0x0008 | Supports `commandEncoder.copy...ToBuffer` |
## Members
- `device`: `Device` - holds a reference to the `Device` that created this `Buffer`.
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `BufferProps` - holds a copy of the `BufferProps` used to create this `Buffer`.
## Methods
### `constructor(props: BufferProps)`
`Buffer` is an abstract class and cannot be instantiated directly. Create with `device.createBuffer(...)`.
### `destroy(): void`
Free up any GPU resources associated with this buffer immediately (instead of waiting for garbage collection).

0
docs/api-reference/resources/command-encoder.md Normal file
View File

42
docs/api-reference/resources/compute-pass.md Normal file
View File

@ -0,0 +1,42 @@
# ComputePass
> Proposed luma.gl v9 API. Open for comments.
A configuration for compute.
## Types
### `BufferProps`
| Property | Type | Description |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| `parameters?` | `Parameters` | GPU pipeline parameters |
## Members
- `device`: `Device` - holds a reference to the `Device` that created this `ComputePass`.
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `ComputePassProps` - holds a copy of the `ComputePassProps` used to create this `ComputePass`.
## Methods
### `constructor(props: ComputePassProps)`
`ComputePass` is an abstract class and cannot be instantiated directly. Create with `device.beginComputePass(...)`.
### `endPass(): void`
Free up any GPU resources associated with this render pass.
### `pushDebugGroup(groupLabel: string): void`
Adds a debug group (implementation dependent).
### `popDebugGroup(): void`
Removes a debug group (implementation dependent).
### `insertDebugMarker(markerLabel: string): void`
Adds a debug marker (implementation dependent).

22
docs/api-reference/resources/compute-pipeline.md
View File

@ -1,4 +1,24 @@
# ComputePipeline
> Proposed luma.gl v9 API. Open for comments.
> `ComputePipeline` is only available on WebGPU. Note that you can still perform
> GPU computations using `RenderPipeline`.
> many GPU computations on WebGL using `RenderPipeline`.
A `ComputePipeline` holds a compiled and linked compute shader.
## Members
- `device`: `Device` - holds a reference to the device that created this resource
- `handle`: `unknown` - holds the underlying WebGL or WebGPU object
- `props`: `ComputePipelineProps` - holds a copy of the `ComputePipelineProps` used to create this `ComputePipeline`.
## Methods
### `constructor(props: ComputePipelineProps)`
`ComputePipeline` is an abstract class and cannot be instantiated directly. Create with `device.createComputePipeline(...)`.
### `destroy(): void`
Free up any GPU resources associated with this compute pipeline immediately (instead of waiting for garbage collection).

271
docs/api-reference/resources/framebuffer.md
View File

@ -1,44 +1,15 @@
# Framebuffer
A `Framebuffer` is a container object that holds one or more textures
that will be used as render targets and optionally a depth / stencil buffer
for the GPU pipeline.
> Proposed luma.gl v9 API. Open for comments.
An application can render into an (HTML or offscreen) canvas by obtaining a
`Framebuffer` object from a `DeviceContext`.
A `Framebuffer` holds textures that will be used as render targets for `RenderPipeline`s:
- one or more color textures
- optionally a depth / stencil buffer
Alternatively an application can create custom framebuffers for rendering directly into textures.
A `Framebuffer` is "shallowly immutable": the list of attachments cannot be changed after creation,
however a Framebuffer can be "resized" causing the attachments to be resized.
The application uses a `Framebuffer` by providing it as a parameter to a `RenderPass`.
## Framebuffer Attachments
A `Framebuffer` holds:
- a list of `Texture` attachments that store data (one or more color `Texture`s)
- plus an optional depth, stencil or combined depth-stencil `Texture`).
Attachments must be in the form of `Texture`s.
## Resizing Framebuffers
A `Framebuffer` is shallowly immutable (the list of attachments cannot be changed after creation),
however a Framebuffer can be "resized". Resizing a framebuffer effectively destroys all current textures
and creates new textures with otherwise similar properties. All data stored in the textures are lost.
This data loss is usually a non-issue as resizes would be performed between render passes,
typically to match the size of an off screen render buffer with the output canvas.
To render into a canvas, a "device context" `Framebuffer` should be obtained from a `DeviceContext`.
A device context `Framebuffer` and has a (single) special color attachment that is connected to the
current swap chain buffer. It updates every frame, and also automatically resizes based on the size of the connected canvas
and should not be manually resized.
Remarks:
- WebGPU: The `Framebuffer` concept does not exist natively in WebGPU (this information has to be provided through the `GPURenderPassDescriptor` `colorAttachments` and the `depthStencilAttachment` fields every frame when a render pass is created).`.
- WebGL: A native `WebGLFramebuffer` object exists that manages a set of attachments.
- OpenGL Wiki [Framebuffer](https://www.khronos.org/opengl/wiki/Framebuffer)
- OpenGL Wiki [Framebuffer Object](https://www.khronos.org/opengl/wiki/Framebuffer_Object).
The use of framebuffers is described in detail in the [Rendering Guide](../../api-guide/rendering)/
## Usage
@ -48,226 +19,80 @@ Creating a framebuffer with default color and depth attachments
const framebuffer = device.createFramebuffer({
width: window.innerWidth,
height: window.innerHeight,
color: true,
depthStencil: true
colorAttachments: ['rgb8unorm'],
depthStencilAttachment: 'depth24unorm-stencil8'
});
```
Attaching textures and renderbuffers
Resizing a framebuffer to the size of a window by resizing all attachments.
```typescript
device.createFramebuffer({
depthStencil: new Renderbuffer(gl, {...}),
color0: new Texture(gl, {...}),
color1: [new TextureCube(gl, {...}), GL.TEXTURE_CUBE_MAP_POSITIVE_X],
color2: [new TextureArray2D(gl, {...}), 0],
color3: [new TextureArray2D(gl, {...}), 1],
color4: [new Texture3D(gl, {..., depth: 8}), 2]
});
framebuffer.checkStatus(); // optional
```
Resizing a framebuffer to the size of a window. Resizes all attachements with a single `framebuffer.resize()` call
```typescript
// Note: this resizes (and possibly clears) all attachments
framebuffer.resize({width: window.innerWidth, height: window.innerHeight});
```
Clearing a framebuffer
```typescript
framebuffer.clear();
framebuffer.clear({color: [0, 0, 0, 0], depth: 1, stencil: 0});
framebuffer.resize(window.innerWidth, window.innerHeight);
```
Specifying a framebuffer for rendering in each render calls
```typescript
const offScreenBuffer = new Framebuffer();
program1.draw({
framebuffer: offScreenBuffer,
parameters: {}
});
model.draw({
framebuffer: null, // the default drawing buffer
parameters: {}
});
const offScreenBuffer = device.createFramebuffer(...);
const offScreenRenderPass = device.beginRenderPass({framebuffer: offScreenFramebuffer});
model1.draw({renderPass: offScreenRenderPass});
offScreenRenderPass.endPass();
const screenRenderPass = device.getDefaultRenderPass();
model2.draw({renderPass: screenRenderPass});
```
Binding a framebuffer for multiple render calls
## Types
```typescript
const framebuffer1 = device.createFramebuffer({...});
const framebuffer2 = device.createFramebuffer({...});
### `FramebufferProps`
const renderPass1 = device.createRenderPass({framebuffer: framebuffer1});
program.draw(renderPass1);
renderPass1.endPass();
| Property | Type | Description |
| ------------------------- | -------------------------- | ------------------------------------ |
| `id?` | `string` | An optional name (id) of the buffer. |
| `width? = 1` | `number` | The width of the framebuffer. |
| `height? = 1` | `number` | The height of the framebuffer. |
| `colorAttachments` | `TextureFormat\|Texture[]` | Array of render target textures. |
| `depthStencilAttachment?` | `TextureFormat\|Texture[]` | Depth/stencil texture. |
const renderPass2 = device.createRenderPass({framebuffer: framebuffer1});
program.draw(renderPass2);
renderPass2.endPass();
## Members
```
### Reading, copying or blitting data from a Framebuffer attachment.
- For reading data into CPU memory check [`readPixelsToArray`](/docs/api-reference/webgl/moving-data)
- For reading into a Buffer object (GPU memory), doesn't result in CPU and GPU sync, check [`readPixelsToBuffer`](/docs/api-reference/webgl/moving-data)
- For reading into a Texture object (GPU memory), doesn't result in CPU and GPU sync, check [`copyToTexture`](/docs/api-reference/webgl/moving-data)
- For blitting between framebuffers (WebGL 2), check [`blit`](/docs/api-reference/webgl/moving-data)
### Using Multiple Render Targets
Specify which framebuffer attachments the fragment shader will be writing to when assigning to `gl_FragData[]`
```typescript
framebuffer.update({
drawBuffers: [
GL.COLOR_ATTACHMENT0, // gl_FragData[0]
GL.COLOR_ATTACHMENT1, // gl_FragData[1]
GL.COLOR_ATTACHMENT2, // gl_FragData[2]
GL.COLOR_ATTACHMENT3 // gl_FragData[3]
]
});
```
Writing to multiple framebuffer attachments in GLSL fragment shader
```
#extension GL_EXT_draw_buffers : require
precision highp float;
void main(void) {
gl_FragData[0] = vec4(0.25);
gl_FragData[1] = vec4(0.5);
gl_FragData[2] = vec4(0.75);
gl_FragData[3] = vec4(1.0);
}
```
Clearing a specific draw buffer in a framebuffer (WebGL 2)
```typescript
framebuffer.clear({
[GL.COLOR]: [0, 0, 1, 1], // Blue
[GL.COLOR]: new Float32Array([0, 0, 0, 0]), // Black/transparent
[GL.DEPTH_BUFFER]: 1, // Infinity
[GL.STENCIL_BUFFER]: 0 // no stencil
});
framebuffer.clear({
[GL.DEPTH_STENCIL_BUFFER]: [1, 0] // Infinity, no stencil
});
```
## Limits
- `GL.MAX_COLOR_ATTACHMENTS` - The maximum number of color attachments supported. Can be `0` in WebGL 1.
- `GL.MAX_DRAW_BUFFERS` - The maximum number of draw buffers supported. Can be `0` in WebGL 1, which means that `gl_FragData[]` is not available in shaders.
It is possible that you can have a certain number of attachments, but you can't draw to all of them at the same time.
- `device`: `Device` - holds a reference to the `Device` that created this `Framebuffer`.
- `handle`: `unknown` - WebGL: holds the underlying `WebGLFramebuffer`. No underlying object on WebGPU.
- `props`: `BufferProps` - holds a copy of the `BufferProps` used to create this `Buffer`.
## Methods
### constructor
A `Framebuffer` is created via `device.createFramebuffer(props: FramebufferProps)`.
`Framebuffer` is an abstract class and cannot be instantiated directly. Create with `device.createFramebuffer(props: FramebufferProps)`.
Creates a new framebuffer, optionally creating and attaching `Texture` attachments.
An application can render into an (HTML or offscreen) canvas by obtaining a
`Framebuffer` object from a `CanvasContext` using `canvasContext.getDefaultFramebuffer()`. Alternatively can create texture based framebuffers for off-screen rendering.
```
device.createFramebuffer(gl, {
id,
width,
height,
attachments,
color,
depth,
stencil
})
```
### destroy(): void
- `id`= - (_String_) - An optional name (id) of the buffer.
- `width`=`1` - (_number_) The width of the framebuffer.
- `height`=`1` - (_number_) The height of the framebuffer.
- `colorAttachments`=[] - (_Object_, optional) - a map of Textures and/or Renderbuffers, keyed be "attachment points" (see below).
- `depthStencilAttachment?`
- `color` - shortcut to the attachment in `GL.COLOR_ATTACHMENT0`
- `depth` - shortcut to the attachment in `GL.DEPTH_ATTACHMENT`
- `stencil` - shortcut to the attachment in `GL.STENCIL_ATTACHMENT`
Free up any GPU resources associated with this buffer immediately (instead of waiting for garbage collection).
The luma.gl `Framebuffer` constructor enables the creation of a framebuffer with all the proper attachments in a single step and also the `resize` method makes it easy to efficiently resize a all the attachments of a `Framebuffer` with a single method.
TBD - When destroying `Framebuffer` will also destroy any `Texture` that was created automatically during Framebuffer creation. Supplied textures will not be destroyed (but will eventually be garbage collected and destroyed).
When no attachments are provided during `Framebuffer` object creation, new resources are created and used as default attachments for enabled targets (color and depth).
For color, new `Texture2D` object is created with no mipmaps and following filtering parameters are set.
### resize(width: number, height: number): void
| Texture parameter | Value |
| ----------------- | --------------- |
| `minFilter` | `linear` |
| `magFilter` | `linear` |
| `addressModeU` | `clamp-to-edge` |
| `addressModeV` | `clamp-to-edge` |
### destroy()
Destroys the underlying GPU object. When destroying `Framebuffer` will also destroy any `Texture` that was created automatically during Framebuffer creation. Supplied textures will not be destroyed (but will eventually be garbage collected and destroyed).
### resize(width: number, height: number): Framebuffer
`Framebuffer.resize({width, height})`
`Framebuffer.resize(width, height)`
Resizes all the `Framebuffer`'s current attachments to the new `width` and `height` by calling `resize` on those attachments.
- `width` (GLint) - width of `Framebuffer` in pixels
- `height` (GLint) - height of `Framebuffer` in pixels
- `width` - the new width of `Framebuffer` in pixels
- `height` - the new height of `Framebuffer` in pixels
Returns itself to enable chaining
- Each attachment's `resize` method checks if `width` or `height` have actually changed before reinitializing their data store, so calling `resize` multiple times with the same `width` and `height` does not trigger multiple resizes.
- If a resize happens, `resize` erases the current content of the attachment in question.
### clear(options: Object): Framebuffer
Clears the contents (pixels) of the framebuffer attachments.
- `options.color` (Boolean or Array) - clears all active color buffers (any selected `drawBuffer`s) with either the provided color or the default color.
- `options.depth`
- `options.stencil`
- `options.drawBuffers`=`[]` - An array of color values, with indices matching the buffers selected by `drawBuffers` argument.
Notes:
- The scissor box bounds the cleared region.
- The pixel ownership test, the scissor test, dithering, and the buffer writemasks affect the operation of `clear`.
- Alpha function, blend function, logical operation, stenciling, texture mapping, and depth-buffering are ignored by `clear`.
### Framebuffer Attachment Values
The following values can be provided for each attachment point
- `Texture` - attaches at mipmapLevel 0 of the supplied `Texture2D`.
- [`Texture`, 0, mipmapLevel] - attaches the specified mipmapLevel from the supplied `Texture2D` (WebGL 2), or cubemap face. The second element in the array must be `0`. In WebGL 1, mipmapLevel must be 0.
- [`Texture` (cube), face (number), mipmapLevel=0 (number)] - attaches the specifed cubemap face from the `Texture`, at the specified mipmap level. In WebGL 1, mipmapLevel must be 0.
- [`Texture`, layer (number), mipmapLevel=0 (number)] - attaches the specifed layer from the `Texture2DArray`, at the specified mipmap level.
- [`Texture3D`, layer (number), mipmapLevel=0 (number)] - attaches the specifed layer from the `Texture3D`, at the specified mipmap level.
Note the `framebuffer.resize()` method has been designed so that it can be called every frame without performance concerns. While the actual resizing of attachments can be expensive, the `resize()` methods checks if `width` or `height` have changed before actually resizing any attachments.
## Remarks
- In the raw WebGL API, creating a set of properly configured and matching textures and renderbuffers can require a lot of careful coding and boilerplate.
- This is further complicated by many capabilities (such as support for multiple color buffers and various image formats) depending on WebGL extensions or WebGL versions.
### WebGL Notes:
This class makes calls to the following WebGL APIs:
[`gl.framebufferRenderbuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/framebufferRenderbuffer),
[`gl.bindFramebuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bindFramebuffer),
[`gl.framebufferTexture2D`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/framebufferTexture2D),
[`gl.bindFramebuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bindFramebuffer),
[`gl.framebufferTextureLayer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/framebufferTextureLayer),
[`gl.bindFramebuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bindFramebuffer) (This is for WebGL 2 only)
[`gl.checkFramebufferStatus`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/checkFramebufferStatus), [`gl.bindFramebuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bindFramebuffer)
[`gl.invalidateFramebuffer`](<WebGL2RenderingContext.invalidateFramebuffer()>), [`gl.invalidateSubFramebuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/invalidateSubFramebuffer), [`gl.bindFramebuffer`](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bindFramebuffer)
For depth, new `Renderbuffer` object is created with `GL.DEPTH_COMPONENT16` format.
- WebGPU: `resize()` will destroy and recreate textures (meaning the the underlying `GPUTexture` / `GPUTextureView` handles are no longer the same after a `resize()`
- WebGL: `resize()` will erase the current content of any attachments, but not actually create them (The underlying`WebGLTexture` / `WebGLRenderbuffer` handles are not changed).
- WebGPU: The `Framebuffer` class is a pure luma.gl class as this concept does not exist natively in WebGPU (attachment information has to be provided through the `GPURenderPassDescriptor` `colorAttachments` and the `depthStencilAttachment` fields every frame when a render pass is created).`.
- WebGL: The `Framebuffer` class wraps the `WebGLFramebuffer` object exists, see e.g. [Framebuffer](https://www.khronos.org/opengl/wiki/Framebuffer)
and [Framebuffer Object](https://www.khronos.org/opengl/wiki/Framebuffer_Object) in the OpenGL Wiki.

198
docs/api-reference/resources/pipeline.md
View File

@ -1,198 +0,0 @@
# RenderPipeline
A `RenderPipeline` contains a matched pair of vertex and fragment [shaders](/docs/api-reference/webgl/shader) that can be exectued on the GPU by calling `RenderPipeline.draw()`. Programs handle compilation and linking of shaders, and store uniform values. They provide `draw` call which allows the application to run the shaders on specified input data.
## Usage
Creating a pipeline
```js
const pipeline = device.createRenderPipeline({
id: 'my-pipeline',
vs: vertexShaderSourceString,
fs: fragmentShaderSourceString
});
```
Set or update uniforms, in this case world and projection matrices
```js
pipeline.setUniforms({
uMVMatrix: view,
uPMatrix: projection
});
```
Create a `VertexArray` to store buffer values for the vertices of a triangle and drawing
```js
const pipeline = device.createRenderPipeline({vs, fs});
const vertexArray = new VertexArray(gl, {pipeline});
vertexArray.setAttributes({
aVertexPosition: new Buffer(gl, {data: new Float32Array([0, 1, 0, -1, -1, 0, 1, -1, 0])})
});
pipeline.draw({vertexArray, ...});
```
Creating a pipeline for transform feedback, specifying which varyings to use
```js
const pipeline = device.createRenderPipeline({vs, fs, varyings: ['gl_Position']});
```
## Members
- `gl` : `WebGLRenderingContext`
- `handle` : `WebGLProgram` - The WebGL `WebGLProgram` instance.
- `id` : `String` - `id` string for debugging.
## Constructor
### RenderPipeline(gl : WebGLRenderingContext, props : Object)
Creates a new pipeline using the supplied vertex and fragment shaders. The shaders are compiled into WebGLShaders and is created and the shaders are linked.
```js
const pipeline = device.createRenderPipeline({
id: 'my-identifier',
vs: vertexShaderSource,
fs: fragmentShaderSource,
varyings: ['gl_Position', 'vColor']
});
```
- `id` (`string`, optional) - string id (to help indentify the pipeline during debugging).
- `vs` (`VertexShader`|`String`) - A vertex shader object, or source as a string.
- `fs` (`FragmentShader`|`String`) - A fragment shader object, or source as a string.
- `varyings` WebGL 2 (`String[]`) - a list of names of varyings.
- `bufferMode`=`GL.SEPARATE_ATTRIBS` WebGL 2 (`GLenum`) - Optional, specifies how transform feedback should store the varyings.
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | Description |
| ----------------------------------- | ---------------------------- |
| `GL.SEPARATE_ATTRIBS` | One varying per buffer |
| `GL.INTERLEAVED_ATTRIBS` | Multiple varyings per buffer |
WebGL References [WebGLProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram), [gl.createProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/createProgram)
### delete() : RenderPipeline
Deletes resources held by pipeline. Note: Does not currently delete shaders (to enable shader caching).
## Methods
### initialize(props : Object) : RenderPipeline
Relinks a pipeline. Takes the same options as the constructor
### setUniforms(uniforms : Object) : RenderPipeline
Sets named uniforms from a map, ignoring names
- `key` (_String_) - The name of the uniform to be set. The name of the uniform will be matched with the name of the uniform declared in the shader. You can set more uniforms on the RenderPipeline than its shaders use, the extra uniforms will simply be ignored.
- `value` (_mixed_) - The value to be set. Can be a float, an array of floats, a typed array, a boolean, `Texture` etc. The values must match the declarations in the shader.
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram)
### draw(opts) : RenderPipeline
`RenderPipeline.draw` is the entry point for running shaders, rendering and (optionally calculating data using transform feedback techniques).
```js
RenderPipeline.draw({
vertexArray,
uniforms = {},
transformFeedback = null,
samplers = {},
parameters = {},
drawMode = GL.TRIANGLES,
vertexCount,
offset = 0,
isIndexed = false,
indexType = GL.UNSIGNED_SHORT,
isInstanced = false,
instanceCount = 0,
start = 0,
end=
})
```
Main parameters
- `vertexArray` - a `VertexArray` object that will be bound and unbound before and after the draw call.
- `uniforms`=`{}` - a map of uniforms that will be set just before the draw call (and remain set after the call).
- `samplers`=`{}` - a map of texture `Sampler`s that will be bound before the draw call.
- `parameters` - temporary gl settings to be applied to this draw call.
- `transformFeedback`=`null` - optional `TransformFeedback` object containing buffers that will receive the output of the transform feedback operation.
Potentially autodeduced parameters
- `drawMode`=`GL.TRIANGLES` - geometry primitive format of vertex data
- `vertexCount` - number of vertices to draw
- `offset`=`0` - first vertex to draw
- `isIndexed`=`false` - use indices in the "elements" buffer
- `indexType`=`GL.UNSIGNED_SHORT` - must match the type of the "elements" buffer
- `isInstanced`=`false` - Set to enable instanced rendering.
- `instanceCount`=`0` - Number of instances
Parameters for drawing a limited range (WebGL 2 only)
- `start` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
- `end` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
Returns: `true` if successful, `false` if draw call is blocked due to missing resources.
Notes:
- Runs the shaders in the pipeline, on the attributes and uniforms.
- Indexed rendering uses the element buffer (`GL.ELEMENT_ARRAY_BUFFER`), make sure your attributes or `VertexArray` contains one.
- If a `TransformFeedback` object is supplied, `transformFeedback.begin()` and `transformFeedback.end()` will be called before and after the draw call.
- A `Sampler` will only be bound if there is a matching Texture with the same key in the supplied `uniforms` object.
- Once a uniform is set, it's size should not be changed. This is only a concern for array uniforms.
The following WebGL APIs are called in this function:
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram),
[gl.drawElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawElements),
[gl.drawRangeElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawRangeElements) (WebGL 2),
[gl.drawArrays](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawArrays),
[gl.drawElementsInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawElementsInstanced) (WebGL 2),
[gl.drawArraysInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawArraysInstanced) (WebGL 2),
[gl.getExtension](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getExtension), [ANGLE_instanced_arrays](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays),
[gl.drawElementsInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawElementsInstancedANGLE),
[gl.drawArraysInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawArraysInstancedANGLE)
## Constants
### Limits
| Limit | Value | Description |
| ---------------------------------------------------- | -------------- | ----------- |
| `GL.MAX_VERTEX_TEXTURE_IMAGE_UNITS` | >= 0 (GLint) | |
| `GL.MAX_RENDERBUFFER_SIZE` | >= 1 (GLint) | |
| `GL.MAX_VARYING_VECTORS` | >= 8 (GLint) | |
| `GL.MAX_VERTEX_ATTRIBS` | >= 8 (GLint) | |
| `GL.MAX_VERTEX_UNIFORM_VECTORS` | >= 128 (GLint) | |
| `GL.MAX_FRAGMENT_UNIFORM_VECTORS` | >= 16 (GLint) | |
| `GL.TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH` (WebGL 2) | - | - |
### Parameters
Use with `RenderPipeline.getParameter(parameter)`
| Parameter | Type | Description |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GL.DELETE_STATUS` | GLboolean | If true, pipeline has been flagged for deletion (by calling `RenderPipeline.delete()`), but the delete is pending because pipeline is still part of current rendering state |
| `GL.LINK_STATUS` | GLboolean | Indicates whether last link operation was successful. RenderPipeline linking is performed by luma on pipeline initialization |
| `GL.VALIDATE_STATUS` | GLboolean | Result of last `gl.validateProgram()` operation |
| `GL.ATTACHED_SHADERS` | GLint | Number of attached shaders (`0`, `1` or `2`) |
| `GL.ACTIVE_ATTRIBUTES` | GLint | Number of active attribute variables to a pipeline |
| `GL.ACTIVE_UNIFORMS` | GLint | Number of active attribute variables to a pipeline |
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | GLenum | (WebGL 2) Buffer capture mode, `GL.SEPARATE_ATTRIBS` or `GL.INTERLEAVED_ATTRIBS` |
| `GL.TRANSFORM_FEEDBACK_VARYINGS` | GLint | (WebGL 2) Number of varying variables to capture in transform feedback mode. |
| `GL.ACTIVE_UNIFORM_BLOCKS` | GLint | (WebGL 2) Number of uniform blocks containing active uniforms. |

43
docs/api-reference/resources/render-pass.md Normal file
View File

@ -0,0 +1,43 @@
# RenderPass
> Proposed luma.gl v9 API. Open for comments.
A configuration for rendering.
## Types
### `BufferProps`
| Property | Type | Description |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| `framebuffer?` | `Framebuffer` | Provides render target textures and depth/stencil texture |
| `parameters?` | `Parameters` | GPU pipeline parameters |
## Members
- `device`: `Device` - holds a reference to the `Device` that created this `RenderPass`.
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `RenderPassProps` - holds a copy of the `RenderPassProps` used to create this `RenderPass`.
## Methods
### `constructor(props: RenderPassProps)`
`RenderPass` is an abstract class and cannot be instantiated directly. Create with `device.beginRenderPass(...)`.
### `endPass(): void`
Free up any GPU resources associated with this render pass.
### `pushDebugGroup(groupLabel: string): void`
Adds a debug group (implementation dependent).
### `popDebugGroup(): void`
Removes a debug group (implementation dependent).
### `insertDebugMarker(markerLabel: string): void`
Adds a debug marker (implementation dependent).

202
docs/api-reference/resources/render-pipeline.md
View File

@ -1,5 +1,7 @@
# RenderPipeline
> Proposed luma.gl v9 API. Open for comments.
A `RenderPipeline` contains a matched pair of vertex and fragment [shaders](/docs/api-reference/webgl/shader) that can be exectued on the GPU by calling `RenderPipeline.draw()`. handle compilation and linking of shaders, and store uniform values. They provide `draw` call which allows the application to run the shaders on specified input data.
A RenderPipeline controls the vertex and fragment shader stages, and can be used in GPURenderPassEncoder as well as GPURenderBundleEncoder.
@ -182,15 +184,182 @@ Notes:
The following WebGL APIs are called in this function:
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram),
[gl.drawElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawElements),
[gl.drawRangeElements](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawRangeElements) (WebGL 2),
[gl.drawArrays](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawArrays),
[gl.drawElementsInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawElementsInstanced) (WebGL 2),
[gl.drawArraysInstanced](https://developer.mozilla.org/en-US/docs/Web/API/WebGL2RenderingContext/drawArraysInstanced) (WebGL 2),
[gl.getExtension](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getExtension), [ANGLE_instanced_arrays](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays),
[gl.drawElementsInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawElementsInstancedANGLE),
[gl.drawArraysInstancedANGLE](https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays/drawArraysInstancedANGLE)
# RenderPipeline
> Proposed luma.gl v9 API. Open for comments.
A `RenderPipeline` contains a matched pair of vertex and fragment [shaders](/docs/api-reference/webgl/shader) that can be exectued on the GPU by calling `RenderPipeline.draw()`. Programs handle compilation and linking of shaders, and store uniform values. They provide `draw` call which allows the application to run the shaders on specified input data.
## Usage
Creating a pipeline
```js
const pipeline = device.createRenderPipeline({
id: 'my-pipeline',
vs: vertexShaderSourceString,
fs: fragmentShaderSourceString
});
```
Set or update uniforms, in this case world and projection matrices
```js
pipeline.setUniforms({
uMVMatrix: view,
uPMatrix: projection
});
```
Create a `VertexArray` to store buffer values for the vertices of a triangle and drawing
```js
const pipeline = device.createRenderPipeline({vs, fs});
const vertexArray = new VertexArray(gl, {pipeline});
vertexArray.setAttributes({
aVertexPosition: new Buffer(gl, {data: new Float32Array([0, 1, 0, -1, -1, 0, 1, -1, 0])})
});
pipeline.draw({vertexArray, ...});
```
Creating a pipeline for transform feedback, specifying which varyings to use
```js
const pipeline = device.createRenderPipeline({vs, fs, varyings: ['gl_Position']});
```
## Members
- `device`: `Device` - holds a reference to the `Device` that created this `Buffer`.
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `BufferProps` - holds a copy of the `BufferProps` used to create this `Buffer`.
## Methods
### `constructor(props: BufferProps)`
`Buffer` is an abstract class and cannot be instantiated directly. Create with `device.createBuffer(...)`.
### `destroy(): void`
Free up any GPU resources associated with this buffer immediately (instead of waiting for garbage collection).
## Members
- `gl` : `WebGLRenderingContext`
- `handle` : `WebGLProgram` - The WebGL `WebGLProgram` instance.
- `id` : `String` - `id` string for debugging.
## Constructor
### RenderPipeline(gl : WebGLRenderingContext, props : Object)
Creates a new pipeline using the supplied vertex and fragment shaders. The shaders are compiled into WebGLShaders and is created and the shaders are linked.
```js
const pipeline = device.createRenderPipeline({
id: 'my-identifier',
vs: vertexShaderSource,
fs: fragmentShaderSource,
varyings: ['gl_Position', 'vColor']
});
```
- `id` (`string`, optional) - string id (to help indentify the pipeline during debugging).
- `vs` (`VertexShader`|`String`) - A vertex shader object, or source as a string.
- `fs` (`FragmentShader`|`String`) - A fragment shader object, or source as a string.
- `varyings` WebGL 2 (`String[]`) - a list of names of varyings.
- `bufferMode`=`GL.SEPARATE_ATTRIBS` WebGL 2 (`GLenum`) - Optional, specifies how transform feedback should store the varyings.
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | Description |
| ----------------------------------- | ---------------------------- |
| `GL.SEPARATE_ATTRIBS` | One varying per buffer |
| `GL.INTERLEAVED_ATTRIBS` | Multiple varyings per buffer |
WebGL References [WebGLProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLProgram), [gl.createProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/createProgram)
### delete() : RenderPipeline
Deletes resources held by pipeline. Note: Does not currently delete shaders (to enable shader caching).
## Methods
### initialize(props : Object) : RenderPipeline
Relinks a pipeline. Takes the same options as the constructor
### setUniforms(uniforms : Object) : RenderPipeline
Sets named uniforms from a map, ignoring names
- `key` (_String_) - The name of the uniform to be set. The name of the uniform will be matched with the name of the uniform declared in the shader. You can set more uniforms on the RenderPipeline than its shaders use, the extra uniforms will simply be ignored.
- `value` (_mixed_) - The value to be set. Can be a float, an array of floats, a typed array, a boolean, `Texture` etc. The values must match the declarations in the shader.
[gl.useProgram](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/useProgram)
### draw(opts) : RenderPipeline
`RenderPipeline.draw` is the entry point for running shaders, rendering and (optionally calculating data using transform feedback techniques).
```js
RenderPipeline.draw({
vertexArray,
uniforms = {},
transformFeedback = null,
samplers = {},
parameters = {},
drawMode = GL.TRIANGLES,
vertexCount,
offset = 0,
isIndexed = false,
indexType = GL.UNSIGNED_SHORT,
isInstanced = false,
instanceCount = 0,
start = 0,
end=
})
```
Main parameters
- `vertexArray` - a `VertexArray` object that will be bound and unbound before and after the draw call.
- `uniforms`=`{}` - a map of uniforms that will be set just before the draw call (and remain set after the call).
- `samplers`=`{}` - a map of texture `Sampler`s that will be bound before the draw call.
- `parameters` - temporary gl settings to be applied to this draw call.
- `transformFeedback`=`null` - optional `TransformFeedback` object containing buffers that will receive the output of the transform feedback operation.
Potentially autodeduced parameters
- `drawMode`=`GL.TRIANGLES` - geometry primitive format of vertex data
- `vertexCount` - number of vertices to draw
- `offset`=`0` - first vertex to draw
- `isIndexed`=`false` - use indices in the "elements" buffer
- `indexType`=`GL.UNSIGNED_SHORT` - must match the type of the "elements" buffer
- `isInstanced`=`false` - Set to enable instanced rendering.
- `instanceCount`=`0` - Number of instances
Parameters for drawing a limited range (WebGL 2 only)
- `start` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
- `end` - hint to GPU, activates `gl.drawElementsRange` (WebGL 2)
Returns: `true` if successful, `false` if draw call is blocked due to missing resources.
Notes:
- Runs the shaders in the pipeline, on the attributes and uniforms.
- Indexed rendering uses the element buffer (`GL.ELEMENT_ARRAY_BUFFER`), make sure your attributes or `VertexArray` contains one.
- If a `TransformFeedback` object is supplied, `transformFeedback.begin()` and `transformFeedback.end()` will be called before and after the draw call.
- A `Sampler` will only be bound if there is a matching Texture with the same key in the supplied `uniforms` object.
- Once a uniform is set, it's size should not be changed. This is only a concern for array uniforms.
The following WebGL APIs are called in this function:
## Constants
@ -206,18 +375,3 @@ The following WebGL APIs are called in this function:
| `GL.MAX_FRAGMENT_UNIFORM_VECTORS` | >= 16 (GLint) | |
| `GL.TRANSFORM_FEEDBACK_VARYING_MAX_LENGTH` (WebGL 2) | - | - |
### Parameters
Use with `RenderPipeline.getParameter(parameter)`
| Parameter | Type | Description |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GL.DELETE_STATUS` | GLboolean | If true, pipeline has been flagged for deletion (by calling `RenderPipeline.delete()`), but the delete is pending because pipeline is still part of current rendering state |
| `GL.LINK_STATUS` | GLboolean | Indicates whether last link operation was successful. RenderPipeline linking is performed by luma on pipeline initialization |
| `GL.VALIDATE_STATUS` | GLboolean | Result of last `gl.validateProgram()` operation |
| `GL.ATTACHED_SHADERS` | GLint | Number of attached shaders (`0`, `1` or `2`) |
| `GL.ACTIVE_ATTRIBUTES` | GLint | Number of active attribute variables to a pipeline |
| `GL.ACTIVE_UNIFORMS` | GLint | Number of active attribute variables to a pipeline |
| `GL.TRANSFORM_FEEDBACK_BUFFER_MODE` | GLenum | (WebGL 2) Buffer capture mode, `GL.SEPARATE_ATTRIBS` or `GL.INTERLEAVED_ATTRIBS` |
| `GL.TRANSFORM_FEEDBACK_VARYINGS` | GLint | (WebGL 2) Number of varying variables to capture in transform feedback mode. |
| `GL.ACTIVE_UNIFORM_BLOCKS` | GLint | (WebGL 2) Number of uniform blocks containing active uniforms. |

166
docs/api-reference/resources/sampler.md
View File

@ -1,16 +1,20 @@
# Sampler
A Sampler is an immutable object that holds a set of sampling parameters for texture access.
> Proposed luma.gl v9 API. Open for comments.
A `Sampler` is an immutable object that holds a set of sampling parameters for texture access.
Sampling parameters are applied during shader execution and control how values ("texels")
are read from textures.
Samplers allow texture sampling parameters to be specified independently of textures.
By using samplers an application can render the same texture with different
parameters without duplicating the texture, or modifying the texture parameters.
Note that luma.gl automatically creates a default `Sampler` for each `Texture`.
A texture's default sampler parameters can be specified creating the texture via `device.createTexture({sampler: SamplerProps}))`.
Unless an application needs to render the same texture with different sampling parameters,
an application typically does not need to explicitly instantiate samplers.
References:
- [OpenGL Wiki](https://www.khronos.org/opengl/wiki/Sampler_Object).
Finally, a **Comparison sampler** is a special type of `Sampler` that compares against the depth buffer.
During comparison sampling, the interpolated and clamped `r` texture coordinate is compared to currently bound depth texture,
and the result of the comparison (`0` or `1`) is assigned to the red channel.
Specifying the `compare` sampler property creates a comparison sampler.
## Usage
@ -24,7 +28,7 @@ const sampler = device.createSampler(gl, {
});
```
A `Sampler` is automatically created for each texture.
Note that a default `Sampler` is automatically created for each texture:
```typescript
// Create a texture
@ -37,29 +41,18 @@ const texture = device.createTexture({
console.log(texture.sampler);
```
## Base Classes
Sampler inherits from [Resource](/docs/modules/api/api-reference/resources/resource.md) and supports the same use cases.
## Methods
### Base Class
`Sampler` inherits methods and members from [Resource](/docs/modules/api/api-reference/resources/resource.md):
### constructor
Create a new **comparison sampler**, by specifying the `compare` sampler property creates a comparison sampler.
```typescript
device.createSampler({...})
const sampler = device.createSampler(gl, {
compare: 'lequal'
});
```
- `props` - an object where each key represents a sampler parameter and its value.
### destroy
## Types
Frees the underlying WebGL resource
## Sampler Parameters
### SamplerProps
| Sampler Parameter | Values | Description |
| ----------------- | ---------------------------------------------------- | ------------------------------------------------------------------- |
@ -69,47 +62,12 @@ Frees the underlying WebGL resource
| `magFilter?` | `'nearest'` \| `'linear'` | Sample nearest texel, or interpolate closest texels |
| `minFilter?` | `'nearest'` \| `'linear'` | Sample nearest texel, or interpolate closest texels |
| `mipmapFilter?` | `'nearest'` \| `'linear'` | Sample closest mipmap, or interpolate two closest mipmaps |
| `maxAnisotropy?` | `number` | Combine samples from multiple mipmap levels when appropriate |
| `lodMinClamp?` | `number` | Minimum level of detail to use when sampling |
| `lodMaxClamp?` | `number` | Maximum level of detail to use when sampling |
| `compare?` | `lequal` etc (see below) | Create a depth "comparison sampler" with specified compare function |
| `maxAnisotropy?` | `number` | Combine samples from multiple mipmap levels when appropriate |
### Texture Magnification Filter
Controls how a pixel is textured when it maps to less than one texel.
Parameter: `texture_mag_filter`
| Value | Description |
| ------------------- | ------------------ |
| `linear` | interpolated texel |
| `nearest` (default) | nearest texel |
- `nearest` is faster than `linear`, but is not as smooth.
### Texture Minification Filter
Controls how a pixel is textured maps to more than one texel.
ParameterL `texture_min_filter`
| Value | Description |
| --------- | ------------------ |
| `linear` | interpolated texel |
| `nearest` | nearest texel |
### Texture Minification Filter
Controls how a pixel is textured maps to more than one texel.
ParameterL `texture_min_filter`
| Value | Description |
| --------- | ------------------ |
| `linear` | interpolated texel |
| `nearest` | nearest texel |
### Texture Wrapping
#### Texture Wrapping
Controls how texture coordinates outside of the [0, 1] range are sampled.
@ -121,26 +79,52 @@ Controls how texture coordinates outside of the [0, 1] range are sampled.
| `clamp-to-edge` | clamp texture coordinates |
| `mirrored-repeat` | use fractional part of texture coordinate if integer part is odd, otherwise `1 - frac` |
### Comparison Samplers
#### Texture Magnification Filter
Specifying the `compare` sampler property creates a comparison sampler.
Comparison samplers are special samplers that compare against the depth buffer.
Controls how a pixel is textured when it maps to less than one texel.
In other words, specifies the texture comparison mode for currently bound depth textures
(i.e. textures whose internal format is `depth_component_*`).
Parameter: `magFilter`
```typescript
const sampler = device.createSampler(gl, {
compare: 'lequal'
});
```
| Value | Description |
| ------------------- | ------------------ |
| `linear` | interpolated texel |
| `nearest` (default) | nearest texel |
During sampling, the interpolated and clamped `r` texture coordinate is compared to currently bound depth texture,
and the result of the comparison (`0` or `1`) is assigned to the red channel.
- `nearest` is faster than `linear`, but is not as smooth.
### Texture Comparison Function
#### Texture Minification Filter
Parameter: `texture_compare_func`
Controls how a pixel is textured when it maps to more than one texel.
Parameter: `minFilter`
| Value | Description |
| --------- | ------------------ |
| `linear` | interpolated texel |
| `nearest` | nearest texel |
#### Texture Mipmap Filter
Controls if a pixel is textured by referencing more than one mipmap level.
ParameterL `mipmapFilter`
| Value | Description |
| --------- | --------------------------- |
| `linear` | interpolate between mipmaps |
| `nearest` | nearest mipmap |
| N/A | no mipmaps |
#### Texture Max Anisotropy
Controls multiple mipmap level can be consulted when texturing a pixel.
#### Texture Comparison Function
> Specifying the `compare` sampler property creates a comparison sampler.
> Comparison samplers are special samplers that compare against the depth buffer.
Parameter: `compare`
| `Value | Computed result |
| ------------------ | ---------------------------------- |
@ -152,3 +136,33 @@ Parameter: `texture_compare_func`
| `notequal` | result = 1.0 0.0, r ≠ D t r = D t |
| `always` | result = 1.0 |
| `never` | result = 0.0 |
During sampling, the interpolated and clamped `r` texture coordinate is compared to currently bound depth texture,
and the result of the comparison (`0` or `1`) is assigned to the red channel.
## Members
- `device`: `Device` - holds a reference to the `Device` that created this `Sampler`.
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `SamplerProps` - holds a copy of the `SamplerProps` used to create this `Sampler`.
## Methods
### `constructor(props: SamplerProps)`
`Sampler` is an abstract class and cannot be instantiated directly. Create with `device.createSampler(...)`.
```typescript
device.createSampler({...})
```
### `destroy(): void`
Free up any GPU resources associated with this sampler immediately (instead of waiting for garbage collection).
## Methods
`Sampler` inherits methods and members from [Resource](/docs/modules/api/api-reference/resources/resource.md).
## Remarks
- WebGL: More information about `WebGLSampler` can be found in the [OpenGL Wiki](https://www.khronos.org/opengl/wiki/Sampler_Object).

40
docs/api-reference/resources/shader.md
View File

@ -1,6 +1,11 @@
# Shader
The `Shader` class
> Proposed luma.gl v9 API. Open for comments.
The `Shader` class holds a compiled shader.
- It takes shader source code and compiles it during construction.
- Shaders are used as inputs when creating `RenderPipeline` and `ComputePipeline` objects.
- A `Shader` is immutable and the same compiled shader can safely be referenced by many pipelines.
## Usage
@ -11,19 +16,40 @@ const vs = device.createShader({stage: 'vertex', source});
const fs = device.createShader({stage: 'fragment', source});
```
## Types
### ShaderProps
Properties for a Shader
| Field | Type | Description |
| ------------- | ----------------------------------- | ------------------------------------- |
| `id` | `string` | name/identifier (for debugging) |
| `stage` | 'vertex' \| 'fragment' \| 'compute' | Required by WebGL and GLSL transpiler |
| `source` | `string` | Shader source code |
| `sourceMap?` | `string` | WebGPU only |
| `language?` | 'glsl' \| 'wgsl' | wgsl in WebGPU only |
| `entryPoint?` | `string` | WGLSL only, name of main function |
## Members
- `handle` - holds the underlying `WebGLShader` object
- `device`: `Device` - holds a reference to the
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `ShaderProps` - holds a copy of the `ShaderProps` used to create this `Shader`.
## Methods
### constructor
### `constructor(props: ShaderProps)`
`Shader` is an abstract class and cannot be instantiated directly. Create with `device.createShader(...)`.
### `destroy(): void`
Free up any GPU resources associated with this shader immediately (instead of waiting for garbage collection).
### `getInfoLog(): Promise<CompilerMessage[]>`
- `source` - string containing shader instructions.
## Remarks
- Shader sources: A `Program` needs to be constructed with two strings containing source code for vertex and fragment shaders.
- Default Shaders: luma.gl comes with a set of default shaders that can be used for basic rendering and picking.
- Shader compilation is fairly fast, in particular compared to Pipeline linking.

106
docs/api-reference/resources/texture.md
View File

@ -1,32 +1,21 @@
# Texture
> Proposed luma.gl v9 API. Open for comments.
A `Texture` is a WebGL object that contains one or more images that all have the same image format. Shaders can read from textures (through a sampler uniform) and they can be set up as render targets (by attaching them to a framebuffer).
Note: This section describes the `Texture` base class that implements functionality common to all four types of WebGL:
- [`1d`] - Contains a "normal" image texture
- [`2d`] - Contains a "normal" image texture
- [`2d-array`](WebGL 2) - Holds a "stack" of textures which enables 3D interpolation.
- [`3d`](WebGL 2) - Holds a "stack" of textures which enables 3D interpolation.
- [`cube`] - Holds 6 textures representing sides of a cube.
- [`cube-array`] - Holds 6 textures representing sides of a cube.
For more details see [OpenGL Wiki](https://www.khronos.org/opengl/wiki/Texture).
Note that textures have a lot of optional capabilities made available by extensions, see the Limits section below.
## Usage
- For additional usage examples, `Texture` inherits from [`Resource`](/docs/api-reference/webgl/resource).
Configuring a Texture
Creating a texture
```js
const texture = device.createTexture);
texture.setParameters({
[GL.TEXTURE_WRAP_S]: GL.CLAMP
});
const texture = device.createTexture({sampler: {addressModeU: 'clamp-to-edge'});
```
Using Textures
@ -47,6 +36,59 @@ model.draw({
});
```
- For additional usage examples, `Texture` inherits from [`Resource`](/docs/api-reference/webgl/resource).
## Types
### `BufferProps`
| Property | Type | Description |
| ------------- | -------------------------------- | ---------------------------------------------------------------------------- |
| `usage?` | `number` | Bit mask of Usage flags |
| `byteLength?` | `number` | Length of buffer (cannot be changed after creation). |
| `data?` | `ArrayBuffer \| ArrayBufferView` | Data to be copied into buffer. `byteLength` will be deduced if not supplied. |
| `byteOffset?` | `number` | Offset for `data` |
| `indexType?` | `'uint16' \| 'uint32'` | If props.usage & Buffer.INDEX |
### Usage
Usage expresses two things: The type of texture and what operations can be performed on it.
Note that the allowed combinations are very limited, especially in WebGPU.
| Usage Flag | Value | Description |
| ---------------------- | ------ | -------------------------------------------------------- |
| `Texture.COPY_SRC` | 0x01 | |
| `Texture.COPY_DST` | 0x02 | |
| `Texture.TEXTURE_BINDING` | 0x04 | |
| `Texture.STORAGE_BINDING` | 0x08 | |
| `Texture.RENDER_ATTACHMENT` | 0x10 | |
## TextureDimension
| Dimension | WebGPU | WebGL2 | WebGL1 | Description |
| ------------ | ------ | ------ | ------ | -------------------------------------------------------------------- |
| `1d` | ✅ | ❌ | ❌ | Contains a one dimensional texture (typically used for compute ) |
| `2d` | ✅ | ✅ | ✅ | Contains a "normal" image texture |
| `2d-array` | ✅ | ✅ | ❌ | Holds an "array" of 2D textures. |
| `3d` | ✅ | ✅ | ❌ | Holds a "stack" of textures which enables 3D interpolation. |
| `cube` | ✅ | ✅ | ✅ | Holds 6 textures representing sides of a cube. |
| `cube-array` | ✅ | ❌ | ❌ | Holds an array where every 6 textures represent the sides of a cube. |
## TextureData
WebGL allows textures to be created from a number of different data sources.
| Type | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `null` | A texture will be created with the appropriate format, size and width. Bytes will be "uninitialized". |
| `typed array` | Bytes will be interpreted according to format/type parameters and pixel store parameters. |
| `Buffer` or `WebGLBuffer` (`WebGL 2`) | Bytes will be interpreted according to format/type parameters and pixel store parameters. |
| `Image` (`HTMLImageElement`) | image will be used to fill the texture. width and height will be deduced. |
| `Video` (`HTMLVideoElement`) | video will be used to continously update the texture. width and height will be deduced. |
| `Canvas` (`HTMLCanvasElement`) | canvas will be used to fill the texture. width and height will be deduced. |
| `ImageData` | `canvas.getImageData()` - Used to fill the texture. width and height will be deduced. |
## Members
A number of read only accessors are available:
@ -67,18 +109,21 @@ Sampler parameters can be accessed using `Texture.getParameter`, e.g:
`texture.getParameter(GL.TEXTURE_MAG_FILTER);`
## Members
- `device`: `Device` - holds a reference to the `Device` that created this `Texture`.
- `handle`: `unknown` - holds the underlying WebGL or WebGPU shader object
- `props`: `TextureProps` - holds a copy of the `TextureProps` used to create this `Texture`.
## Methods
### constructor(gl : WebGLRenderingContext, props : Object)
### `constructor(props: TextureProps)`
`Texture` is an abstract class and cannot be instantiated directly. Create with `device.createTexture(...)`.
- [`Texture2D`](/docs/api-reference/webgl/texture-2d),
- [`TextureCube`](/docs/api-reference/webgl/texture-cube) and
- [`Texture3D`](/docs/api-reference/webgl/texture-3d).
### `destroy(): void`
The constructors for these classes should be used to create textures. They constructors all take common parameters, many of which are specified in this document.
- Pixel store parameters are described in [`State Management`](/docs/api-reference/gltools/parameter-setting).
Free up any GPU resources associated with this texture immediately (instead of waiting for garbage collection).
### resize(options : Object) : Texture2D
@ -200,21 +245,7 @@ The following WebGL APIs are called in the function
The following WebGL APIs are called in the function
[gl.activeTexture](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/activeTexture), [gl.bindTexture](https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bindTexture)
## Texture Image Data
WebGL allows textures to be created from a number of different data sources.
| Type | Description |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `null` | A texture will be created with the appropriate format, size and width. Bytes will be "uninitialized". |
| `typed array` | Bytes will be interpreted according to format/type parameters and pixel store parameters. |
| `Buffer` or `WebGLBuffer` (`WebGL 2`) | Bytes will be interpreted according to format/type parameters and pixel store parameters. |
| `Image` (`HTMLImageElement`) | image will be used to fill the texture. width and height will be deduced. |
| `Video` (`HTMLVideoElement`) | video will be used to continously update the texture. width and height will be deduced. |
| `Canvas` (`HTMLCanvasElement`) | canvas will be used to fill the texture. width and height will be deduced. |
| `ImageData` | `canvas.getImageData()` - Used to fill the texture. width and height will be deduced. |
## NPOT Textures (WebGL 1)
## NOT (Non-Power-of-Two) Textures (WebGL 1)
- Any texture with a `non power of two` dimension (width or height) is referred as `NPOT` texture, under WebGL 1 NPOT textures have following limitations.
@ -234,3 +265,4 @@ WebGL allows textures to be created from a number of different data sources.
- Textures can be created from a number of different sources, including typed arrays, HTML Images, HTML Canvases, HTML Videos and WebGLBuffers (WebGL 2).
- The WebGL Context has global "pixel store" parameters that control how pixel data is laid out, including Y direction, color space etc.
- Textures are read from supplied data and written to the specified format/type parameters and pixel store parameters.
- WebGL: Pixel store parameters are described in [`State Management`](/docs/api-reference/gltools/parameter-setting).

8
docs/api-guide/texture-formats.mdx → docs/api-reference/texture-formats.mdx
View File

@ -2,6 +2,8 @@ import {DeviceTabs, Format as Ft, Filter as L, Render as R} from '@luma.gl/react
# Texture Formats
> Proposed luma.gl v9 API. Open for comments.
GPUs support a wide range of texture formats. In luma.gl,
each format is identified with a string (the `TextureFormat` type).
@ -208,9 +210,9 @@ See [Compressed Textures in 2020](https://aras-p.info/blog/2020/12/08/Texture-Co
On WebGL devices, luma.gl maps WebGPU style format strings to WebGL constants under the hood.
It is however possible to provide overrides for the WebGL constants. The following tables provide some information about WebGL texture constants
If an application wants to store the texture at a certain resolution or in a certain format,
it can request the resolution and format with `internalFormat`.
WebGL will choose an internal representation with least the internal component sizes,
If an application wants to store the texture at a certain resolution or in a certain format,
it can request the resolution and format with `internalFormat`.
WebGL will choose an internal representation with least the internal component sizes,
and exactly the component types shown for that format, although it may not match exactly.
### Internal Formats

15
docs/api-reference/types/shader-layout.md
View File

@ -1,5 +1,7 @@
# ShaderLayout (Type)
> Proposed luma.gl v9 API. Open for comments.
Shader code contains declarations of attributes, uniform blocks, samplers etc in the GLSL or WGSL code,
that collectively define the layout of data that needs to be bound before the shader can execute on the
GPU.
@ -15,18 +17,11 @@ or be automatically generated by parsing shader source code or using e.g. the We
```typescript
type ShaderLayout = {
vs?: Shader;
fsEntryPoint?: string;
fs?: Shader;
fsEntryPoint?: string;
cs?: Shader;
csEntryPoint?: string;
attributes: {[attributeName: string]: AttributeLayout};
attributes: [
instancePositions: {location: 0, format: 'float32x2', stepMode: 'instance'},
instanceVelocities: {location: 1, format: 'float32x2', stepMode: 'instance'},
vertexPositions: {location: 2, format: 'float32x2', stepMode: 'vertex'}
},
],
bindings: {[bindingName: string]: BindingLayout};
projectionUniforms: {location: 0, type: 'uniforms'},
@ -36,7 +31,7 @@ type ShaderLayout = {
}
type AttributeLayout =
{location: number, format: VertexFormat, stepMode: 'vertex' | 'instance'}
{name: , location: number, format: VertexFormat, stepMode: 'vertex' | 'instance'}
type BindingLayout =
{type: 'uniform', location: number} |

67
docs/design-notes/v9-api.md
View File

@ -1,67 +0,0 @@
# luma.gl API
> This section describes the experimental, work-in-progress v9 luma.gl API.
The luma.gl API is designed to expose the capabilities of the GPU and shader programming to web applications.
Naturally, core responsibilities for any GPU library:
- GPU resource management (create and destroy GPU resources like Buffers, Textures etc)
- GPU Bindings (making attribute buffers, uniform buffers, textures, samplers etc available to GPU shaders.
- Shader execution (draw, compute)
- Shader composition
- Cross platform support: backwards compatibility with WebGL 2 (WebGL on a "best effort" basis).
## v9 API notes
The v9 API represents a break with luma.gl v8 and earlier, which was designed around providing a set of classes explicitly designed for working with the WebGL2 API.
Many key concepts have carried forward from the v8 API to the v9 API, and programmers should find themselves working on the same abstraction level as before with similar classes, such as `Model`, `AnimationLoop`, `Buffer`, `Texture` etc. But there are a number of important differences, more on that below.
luma.gl v9 is an abstract API, specified in terms of TypeScript interfaces (such as `Buffer`, `Texture` etc). A `Device` class provides concrete classes that implement these interfaces using the corresponding implementation API.
| Interface | Description |
| --- | --- |
| `Adapter` | luma.gl exposes GPU capabilities on the device in the form of one or more as `Adapter`s. |
| `Device` | Manages resources, and the device’s GPUQueues, which execute commands. |
| `Buffer` | The physical resources backed by GPU memory. A `Device` may have its own memory with high-speed access to the processing units. |
| `Texture` | Like buffer, but supports random access |
GPUCommandBuffer and GPURenderBundle are containers for user-recorded commands.
| `Shader` | Compiled shader code.
| `Sampler` | or GPUBindGroup, configure the way physical resources are used by the GPU. |
GPUs execute commands encoded in GPUCommandBuffers by feeding data through a pipeline, which is a mix of fixed-function and programmable stages. Programmable stages execute shaders, which are special programs designed to run on GPU hardware. Most of the state of a pipeline is defined by a GPURenderPipeline or a GPUComputePipeline object. The state not included in these pipeline objects is set during encoding with commands, such as beginRenderPass() or setBlendColor().
## v9 vs v8 API
- The API is now abstract, specified in terms of TypeScript interfaces, such as `Buffer`, `Texture` etc. A `Device` class provides concrete classes that implement these interfaces using the corresponding implementation API.
- Reading and writing buffers is now an async operation. While WebGL does not support async reads and writes on MacOS, the API is still async to ensure portability.
- Uniform buffers are now the standard way for the application to specify uniforms. Uniform buffers are "emulated" under WebGL.
- The v9 API no longer accepts/returns `GL` constants, but instead uses the corresponding string values from the WebGPU standard (mapping those transparently under WebGL).
- The parameter API has been updated to more closely match the WebGPU API. Also parameters are built into pipelines and not as easy to change in a draw call.
## Get Started
```js
import {GPU} from '@luma.gl/webgpu';
const device = GPU.getDevice({canvas});
const {Buffer, Model, AnimationLoop} = device;
const buffer = new Buffer(device, {});
const animationLoop = new AnimationLoop({
device,
onInitialize({device}) {
},
onFinalize({device}) {
},
onRender({device}) {
}
});
animationLoop.run();
```

32
docs/design-notes/webgpu-vs-webgl.md
View File

@ -1,32 +0,0 @@
# WebGPU vs WebGL
WebGPU is the next generation GPU API for the browser.
This section explains some of the notable differences between WebGPU and WebGL. This is essentially a set of author's notes, included for the curious.
## WebGPU Device vs WebGL Context
A WebGL context is associated with a specific canvas.
- The default drawing buffer is associated with the canvas
- Rendering to other canvases either requires separate WebGL contexts (with duplicated GPU resources) or going through hoops with framebuffer rendering and image copies.
- A WebGPU device enables the application to create separate swap chains for different canvases and reuse resources
## Parameters and State Management
In WebGL many parameters are set on the WebGL context using individual function calls.
- This does cause problems when trying to make different modules work together.
- But it does make it easier to change settings between draw calls.
## Programs
| WebGPU limitation | Alternatives |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| No GLSL support | 1) glslang project seems stale. 2) Use Naga (Rust) to build a WebAssembly transpiler. 3) write two sets of shaders. |
| No constant attributes | 1) Create dummy buffers 2) dynamically generate shaders with uniforms. |
| Interleaving specified at Pipeline creation | New `PipelineProps.bufferMap` concept |
| No transform feedback | Compute shaders (storage buffers) |
| No uniforms, only Uniform buffers | Add strong uniform buffer support to API, WebGL1 fallback? |

8
docs/developer-guide/README.md
View File

@ -12,6 +12,8 @@
| Module | Exports |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@luma.gl/engine` | `AnimationLoop`, `Model`, `Transform`, `ProgramManager`, Timeline, Geometry, ClipSpace, ConeGeometry, CubeGeometry, CylinderGeometry, IcoSphereGeometry, PlaneGeometry, SphereGeometry, TruncatedConeGeometry |
| webgl | lumaStats, FEATURES, hasFeature, hasFeatures, Buffer, Program, Framebuffer, Renderbuffer, Texture2D, TextureCube, clear, readPixelsToArray, readPixelsToBuffer, cloneTextureFrom, copyToTexture, Texture3D, TransformFeedback |
| gltools | createGLContext, instrumentGLContext, isWebGL, isWebGL2, getParameters, setParameters, withParameters, resetParameters, cssToDeviceRatio, cssToDevicePixels |
| shadertools | normalizeShaderModule, fp32, fp64, project, dirlight, picking, gouraudLighting, phongLighting, pbr |
| `@luma.gl/api` | lumaStats, FEATURES, hasFeature, hasFeatures, Buffer, Program, Framebuffer, Renderbuffer, Texture2D, TextureCube, clear, readPixelsToArray, readPixelsToBuffer, cloneTextureFrom, copyToTexture, Texture3D, TransformFeedback |
| `@luma.gl/webgl` |
| `@luma.gl/webgpu` |
| `@luma.gl/gltools` | createGLContext, instrumentGLContext, isWebGL, isWebGL2, getParameters, setParameters, withParameters, resetParameters, cssToDeviceRatio, cssToDevicePixels | `@luma.gl/shadertools` | `normalizeShaderModule`, `fp32`, `fp64`, `project`, `dirlight`, `picking`, `gouraudLighting`, `phongLighting`, `pbr` |
| `@luma.gl/experimental` |

20
docs/getting-started/hello-triangle.mdx
View File

@ -6,13 +6,15 @@ import {HelloTriangleExample} from '../../website';
<DeviceTabs />
<HelloTriangleExample />
This tutorial will demonstrate how to draw a triangle using luma.gl's high-level APIs. It is assumed you've set up your development environment as described in [Getting Started](/docs/getting-started). Your `index.js` file should look like the following:
This tutorial will demonstrate how to draw a triangle using luma.gl's high-level APIs.
It is assumed you've set up your development environment as described in
[Getting Started](/docs/getting-started). Your `index.js` file should look like the following:
```js
import {AnimationLoop} from '@luma.gl/engine';
import {clear} from '@luma.gl/webgl';
const loop = new AnimationLoop({
class AppAnimationLoop extends AnimationLoop ({
onInitialize({device}) {
// Setup logic goes here
},
@ -23,6 +25,7 @@ const loop = new AnimationLoop({
}
});
const loop = new AppAnimationLoop();
loop.start();
```
@ -83,7 +86,7 @@ Next let's add the vertex and fragment shader code we'll be using to draw:
}
```
As a final step in our initialization, we'll create a `Model` and return it from `onInitialize`:
As a final step in our initialization, we'll create a `Model` in `onInitialize`:
```js
onInitialize({device}) {
@ -93,7 +96,7 @@ As a final step in our initialization, we'll create a `Model` and return it from
// Shaders...
const model = new Model(device, {
this.model = new Model(device, {
vs,
fs,
attributes: {
@ -112,9 +115,9 @@ A `Model` can be thought of as gathering all the WebGL pieces necessary for a si
Our `onRender` method is comparitavely much simpler:
```js
onRender({device, model}) {
onRender({device}) {
clear(device, {color: [0, 0, 0, 1]});
model.draw();
this.model.draw();
}
```
@ -126,7 +129,7 @@ The entire application should look like the following:
import {AnimationLoop, Model} from '@luma.gl/engine';
import {clear} from '@luma.gl/webgl';
const loop = new AnimationLoop({
class AppAnimationLoop extends AnimationLoop {
onInitialize({device}) {
const positionBuffer = device.createBuffer(new Float32Array([-0.5, -0.5, 0.5, -0.5, 0.0, 0.5]));
@ -169,7 +172,8 @@ const loop = new AnimationLoop({
clear(device, {color: [0, 0, 0, 1]});
model.draw();
}
});
};
const loop = new AppAnimationLoop();
loop.start();
```

7
docs/modules/gltools/README.md
View File

@ -1,4 +1,7 @@
# @luma.gl/gltools
> The `@luma.gl.gltools` is deprecated from luma.gl v8.6. WebGL context related functionality has been
moved into the `@luma.gl/webgl` module.
> This page describes components in the legacy luma.gl v8 API. While still supported in luma.gl v9, these components are deprecated and will eventually be removed and should not be used in new applications.
From luma.gl v9, the `@luma.gl/gltools` exports the deprecated luma.gl v8 WebGL API.
This module should not be used in new applications.

1
docs/modules/webgl/adapter/webgl-device.md
View File

@ -1 +0,0 @@
# WebGLDevice

9
docs/modules/webgpu/README.md
View File

@ -29,9 +29,12 @@ With a bit more work, typescript users can retrieve the `WebGLRenderingContext`
without ignoring type errors:
```typescript
import {cast} from '@luma.gl/api';
import {Device, cast} from '@luma.gl/api';
import {WebGPUDevice} from '@luma.gl/webgpu'; // Installs the WebGPUDevice adapter
const webgpuDevice = cast<WebGPUDevice>(device);
const gl = webgpuDevice.handle;
function f(device: Device) {
const webgpuDevice = device as WebGPUDevice;
const gpuDevice: GPUDevice = webgpuDevice.handle; // Get underlying WebGPU device
...
}
```

89
docs/table-of-contents.json
View File

@ -34,40 +34,81 @@
{ "entry": "docs/developer-guide/debugging" },
{ "entry": "docs/developer-guide/profiling" },
{ "entry": "docs/developer-guide/testing" },
{ "entry": "docs/developer-guide/contributing" },
{ "entry": "docs/design-notes/v9-api" },
{ "entry": "docs/design-notes/webgpu-vs-webgl" }
{ "entry": "docs/developer-guide/contributing" }
]
},
{
"title": "API Guide",
"entries": [
{ "entry": "docs/api-guide/device-properties" },
{ "entry": "docs/api-guide/canvas-context" },
{ "entry": "docs/api-guide/device" },
{ "entry": "docs/api-guide/parameters" },
{ "entry": "docs/api-guide/texture-formats" },
{ "entry": "docs/api-guide/bindings" },
{ "entry": "docs/api-guide/transform" },
{ "entry": "docs/api-guide/shader-modules" }
{ "entry": "docs/api-guide/shader-modules" },
{ "entry": "docs/api-guide/v9-api" },
{ "entry": "docs/api-guide/webgpu-vs-webgl" }
]
},
{
"title": "API Reference",
"chapters": [
{
"title": "API",
"title": "Main",
"entries": [
{ "entry": "docs/api-reference/device" },
{ "entry": "docs/api-reference/canvas-context" },
{ "entry": "docs/api-reference/device-features" },
{ "entry": "docs/api-reference/device-limits" },
{ "entry": "docs/api-reference/texture-formats" },
{ "entry": "docs/api-reference/types/shader-layout" }
]
},
{
"title": "Resources",
"entries": [
{ "entry": "docs/api-reference/types/shader-layout" },
{ "entry": "docs/api-reference/resources/buffer" },
{ "entry": "docs/api-reference/resources/command-encoder" },
{ "entry": "docs/api-reference/resources/compute-pass" },
{ "entry": "docs/api-reference/resources/compute-pipeline" },
{ "entry": "docs/api-reference/resources/framebuffer" },
{ "entry": "docs/api-reference/resources/pipeline" },
{ "entry": "docs/api-reference/resources/render-pass" },
{ "entry": "docs/api-reference/resources/render-pipeline" },
{ "entry": "docs/api-reference/resources/sampler" },
{ "entry": "docs/api-reference/resources/shader" },
{ "entry": "docs/api-reference/resources/texture" },
{ "entry": "docs/api-reference/canvas-context" },
{ "entry": "docs/api-reference/device" }
{ "entry": "docs/api-reference/resources/texture" }
]
}
]
},
{
"title": "API Reference (v8)",
"chapters": [
{
"title": "API",
"entries": [
{ "entry": "docs/api-reference-legacy/accessor" },
{ "entry": "docs/api-reference-legacy/buffer" },
{ "entry": "docs/api-reference-legacy/framebuffer" },
{ "entry": "docs/api-reference-legacy/program" },
{ "entry": "docs/api-reference-legacy/query" },
{ "entry": "docs/api-reference-legacy/renderbuffer" },
{ "entry": "docs/api-reference-legacy/shader" },
{ "entry": "docs/api-reference-legacy/texture" },
{ "entry": "docs/api-reference-legacy/texture-2d" },
{ "entry": "docs/api-reference-legacy/texture-3d" },
{ "entry": "docs/api-reference-legacy/texture-cube" },
{ "entry": "docs/api-reference-legacy/transform-feedback" },
{ "entry": "docs/api-reference-legacy/uniform-buffer-layout" },
{ "entry": "docs/api-reference-legacy/vertex-array" },
{ "entry": "docs/api-reference-legacy/vertex-array-object" },
{ "entry": "docs/api-reference-legacy/resource" },
{ "entry": "docs/api-reference-legacy/context/feature-checking" },
{ "entry": "docs/api-reference-legacy/context/context-properties" },
{ "entry": "docs/api-reference-legacy/moving-data" },
{ "entry": "docs/api-reference-legacy/context" },
{ "entry": "docs/api-reference-legacy/parameter-setting" },
{ "entry": "docs/api-reference-legacy/device-pixels" }
]
}
]
@ -128,29 +169,7 @@
{
"title": "@luma.gl/webgl",
"entries": [
{ "entry": "docs/modules/webgl" },
{ "entry": "docs/modules/webgl/legacy/accessor" },
{ "entry": "docs/modules/webgl/legacy/buffer" },
{ "entry": "docs/modules/webgl/legacy/framebuffer" },
{ "entry": "docs/modules/webgl/legacy/program" },
{ "entry": "docs/modules/webgl/legacy/query" },
{ "entry": "docs/modules/webgl/legacy/renderbuffer" },
{ "entry": "docs/modules/webgl/legacy/shader" },
{ "entry": "docs/modules/webgl/legacy/texture" },
{ "entry": "docs/modules/webgl/legacy/texture-2d" },
{ "entry": "docs/modules/webgl/legacy/texture-3d" },
{ "entry": "docs/modules/webgl/legacy/texture-cube" },
{ "entry": "docs/modules/webgl/legacy/transform-feedback" },
{ "entry": "docs/modules/webgl/legacy/uniform-buffer-layout" },
{ "entry": "docs/modules/webgl/legacy/vertex-array" },
{ "entry": "docs/modules/webgl/legacy/vertex-array-object" },
{ "entry": "docs/modules/webgl/legacy/resource" },
{ "entry": "docs/modules/webgl/legacy/context/feature-checking" },
{ "entry": "docs/modules/webgl/legacy/context/context-properties" },
{ "entry": "docs/modules/webgl/legacy/moving-data" },
{ "entry": "docs/modules/webgl/legacy/context" },
{ "entry": "docs/modules/webgl/legacy/parameter-setting" },
{ "entry": "docs/modules/webgl/legacy/device-pixels" }
{ "entry": "docs/modules/webgl" }
]
},
{

51
docs/whats-new.md
View File

@ -4,27 +4,48 @@
Target Date: Q1, 2022
The v9.0 release adds WebGPU support and a refreshed luma.gl API. While the changes under the hood are quite extensive,
luma.gl v9.0 should remain compatible with luma.gl 8.x. In addition, a range of APIs are now deprecated and it is recommended
to consult the upgrade guide before upgrading your applications.
The v9.0 release adds WebGPU support and a refreshed luma.gl API.
The changes under the hood are quite extensive, and many APIs have been changed to align more closely with WebGPU conventions and concepts. However all legacy v8 APIs are still available,
so luma.gl v9 should remain reasonably compatible with luma.gl v8 applications, with some caveats.
Please consult the upgrade guide before upgrading your applications.
The luma.gl documentation has been overhauled to focus on the new API. The classic API documentation is still available.
While the luma.gl documentation has been overhauled to focus on the new API,
the legacy API documentation is still available.
The deprecation status of a class or API is noted at the top of each page.
luma.gl v9 has also been updated with more rigorous typescript typings.
While the stronger types may trigger some new warnings during the upgrade process, the hope is that this will ultimately
save developers time and surprises by
automatically highlighting incorrect API usage during the upgrade process.
#### `@luma.gl/api` (new module)
- The new cross-platform luma.gl API is exposed through `@luma.gl/api` module. Applications written against this API can run on both WebGPU and WebGL2 devices.
- The new cross-platform luma.gl API is exposed through the new `@luma.gl/api` module. Applications written against this API can run on both WebGPU and WebGL2 devices.
#### `@luma.gl/engine`
- The classes and APIs in the `@luma.gl/engine` module (`Model`, `AnimationLoop` etc) are now fully portable and work on both WebGPU and WebGL.
#### `@luma.gl/webgpu` (new module)
- Provides a WebGPU implementation of the luma.gl API (`@luma.gl/api`). Importing this module enables the application to create `Device`s of type `'webgpu'`.
- Provides a WebGPU implementation of the luma.gl API (`@luma.gl/api`). Importing this module enables the application to create `Device`s of type `'webgpu'` (requires a browser that supports WebGPU).
#### `@luma.gl/webgl`
- Provides a WebGL / WebGL 2 implementation of the luma.gl API (`@luma.gl/api`). Importing this module enables the application to create `Device`s of type `'webgpu'`.
- The "classic" WebGL classes can still be imported directly from this module.
- TypeScript: the webgl module is more strongly typed.
- Debugging:the [Khronos WebGL developer tools](https://github.com/KhronosGroup/WebGLDeveloperTools) no longer need to be bundled. They are now automatically loaded from CDN when WebGL devices are created with `luma.createDevice({debug: true, type: 'webgl'})`
- Debugging: [Spector.js](https://spector.babylonjs.com/) is pre-integrated. If a `WebGLDevice` is created with `spector: true`, the Spector.js library will be dynamically loaded from CDN, the device canvas will be "captured", and luma.gl API metadata will exposed to the Spector UI.
- The webgl module has been deeply refactored and reorganized to make it smaller and more maintainable.
#### `@luma.gl/core`
- The core module still re-exports the classic luma.gl v8 API (from `@luma.gl/gltools`), to avoid breaking existing applications.
- Applications that want to start using the v9 API should import directly from `@luma.gl/engine` and `@luma.gl/api`.
#### `@luma.gl/gltools` (deprecated)
- The `@luma.gl/gltools` module is now deprecated. It now exports all legacy WebGL APIs and is no longer dedicate to just WebGL context-related utilities.
- The "classic" WebGL classes from luma.gl v8 can now be imported directly from this module.
- The old WebGL dependent `@luma.gl/engine` classes can still be imported from this module.
- The WebGL context related APIs exported by this module in v8 are now simple wrappers for the `WebGLDevice` class.
#### `@luma.gl/shadertools`
@ -33,14 +54,8 @@ The luma.gl documentation has been overhauled to focus on the new API. The class
#### `@luma.gl/debug`
- `makeDebugContext()` from `@luma.gl/debug` is deprecated. Khronos WebGL developer tools no longer need to be bundled, they are now dynamically loaded when WebGL devices are created with `luma.createDevice({debug: true, type: 'webgl'})`.
#### `@luma.gl/core`
- Re-exports of symbols from other luma.gl modules has been deprecated.
#### `@luma.gl/gltools` (deprecated)
- The `@luma.gl/gltools` module is deprecated. WebGL context related code has been moved into the `@luma.gl/webgl` module and the `WebGLDevice` class.
- Debugging:the [Khronos WebGL developer tools](https://github.com/KhronosGroup/WebGLDeveloperTools) no longer need to be bundled. They are now automatically loaded from CDN when WebGL devices are created with `luma.createDevice({debug: true, type: 'webgl'})`
- Debugging: [Spector.js](https://spector.babylonjs.com/) is pre-integrated. If a `WebGLDevice` is created with `spector: true`, the Spector.js library will be dynamically loaded from CDN, the device canvas will be "captured", and luma.gl API metadata will exposed to the Spector UI.
## Version 8.5

2
docs/api-reference/resources/external-texture.md → docs/wip/external-texture.md
View File

@ -1,5 +1,7 @@
# ExternalTexture
> This is the proposed new luma.gl v9 API, which is currently open for comments. It is available for testing using luma.gl v9 alpha releases.
> WebGPU only
While it is possible to use a normal `Texture` for a video element, the `ExternalTexture`

0
docs/api-guide/wip/parameters-legacy.md → docs/wip/parameters-legacy.md
View File

0
docs/api-guide/wip/parameters-upgrade.md → docs/wip/parameters-upgrade.md
View File

0
docs/api-guide/wip/parameters2.md → docs/wip/parameters2.md
View File