Types

TypeScript interfaces and types for Phenomenon

Phenomenon is written in TypeScript and exports several interfaces for type-safe usage. This page documents all available types.

RendererProps

Configuration options for creating a Renderer instance.

interface RendererProps {
  canvas?: HTMLCanvasElement;
  context?: object;
  contextType?: string;
  settings?: object;
  debug?: boolean;
}

canvas · HTMLCanvasElement

The canvas element to render to. Defaults to document.querySelector('canvas').

context · object

WebGL context attributes passed to canvas.getContext(). Common attributes include alpha, antialias, depth, stencil, etc.

contextType · string

WebGL context type. Defaults to 'experimental-webgl'. Use 'webgl' or 'webgl2' for other contexts.

settings · object

Additional renderer settings including devicePixelRatio, clearColor, position, clip, onSetup, and onRender.

debug · boolean

Enable shader compilation error logging. Defaults to false.

InstanceProps

Configuration options for creating a particle instance via renderer.add().

interface InstanceProps {
  attributes?: Array<AttributeProps>;
  vertex?: string;
  fragment?: string;
  geometry?: GeometryProps;
  mode?: number;
  modifiers?: object;
  multiplier?: number;
  uniforms: {
    [key: string]: UniformProps;
  };
}

attributes · AttributeProps[]

Custom vertex attributes for per-particle data. See AttributeProps.

vertex · string

GLSL vertex shader source code.

fragment · string

GLSL fragment shader source code.

geometry · GeometryProps

Base geometry for each particle. See GeometryProps.

mode · number

WebGL drawing mode. 0 for POINTS, 4 for TRIANGLES, etc. Defaults to 0.

modifiers · object

Functions that modify attribute values. Keys are attribute names, values are modifier functions.

multiplier · number

Number of times to repeat the geometry (i.e., number of particles). Defaults to 1.

uniforms · { [key: string]: UniformProps }

Shader uniforms. Defaults to an empty object if not provided. See UniformProps.

onRender · (instance: Instance) => void

Optional callback invoked after each frame. Use this to update uniforms or perform instance-specific calculations.

AttributeProps

Defines a custom vertex attribute.

interface AttributeProps {
  name: string;
  size: number;
  data?: any;
}

name · string · required

Attribute name as used in the vertex shader (e.g., aOffset, aVelocity).

size · number · required

Number of components per attribute. Use 1 for float, 2 for vec2, 3 for vec3, 4 for vec4.

data · (index: number, total: number) => number[]

Optional function that returns attribute data for each particle. Called once per particle with the particle index and total count.

Usage

const offsetAttribute: AttributeProps = {
  name: 'aOffset',
  size: 3,
  data: (i, total) => [
    Math.random() * 2 - 1,
    Math.random() * 2 - 1,
    Math.random() * 2 - 1,
  ],
};

UniformProps

Defines a shader uniform.

interface UniformProps {
  type: string;
  value: Array<number>;
  location?: WebGLUniformLocation;
}

type · string · required

Uniform type. Supported types: 'float', 'vec2', 'vec3', 'vec4', 'mat2', 'mat3', 'mat4'.

value · number[] · required

Uniform value as an array of numbers. Length must match the type (1 for float, 2 for vec2, 3 for vec3, etc.).

location · WebGLUniformLocation

WebGL uniform location. This is set automatically by Phenomenon—you don’t need to provide it.

Usage

const timeUniform: UniformProps = {
  type: 'float',
  value: [0],
};

const colorUniform: UniformProps = {
  type: 'vec3',
  value: [1, 0.5, 0],
};

const matrixUniform: UniformProps = {
  type: 'mat4',
  value: [
    1, 0, 0, 0,
    0, 1, 0, 0,
    0, 0, 1, 0,
    0, 0, 0, 1,
  ],
};

GeometryProps

Defines the base geometry for particles.

interface GeometryProps {
  vertices?: Array<Array<object>>;
  normal?: Array<Array<object>>;
}

vertices · Array<{ x: number; y: number; z: number }>

Array of vertex positions. Each object must have x, y, and z properties. If provided, an aPosition attribute is automatically created.

normal · Array<{ x: number; y: number; z: number }>

Array of vertex normals. Each object must have x, y, and z properties. If provided, an aNormal attribute is automatically created.

Usage

// Single point (default)
const pointGeometry: GeometryProps = {
  vertices: [{ x: 0, y: 0, z: 0 }],
};

// Triangle with normals
const triangleGeometry: GeometryProps = {
  vertices: [
    { x: 0, y: 0.1, z: 0 },
    { x: -0.1, y: -0.1, z: 0 },
    { x: 0.1, y: -0.1, z: 0 },
  ],
  normal: [
    { x: 0, y: 0, z: 1 },
    { x: 0, y: 0, z: 1 },
    { x: 0, y: 0, z: 1 },
  ],
};

BufferProps

Internal type representing a WebGL buffer. You typically don’t create these directly.

interface BufferProps {
  location: number;
  buffer: WebGLBuffer;
  size: number;
}

location · number

The attribute location in the shader program.

buffer · WebGLBuffer

The WebGL buffer object.

size · number

Number of components per vertex (1, 2, 3, or 4).

Type Usage Example

Here’s a complete example using TypeScript types:

import Renderer from 'phenomenon';

// Renderer configuration
const renderer = new Renderer({
  canvas: document.querySelector('#canvas') as HTMLCanvasElement,
  settings: {
    devicePixelRatio: window.devicePixelRatio,
    clearColor: [0, 0, 0, 1],
  },
  debug: true,
});

// Instance configuration
const instance = renderer.add('particles', {
  vertex: `
    attribute vec3 aPosition;
    attribute vec3 aOffset;
    
    uniform mat4 uProjectionMatrix;
    uniform mat4 uModelMatrix;
    uniform mat4 uViewMatrix;
    
    void main() {
      vec3 position = aPosition + aOffset;
      gl_Position = uProjectionMatrix * uModelMatrix * uViewMatrix * vec4(position, 1.0);
      gl_PointSize = 2.0;
    }
  `,
  fragment: `
    precision mediump float;
    
    void main() {
      gl_FragColor = vec4(1.0, 1.0, 1.0, 1.0);
    }
  `,
  uniforms: {
    uTime: {
      type: 'float',
      value: [0],
    },
  },
  attributes: [
    {
      name: 'aOffset',
      size: 3,
      data: (i, total) => [
        Math.random() * 2 - 1,
        Math.random() * 2 - 1,
        Math.random() * 2 - 1,
      ],
    },
  ],
  multiplier: 5000,
  mode: 0,
  onRender: (instance) => {
    instance.uniforms.uTime.value[0] += 0.01;
  },
});