pex-renderer

Physically Based Renderer (PBR) and scene graph designed as ECS for PEX: define entities to be rendered as collections of components with their update orchestrated by systems.

Installation

npm install pex-renderer

Usage

import {
  renderEngine as createRenderEngine,
  world as createWorld,
  entity as createEntity,
  components,
} from "pex-renderer";

import createContext from "pex-context";
import { sphere } from "primitive-geometry";

const ctx = createContext({ pixelRatio: devicePixelRatio });
const renderEngine = createRenderEngine({ ctx });

const world = createWorld();

const cameraEntity = createEntity({
  transform: components.transform({ position: [0, 0, 3] }),
  camera: components.camera(),
  postProcessing: components.postProcessing(),
  orbiter: components.orbiter(),
});
world.add(cameraEntity);

const skyEntity = createEntity({
  skybox: components.skybox({ sunPosition: [1, 0.5, 1] }),
  reflectionProbe: components.reflectionProbe(),
});
world.add(skyEntity);

const geometryEntity = createEntity({
  transform: components.transform({ position: [0, 0, 0] }),
  geometry: components.geometry(sphere()),
  material: components.material({
    baseColor: [1, 0, 0, 1],
    metallic: 0,
    roughness: 0.5,
  }),
});
world.add(geometryEntity);

ctx.frame(() => {
  renderEngine.update(world.entities);
  renderEngine.render(world.entities, cameraEntity);
});

Architecture

• components are plain old data objects
• data lives in components or system caches
• systems are functions
• systems communicate through components
• system order is maintained by the user

API

Modules

Typedefs

pex-renderer

• pex-renderer
  • .components : components
  • .systems : systems
  • .world() ⇒ World
  • .entity([components]) ⇒ Entity
  • .renderEngine() ⇒ RenderEngine
  • .renderGraph(ctx) ⇒ RenderGraph
  • .resourceCache(ctx) ⇒ ResourceCache

pex-renderer.components : components

All components as a function returning a component with default values.

Kind: static property of pex-renderer

pex-renderer.systems : systems

All systems as a function returning a system with a type property and an update function.

Kind: static property of pex-renderer

pex-renderer.world() ⇒ World

Create a world object to store entities and systems

Kind: static method of pex-renderer

pex-renderer.entity([components]) ⇒ Entity

Create an entity from an object of plain data components

Kind: static method of pex-renderer

| Param | Type | Default | | ------------ | ------------------- | --------------- | | [components] | object | {} |

pex-renderer.renderEngine() ⇒ RenderEngine

Create a render engine eg. a collection of systems for default rendering

Kind: static method of pex-renderer

pex-renderer.renderGraph(ctx) ⇒ RenderGraph

Create a render graph for rendering passes

Kind: static method of pex-renderer

| Param | Type | | ----- | ---------------------------------------------- | | ctx | module:pex-context/types/index.js |

pex-renderer.resourceCache(ctx) ⇒ ResourceCache

Create a resource cache for pex-context caching.

Kind: static method of pex-renderer

| Param | Type | | ----- | ---------------------------------------------- | | ctx | module:pex-context/types/index.js |

components

• components
  • .ambientLight([options]) ⇒ object
  • .animation([options]) ⇒ object
  • .areaLight([options]) ⇒ object
  • .axesHelper([options]) ⇒ object
  • .boundingBoxHelper([options]) ⇒ object
  • .cameraHelper([options]) ⇒ object
  • .camera([options]) ⇒ object
  • .directionalLight([options]) ⇒ object
  • .geometry([options]) ⇒ object
  • .gridHelper([options]) ⇒ object
  • .lightHelper([options]) ⇒ object
  • .material([options]) ⇒ object
  • .morph(options) ⇒ object
  • .orbiter(options) ⇒ object
  • .pointLight([options]) ⇒ object
  • .postProcessing([options]) ⇒ object
    • .ssao([options]) ⇒ object
    • .dof([options]) ⇒ object
    • .msaa([options]) ⇒ object
    • .fxaa([options]) ⇒ object
    • .smaa([options]) ⇒ object
    • .fog([options]) ⇒ object
    • .bloom([options]) ⇒ object
    • .vignette([options]) ⇒ object
    • .lut([options]) ⇒ object
    • .colorCorrection([options]) ⇒ object
    • .filmGrain([options]) ⇒ object
  • .reflectionProbe([options]) ⇒ object
  • .skeletonHelper([options]) ⇒ object
  • .skin([options]) ⇒ object
  • .skybox([options]) ⇒ object
  • .spotLight([options]) ⇒ object
  • .transform([options]) ⇒ object
  • .vertexHelper([options]) ⇒ object

components.ambientLight([options]) ⇒ object

Ambient light component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------------- | | [options] | AmbientLightComponentOptions |

components.animation([options]) ⇒ object

Animation component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------- | | [options] | AnimationComponentOptions |

components.areaLight([options]) ⇒ object

Area light component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------- | | [options] | AreaLightComponentOptions |

components.axesHelper([options]) ⇒ object

Axes helper component

Kind: static method of components

| Param | Type | | --------- | ---------------------------------------------------------------------- | | [options] | AxesHelperComponentOptions |

components.boundingBoxHelper([options]) ⇒ object

Bounding box helper component

Kind: static method of components

| Param | Type | | --------- | ------------------------------------------------------------------------------------ | | [options] | BoundingBoxHelperComponentOptions |

components.cameraHelper([options]) ⇒ object

Camera helper component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------------- | | [options] | CameraHelperComponentOptions |

components.camera([options]) ⇒ object

Camera component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------- | | [options] | CameraComponentOptions |

components.directionalLight([options]) ⇒ object

Directional light component

Kind: static method of components

| Param | Type | | --------- | ---------------------------------------------------------------------------------- | | [options] | DirectionalLightComponentOptions |

components.geometry([options]) ⇒ object

Geometry component

Kind: static method of components

| Param | Type | | --------- | ------------------------------------------------------------------ | | [options] | GeometryComponentOptions |

components.gridHelper([options]) ⇒ object

Grid helper component

Kind: static method of components

| Param | Type | | --------- | ---------------------------------------------------------------------- | | [options] | GridHelperComponentOptions |

components.lightHelper([options]) ⇒ object

Light helper component

Kind: static method of components

| Param | Type | | --------- | ------------------------------------------------------------------------ | | [options] | LightHelperComponentOptions |

components.material([options]) ⇒ object

Material component

Kind: static method of components

| Param | Type | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | [options] | MaterialComponentOptions | LineMaterialComponentOptions |

components.morph(options) ⇒ object

Morph component

Kind: static method of components

| Param | Type | | ------- | ------------------------------------------------------------ | | options | MorphComponentOptions |

components.orbiter(options) ⇒ object

Orbiter component

Kind: static method of components

| Param | Type | | ------- | ---------------------------------------------------------------- | | options | OrbiterComponentOptions |

components.pointLight([options]) ⇒ object

Point light component

Kind: static method of components

| Param | Type | | --------- | ---------------------------------------------------------------------- | | [options] | PointLightComponentOptions |

components.postProcessing([options]) ⇒ object

Post Processing component

Kind: static method of components

| Param | Type | | --------- | ------------------------------------------------------------------------------ | | [options] | PostProcessingComponentOptions |

• .postProcessing([options]) ⇒ object
  • .ssao([options]) ⇒ object
  • .dof([options]) ⇒ object
  • .msaa([options]) ⇒ object
  • .fxaa([options]) ⇒ object
  • .smaa([options]) ⇒ object
  • .fog([options]) ⇒ object
  • .bloom([options]) ⇒ object
  • .vignette([options]) ⇒ object
  • .lut([options]) ⇒ object
  • .colorCorrection([options]) ⇒ object
  • .filmGrain([options]) ⇒ object

postProcessing.ssao([options]) ⇒ object

Post Processing SSAO subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | ---------------------------------------------------------- | | [options] | SSAOComponentOptions |

postProcessing.dof([options]) ⇒ object

Post Processing DoF subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | -------------------------------------------------------- | | [options] | DoFComponentOptions |

postProcessing.msaa([options]) ⇒ object

Post Processing MSAA subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | ---------------------------------------------------------- | | [options] | MSAAComponentOptions |

postProcessing.fxaa([options]) ⇒ object

Post Processing FXAA subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | ---------------------------------------------------------- | | [options] | FXAAComponentOptions |

postProcessing.smaa([options]) ⇒ object

Post Processing SMAA subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | ---------------------------------------------------------- | | [options] | SMAAComponentOptions |

postProcessing.fog([options]) ⇒ object

Post Processing Fog subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | -------------------------------------------------------- | | [options] | FogComponentOptions |

postProcessing.bloom([options]) ⇒ object

Post Processing Bloom subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | ------------------------------------------------------------ | | [options] | BloomComponentOptions |

postProcessing.vignette([options]) ⇒ object

Post Processing Vignette subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | ------------------------------------------------------------------ | | [options] | VignetteComponentOptions |

postProcessing.lut([options]) ⇒ object

Post Processing LUT subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | -------------------------------------------------------- | | [options] | LutComponentOptions |

postProcessing.colorCorrection([options]) ⇒ object

Post Processing Color Correction subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | -------------------------------------------------------------------------------- | | [options] | ColorCorrectionComponentOptions |

postProcessing.filmGrain([options]) ⇒ object

Post Processing Film Grain subcomponent

Kind: static method of postProcessing

| Param | Type | | --------- | -------------------------------------------------------------------- | | [options] | FilmGrainComponentOptions |

components.reflectionProbe([options]) ⇒ object

Reflection probe component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------------------- | | [options] | ReflectionProbeComponentOptions |

components.skeletonHelper([options]) ⇒ object

Skeleton helper component

Kind: static method of components

| Param | Type | | --------- | ------------------------------------------------------------------------------ | | [options] | SkeletonHelperComponentOptions |

components.skin([options]) ⇒ object

Skin component

Kind: static method of components

| Param | Type | | --------- | ---------------------------------------------------------- | | [options] | SkinComponentOptions |

components.skybox([options]) ⇒ object

Skybox component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------- | | [options] | SkyboxComponentOptions |

components.spotLight([options]) ⇒ object

Spot light component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------- | | [options] | SpotLightComponentOptions |

components.transform([options]) ⇒ object

Transform component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------- | | [options] | TransformComponentOptions |

components.vertexHelper([options]) ⇒ object

Vertex helper component

Kind: static method of components

| Param | Type | | --------- | -------------------------------------------------------------------------- | | [options] | VertexHelperComponentOptions |

systems

• systems
  • .renderer : renderer
  • .animation() ⇒ System
  • .camera() ⇒ System
  • .geometry(options) ⇒ System
  • .helper() ⇒ System
  • .layer() ⇒ System
  • .light() ⇒ System
  • .morph() ⇒ System
  • .reflectionProbe(options) ⇒ System
  • .skin() ⇒ System
  • .skybox(options) ⇒ System
  • .transform() ⇒ System
  • .renderPipeline(options) ⇒ System

systems.renderer : renderer

All renderer systems

Kind: static property of systems

systems.animation() ⇒ System

Animation system

Kind: static method of systems

systems.camera() ⇒ System

Camera system

Adds:

• "_orbiter" to orbiter components

Kind: static method of systems

systems.geometry(options) ⇒ System

Geometry system

Adds:

• "bounds" to geometry components
• "dirty" to geometry components properties
• "_geometry" to entities as reference to internal cache

Kind: static method of systems

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

systems.helper() ⇒ System

Helper system

Kind: static method of systems

systems.layer() ⇒ System

Layer system

Kind: static method of systems

systems.light() ⇒ System

Light system

Adds:

• "_projectionMatrix" and "_viewMatrix" to light components
• "_direction" to directional and spot light components

Kind: static method of systems

systems.morph() ⇒ System

Morph system

Kind: static method of systems

systems.reflectionProbe(options) ⇒ System

Reflection Probe system

Adds:

• "_reflectionProbe" to reflectionProbe components

Kind: static method of systems

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

systems.skin() ⇒ System

Skin system

Kind: static method of systems

systems.skybox(options) ⇒ System

Skybox system

Adds:

• "_skyTexture" to skybox components with no envMap for skybox-renderer to render
• "_skyTextureChanged" to skybox components for reflection-probe system

Kind: static method of systems

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

systems.transform() ⇒ System

Transform system

Adds:

• "worldBounds", "dirty" and "aabbDirty" to transform components
• "_transform" to entities as reference to internal cache

Kind: static method of systems

systems.renderPipeline(options) ⇒ System

Render pipeline system

Adds:

• "_near", "_far", "_radiusUV" and "_sceneBboxInLightSpace" to light components that cast shadows
• "_shadowCubemap" to pointLight components and "_shadowMap" to other light components
• "_targets" to postProcessing components

Kind: static method of systems

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

renderer

• renderer
  • .base() ⇒ RendererSystem
  • .basic(options) ⇒ RendererSystem
  • .line(options) ⇒ RendererSystem
  • .skybox(options) ⇒ RendererSystem
  • .standard(options) ⇒ RendererSystem

renderer.base() ⇒ RendererSystem

Base renderer

All renderers are composed with it.

Kind: static method of renderer

renderer.basic(options) ⇒ RendererSystem

Basic renderer

Kind: static method of renderer

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

renderer.line(options) ⇒ RendererSystem

Line renderer

Kind: static method of renderer

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

renderer.skybox(options) ⇒ RendererSystem

Skybox renderer

Renders a skybox (envMap or _skyTexture) to screen or to reflection probes.

Kind: static method of renderer

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

renderer.standard(options) ⇒ RendererSystem

Standard renderer

Kind: static method of renderer

| Param | Type | | ------- | -------------------------------------------- | | options | SystemOptions |

Entity : object

Kind: global typedef Properties

| Name | Type | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | id | number | | [ambientLight] | AmbientLightComponentOptions | | [animation] | AnimationComponentOptions | Array.<AnimationComponentOptions> | | [areaLight] | AreaLightComponentOptions | | [axesHelper] | AxesHelperComponentOptions | | [boundingBoxHelper] | BoundingBoxHelperComponentOptions | | [skeletonHelper] | SkeletonHelperComponentOptions | | [cameraHelper] | CameraHelperComponentOptions | | [camera] | CameraComponentOptions | | [directionalLight] | DirectionalLightComponentOptions | | [geometry] | GeometryComponentOptions | | [gridHelper] | GridHelperComponentOptions | | [lightHelper] | LightHelperComponentOptions | | [material] | MaterialComponentOptions | | [morph] | MorphComponentOptions | | [orbiter] | OrbiterComponentOptions | | [pointLight] | PointLightComponentOptions | | [postProcessing] | PostProcessingComponentOptions | | [reflectionProbe] | ReflectionProbeComponentOptions | | [skin] | SkinComponentOptions | | [skybox] | SkyboxComponentOptions | | [spotLight] | SpotLightComponentOptions | | [transform] | TransformComponentOptions | | [vertexHelper] | VertexHelperComponentOptions |

AmbientLightComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | ----------- | --------------------------------- | ------------------------- | | [color] | Array.<number> | [1, 1, 1, 1] | | [intensity] | number | 1 |

AnimationComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | ---------- | -------------------- | ------------------ | | [playing] | boolean | false | | [loop] | boolean | false | | [time] | number | 0 | | [channels] | Array | [] |

AreaLightComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | --------------- | --------------------------------- | ------------------------- | | [color] | Array.<number> | [1, 1, 1, 1] | | [intensity] | number | 1 | | [disk] | boolean | false | | [doubleSided] | boolean | false | | [bias] | number | 0.1 | | [bulbRadius] | number | 1 | | [castShadows] | boolean | true | | [shadowMapSize] | number | 2048 |

AxesHelperComponentOptions : object

Kind: global typedef

BoundingBoxHelperComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | ------- | --------------------------------- | ------------------------- | | [color] | Array.<number> | [1, 0, 0, 1] |

SkeletonHelperComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | ------- | ------------------------------------------------------------------------------------ | ----------------------------------------- | | [color] | Array.<number> | Array.<Array.<number>> | [[0, 0, 1, 1], [1, 1, 1, 1]] |

CameraHelperComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | ------- | --------------------------------- | ------------------------- | | [color] | Array.<number> | [1, 1, 1, 1] |

CameraView : object

Kind: global typedef Properties

| Name | Type | | ----------- | --------------------------------- | | [totalSize] | Array.<number> | | [size] | Array.<number> | | [offset] | Array.<number> |

CameraComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- | | [projection] | "perspective" | "orthographic" | "perspective" | | | [near] | number | 0.5 | | | [far] | number | 1000 | | | [aspect] | number | 1 | | | [clearColor] | module:pex-color~color | | | | [viewMatrix] | mat4 | | | | [invViewMatrix] | mat4 | | | | [culling] | boolean | false | | | [focalLength] | number | 50 | Focal length of the camera lens [10mm - 200mm] in mm | | [fStop] | number | 2.8 | Ratio of camera lens opening, f-number, f/N, aperture [1.2 - 32] in mm | | [sensorSize] | number | [36, 24] | Physical camera sensor or film size [sensorWidth, sensorHeight] in mm | | sensorFit | "vertical" | "horizontal" | "fit" | "overscan" | "vertical" | | Matching of camera frame to sensor frame | | [view] | CameraView | | | | [fov] | number | Math.PI / 4 | | | [left] | number | -1 | | | [right] | number | 1 | | | [bottom] | number | -1 | | | [top] | number | 1 | | | [zoom] | number | 1 | |

DirectionalLightComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | --------------- | --------------------------------- | ------------------------- | | [color] | Array.<number> | [1, 1, 1, 1] | | [intensity] | number | 1 | | [bias] | number | 0.1 | | [bulbRadius] | number | 1 | | [castShadows] | boolean | true | | [shadowMapSize] | number | 2048 |

GeometryComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | Description | | -------------- | ---------------------------------------------------- | ------------------------------------ | --------------------------- | | [positions] | Float32Array | | | | [normals] | Float32Array | | | | [uvs] | Float32Array | | Alias: texCoords/texCoords0 | | [uvs1] | Float32Array | | Alias: texCoords1 | | [vertexColors] | Float32Array | | | | [cells] | Uint16Array | Uint32Array | | | | [weights] | Float32Array | | | | [joints] | Float32Array | | | | [offsets] | Float32Array | | Instanced | | [rotations] | Float32Array | | Instanced | | [scales] | Float32Array | | Instanced | | [colors] | Float32Array | | Instanced | | [count] | number | | | | [multiDraw] | object | | | | [culled] | boolean | | | | [primitive] | ctx.Primitive | ctx.Primitive.Triangles | |

GridHelperComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | ------- | --------------------------------- | ------------------------- | | [color] | Array.<number> | [1, 1, 1, 1] | | [size] | Array.<number> | 10 |

LightHelperComponentOptions : object

Kind: global typedef

TextureTransform : object

Kind: global typedef Properties

| Name | Type | Description | | ---------- | --------------------------------- | ---------------- | | [offset] | Array.<number> | [x, y] | | [rotation] | number | Angle in radians | | [scales] | Array.<number> | [x, y] |

MaterialComponentOptions : object

Kind: global typedef Properties

| Name | Type | Default | | --------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------- | | [unlit] | boolean | | | [type] | undefined | "line" | "undefined" | | [baseColor] | Array.<number> | [1, 1, 1, 1] | | [emissiveColor] | Array.<number> | "undefined" | | [emissiveIntensity] | number | 1 | | [metallic] | number | 1 | | [roughness] | number | 1 | | [ior] | number | | | [specular] | number | | | [specularTexture] | ctx.texture2D | TextureTransform | | | [specularColor] | Array.<number> | [1, 1, 1] | | [specularColorTexture] | ctx.texture2D | TextureTransform | | | [baseColorTexture] | ctx.texture2D | TextureTransform | | | [emissiveColorTexture] | ctx.texture2D | TextureTransform | | | [normalTexture] | ctx.texture2D | TextureTransform | | | [normalTextureScale] | number | 1 | | [roughnessTexture] | ctx.texture2D | TextureTransform | | | [metallicTexture] | ctx.texture2D | TextureTransform | | | [metallicRoughnessTexture] | ctx.texture2D | TextureTransform | | | [occlusionTexture] | ctx.texture2D | TextureTransform | | | [clearCoat] | number | | | [clearCoatRoughness] | number | | | [clearCoatTexture] | ctx.texture2D | TextureTransform | | | [clearCoatRoughnessTexture] | ctx.texture2D | TextureTransform | | | [clearCoatNormalTexture] | ctx.texture2D | TextureTransform | | | [clearCoatNormalTextureScale] | number | | | [sheenColor] | Array.<number> | | | [sheenRoughness] | number | | | [transmission] | number | | | [transmissionTexture] | ctx.texture2D | TextureTransform | | | [dispersion] | number | | | [diffuseTransmission] | number | | | [diffuseTransmissionTexture] | ctx.texture2D | TextureTransform | | | [diffuseTransmissionColor] | number | [1, 1, 1] | | [diffuseTransmissionColorTexture] | ctx.texture2D | [TextureTra