or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

attributes-uniforms.mdbuffer-management.mdcontext-creation.mdextensions.mdframebuffer-operations.mdindex.mdshader-programs.mdtexture-operations.mdwebgl-rendering.md
tile.json

index.mddocs/

gl (headless-gl)

gl creates a WebGL context in Node.js without making a window or loading a full browser environment. It provides a complete WebGL 1.0.3 implementation that enables server-side graphics rendering, GPGPU computations, and headless graphics testing with full conformance to the WebGL specification.

Package Information

  • Package Name: gl
  • Package Type: npm
  • Language: JavaScript (Node.js native addon)
  • Installation: npm install gl

Core Imports

const gl = require('gl');

For browser environments with bundlers:

import gl from 'gl';

Basic Usage

const gl = require('gl');

// Create a 64x64 WebGL context
const width = 64;
const height = 64;
const context = gl(width, height, { preserveDrawingBuffer: true });

// Clear screen to red
context.clearColor(1, 0, 0, 1);
context.clear(context.COLOR_BUFFER_BIT);

// Read pixels back
const pixels = new Uint8Array(width * height * 4);
context.readPixels(0, 0, width, height, context.RGBA, context.UNSIGNED_BYTE, pixels);

Architecture

gl is built around several key components:

  • Context Creation: Automatic environment detection (Node.js vs browser) with appropriate WebGL implementation
  • Native OpenGL Backend: Uses ANGLE for consistent cross-platform OpenGL ES implementation
  • WebGL 1.0.3 Compliance: Full conformance to WebGL specification with complete API surface
  • Extension System: Support for standard WebGL extensions plus custom headless-specific extensions
  • Resource Management: Automatic cleanup and reference counting for WebGL objects

Capabilities

Context Creation and Management

Creates and manages WebGL rendering contexts with configurable attributes and automatic environment detection.

/**
 * Create a WebGL rendering context (main module export)
 * @param width - Width of the drawing buffer (must be > 0)
 * @param height - Height of the drawing buffer (must be > 0) 
 * @param options - Optional context attributes
 * @returns WebGLRenderingContext or null if creation fails
 */
function gl(width, height, options);

interface WebGLContextAttributes {
  /** Enable alpha channel in color buffer (default: true) */
  alpha?: boolean;
  /** Enable depth buffer (default: true) */
  depth?: boolean;
  /** Enable stencil buffer (default: false) */
  stencil?: boolean;
  /** Enable antialiasing (default: true, but forced to false) */
  antialias?: boolean;
  /** Enable premultiplied alpha (default: true) */
  premultipliedAlpha?: boolean;
  /** Preserve drawing buffer contents (default: false) */
  preserveDrawingBuffer?: boolean;
  /** Prefer low power GPU (default: false) */
  preferLowPowerToHighPerformance?: boolean;
  /** Fail if major performance caveat (default: false) */
  failIfMajorPerformanceCaveat?: boolean;
}

Context Creation

WebGL Rendering Context

Complete WebGL 1.0.3 API implementation with all standard methods, properties, and constants for graphics rendering.

class WebGLRenderingContext {
  // Drawing buffer dimensions
  readonly drawingBufferWidth: number;
  readonly drawingBufferHeight: number;
  
  // Core rendering methods
  clear(mask: number): void;
  drawArrays(mode: number, first: number, count: number): void;
  drawElements(mode: number, count: number, type: number, offset: number): void;
  
  // Resource creation
  createBuffer(): WebGLBuffer | null;
  createTexture(): WebGLTexture | null;
  createFramebuffer(): WebGLFramebuffer | null;
  createRenderbuffer(): WebGLRenderbuffer | null;
  createProgram(): WebGLProgram | null;
  createShader(type: number): WebGLShader | null;
  
  // Context information
  getParameter(pname: number): any;
  getError(): number;
  getContextAttributes(): WebGLContextAttributes | null;
  isContextLost(): boolean;
  
  // Extension management
  getExtension(name: string): any;
  getSupportedExtensions(): string[] | null;
}

WebGL Rendering

Buffer Management

WebGL buffer operations for vertex data, index data, and GPU memory management.

// Buffer binding and management
bindBuffer(target: number, buffer: WebGLBuffer | null): void;
bufferData(target: number, data: ArrayBuffer | ArrayBufferView | number, usage: number): void;
bufferSubData(target: number, offset: number, data: ArrayBuffer | ArrayBufferView): void;
deleteBuffer(buffer: WebGLBuffer): void;

Buffer Management

Texture Operations

Complete texture management including 2D textures, cube maps, and texture parameters.

// Texture binding and configuration
bindTexture(target: number, texture: WebGLTexture | null): void;
texImage2D(target: number, level: number, internalformat: number, 
          width: number, height: number, border: number, 
          format: number, type: number, pixels: ArrayBufferView | null): void;
texParameteri(target: number, pname: number, param: number): void;

Texture Operations

Shader Programs

Shader compilation, linking, and program management for vertex and fragment shaders.

// Shader operations
shaderSource(shader: WebGLShader, source: string): void;
compileShader(shader: WebGLShader): void;
attachShader(program: WebGLProgram, shader: WebGLShader): void;
linkProgram(program: WebGLProgram): void;
useProgram(program: WebGLProgram | null): void;

Shader Programs

Vertex Attributes and Uniforms

Management of vertex attributes and uniform variables for shader programs.

// Vertex attributes
getAttribLocation(program: WebGLProgram, name: string): number;
enableVertexAttribArray(index: number): void;
vertexAttribPointer(index: number, size: number, type: number, 
                   normalized: boolean, stride: number, offset: number): void;

// Uniforms
getUniformLocation(program: WebGLProgram, name: string): WebGLUniformLocation | null;
uniform1f(location: WebGLUniformLocation, x: number): void;
uniform4fv(location: WebGLUniformLocation, value: Float32Array): void;

Vertex Attributes and Uniforms

Framebuffer Operations

Framebuffer and renderbuffer management for off-screen rendering and render-to-texture operations.

// Framebuffer operations
bindFramebuffer(target: number, framebuffer: WebGLFramebuffer | null): void;
framebufferTexture2D(target: number, attachment: number, textarget: number, 
                     texture: WebGLTexture | null, level: number): void;
checkFramebufferStatus(target: number): number;

Framebuffer Operations

Extensions

Standard WebGL extensions plus custom headless-specific extensions for context management.

// Extension management
getExtension(name: string): any;
getSupportedExtensions(): string[];

// Custom extensions
interface STACKGL_resize_drawingbuffer {
  resize(width: number, height: number): void;
}

interface STACKGL_destroy_context {
  destroy(): void;
}

Extensions

State Management

Complete WebGL state management including blending, depth testing, and viewport configuration.

// State control
enable(cap: number): void;
disable(cap: number): void;
isEnabled(cap: number): boolean;

// Viewport and scissor
viewport(x: number, y: number, width: number, height: number): void;
scissor(x: number, y: number, width: number, height: number): void;

// Depth and stencil
depthFunc(func: number): void;
depthMask(flag: boolean): void;
depthRange(zNear: number, zFar: number): void;
stencilFunc(func: number, ref: number, mask: number): void;
stencilMask(mask: number): void;
stencilOp(fail: number, zfail: number, zpass: number): void;

// Blending
blendFunc(sfactor: number, dfactor: number): void;
blendFuncSeparate(srcRGB: number, dstRGB: number, srcAlpha: number, dstAlpha: number): void;
blendEquation(mode: number): void;
blendColor(red: number, green: number, blue: number, alpha: number): void;

WebGL Constants

// Buffer targets
static readonly ARRAY_BUFFER: number;
static readonly ELEMENT_ARRAY_BUFFER: number;

// Buffer usage patterns
static readonly STATIC_DRAW: number;
static readonly DYNAMIC_DRAW: number;
static readonly STREAM_DRAW: number;

// Data types
static readonly BYTE: number;
static readonly UNSIGNED_BYTE: number;
static readonly SHORT: number;
static readonly UNSIGNED_SHORT: number;
static readonly INT: number;
static readonly UNSIGNED_INT: number;
static readonly FLOAT: number;

// Primitive types
static readonly POINTS: number;
static readonly LINES: number;
static readonly LINE_LOOP: number;
static readonly LINE_STRIP: number;
static readonly TRIANGLES: number;
static readonly TRIANGLE_STRIP: number;
static readonly TRIANGLE_FAN: number;

// Texture targets and formats
static readonly TEXTURE_2D: number;
static readonly TEXTURE_CUBE_MAP: number;
static readonly RGBA: number;
static readonly RGB: number;
static readonly ALPHA: number;
static readonly LUMINANCE: number;
static readonly LUMINANCE_ALPHA: number;

// Shader types
static readonly VERTEX_SHADER: number;
static readonly FRAGMENT_SHADER: number;

// Clear buffer bits
static readonly COLOR_BUFFER_BIT: number;
static readonly DEPTH_BUFFER_BIT: number;
static readonly STENCIL_BUFFER_BIT: number;

// Capabilities
static readonly DEPTH_TEST: number;
static readonly STENCIL_TEST: number;
static readonly BLEND: number;
static readonly CULL_FACE: number;
static readonly SCISSOR_TEST: number;

Types

// Core WebGL object types
interface WebGLBuffer {}
interface WebGLTexture {}
interface WebGLFramebuffer {}
interface WebGLRenderbuffer {}
interface WebGLProgram {}
interface WebGLShader {}
interface WebGLUniformLocation {}

interface WebGLActiveInfo {
  readonly name: string;
  readonly size: number;
  readonly type: number;
}

interface WebGLShaderPrecisionFormat {
  readonly rangeMin: number;
  readonly rangeMax: number;
  readonly precision: number;
}