pex-context v3.2.0

pex-context

Modern WebGL state wrapper for PEX: allocate GPU resources (textures, buffers), setup state pipelines and passes, and combine them into commands.

Installation

npm install pex-context

Usage

import createContext from "pex-context";

import { mat4 } from "pex-math";
import { cube } from "primitive-geometry";

const W = 640;
const H = 480;
const ctx = createContext({ width: W, height: H });

const geom = cube();

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

const drawCmd = {
  pipeline: ctx.pipeline({
    depthTest: true,
    vert: /* glsl */ `
attribute vec3 aPosition;
attribute vec3 aNormal;

uniform mat4 uProjectionMatrix;
uniform mat4 uViewMatrix;

varying vec4 vColor;

void main () {
  vColor = vec4(aNormal * 0.5 + 0.5, 1.0);

  gl_Position = uProjectionMatrix * uViewMatrix * vec4(aPosition, 1.0);
}
`,
    frag: /* glsl */ `
precision highp float;

varying vec4 vColor;

void main() {
  gl_FragColor = vColor;
}
`,
  }),
  attributes: {
    aPosition: ctx.vertexBuffer(geom.positions),
    aNormal: ctx.vertexBuffer(geom.normals),
  },
  indices: ctx.indexBuffer(geom.cells),
  uniforms: {
    uProjectionMatrix: mat4.perspective(
      mat4.create(),
      Math.PI / 4,
      W / H,
      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);
});

API

Objects

Functions

Typedefs

ctx : object

Kind: global namespace

• ctx : object
  • .gl
  • .capabilities
  • .width ⇒ number
  • .height ⇒ number
  • .BlendFactor
  • .CubemapFace
  • .DepthFunc
  • .Face
  • .Filter
  • .PixelFormat
  • .RenderbufferFloatFormat
  • .Encoding
  • .Primitive
  • .Usage
  • .Wrap
  • .QueryTarget
  • .QueryState
  • .set(options)
  • .debug([enabled])
  • .frame(cb)
  • .submit(cmd, [batches], [subCommand])
  • .pass(opts) ⇒ PexResource
  • .pipeline(opts) ⇒ PexResource
  • .vertexArray(opts) ⇒ PexResource
  • .transformFeedback(opts) ⇒ PexResource
  • .texture2D(opts) ⇒ PexResource
  • .texture2DArray(opts) ⇒ PexResource
  • .textureCube(opts) ⇒ PexResource
  • .renderbuffer(opts) ⇒ PexResource
  • .vertexBuffer(opts) ⇒ PexResource
  • .indexBuffer(opts) ⇒ PexResource
  • .query(opts) ⇒ PexResource
  • .beginQuery(query)
  • .endQuery(query)
  • .readPixels(viewport) ⇒ Uint8Array
  • .update(resource, opts)
  • .dispose([resource])

ctx.gl

The RenderingContext returned by pex-gl

Kind: static property of ctx

ctx.capabilities

Max capabilities and extensions availability. See Capabilities Table.

Kind: static property of ctx

ctx.width ⇒ number

Getter for gl.drawingBufferWidth

Kind: static property of ctx

ctx.height ⇒ number

Getter for gl.drawingBufferHeight

Kind: static property of ctx

ctx.BlendFactor

Kind: static enum of ctx Properties

ctx.CubemapFace

Kind: static enum of ctx Properties

ctx.DepthFunc

Kind: static enum of ctx Properties

ctx.Face

Kind: static enum of ctx Properties

ctx.Filter

Kind: static enum of ctx Properties

ctx.PixelFormat

Mapping of ctx.TextureFormat keys to their string values and legacy depth formats

One of:

• Unsized: RGB, RGBA, LUMINANCE_ALPHA, LUMINANCE, ALPHA
• Sized 1 component: R8, R8_SNORM, R16F, R32F, R8UI, R8I, R16UI, R16I, R32UI, R32I
• Sized 2 components: RG8, RG8_SNORM, RG16F, RG32F, RG8UI, RG8I, RG16UI, RG16I, RG32UI, RG32I
• Sized 3 components: RGB8, RGB8_SNORM, RGB16F, RGB32F, RGB8UI, RGB8I, RGB16UI, RGB16I, RGB32UI, RGB32I
• Sized 4 components: RGBA8, RGBA8_SNORM, RGBA16F, RGBA32F, RGBA8UI, RGBA8I, RGBA16UI, RGBA16I, RGBA32UI, RGBA32I
• Sized special: SRGB8, RGB565, R11F_G11F_B10F, RGB9_E5, SRGB8_ALPHA8, RGB5_A1, RGBA4, RGB10_A2, RGB10_A2UI
• Sized depth/stencil: DEPTH_COMPONENT16, DEPTH_COMPONENT24, DEPTH_COMPONENT32F, DEPTH24_STENCIL8, DEPTH32F_STENCIL8

Kind: static enum of ctx

ctx.RenderbufferFloatFormat

Kind: static enum of ctx Properties

ctx.Encoding

Kind: static enum of ctx Properties

ctx.Primitive

Kind: static enum of ctx Properties

ctx.Usage

Kind: static enum of ctx Properties

ctx.Wrap

Kind: static enum of ctx Properties

ctx.QueryTarget

Kind: static enum of ctx Properties

ctx.QueryState

Kind: static enum of ctx Properties

ctx.set(options)

Set the context size and pixelRatio The new size and resolution will not be applied immediately but before drawing the next frame to avoid flickering. Context's canvas doesn't resize automatically, even if you don't pass width/height on init and the canvas is assigned the dimensions of the window. To handle resizing use the following code:

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

Kind: static method of ctx

ctx.debug(enabled)

Enable debug mode

Kind: static method of ctx

ctx.frame(cb)

Render Loop

Kind: static method of ctx

ctx.submit(cmd, batches, subCommand)

Submit a command to the GPU. Commands are plain js objects with GPU resources needed to complete a draw call.

const cmd = {
  pass: Pass
  pipeline: Pipeline,
  attributes: { name:  VertexBuffer | { buffer: VertexBuffer, offset: number, stride: number } },
  indices: IndexBuffer | { 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.

Kind: static method of ctx

Example

• ctx.submit(cmd, opts): submit partially updated command without modifying the original one.

// 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.

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

• 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.

// Render to texture
ctx.submit(renderToFboCmd, () => {
  ctx.submit(drawMeshCmd);
});

ctx.pass(opts) ⇒ PexResource

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

Kind: static method of ctx

Example

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

ctx.pipeline(opts) ⇒ PexResource

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

Kind: static method of ctx

Example

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,
});

ctx.vertexArray(opts) ⇒ PexResource

Create a VAO resource.

Kind: static method of ctx

Example

const vertexLayout = {
  aPosition: { location: 0, type: "vec3" },
  aNormal: { location: 1, type: "vec3" },
};

const drawCmd = {
  pipeline: ctx.pipeline({
    vertexLayout,
    // ...
  }),
  vertexArray: ctx.vertexArray({
    vertexLayout,
    attributes: {
      aPosition: ctx.vertexBuffer(geom.positions),
      aNormal: { buffer: ctx.vertexBuffer(geom.normals) },
    },
    indices: ctx.indexBuffer(geom.cells),
  }),
  // ...
};

ctx.transformFeedback(opts) ⇒ PexResource

Create a transform feedback

Kind: static method of ctx

Example

const tex = ctx.transformFeedback({
  varyings: {
    outPosition: positionsBuf,
  },
});

ctx.texture2D(opts) ⇒ PexResource

Create a 2D Texture resource.

Kind: static method of ctx

Example

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,
});

ctx.texture2DArray(opts) ⇒ PexResource

Create a 2D Texture Array resource.

Kind: static method of ctx

Example

const tex = ctx.texture2DArray({
  data: [img, img, img],
});

ctx.textureCube(opts) ⇒ PexResource

Create a 2D Texture cube resource.

Kind: static method of ctx

Example

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

ctx.renderbuffer(opts) ⇒ PexResource

Renderbuffers represent pixel data store for rendering operations.

Kind: static method of ctx

Example

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

ctx.vertexBuffer(opts) ⇒ PexResource

Create an attribute buffer (ARRAY_BUFFER) resource. Stores vertex data in the GPU memory.

Kind: static method of ctx

Example

const vertexBuffer = ctx.vertexBuffer({
  data: Array | TypedArray | ArrayBuffer,
});

ctx.indexBuffer(opts) ⇒ PexResource

Create an index buffer (ELEMENT_ARRAY_BUFFER) resource. Stores index data in the GPU memory.

Kind: static method of ctx

Example

const indexBuffer = ctx.vertexBuffer({
  data: Array | TypedArray | ArrayBuffer,
});

ctx.query(opts) ⇒ PexResource

Queries can be used for GPU timers.

Kind: static method of ctx

Example

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

ctx.beginQuery(query)

Begin the query measurement.

Kind: static method of ctx

ctx.endQuery(query)

End the query measurement.

Kind: static method of ctx

ctx.readPixels(viewport) ⇒ Uint8Array

Helper to read a block of pixels from a specified rectangle of the current color framebuffer.

Kind: static method of ctx

ctx.update(resource, opts)

Update a resource.

Kind: static method of ctx

Example

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

ctx.update(texture, {
  width: 1,
  height: 1,
  data: new Uint8Array([255, 0, 0, 255]),
});

ctx.dispose(resource)

Delete one or all resource(s). Disposed resources are no longer valid for use.

Kind: static method of ctx

Example Delete all allocated resources:

ctx.dispose();

Delete a single resource:

ctx.dispose(texture);

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

createContext(options) ⇒ ctx

Create a context object

Kind: global function

BufferOptions : PexResource

Kind: global typedef Properties

Attachment : object

Kind: global typedef Properties

PassOptions : PexResource

Kind: global typedef Properties

PipelineOptions : PexResource

Kind: global typedef Properties

QueryOptions : PexResource

Kind: global typedef Properties

PexQuery : QueryOptions

Kind: global typedef Properties

RenderbufferOptions : PexResource

Kind: global typedef Properties

TextureOptionsData : HTMLImageElement | HTMLVideoElement | HTMLCanvasElement

Kind: global typedef Properties

TextureTarget : WebGLRenderingContext.TEXTURE_2D | WebGLRenderingContext.TEXTURE_CUBE_MAP | WebGL2RenderingContext.TEXTURE_2D_ARRAY | WebGL2RenderingContext.TEXTURE_3D

Kind: global typedef

TextureOptions : PexResource

Kind: global typedef Properties

Texture2DArrayOptions : PexResource

Kind: global typedef Extends: TextureOptions Properties

TextureCubeOptions : PexResource

Kind: global typedef Extends: TextureOptions Properties

TransformFeedbackOptions : PexResource

Kind: global typedef Properties

PexContextOptions : object

Kind: global typedef Properties

PexResource : object

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.

Kind: global typedef Properties

PexTexture2D : object

Kind: global typedef

PexAttribute : object

Kind: global typedef Properties

PexCommand : object

Kind: global typedef Properties

MultiDrawOptions : object

Kind: global typedef See

• WEBGL_multi_draw extension
• WEBGL_draw_instanced_base_vertex_base_instance extension
• WEBGL_multi_draw_instanced_base_vertex_base_instance extension

Properties

PexContextSetOptions : object

Kind: global typedef Properties

Viewport : Array.<number>

x, y, w, h

Kind: global typedef

Color : Array.<number>

r, g, b, a

Kind: global typedef

TypedArray : Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | Uint16Array | Int32Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array

Kind: global typedef

VertexArrayOptions : PexResource

Kind: global typedef Properties

Capabilities

Example

const maxTextureSize = ctx.capabilities.maxTextureSize;

License

MIT. See license file.