Renderer

Complete API reference for the Renderer class

The Renderer class is the main entry point for Phenomenon. It manages the WebGL context, handles the render loop, and orchestrates multiple particle instances.

Constructor

Creates a new Renderer instance with the specified configuration.

new Renderer(props?: RendererProps)

props · RendererProps

Configuration options for the renderer

Show properties

canvas · HTMLCanvasElement · default: "document.querySelector('canvas')"

The canvas element to render to. If not provided, Phenomenon will use the first canvas element found in the document.

context · object · default: "{}"

WebGL context attributes passed to getContext(). By default, Phenomenon sets alpha: false and antialias: false.

contextType · string · default: "'experimental-webgl'"

The type of WebGL context to create. You can use 'webgl' or 'experimental-webgl'.

settings · object · default: "{}"

Additional renderer settings that override defaults.

Show available settings

devicePixelRatio · number · default: "1"

Controls canvas resolution scaling. Set to window.devicePixelRatio for high-DPI displays.

clearColor · [number, number, number, number] · default: "[1, 1, 1, 1]"

Background color as RGBA values (0-1 range). Default is white.

position · { x: number; y: number; z: number } · default: "{ x: 0, y: 0, z: 2 }"

Camera position in 3D space.

clip · [number, number] · default: "[0.001, 100]"

Near and far clipping planes for the perspective projection.

onSetup · (gl: WebGLRenderingContext) => void

Callback invoked once before the first render. Use this to modify the WebGL context.

shouldRender · boolean · default: "true"

Whether the scene should start rendering automatically. Set to false to manually control rendering.

uniforms · object · default: "{}"

Shared uniforms available to all instances. By default includes uProjectionMatrix, uModelMatrix, and uViewMatrix.

onSetup · (gl: WebGLRenderingContext) => void

Callback invoked once before the first render. Use this to modify the WebGL context.

onRender · (renderer: Renderer) => void

Callback invoked on every frame after all instances have rendered.

debug · boolean · default: "false"

Enable debug mode to log shader compilation errors to the console.

Example

import Renderer from 'phenomenon';

const renderer = new Renderer({
  canvas: document.querySelector('#canvas'),
  context: {
    alpha: true,
    antialias: true,
  },
  settings: {
    devicePixelRatio: window.devicePixelRatio,
    clearColor: [0, 0, 0, 1],
    position: { x: 0, y: 0, z: 3 },
    onRender: (renderer) => {
      // Update uniforms or perform calculations each frame
    },
  },
  debug: true,
});

Methods

add()

Adds a new particle instance to the renderer.

add(key: string, settings: InstanceProps): Instance

key · string · required

Unique identifier for this instance. Used to reference or remove the instance later.

settings · InstanceProps · required

Configuration for the particle instance. See the Instance page for all available options.

return · Instance

Returns the created Instance object.

Example

const instance = renderer.add('particles', {
  vertex: `
    attribute vec3 aPosition;
    uniform mat4 uProjectionMatrix;
    uniform mat4 uModelMatrix;
    uniform mat4 uViewMatrix;
    
    void main() {
      gl_Position = uProjectionMatrix * uModelMatrix * uViewMatrix * vec4(aPosition, 1.0);
      gl_PointSize = 2.0;
    }
  `,
  fragment: `
    precision mediump float;
    
    void main() {
      gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
    }
  `,
  mode: 0,
  multiplier: 10000,
});

remove()

Removes an instance from the renderer and destroys its resources.

remove(key: string): void

key · string · required

The unique identifier of the instance to remove.

Example

renderer.remove('particles');

resize()

Manually triggers a resize event. This recalculates the canvas dimensions, viewport, and projection matrices.

resize(): void

You typically don’t need to call this manually, as Phenomenon automatically handles window resize events.

Example

renderer.resize();

toggle()

Starts or stops the render loop.

toggle(shouldRender?: boolean): void

shouldRender · boolean

If true, starts rendering. If false, stops rendering. If not provided, toggles the current state.

Example

// Stop rendering
renderer.toggle(false);

// Resume rendering
renderer.toggle(true);

// Toggle current state
renderer.toggle();

render()

Manually renders a single frame. This clears the canvas and renders all instances.

render(): void

You typically don’t need to call this manually, as it runs automatically in a requestAnimationFrame loop.

Example

renderer.render();

destroy()

Destroys the renderer and all its instances, cleaning up WebGL resources and stopping the render loop.

destroy(): void

Example

renderer.destroy();

Properties

The Renderer instance exposes these public properties:

gl · WebGLRenderingContext

The WebGL rendering context.

canvas · HTMLCanvasElement

The canvas element being rendered to.

instances · Map<string, Instance>

Map of all active instances, keyed by their identifier.

uniforms · { [key: string]: UniformProps }

Shared uniforms available to all instances. Automatically includes uProjectionMatrix, uModelMatrix, and uViewMatrix.

shouldRender · boolean

Whether the render loop is active.

devicePixelRatio · number

The current device pixel ratio used for canvas scaling.

clearColor · [number, number, number, number]

The current background color as RGBA values.

position · { x: number; y: number; z: number }

The current camera position.

clip · [number, number]

Near and far clipping planes.