regl is a functional abstraction for WebGL that simplifies the process of creating and managing WebGL contexts and rendering pipelines. It provides a declarative API for defining shaders, buffers, and other WebGL resources, making it easier to build complex graphics applications.
Creating a WebGL Context
This code initializes a new regl instance, which sets up a WebGL context and prepares it for rendering.
const regl = require('regl')();Drawing a Simple Triangle
This code defines a simple triangle using regl. It specifies the vertex and fragment shaders, the vertex positions, and the draw call. The triangle is drawn in each frame.
const drawTriangle = regl({
frag: `
precision mediump float;
void main () {
gl_FragColor = vec4(1, 0, 0, 1);
}
`,
vert: `
precision mediump float;
attribute vec2 position;
void main () {
gl_Position = vec4(position, 0, 1);
}
`,
attributes: {
position: [
[-1, 0],
[0, -1],
[1, 1]
]
},
count: 3
});
regl.frame(() => {
regl.clear({
color: [0, 0, 0, 1],
depth: 1
});
drawTriangle();
});Managing Buffers
This code demonstrates how to create and use a buffer in regl. The buffer stores vertex positions, which are then used in the draw call.
const positionBuffer = regl.buffer([
[-1, 0],
[0, -1],
[1, 1]
]);
const drawWithBuffer = regl({
frag: `
precision mediump float;
void main () {
gl_FragColor = vec4(0, 1, 0, 1);
}
`,
vert: `
precision mediump float;
attribute vec2 position;
void main () {
gl_Position = vec4(position, 0, 1);
}
`,
attributes: {
position: positionBuffer
},
count: 3
});
regl.frame(() => {
regl.clear({
color: [0, 0, 0, 1],
depth: 1
});
drawWithBuffer();
});Using Uniforms
This code shows how to use uniforms in regl. The uniform 'color' is passed to the fragment shader, allowing dynamic control over the color of the rendered triangle.
const drawWithUniforms = regl({
frag: `
precision mediump float;
uniform vec4 color;
void main () {
gl_FragColor = color;
}
`,
vert: `
precision mediump float;
attribute vec2 position;
void main () {
gl_Position = vec4(position, 0, 1);
}
`,
attributes: {
position: [
[-1, 0],
[0, -1],
[1, 1]
]
},
uniforms: {
color: [0, 0, 1, 1]
},
count: 3
});
regl.frame(() => {
regl.clear({
color: [0, 0, 0, 1],
depth: 1
});
drawWithUniforms();
});Three.js is a popular JavaScript library for creating 3D graphics in the browser. It provides a higher-level abstraction compared to regl, making it easier to create complex 3D scenes with less code. However, it may not offer the same level of control and performance optimization as regl.
PixiJS is a 2D rendering engine that uses WebGL for high-performance graphics. It is designed for creating interactive graphics and games, offering a simpler API compared to regl. While it is more focused on 2D graphics, it can also handle some 3D rendering tasks.
Babylon.js is a powerful, open-source 3D engine that provides a comprehensive set of features for creating 3D applications. It offers a higher-level API than regl, making it easier to get started with 3D graphics, but it may not provide the same fine-grained control over WebGL resources.
regl simplifies WebGL programming by removing as much shared state as it can get away with. To do this, it replaces the WebGL API with two fundamental abstractions, resources and commands:
To define a command you specify a mixture of static and dynamic data for the object. Once this is done, regl takes this description and then compiles it into optimized JavaScript code. For example, here is a simple regl program to draw a triangle:
// Calling the regl module with no arguments creates a full screen canvas and
// WebGL context, and then uses this context to initialize a new REGL instance
const regl = require('regl')()
// Calling regl() creates a new partially evaluated draw command
const drawTriangle = regl({
// Shaders in regl are just strings. You can use glslify or whatever you want
// to define them. No need to manually create shader objects.
frag: `
precision mediump float;
uniform vec4 color;
void main() {
gl_FragColor = color;
}`,
vert: `
precision mediump float;
attribute vec2 position;
void main() {
gl_Position = vec4(position, 0, 1);
}`,
// Here we define the vertex attributes for the above shader
attributes: {
// regl.buffer creates a new array buffer object
position: regl.buffer([
[-2, -2], // no need to flatten nested arrays, regl automatically
[4, -2], // unrolls them into a typedarray (default Float32)
[4, 4]
])
// regl automatically infers sane defaults for the vertex attribute pointers
},
uniforms: {
// This defines the color of the triangle to be a dynamic variable
color: regl.prop('color')
},
// This tells regl the number of vertices to draw in this command
count: 3
})
// regl.frame() wraps requestAnimationFrame and also handles viewport changes
regl.frame(({time}) => {
// clear contents of the drawing buffer
regl.clear({
color: [0, 0, 0, 0],
depth: 1
})
// draw a triangle using the command defined above
drawTriangle({
color: [
Math.cos(time * 0.001),
Math.sin(time * 0.0008),
Math.cos(time * 0.003),
1
]
})
})
See this example live
Check out the gallery. The source code of all the gallery examples can be found here.
regl has no dependencies, so setting it up is pretty easy. There are 3 basic ways to do this:
To try out regl right away, you can use the live editor in the gallery.
The easiest way to use regl in a project is via npm. Once you have node set up, you can install and use regl in your project using the following command:
npm i -S regl
For more info on how to use npm, check out the official docs.
If you are using npm, you may also want to try budo which is a live development server.
By default if you compile regl with browserify then all error messages and run time checks are removed. This is done to reduce the size of the final bundle. If you are developing an application, you should run browserify using the --debug flag in order to enable error messages. This will also generate source maps which make reading the source code of your application easier.
You can also use regl as a standalone script if you are really stubborn. The most recent versions can be found in the dist/ folder and is also available from npm cdn in both minified and unminified versions.
There are some difference when using regl in standalone. Because script tags don't assume any sort of module system, the standalone scripts inject a global constructor function which is equivalent to the module.exports of regl:
<!DOCTYPE html>
<html>
<head>
<meta content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=0" name="viewport" />
<meta charset=utf-8>
</head>
<body>
</body>
<script language="javascript" src="https://npmcdn.com/regl/dist/regl.js"></script>
<script language="javascript">
var regl = createREGL()
regl.frame(function () {
regl.clear({
color: [0, 0, 0, 1]
})
})
</script>
</html>
reglregl just removes shared state from WebGL. You can do anything you could in regular WebGL with little overhead and way less debugging. regl emphasizes the following values:
regl has more than 30,000 unit tests and above 95% code coverage. In development mode, regl performs strong validation and sanity checks on all input data to help you catch errors faster.regl uses dynamic code generation and partial evaluation to remove almost all overhead.regl just wraps WebGL. It is not a game engine and doesn't have opinions about scene graphs or vector math libraries. Any feature in WebGL is accessible, including advanced extensions like multiple render targets or instancing.regl takes interface compatibility and semantic versioning seriously, making it well suited for long lived applications that must be supported for months or years down the road. It also has no dependencies limiting exposure to risky or unplanned updates.While regl is lower level than many 3D engines, code written in it tends to be highly compact and flexible. A comparison of regl to various other WebGL libraries across several tasks can be found here.
In order to prevent performance regressions, regl is continuously
benchmarked. You can run benchmarks locally using npm run bench or
check them out
online. The
results for the last few days can be found
here.
These measurements were taken using our custom scripts bench-history and
bench-graph. You can read more about them in the development guide.
The following is an incomplete list of projects using regl:
If you have a project using regl that isn't on this list that you would like to see added, please send us a pull request!
regl is still under active developement, and anyone willing to contribute is very much welcome to do so. Right now, what we need the most is for people to write examples and demos with the framework. This will allow us to find bugs and deficiencies in the API. We have a list of examples we would like to be implemented here, but you are of course welcome to come up with your own examples. To add an example to our gallery of examples, please send us a pull request!
regl has extensive API documentation. You can browse the docs online here.
The latest changes in regl can be found in the CHANGELOG.
For info on how to build and test headless, see the contributing guide here
All code (c) 2016 MIT License
Development supported by the Freeman Lab and the Howard Hughes Medical Institute (@freeman-lab on GitHub)
Many examples use creative commons or public domain artwork for illustrative purposes. These assets are not included in any of the redistributable packages of regl.
audio.js example is "Bamboo Cactus" by 8bitpeoples. CC BY-ND-NC 1.0 license1.5.0
FAQs
regl is a fast functional WebGL framework.
The npm package regl receives a total of 188,674 weekly downloads. As such, regl popularity was classified as popular.
We found that regl demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 5 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.
Security News
RubyGems.org has added a new "maintainer" role that allows for publishing new versions of gems. This new permission type is aimed at improving security for gem owners and the service overall.
Security News
Node.js will be enforcing stricter semver-major PR policies a month before major releases to enhance stability and ensure reliable release candidates.