luma.gl/dev-docs/tech-docs-wip/README-WEBGL.md

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

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

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