@luma.gl/engine

What is @luma.gl/engine?

@luma.gl/engine is a high-performance WebGL2 framework designed for GPU-powered data visualization and graphics rendering. It provides a suite of tools and abstractions to simplify the creation of complex 3D scenes, animations, and visual effects.

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

Creating a WebGL Context

This feature allows you to create and manage a WebGL context using the AnimationLoop class. The onInitialize method is used to set up the WebGL context, and the onRender method is used to render each frame.

const {AnimationLoop} = require('@luma.gl/engine');

const animationLoop = new AnimationLoop({
  onInitialize: ({gl}) => {
    // Initialize WebGL context
  },
  onRender: ({gl}) => {
    // Render frame
  }
});

animationLoop.start();

Loading and Displaying a 3D Model

This feature allows you to load and display a 3D model using the Model and Geometry classes. You can define the vertex and fragment shaders, as well as the geometry attributes like positions and normals.

const {Model, Geometry} = require('@luma.gl/engine');

const model = new Model(gl, {
  vs: `...`, // Vertex shader
  fs: `...`, // Fragment shader
  geometry: new Geometry({
    attributes: {
      positions: new Float32Array([...]),
      normals: new Float32Array([...])
    }
  })
});

model.draw();

Handling User Input

This feature allows you to handle user input events such as mouse clicks and keyboard presses using the EventManager class. You can attach event listeners to the canvas and respond to user interactions.

const {EventManager} = require('@luma.gl/engine');

const eventManager = new EventManager(canvas);

eventManager.on('click', (event) => {
  console.log('Canvas clicked', event);
});

Other packages similar to @luma.gl/engine

three

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

babylonjs

Babylon.js is another powerful 3D engine for rendering graphics in the browser. It offers a comprehensive set of features for game development, including physics, animations, and advanced materials. Compared to @luma.gl/engine, Babylon.js provides more out-of-the-box functionality but may be less flexible for custom rendering techniques.

pixi.js

PixiJS is a 2D rendering engine that can also handle some 3D graphics. It is optimized for performance and ease of use, making it a good choice for creating interactive applications and games. While it is not as focused on 3D rendering as @luma.gl/engine, it offers a simpler API for 2D and basic 3D graphics.

README

Shader Module: Picking

Provides support for color-coding-based picking and highlighting. In particular, supports picking a specific instance in an instanced draw call and highlighting an instance based on its picking color, and correspondingly, supports picking and highlighting groups of primitives with the same picking color in non-instanced draw-calls

Color based picking lets the application draw a primitive with a color that can later be used to index this specific primitive.

Highlighting allows application to specify a picking color corresponding to an object that need to be highlighted and the highlight color to be used.

Usage

In your vertex shader, your inform the picking module what object we are currently rendering by supplying a picking color, perhaps from an attribute.

in vec3 aPickingColor;
main() {
  picking_setColor(aPickingColor);
  ...
}

In your fragment shader, you simply apply (call) the picking_filterColor filter function at the very end of the shader. This will return the normal color, or the highlight color, or the picking color, as appropriate.

main() {
  fragColor = ...
  fragColor = picking_filterColor(color);
}

If highlighting is not needed, you simply apply (call) the picking_filterPickingColor filter function at the very end of the shader. This will return the normal color or the picking color, as appropriate.

main() {
  fragColor = ...
  fragColor = picking_filterPickingColor(fragColor);
}

If additional filters need to be applied on the non-picking color (vertex or highlight color) you can use above functions in following order.

main() {
  fragColor = ...
  fragColor = picking_filterHighlightColor(fragColor);
   ... apply any filters on fragColor ...
 fragColor = picking_filterPickingColor(fragColor);
}

JavaScript Functions

getUniforms

getUniforms takes an object with key/value pairs, returns an object with key/value pairs representing the uniforms that the picking module shaders need.

getUniforms(opts) opts can contain following keys:

• pickingSelectedColorValid (boolean) - When true current instance picking color is ignored, hence no instance is highlighted.
• pickingSelectedColor (array) - Picking color of the currently selected instance.
• pickingHighlightColor (array)- Color used to highlight the currently selected instance.
• pickingActive=false (boolean) - When true, renders the picking colors instead of the normal colors. Normally only used with an off-screen framebuffer during picking. Default value is false.

Note that the selected item will be rendered using pickingHighlightColor, if blending is enabled for the draw, alpha channel can be used to control the blending result.

Vertex Shader Functions

void picking_setPickingColor(vec3)

Sets the color that will be returned by the fragment shader if color based picking is enabled. Typically set from a pickingColor uniform or a pickingColors attribute (e.g. when using instanced rendering, to identify the actual instance that was picked).

Fragment Shader Functions

picking_filterPickingColor

If picking active, returns the current vertex's picking color set by picking_setPickingColor, otherwise returns its argument unmodified.

vec4 picking_filterPickingColor(vec4 color)

picking_filterHighlightColor

Returns picking highlight color if the pixel belongs to currently selected model, otherwise returns its argument unmodified.

vec4 picking_filterHighlightColor(vec4 color)

Remarks

• It is strongly recommended that picking_filterPickingColor is called last in a fragment shader, as the picking color (returned when picking is enabled) must not be modified in any way (and alpha must remain 1) or picking results will not be correct.

Changelog

9.1.0-alpha.19

• webgl: clip image write based on texture size (#2234)