WebGLazy
Responsive + configurable WebGL canvas replacement
How to Use
Browser
- Download ./dist/WebGLazy.min.js and add it to your project's files
- Add
<script src='WebGLazy.min.js'></script>to your page's<head>
Node
npm install webglazy --saveimport WebGLazy from 'webglazy';
Use
Add new WebGLazy(); somewhere in your code after your game's canvas has been initialized. If you're not sure where/when that happens, alternatively add a new tag that calls the same code after a short delay (e.g. <script>setTimeout(function(){new WebGLazy();}, 1000);</script>).
Configuration
WebGLazy behaviour can be configured by passing an options object into the constructor; e.g.:
new WebGLazy({
background: 'white',
scaleMode: WebGLazy.SCALE_MODES.COVER,
source: document.getElementById('myGameCanvas')
});-
source: Element to treat as a source for output; default: seesources -
sources: Ifsourceisn't provided, finds the first tag from this list of possible tags; default:['canvas', 'video', 'img'] -
hideSource: Iftrue, extra CSS is used to hide everything except the output canvas; default:true -
background: Background CSS applied to HTML, BODY, and canvasContainer element; default:'black' -
scaleMultiplier: Multiplier applied to size of source canvas; default:1 -
scaleMode: Defines the scaling behaviour of the output canvas; see Scale Modes for possible settings; default:WebGLazy.SCALE_MODES.FIT -
allowDownscaling: Allow scaling the output canvas smaller than the original size *scaleMultiplier(only applies when scaleMode isFITorCOVER); default:false -
autoInit: Callthis.initin constructor; default:true -
timestep: Target duration between frames (in milliseconds); default:1 / 60 * 1000, i.e. 60fps -
pixelate: Iftrue, usesGL_NEARESTandimage-rendering: pixelated; default:true -
disableFeedbackTexture: Disables a second texture, which contains a copy of the WebGL output; default:false -
disableMouseEvents: iftrue, MouseEvents triggered on the output canvas will not be dispatched on the source element; default:false -
vertex: Vertex shader source; default: a functional pass-through -
fragment: Frament shader source; default: a functional pass-through
Scale Modes
Scale modes define how the output canvas is scaled in relation to the screen size. Available scale modes are:
-
WebGLazy.SCALE_MODES.FIT: scale output canvas to fit screen (i.e. largest possible size with all content visible) -
WebGLazy.SCALE_MODES.COVER: scale output canvas to cover screen (i.e. smallest possible size with no background visible) -
WebGLazy.SCALE_MODES.MULTIPLES: scale up in multiples of original size (e.g. if the source's original size was 256x256 and the screen size is 1920x1080, the output canvas will be 1024x1024). This mode is particularly useful for upscaling pixel-art without artifacts. -
WebGLazy.SCALE_MODES.NONE: output canvas size doesn't scale with screen
Post-processing
Since WebGLazy renders to a WebGL canvas, simple post-processing shader support is made trivially easy!
Use the vertex and fragment options to override the default shaders.
Available uniforms:
uniform sampler2D tex0; // source
uniform sampler2D tex1; // output from last frame
uniform vec2 resolution; // size of output (uv coordinates = gl_FragCoord.xy / resolution)
uniform float time; // milliseconds since initialization (equal to performance.now())Example vertex shader:
// pass-through vertex shader
attribute vec4 position;
void main(){
gl_Position = position;
}Example fragment shader:
// uv-wave fragment shader
precision mediump float;
uniform sampler2D tex0;
uniform sampler2D tex1;
uniform float time;
uniform vec2 resolution;
void main(){
vec2 coord = gl_FragCoord.xy;
vec2 uv = coord.xy / resolution.xy;
uv.x += sin(uv.y * 10.0 + time / 200.0) / 60.0;
uv.y += cos(uv.x * 10.0 + time / 200.0) / 60.0;
vec3 col = texture2D(tex0,uv).rgb;
gl_FragColor = vec4(col, 1.0);
}Limitations
- Behaviour with multiple instances of
WebGLazyon a single page is undefined - If WebGL is not supported,
WebGLazywill fallback to 2D canvas rendering, which does not support shaders