pex-context

Modern WebGL state wrapper for PEX. With pex-context you allocate GPU resources (textures, buffers), setup state pipelines and passes and combine them together into commands.

• Example
• Code examples
• Context
• Render loop
• Commands
• Resources
  • Pass
  • Pipeline
  • Texture
  • Renderbuffer
  • Buffer
  • Query
• Updating resources
• Enums

Example

const createContext = require('pex-context')
const createCube = require('primitive-cube')
const mat4 = require('pex-math/mat4')

const ctx = createContext({ width: 640, height: 480 })
const cube = createCube()

const clearCmd = {
  pass: ctx.pass({
    clearColor: [0, 0, 0, 1],
    clearDepth: 1
  })
}

const drawCmd = {
  pass: ctx.pass({
    clearColor: [0.2, 0.2, 0.2, 1],
    clearDepth: 1
  }),
  pipeline: ctx.pipeline({
    depthTest: true,
    vert: `
      attribute vec3 aPosition;
      attribute vec3 aNormal;
      uniform mat4 uProjectionMatrix;
      uniform mat4 uViewMatrix;
      varying vec3 vNormal;
      void main () {
        gl_Position = uProjectionMatrix * uViewMatrix * vec4(aPosition, 1.0);
        vNormal = aNormal;
      }
    `,
    frag: `
      precision mediump float;
      varying vec3 vNormal;
      void main () {
        gl_FragColor.rgb = vNormal;
        gl_FragColor.a = 1.0;
      }
    `
  }),
  attributes: {
    aPosition: ctx.vertexBuffer(cube.positions),
    aNormal: ctx.vertexBuffer(cube.normals)
  },
  indices: ctx.indexBuffer(cube.cells),
  uniforms: {
    uProjectionMatrix: mat4.perspective(
      mat4.create(),
      Math.PI / 4,
      640 / 480,
      0.1,
      100
    ),
    uViewMatrix: mat4.lookAt(mat4.create(), [2, 2, 5], [0, 0, 0], [0, 1, 0])
  }
}

ctx.frame(() => {
  ctx.submit(clearCmd)
  ctx.submit(drawCmd)
})

You can find runnable examples in the /examples folder in this repository. To run an example install Node.js, clone or download this repository and then run:

# go to the example folder
cd examples

# install examples dependencies
npm i

# run the example in your default browser window
npx budo example-name.js --open --start

API

Context

Creating gl context wrapper.

ctx = createContext(opts)

const createContext = require('pex-context')

// full window canvas
const ctx = createContext()

// creates gl context from existing canvas and keeps it's size
const ctx = createContext({ gl: gl })

// creates gl context from existing canvas and keeps it's size
const ctx = createContext({ canvas: canvas })

// creates new canvas with given width and height
const ctx = createContext({ width: Number, height: Number })

ctx.set(opts)

ctx.set({
  pixelRatio: 2,
  width: 1280,
  height: 720
})

Note 1: The new size and resolution will be applied not immediately but before drawing the next frame to avoid flickering.

Note 2: Context's canvas doesn't resize automatically, even if you skip width/height on init and the canvas will be asigned dimensions of the window. To handle resizing use the following code:

window.addEventListener('resize', () => {
  ctx.set({
    width: window.innerWidth,
    height: window.innerWidth
  })
})

Render Loop

ctx.frame(cb)

• cb: Function - Request Animation Frame callback

Commands

Commands are plain js objects with GPU resources needed to complete a draw call

const cmd = {
  pass: Pass
  pipeline: Pipeline,
  attributes: {
    name:  VertexBuffer,
    // or
    name: { buffer: VertexBuffer, offset: Number, stride: Number }
  },
  indices: IndexBuffer,
  // or
  indices: { buffer: IndexBuffer, offset: Number, count: Number },
  // or
  count: Number,
  instances: Number,
  uniforms: {
    name: Number,
    name: Array,
    name: Texture2D
  },
  viewport: [0, 0, 1920, 1080],
  scissor: [0, 0, 1920, 1080]
}

Note: either indices or count need to be specified when drawing geometry Note: scissor region is by default set to null and scissor test disabled

Submitting commands to the GPU

ctx.submit(cmd)

ctx.submit({
  pass: ctx.pass({
    clearColor: [1, 0, 0, 1]
  }),
  pipeline: ctx.pipeline({
    vert: '...',
    frag: '...'
  }),
  attributes: {...},
  indices: indexBuffer,
  uniforms: {...},
  ...
})

ctx.submit(cmd, opts)

Submit partially updated command without modifying the original one

// E.g. draw mesh with custom color
ctx.submit(cmd, {
  uniforms: {
    uColor: [1, 0, 0, 0]
  }
})

ctx.submit(cmd, [opts1, opts2, opts3...])

Submit a batch of commands differences in opts.

// E.g. draw same mesh twice with different material and position
ctx.submit(cmd, [
  { pipeline: material1, uniforms: { uModelMatrix: position1 },
  { pipeline: material2, uniforms: { uModelMatrix: position2 }
])

Subcommands

ctx.submit(cmd, cb)

Submit command while preserving state from another command.

This approach allows to simulate state stack with automatic cleanup at the end of callback.

// E.g. render to texture
ctx.submit(renderToFboCmd, () => {
  ctx.submit(drawMeshCmd)
})

Resources

All resources are plain js object and once constructed their properties can be accessed directly. Please note those props are read only. To set new values or upload new data to GPU see updating resources.

const tex = ctx.texture2D({
  width: 256,
  pixelFormat: ctx.PixelFormat.RGBA8
})

tex.width //256
tex.pixelFormat //'rgba8'

//but also those properties has been added
tex.type //gl.UNSIGNED_BYTE
tex.internalFormat //gl.RGBA

Pass

Passes are responsible for setting render targets (textures) and their clearing values. FBOs are created internally and automatically by pex-context.

pass = ctx.pass(opts)

const pass = ctx.pass({
  color: [Texture2D, ...]
  color: [{ texture: Texture2D | TextureCube, target: CubemapFace }, ...]
  depth: Texture2D
  clearColor: Array,
  clearDepth: Number
})

Pipeline

Pipelines represent the state of the GPU rendering pipeline (shaders, blending, depth test etc).

pipeline = ctx.pipeline(opts)

const pipeline = ctx.pipeline({
  vert: String,
  frag: String,
  depthWrite: Boolean,
  depthTest: Boolean,
  depthFunc: DepthFunc,
  blend: Boolean,
  blendSrcRGBFactor: BlendFactor,
  blendSrcAlphaFactor: BlendFactor,
  blendDstRGBFactor: BlendFactor,
  blendDstAlphaFactor: BlendFactor,
  cullFace: Boolean,
  cullFaceMode: Face,
  colorMask: Array,
  primitive: Primitive
})

Texture

Textures represent pixel data uploaded to the GPU.

texture = ctx.texture2D(opts)

const tex = ctx.texture2D({
  data: [255, 255, 255, 255, 0, 0, 0, 255],
  width: 2,
  height: 1,
  pixelFormat: ctx.PixelFormat.RGB8,
  encoding: ctx.Encoding.Linear,
  wrap: ctx.Wrap.Repeat
})

¹ requries EXT_texture_filter_anisotropic ² requires min to be set to ctx.Filter.LinearMipmapLinear or similar ³ read only

texture = ctx.textureCube(opts)

• opts: Object - see ctx.texture2D(opts)
• opts.data: Array of Images or TypedArrays - 6 images, one for each face +X, -X, +Y, -Y, +Z, -Z

const tex = ctx.textureCube({
  data: [ posx, negx, posy, negy, posz, negz ],
  width: 64,
  height: 64
])

Renderbuffer

Renderbuffers represent pixel data store for rendering operations

renderbuffer = ctx.renderbuffer(opts)

const tex = ctx.renderbuffer({
  width: 1280,
  height: 720,
  pixelFormat: ctx.PixelFormat.Depth16
})

¹ only PixelFormat.Depth16 equal to gl.DEPTH_COMPONENT16 is currently supported for use as render pass depth storage (e.g. ctx.pass({ depth: renderbuffer})) for platforms with no WEBGL_depth_texture support.

Buffer

Buffers store vertex and index data in the GPU memory.

buffer = ctx.vertexBuffer(opts)

buffer = ctx.indexBuffer(opts)

const buf = ctx.vertexBuffer({ data: Array }) // aka Attribute Buffer

const buf = ctx.indexBuffer({ data: Array }) // aka Index Buffer

Query

Queries are used for GPU timers.

query = ctx.query(opts)

Note: Requires EXT_disjoint_timer_query

const query = ctx.query({
  target: QueryTarget
})

ctx.beginQuery(q)

Begin the query measurement.

Note: There can be only one query running at the time.

ctx.endQuery(q)

End the query measurement.

Note: The result is not available immediately and will be null until the state changes from ctx.QueryState.Pending to ctx.QueryState.Ready

Updating resources

ctx.update(res, opts)

Update a resource.

ctx.update(res, { data: [] })

const tex = ctx.texture2D({...})
ctx.update(tex, {
  width: 1,
  height: 1,
  data: new Uint8Array([255, 0, 0, 255])
})

Disposing resources

ctx.dispose()

Delete all allocated resources and stop render loop. Disposed context is no longer valid to use.

ctx.dispose()

ctx.dispose(res)

Delete a resource. Disposed resource is no longer valid for use.

const tex = ctx.texture2D({})
...
ctx.dispose(tex)

Note: Framebuffers are ref counted and released by Pass, Programs are also ref counted and released by Pipeline

Capabilities

Get capabilities and extensions availability.

const maxTextureSize = ctx.maxTextureSize

Enums

ctx.BlendFactor

const BlendFactor = {
  One: gl.ONE,
  Zero: gl.ZERO,
  SrcAlpha: gl.SRC_ALPHA,
  OneMinusSrcAlpha: gl.ONE_MINUS_SRC_ALPHA,
  DstAlpha: gl.DST_ALPHA,
  OneMinusDstAlpha: gl.ONE_MINUS_DST_ALPHA,
  SrcColor: gl.SRC_COLOR,
  OneMinusSrcColor: gl.ONE_MINUS_SRC_COLOR,
  DstColor: gl.DST_COLOR,
  OneMinusDstColor: gl.ONE_MINUS_DST_COLOR
}

ctx.CubemapFace

const CubemapFace = {
  PositiveX: gl.TEXTURE_CUBE_MAP_POSITIVE_X,
  NegativeX: gl.TEXTURE_CUBE_MAP_NEGATIVE_X,
  PositiveY: gl.TEXTURE_CUBE_MAP_POSITIVE_Y,
  NegativeY: gl.TEXTURE_CUBE_MAP_NEGATIVE_Y,
  PositiveZ: gl.TEXTURE_CUBE_MAP_POSITIVE_Z,
  NegativeZ: gl.TEXTURE_CUBE_MAP_NEGATIVE_Z
}

ctx.DataType

const DataType = {
  Float32: gl.FLOAT,
  Uint8: gl.UNSIGNED_BYTE,
  Uint16: gl.UNSIGNED_SHORT,
  Uint32: gl.UNSIGNED_INT
}

ctx.DepthFunc

const DepthFunc = {
  Never: gl.NEVER,
  Less: gl.LESS,
  Equal: gl.EQUAL,
  LessEqual: gl.LEQUAL,
  Greater: gl.GREATER,
  NotEqual: gl.NOTEQUAL,
  GreaterEqual: gl.GEQUAL,
  Always: gl.ALWAYS
}

ctx.Face

const Face = {
  Front: gl.FRONT,
  Back: gl.BACK,
  FrontAndBack: gl.FRONT_AND_BACK
}

ctx.PixelFormat

const PixelFormat = {
  RGBA8: 'rgba8', // gl.RGBA + gl.UNSIGNED_BYTE
  RGBA32F: 'rgba32f', // gl.RGBA + gl.FLOAT
  RGBA16F: 'rgba16f', // gl.RGBA + gl.HALF_FLOAT
  R32F: 'r32f', // gl.ALPHA + gl.FLOAT
  R16F: 'r16f', // gl.ALPHA + gl.HALF_FLOAT
  Depth: 'depth', // gl.DEPTH_COMPONENT + gl.UNSIGNED_SHORT
  Depth16: 'depth16', // gl.DEPTH_COMPONENT + gl.UNSIGNED_SHORT
  Depth24: 'depth24' // gl.DEPTH_COMPONENT + gl.UNSIGNED_INT
}

ctx.Primitive

const Primitive = {
  Points: gl.POINTS,
  Lines: gl.LINES,
  LineStrip: gl.LINE_STRIP,
  Triangles: gl.TRIANGLES,
  TriangleStrip: gl.TRIANGLE_STRIP
}

ctx.Encoding

const Encoding = {
  Linear: 1,
  Gamma: 2,
  SRGB: 3,
  RGBM: 4
}

ctx.Usage

const Usage = {
  StaticDraw: gl.STATIC_DRAW,
  DynamicDraw: gl.DYNAMIC_DRAW,
  StreamDraw: gl.STREAM_DRAW
}

ctx.Wrap

const Wrap = {
  ClampToEdge: gl.CLAMP_TO_EDGE,
  Repeat: gl.REPEAT
}

ctx.QueryTarget

const QueryTarget = {
  TimeElapsed: gl.TIME_ELAPSED
}

ctx.QueryState

const QueryState = {
  Ready: 'ready',
  Active: 'active',
  Pending: 'pending'
}

License

MIT, see LICENSE.md for details.