Regl Line

A regl function to conveniently draw flat 2D and 3D lines.

This small library is inspired by Regl's line example and Matt Deslauriers' wonderful blog post on drawing lines in WebGL.

Install

npm -i regl-line

Getting started

import createRegl from 'regl';
import createCamera from 'canvas-orbit-camera';
import createLine from 'regl-line';

// Setup the canvas
const canvas = document.getElementById('canvas');
const { width, height } = canvas.getBoundingClientRect();
canvas.width = width * resize.scale;
canvas.height = height * resize.scale;

// Setup Regl
const regl = createRegl(canvas);
const camera = createCamera(canvas);

// Create a line
const line = createLine(regl, {
  width: 2,
  color: [0.8, 0.2, 0.0, 1.0],
  is2d: true,
  // Flat list of normalized-device coordinates
  points: [-0.9, +0.9, +0.9, +0.9, +0.9, -0.9, -0.9, -0.9, -0.9, +0.85],
});

// Draw
regl.frame(() => {
  regl.clear({ color: [0, 0, 0, 1], depth: 1 });
  camera.tick();
  line.draw({ view: camera.view() });
});

For a complete example, see example/index.js.

Draw Multiple Lines At Once

To draw multiple lines, you can pass a list of lists of flat point coordinates to setPoints() or the constructor.

line.setPoints([
  [-0.8, +0.9, +0.8, +0.9], // top line
  [+0.9, +0.8, +0.9, -0.8], // right line
  [+0.8, -0.9, -0.8, -0.9], // bottom line
  [-0.9, -0.8, -0.9, +0.8], // left line
]);

Variable Line Color

To give each line an individual color, you have to do 2 things. First, you have to specify all the colors you plan to use.

line.setStyle({
  color: [
    [0, 1, 1, 1], // cyan
    [1, 1, 0, 1], // yellow
  ],
});

Next, when you set the points (with setPoints()), specify an array of indices to associate lines with your previously specified colors.

line.setPoints(points, {
  colorIndices: [
    0, //    top line will be cyan
    1, //  right line will be yellow
    0, // bottom line will be cyan
    1, //   left line will be yellow
  ],
});

Color Gradient

You could even go one step further and specify the color for each point on the line using a list of list of indices.

line.setPoints(points, {
  colorIndices: [
    [0, 0, 1, 1], //    top line will have a cyan to yellow gradient
    [1, 1, 0, 0], //  right line will have a yellow to cyan gradient
    [0, 1, 0, 1], // bottom line will have a cyan, yellow, cyan, yellow gradient
    [0, 1, 1, 0], //   left line will have a cyan, yellow, cyan gradient
  ],
});

Variable Line Opacity

To adjust, you can adjust the line width using

line.setPoints(points, {
  opacities: [
    0.25, //    top line will have an opacity of 0.25
    0.5, //  right line will have an opacity of 0.5
    0.75, // bottom line will have an opacity of 0.75
    1.0, //   left line will have an opacity of 1.0
  ],
});

Similar to color gradient, you can also specify the opacity for each point on the line using a list of list of numbers.

Variable Line Width

To adjust, you can adjust the line width using

line.setPoints(points, {
  widths: [
    1, //    top line will have a width of 1
    2, //  right line will have a width of 2
    3, // bottom line will have a width of 3
    4, //   left line will have a width of 4
  ],
});

Similar to color gradient, you can also specify the width for each point on the line using a list of list of numbers.

API

Constructor

# createLine(regl, options = {})

Create a line instance.

Args:

1. regl [regl]: Regl instance to be used for drawing the line.
2. options [object]: An object with the following props to customize the line creator.
   • projection [mat4]: projection matrix (Defaut: identity matrix)
   • model [mat4]: model matrix (Defaut: identity matrix)
   • view [mat4]: view matrix (Defaut: identity matrix)
   • points [array]: flat list of normalized-device coordinates alternating x,y if is2d is true or x,y,z. (Defaut: []). To draw multiple lines at once, pass in a list of lists of coordinates.
   • widths [array]: flat array of point-wise widths, i.e., the line width at every point. (Defaut: [])
   • color [array]: a quadruple of floats (RGBA) ranging in [0,1] defining the color of the line. (Defaut: [0.8, 0.5, 0, 1])
   • width [number]: uniform line width scalar. This number sets the base line width. (Defaut: 1)
   • miter [boolean]: if true line segments are miter joined. (Defaut: true)
   • is2d [boolean]: if true points are expected to have only x,y coordinates otherwise x,y,z coordinates are expected. (Defaut: false)
   • zPos2d [number]: if is2d is true this value defines the uniform z coordinate. (Defaut: 0)

Returns: line instance.

Methods

# line.clear()

Clears all of the data to remove the drawn line.

# line.destroy()

Destroys all related objects to free memory.

# line.draw({ projection, model, view })

Draws the line according to the projection, model, and view matrices.

Args:

1 options [object]:

• projection [mat4]: projection matrix (Defaut: identity matrix)
• model [mat4]: model matrix (Defaut: identity matrix)
• view [mat4]: view matrix (Defaut: identity matrix)

# line.getBuffer()

Get a reference to the point, width, and color index buffer objects. This can be useful for efficient animations.

Returns: { points, widths, colorIndices }

# line.getData()

Get a reference to the buffers' typed data arrays.

Returns: { points, widths, colorIndices }

# line.getPoints()

Get the original list of points defining the line.

Return: flat array of points

# line.getStyle()

Get all the style settings.

Returns: { color, miter, width }

# line.setPoints(points, widths, is2d)

Set points defining the line, the point-wise widths, and change the dimensionality.

Args:

1. points [array]: flat list of normalized-device coordinates alternating x,y if is2d is true or x,y,z. To draw multiple lines at once, pass in a list of lists of coordinates.
2. widths [array]: flat array of point-wise widths, i.e., the line width at every point.
3. is2d [boolean]: if true points are expected to have only x,y coordinates otherwise x,y,z coordinates are expected.

# line.setStyle({ color, miter, width })

Args:

1. option [object]:
   • color [array]: a quadruple of floats (RGBA) ranging in [0,1] defining the color of the line.
   • width [number]: uniform line width scalar. This number sets the base line width.
   • miter [boolean]: if true line segments are miter joined.