2022-02-06 13:21:32 -08:00
..

@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 class.

| ----------------------------------- | ============== | =============== | | Resource Class | WebGL Type | Description | | ----------------------------------- | ============== | =============== | | Buffer | WebGLBuffer | Holds memory on GPU | | Framebuffer | WebGLFrameBuffer | Off-screen render target, Container for textures and renderbuffers. | | Renderbuffer | WebGLRenderBuffer | Holds image data that is optimized for rendering but does not supporting sampling | | Program | WebGLProgram | Shaders, attributes and uniforms. | | Shader | WebGLShader | Holds a compiled GLSL shader program. | | Texture2D | WebGLTexture(GL.TEXTURE_2D) | Holds a loaded texture in a format that supports sampling | | TextureCube | WebGLTexture(GL.TEXTURE_CUBE) | Holds 6 textures | | WebGLTexture(GL.TEXTURE_2D_ARRAY) | Holds an array of textures | | Texture3D WebGL2 | WebGLTexture(GL.TEXTURE_3D) | Holds a stack of textures | | Query WebGL2/ext* | WebGLQuery | Occlusion, Tranform Feedback and Performance Queries | | WebGLSampler | Stores texture sampling params | | Sync WebGL2 | WebGLSync | Synchronize GPU and app. | | TransformFeedback WebGL2 | WebGLTransformFeedback | Capture Vertex Shader output | | VertexArrayObject WebGL2/ext | WebGLVertexArrayObject | Save global vertex attribute array. |

| ----------------------------------- | ============== | =============== | | Class/Module | WebGL Type | Description | | ----------------------------------- | ============== | =============== | | context | WebGLRenderingContext | The main GL context. | | VertexAttributes | gl.vertexAttrib* | Manipulates shader attributes (TBD merge with VAO?) |

Class/Module WebGL Type Description
createGLContext WebGLRenderingContext The main GL context.
Buffer WebGLBuffer Holds memory on GPU
FrameBuffer WebGLFrameBuffer Holds a framebuffer
RenderBuffer WebGLRenderBuffer Holds a renderbuffer
Program WebGLProgram Shaders, attributes and uniforms.
Shader WebGLShader Shaders, attributes and uniforms.
Texture2D WebGLTexture(GL.TEXTURE_2D) Holds a loaded texture
TextureCube WebGLTexture(GL.TEXTURE_CUBE) Holds a loaded texture
Texture2DArray WebGL2 WebGLTexture(GL.TEXTURE_2D_ARRAY) Holds a loaded texture
Texture3D WebGL2 WebGLTexture(GL.TEXTURE_3D) Holds a loaded texture
Query WebGL2/ext WebGLQuery Occlusion, Tranform Feedback and Performance Queries
Sampler WebGL2 WebGLSampler Stores texture sampling params
Sync WebGL2 WebGLSync Synchronize GPU and app.
TransformFeedback WebGL2 WebGLTransformFeedback Capture Vertex Shader output
VertexArrayObject WebGL2/ext WebGLVertexArrayObject Save global vertex attribute array.
VertexAttributes gl.vertexAttrib* Manipulates shader attributes (TBD merge with VAO?)
VertexAttributes gl.vertexAttrib* 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.