@luma.gl/webgl

What is @luma.gl/webgl?

@luma.gl/webgl is a WebGL framework that provides a set of tools and utilities for working with WebGL. It is designed to simplify the process of creating high-performance 3D graphics applications in the browser. The package offers a range of features including context creation, shader management, buffer handling, and more.

What are @luma.gl/webgl's main functionalities?

Context Creation

This feature allows you to create a WebGL context, which is the starting point for any WebGL application. The code sample demonstrates how to create a WebGL context using a canvas element.

const {createGLContext} = require('@luma.gl/webgl');
const canvas = document.createElement('canvas');
const gl = createGLContext({canvas});

Shader Management

This feature provides utilities for managing shaders, which are essential for rendering graphics in WebGL. The code sample shows how to create vertex and fragment shaders using the @luma.gl/webgl package.

const {Shader} = require('@luma.gl/webgl');
const vertexShaderSource = `
  attribute vec4 position;
  void main() {
    gl_Position = position;
  }
`;
const fragmentShaderSource = `
  void main() {
    gl_FragColor = vec4(1, 0, 0, 1);
  }
`;
const vertexShader = new Shader(gl, {source: vertexShaderSource, shaderType: gl.VERTEX_SHADER});
const fragmentShader = new Shader(gl, {source: fragmentShaderSource, shaderType: gl.FRAGMENT_SHADER});

Buffer Handling

This feature allows you to create and manage buffers, which are used to store vertex data. The code sample demonstrates how to create a buffer and upload vertex positions to it.

const {Buffer} = require('@luma.gl/webgl');
const positions = new Float32Array([
  -1, -1,
   1, -1,
  -1,  1,
   1,  1
]);
const positionBuffer = new Buffer(gl, {data: positions});

Other packages similar to @luma.gl/webgl

three

Three.js is a popular JavaScript library for creating 3D graphics in the browser. It provides a higher-level API compared to @luma.gl/webgl, making it easier to create complex 3D scenes with less code. However, it may offer less control over low-level WebGL operations.

babylonjs

Babylon.js is another powerful 3D engine for the web. It offers a comprehensive set of features for creating 3D games and applications, including physics, animations, and more. Like Three.js, it provides a higher-level API compared to @luma.gl/webgl.

pixi.js

PixiJS is a 2D rendering engine that can also handle some 3D graphics. It is designed for high-performance rendering and is often used for creating interactive graphics and games. While it focuses more on 2D, it can be a good alternative for simpler 3D tasks.

README

@luma.gl/webgl

This module contains a set of JavaScript class wrappers for the WebGL2 API.

webgl-utils

This luma.gl sub-module contains a number of completely generic WebGL helper functions that luma.gl relies on. They are independent of the luma.gl API and of each other, and could possibly be of generic interest for other webgl programs or frameworks that don't want to use luma.gl itself.

Since all luma.gl code is MIT licensed you are of course welcome to copy these into your projects should you find them helpful.

Canvas Management

The canvas manages the default drawing buffer including the size of the default drawing buffer, so the canvas typically needs to be updated when the window resizes

getPageLoadPromise

Returns a promise that resolves when the page's HTML has loaded (meaning that any canvas specified in the HTML can now be queried by id).

createCanvas

Programatically creates a canvas element with a certain size and id, and inserts it into the documents body once the page is loaded (see getPageLoadPromise).

createContext

Gives a controlled interface to create a WebGL1 or WebGL2 context from a canvas.

GLSL Error Parser

formatGLSLError

A formatter for parsing errors and warnings from the GLSL compiler. see parseGLSLError.

• errLog (String) - error log (from gl.getShaderInfoLog)
• src (String) - original shader source code
• shaderType (Number) - shader type (GL constant) Return (String) - Formatted string, has the error marked inline with src.

parseGLSLError

A parse for GLSL compiler error logs. Note that the format of the error logs generated by the GLSL compiler is defined the WebGL spec, so it is possible to portably parse these logs.

This function formats each GLSL shader compiler error or warning and generates text showing the source code around the error with marks pointing out where the issue was encountered.

• errLog (String) - error log (from gl.getShaderInfoLog)
• src (String) - original shader source code
• shaderType (Number) - shader type (GL constant) Return (object) - with shaderName, errors and warnings fields (all strings).

WebGL Constants

GL (namespace)

All WebGL2 and extension constants exported as a single namespace GL. Allows constants to be referenced without tracking which version of WebGL or what extensions are available.

getKeyValue

Resolves a WebGL enumeration name (returns itself if already a number)

getKeyValue(gl, name)

• gl (WebGLRenderingContext) - gl context
• name (String)

getKeyValue

Returns a key that matches the number.

getKey(gl, value)

• gl (WebGLRenderingContext) - gl context

Changelog

8.0.0-beta.2

• Export fp64-arithmetic shader module (#1309)
• Upgrade probe.gl (#1310)