AnimationLoop

While this class is named to suggest that it is a wrapper for requestAnimationFrame, it provides a number of features related to initialization and animation of a WebGLRenderingContext.

Makes it easy to wait for the HTML page to load before creating resources.
Provides a number of commonly needed variables to the renderFrame method as part of the context object.
By default, manages resizing of canvas and viewport which is usually all that simpler apps and demos need. Advanced apps can override.

Usage

Short example:

new AnimationLoop({
  onCreateContext() {
    return createGLContext({canvas: 'canvas-0'}))
  },
  onInitialize({gl}) {
    return {
      clipSpaceQuad: new ClipSpaceQuad({gl, fs: CONTEXT_0_FRAGMENT_SHADER})
    };
  },
  onRenderFrame({tick, clipSpaceQuad}) {
    clipSpaceQuad.render({uTime: tick * 0.01});
  }
});

To avoid problems with page load timing, move context creation to the initContext method. Also the setupFrame method enables the app to control the resizing of canvas, framebuffer and viewport.

new AnimationLoop()
  onCreateContext() {
    return createGLContext({canvas: 'canvas-0'});
  },
  onInit(({gl}) => ({
    clipSpaceQuad: new ClipSpaceQuad({gl, fs: CONTEXT_0_FRAGMENT_SHADER})
  }.
  onInitFrame({gl, canvas}) {
    canvas.width = canvas.clientWidth;
    canvas.style.height = `${canvas.width}px`;
    canvas.height = canvas.width;
    gl.viewport(0, 0, canvas.width, canvas.height);
  },
  onDrawFrame({tick, clipSpaceQuad}) {
    clipSpaceQuad.render({uTime: tick * 0.01});
  }
});

Callback Parameters

The callbacks that the app supplies to the AnimationLoop will be called with an object containing named parameters. The parametre object will contain the following values:

gl - This AnimationLoop's WebGLRenderingContext.
canvas - The canvas associated with the rendering context.
width: The canvas width, in device pixels.
height: The canvas height, in device pixels.
aspect: The canvas aspect ratio (width/height) to update projection matrices
pixelRatio: Pixel ratio of the canvas drawingBuffer.
time: A monotonic value in milliseconds since AnimationLoop was created.
tick: A monotonic counter that updates 60 times per second.
tock: A monotonic counter that updates for every frame rendered.

Methods

constructor

Parameters:

onInitialize (callback) - function that will be called exactly once after start() has been called, after page load completes and a context has been created. The callback will be called with an initial object containing a gl context object. Can return a promise (e.g. for texture or model loads)
onSetupFrame (callback) - Supplying this callback overrides the default frame setup code, which resizes the canvas and the viewport after the window size. For applications that use a single full screen canvas, this function is usually not needed.
onRenderFrame (callback) - Calling frame will automatically start the animation. If this is not desired, follow immediately with a stop().
onCreateContext (callback) - function without parameters that returns a WebGLRenderingContext. This callback will be called exactly once, after page load completes.

Remarks:

Postpones context creation until the page (i.e. all HTML) has been loaded. At this time it is safe to specify canvas ids when calling createGLContext.
The supplied callback function must return a WebGLRenderingContext or an error will be thrown.
This callback registration function should not be called if a WebGLRenderingContext was supplied to the AnimationLoop constructor.

start

Restarts the animation

stop

Stops the animation

Remarks

You can instantiate multiple AnimationLoop classes in parallel, rendering into the same or different WebGLRenderingContexts.
Works both in browser and under Node.js.
All AnimationLoop methods can be chained.

3.9 KiB Raw Blame History