Table of Contents
- shaderWebBackground.shade(config)
- Config
- Context
- shaderWebBackground.Error
- shaderWebBackground.ConfigError
- shaderWebBackground.GlError
ℹ️ The detailed API is defined in src/main/js/shader-web-background-api.js as Closure Compiler externs.
Shading starts with the shaderWebBackground.shade(config) call which requires
providing a Config object and returns a Context object.
The processing of configuration and shader compilation will start immediately, however the animation frames will be requested only when the page is loaded.
This function might throw shaderWebBackground.Errors of type:
- shaderWebBackground.ConfigError - on misconfiguration
- shaderWebBackground.GlError - on lack of required WebGL capabilities
An object with the following attributes:
| attribute (* - required) | type (=: optional argument) |
description |
|---|---|---|
| canvas | HTMLCanvasElement | canvas to render to |
| onInit | function(Context=) | called before first run |
| onResize | function(number, number, Context=) | called when the canvas is resized |
| onBeforeFrame | function(Context=) | called before each frame |
| shaders * | Object of Shaders | definition of shaders (rendering pipeline) |
| onAfterFrame | function(Context) | called when the frame is complete |
| onError | function(Error, HTMLCanvasElement) | called when shading cannot be started |
Only shaders attribute is required. The order of attributes is arbitrary, but in this table they are sorted by a convenient order of their "lifecycle" in the rendering of each frame.
If canvas attribute is not specified, the default one will be created, with
fixed position expending over the whole viewport and located behind other
DOM elements (z-index: -9999).
The onInit function is called when the shader is loaded for the first time, before
any rendering starts. The Context is passed as an argument.
The onResize function is called with width, height and Context
parameters when the browser window is resized.
ℹ️ Note: onResize will be also called before the first frame
just after Config: onInit.
The onBeforeFrame function is called with the Context before rendering each frame.
The shaders is the only required attribute of the Config object. It's an object where
each attribute represents one shader definition, therefore multiple
shaders can be defined in sequence. All together they will establish a rendering pipeline
where the output of each shader can be wired as an input of another.
Example:
shaderWebBackground.shade({
shaders: {
BufferA: {
uniforms: {
iChannel0: (gl, loc, ctx) => ctx.texture(loc, ctx.buffers.BufferA) // previous frame of self
}
},
BufferB: {
uniforms: {
iChannel0: (gl, loc, ctx) => ctx.texture(loc, ctx.buffers.BufferA), // the latest output of BufferA
iChannel1: (gl, loc, ctx) => ctx.texture(loc, ctx.buffers.BufferB) // previous frame of self
}
},
Image: {
uniforms: {
iChannel0: (gl, loc, ctx) => ctx.texture(loc, ctx.buffers.BufferA), // the latest output
iChannel1: (gl, loc, ctx) => ctx.texture(loc, ctx.buffers.BufferB) // the latest output
}
}
}
});ℹ️ Note: shader names are arbitrary. The last shader will render to screen, the previous ones (if more than one) to offscreen buffers. See Shader: uniforms
An object with the following attributes:
| attribute (* - required) | type | description |
|---|---|---|
| texture | function(WebGLRenderingContext, Context) | texture initializer |
| uniforms * | Object of Uniform setters | uniform setters |
Optional texture initializer called with WebGLRenderingContext and Context arguments. Here is the default initializer:
(gl, ctx) => {
ctx.initHalfFloatRGBATexture(ctx.width, ctx.height);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
}vec4 repeatedTexture(in sampler2D sampler, in vec2 uv) {
return texture2D(sampler, mod(uv, 1.));
}
// or
#define repeatedTexture(sampler, uv) texture2D(sampler, mod(uv, 1.))See WebGLTexture, Context: initHalfFloatRGBATexture
An object where an attribute name should match a shader uniform name, and an attribute value represents a uniform setter function.
A function called with WebGLRenderingContext, WebGLUniformLocation of the uniform it belongs to and Context. It is intended to use all the provided arguments to effectively set uniform value.
Example 1 - setting floating-point value kept in JavaScript time variable:
(gl, loc) => gl.uniform1f(loc, time)ℹ️ Note: the last argument of type Context is often not used and can be omitted in declaration, like in the example above.
Example 2 - setting resolution:
(gl, loc, ctx) => gl.uniform2f(loc, ctx.width, ctx.height)See WebGLRenderingContext.uniform specification for details.
Example 3 - setting other shader's output as input texture:
(gl, loc, ctx) => ctx.texture(loc, ctx.buffers.BufferA)See Context: buffers
Example 4 - setting texture:
(gl, loc, ctx) => gl.texture(loc, webCamTexture)Where webCamTexture is an instance of WebGLTexture.
The onAfterFrame function is called after processing all the shaders.
The onError function is called in case of any Error which occurs while handling
the shadeWebBackground.shade(config) call. It
be called with the Error and the canvas as arguments.
An object with the following attributes:
| attribute | type | description |
|---|---|---|
| gl | WebGLRenderingContext | handle for WebGL calls |
| canvas | HTMLCanvasElement | the canvas being shaded |
| width | number | device pixel width |
| height | number | device pixel height |
| cssPixelRatio | number | device pixel / CSS pixel |
| cssWidth | number | width in CSS pixels |
| cssHeight | number | height in CSS pixels |
| isOverShader | function(number, number): boolean | checks if mouse is over shader |
| toShaderX | function(number): number | CSS x coordinate to shader x . |
| toShaderY | function(number): number | CSS y coordinate to shader y |
| buffers | Object | buffers of offscreen shaders |
| texture | function(WebGLUniformLocation, (WebGLTexture|Buffer)) | binds texture as a uniform |
| initHalfFloatRGBATexture | function(number, number) | init floating-point RGBA texture |
ℹ️ Note: this object is passed as an argument to many functions and it is also returned by the shaderWebBackground.shade(config) call.
The HTML canvas element associated with this context.
The "pixel" width of the canvas, might differ from the cssWidth.
Typically used together with the height attribute.
The "pixel" height of the canvas, might differ from the cssHeight.
Example usage:
shaderWebBackground.shade({
shaders: {
image: {
uniforms: {
iResolution: (gl, loc, ctx) => gl.uniform2f(loc, ctx.width, ctx.height)
}
}
}
});The ratio of "CSS pixels" comparing to real "pixels", might be necessary for some calculations, for example simulation of background scrolling, possibly with parallax scrolling:
shaderWebBackground.shade({
onBeforeFrame: (ctx) => {
ctx.iVerticalShift = window.scrollY * ctx.cssPixelRatio;
},
shaders {
scrollableBackground: {
uniforms: {
iVerticalShift: (gl, loc, ctx) => gl.uniform1f(loc, ctx.iVerticalShift)
}
}
}
});The width of the canvas as reported by the browser, might differ from the pixel width.
The height of the canvas as reported by the browser, might differ from the pixel height.
A helper function to tell if provided coordinates are within the rectangle of shader canvas. Not very useful for full screen shaders, but might be handy for smaller canvases.
Translates horizontal CSS coordinate (e.g. mouse pointer position) to corresponding pixel coordinate of this shader.
Translates vertical CSS coordinate (e.g. mouse pointer position) to corresponding pixel coordinate of this shader.
(0, 0) is located in the bottom-left
corner, so the Y-axis is reversed. Actual coordinate passed to the shader
in gl_FragCoord is actually in the middle of the pixel, therefore in case of
a background shader covering the whole browser window the bottom-left corner
pixel will receive values (.5, .5). The getCoordinate[X|Y] functions account
for this as well.
An object representing offscreen buffers of all the shaders except for the last one in the rendering pipeline. The attribute names match the shader names, except for the last shader which is rendering to screen not to a buffer.
It's a placeholder object referencing the offscreen double buffer of a shader.
See Shader uniforms section to check how it is being used.
A function to bind uniforms of type sampler2D.
A function to initialize a texture where each pixel RGBA values have
floating-point precision. It takes width and height as parameters.
Example usage:
shaderWebBackground.shade({
shaders: {
feedback: {
texture: (gl, ctx) => {
ctx.initHalfFloatRGBATexture(ctx.width, ctx.height);
// standard WebGL texture parameters
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.NEAREST);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.REPEAT);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.REPEAT);
}
}
}
});A base class to indicate problems with the the shaderWebBackground.shade(config) call.
See Config: onError and README: Handling errors.
Extends shaderWebBackground.Error to indicate misconfiguration of the shaderWebBackground.shade(config) call.
See Config: onError and README: Handling errors.
Extends shaderWebBackground.Error to indicate that the shaderWebBackground.shade(config) call cannot be satisfied due to lack of WebGL capabilities of the browser (might be a hardware limitation).
See Config: onError and README: Handling errors.