README.md

Documentation

Components

Common usage with ReglContainer and its default renderer.

ReglContainer

Creates a Regl context that is accessible through a consumer. All children are rendered into a view (default: fullscreen canvas) with ReglRenderer by default.

To prevent context loss, it is advised to have at most one container component. There is a react-multi-regl package, if you wish to multiplex a regl instance across different views.

import { ReglContainer } from '@psychobolt/react-regl';

import Scene from './Scene';

export default props => <ReglContainer {...props}><Scene /></ReglContainer>;

Props

renderer?: ReglRenderer

The default is ReglRenderer. Alternatively, you can extend and pass in your own.

types?: { [type: string]: (props: {}, context: ContextContainer ) => Object }

If you prefer to not extend ReglRenderer, another option is to provide a list of types similiar to the renderer's default types.

viewProps?: {}

Props to be passed to the view.

View?: React.ElementType | WebGLRenderingContext | Element

If no view is provided, the default view will be generated by regl.

contextProps?: {}

Initialization options for regl.

statsWidget?: boolean

If the value is true, a widget appears on the top left corner of the view and displays the average render time for each Drawable. The stats widget requires you to have styled-components@4.1.x.

onMount?: (context: ContextContainer) => any

Callback function to be called when the container has mounted. Receives API access to the context container.

Context.Consumer

Allows API access to the current context container object. Same API as React's Context.Consumer.

import { Context } from '@psychobolt/react-regl';

import Scene from './Scene';

export default () => (
  <Context.Consumer>
    {({ context }) => <Scene context={context} />}
  </Context.Consumer>
);

Collection

Allows mapping of a hierarchy similiar to the DOM tree. Provides a simple data structure, array, for connecting react-regl type instances.

import React from 'react';
import { Collection } from '@psychobolt/react-regl';

import { Object } from './Object';

export default () => <Collection><Object /></Collection>;

Types

Following are collection types with specific roles.

Drawable

Regl's draw command.

import React from 'react'
import { Drawable } from '@psyhcobolt/react-regl';

import frag from './Triangle.frag';
import vert from './Triangle.vert';

const attributes = {
  position: [[0, -1], [-1, 0], [1, 1]]
};

export default () => (
  <Drawable frag={frag} vert={vert} attributes={attributes} count={3}>
    {/* children */}
  </Drawable>
);

Props

For full list of props, see regl's documentation. Following, are some additional control props.

name?: string

Optional name for the draw command.

args?: {} | (context: ReglContext) => {}

Arguments that are passed to the command on execution. You may use a function that accepts regl's context variables to construct arguments.

render?: (args: {}) => void

Instead of running a regl command, the render function is called in place.

scoped?: boolean

If the value is true, during render, sub commands are executed in scope.

Frame

Render children within regl's frame callback.

import React from 'react';
import { Frame } from '@psychobolt/react';

function onFrame({ regl }) {
  regl.clear({
    color: [0, 0, 0, 1],
    depth: 1,
  });
}

export default () => <Frame onFrame={onFrame}>{/* children */}</Frame>

Props

onFrame?: (context: ContextContainer & ReglContext) => any

Callback that is invoked before any children is updated.

onUpdate?: (context: ContextContainer & ReglContext & { drawCallback }) => any

Overrides the default frame update.

function onUpdate({ draw, ...context)) {
  // Do your own work here
  draw({}); // drawCallback?: (args: {}) => void
}

Framebuffer

A component helper to create and provide a framebuffer.

import React from 'react';
import { Framebuffer } from '@psychobolt/react-regl';

export default ({ children, ...props }) => <Framebuffer {...props}>{fbo => children(fbo)}</Framebuffer>

Props

Inherits props from Drawable. Pass in any props that is taken by regl's framebuffer constructor.

children?: fbo => React.Node

The framebuffer object can be accessed from the children prop function.

fitView?: boolean

If true, the framebuffer will automatically be sized as viewport's width and height. Default is false.

Cube

A component helper to create and provide a cube map.

import React from 'react';
import { Cube } from '@psychobolt/react-paperjs';

import Scene from './Scene';
import images from './images';

export default () => <Cube images={images}>{cube => <Scene cube={cube} />}</Cube>;

Props

Inherits props from Drawable.

images?: Image[]

A array of images for faces: positive X, negative X, positive Y, negative Y, positive Z, and negative Z. Providing this prop is equivilent to regl.cube(...images). Hence, other props besides args are ignored.

Resource

Preload and provide resource objects. See API for resl for more details.

import React from 'react';
import { Resource } from 'react';

import Scene from './Scene';
import video from './video.mp4'; // imported with webpack url loader plugin

const manifest = {
  video: {
    'type': 'video',
    stream: true,
    src: video, // a url string
  }
};

export default () => <Resource manifest={manifest}>{video => <Scene video={video} />}</Resource>;

Props

All props are passed to the constructor.

Texture

Create and provide a regl texture.

import React from 'react';
import { Texture } from '@psychobolt/react';

import Scene from './Scene';
import image from './image.jpg';

export default () => <Texture source={image}>{texture => <Scene texture={texture} />}</Texture>;

Props

Inherits props from Drawable.

source?: | number[] | Image | CanvasRenderingContext2D | HTMLVideoElement

A object that consist of the media. Providing this prop is equivilant to regl.texture(source). Hence, other props besides args are ignored.

API

Context Container

The context container is instantiated when ReglContainer is mounted. The context container provides access to the collection, regl's instance, and view element.

function callback(context) {
  const { regl, children, view } = context;
  // custom logic here
}

ReglRenderer

Currently a synchronous but extensible implementation.

Members

defaultHostConfig: {}

The host config that is passed into React Reconciler by default. This should not be mutated. Instead, extend ReglRenderer with a getHostConfig function.

defaultTypes: { [type: string]: (props: {}, context: ContextContainer ) => Object }

A mapping of types with their instance factory method. This should not be mutated. Instead, extend ReglRenderer with a getHostConfig function.

Extension Example

import React from 'react';
import { ReglContainer, ReglRenderer } from '@psychobolt/react-regl';

import MyCustomType, { CONSTANTS, Types } from './types'

class MyReglRenderer extends ReglRenderer {
  getInstanceFactory() {
    return {
      ...super.getInstanceFactory(),
      [CONSTANTS.MyCustomType]: (props, context) => new Types.MyCustomType(props, context),
    };
  }
}

export default props => (
  <ReglContainer {...props} renderer={MyReglRenderer}>
    <MyCustomType />
  </ReglContainer>
);

The above code adds a custom Component Type to the renderer's instance factory. Then the component can be rendered inside the container.