OGL-TypeScript

Common errors

• TypeError: Cannot read properties of undefined (reading 'getContext')

  cause The `Renderer` constructor was called without a valid HTMLCanvasElement, or the provided canvas was null/undefined, preventing WebGL context creation.
  fix Ensure `document.createElement('canvas')` successfully creates an element and it's appended to the DOM, or pass an existing, valid canvas element (e.g., `canvas: document.getElementById('my-canvas')`).

• SyntaxError: The requested module 'ogl-typescript' does not provide an export named 'SomeMissingExport'

  cause Attempting to import a named symbol that does not exist or is misspelled within the `ogl-typescript` package, or it was renamed in a new version.
  fix Review the `ogl-typescript` type definitions or documentation (or the original OGL documentation) to verify the correct symbol name and its export status. Ensure case sensitivity is respected.

• Property 'someProperty' does not exist on type '...' (TypeScript error)

  cause A TypeScript compilation error indicating that an accessed property or method is not part of the expected type, often due to an API change in the underlying OGL library that `ogl-typescript` ports, or incorrect usage.
  fix Check the version compatibility between your `ogl-typescript` package and the corresponding OGL version's API documentation. Update your code to reflect the current API, or consider upgrading `ogl-typescript` if the feature was added recently.

Warnings

• breaking OGL-TypeScript acts as a direct port of the original OGL library. Consequently, any API changes or breaking updates introduced in upstream OGL versions will directly propagate to ogl-typescript, often leading to breaking changes in minor versions (e.g., 0.1.x).
  Fix: Always consult the release notes of the corresponding OGL version that ogl-typescript mirrors (as listed in the versions table in the README) for details on API changes and migration steps when updating.
• gotcha Incorrect or delayed WebGL context initialization, or improper canvas element handling, can lead to rendering failures or errors like 'Cannot read properties of undefined (reading 'getContext')'.
  Fix: Ensure the HTML canvas element is correctly created and appended to the DOM before initializing the Renderer. Verify `renderer.gl` is a valid WebGLRenderingContext after instantiation to confirm context creation.
• gotcha Shader compilation errors in the `Program` constructor are common. Issues often stem from GLSL syntax mistakes, undeclared uniforms/attributes, or type mismatches within the shaders.
  Fix: Thoroughly review your vertex and fragment shader code for GLSL syntax correctness. Utilize browser developer tools (e.g., Chrome's 'WebGL' tab) for detailed shader compilation logs and error messages.

Install

• npm install ogl-typescript npm
• yarn add ogl-typescript yarn
• pnpm add ogl-typescript pnpm

Imports

• Renderer
  wrong:

  const Renderer = require('ogl-typescript').Renderer

  correct:

  import { Renderer } from 'ogl-typescript'

  OGL-TypeScript is designed for ESM; CommonJS `require` syntax is generally not supported for individual named exports in modern setups, leading to potential issues.
• Camera
  wrong:

  import Camera from 'ogl-typescript'

  correct:

  import { Camera } from 'ogl-typescript'

  All core components like Camera are named exports, not default exports. Attempting a default import will result in an error.
• Mesh
  wrong:

  import { Mesh } from 'ogl'

  correct:

  import { Mesh, Program, Geometry } from 'ogl-typescript'

  Ensure you are importing from 'ogl-typescript' and not the original 'ogl' package to benefit from TypeScript types and the ported codebase.

Quickstart

This quickstart initializes a WebGL renderer, sets up a camera, creates a simple 3D plane geometry, defines a basic shader program, and renders a spinning mesh on a canvas, demonstrating core OGL-TypeScript usage.

import { Renderer, Camera, Transform, Program, Geometry, Mesh } from 'ogl-typescript';

// 1. Setup Renderer
const renderer = new Renderer({
    canvas: document.createElement('canvas'),
    width: window.innerWidth,
    height: window.innerHeight,
    dpr: Math.min(window.devicePixelRatio, 2),
});
document.body.appendChild(renderer.canvas);

// 2. Setup Camera
const camera = new Camera({ fov: 45 });
camera.position.set(0, 0, 5);
camera.lookAt([0, 0, 0]);

// 3. Create a Scene (as a Transform) to hold objects
const scene = new Transform();

// 4. Create Geometry (a simple plane)
const geometry = new Geometry(renderer.gl, {
    position: {
        size: 3,
        data: new Float32Array([
            -1, 1, 0, // Top-left
            -1, -1, 0, // Bottom-left
            1, -1, 0, // Bottom-right
            1, 1, 0, // Top-right
        ]),
    },
    uv: {
        size: 2,
        data: new Float32Array([
            0, 1,
            0, 0,
            1, 0,
            1, 1,
        ]),
    },
    index: {
        data: new Uint16Array([
            0, 1, 2,
            0, 2, 3,
        ]),
    },
});

// 5. Create a basic Program (shader) to define material properties
const program = new Program(renderer.gl, {
    vertex: /* glsl */ `
        attribute vec3 position;
        attribute vec2 uv;

        uniform mat4 modelViewMatrix;
        uniform mat4 projectionMatrix;

        varying vec2 vUv;

        void main() {
            vUv = uv;
            gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
        }
    `,
    fragment: /* glsl */ `
        precision highp float;

        varying vec2 vUv;

        void main() {
            gl_FragColor = vec4(vUv.x, vUv.y, 0.5, 1.0);
        }
    `,
});

// 6. Create a Mesh by combining geometry and program, then add to scene
const mesh = new Mesh(renderer.gl, { geometry, program });
mesh.setParent(scene);

// 7. Render Loop for animation
function update() {
    requestAnimationFrame(update);

    // Rotate the mesh for visual interest
    mesh.rotation.y -= 0.005;
    mesh.rotation.x -= 0.003;

    renderer.render({ scene, camera });
}
requestAnimationFrame(update);

// Basic resize handling to keep aspect ratio correct
window.addEventListener('resize', () => {
    renderer.setSize(window.innerWidth, window.innerHeight);
    camera.perspective({ aspect: window.innerWidth / window.innerHeight });
});