@carrot/engine-renderer

Low-level WebGL2 rendering foundation - owns the GL context, GPU state cache, mesh upload pipeline, and frame lifecycle.

Installation

bash

npm install @carrot/engine-renderer

Architecture / How It Works

This package is the bottom layer of the rendering stack. It provides the raw draw API without any knowledge of render graphs, passes, or scene structure. Higher-level packages (@carrot/engine-renderer-graph) build on top of this.

Core Components

Renderer is the entry point. It creates a WebGL2 context from a canvas, and owns three subsystems:

RenderStateCache - tracks current GPU state (blend mode, depth, cull face, scissor, bound shaders/textures) and only issues GL calls when state actually changes. This is critical for batching performance.
MeshUploader - manages the CPU-to-GPU mesh upload lifecycle. Creates VAOs with attribute bindings (positions, normals, tangents, up to 6 UV channels, vertex colours), caches by Mesh.uniqueId, and re-uploads when meshes are marked dirty.
DrawList - collects submitted DrawCall objects, supports layer-mask filtering, and multi-criteria sorting (shader key, material key, depth) for optimal batching.

Frame Lifecycle

renderer.beginFrame(delta, total) - increments frame counter, updates timing
Game code submits draw calls via renderer.submit(call)
The render graph (or manual code) iterates draw calls, binding shaders/materials/state and calling renderer.draw(gpuMesh) - draw calls submitted before pipeline.execute() survive into pass execution because beginFrame does not clear the draw list
renderer.endFrame() - clears the draw list and performs post-frame cleanup

The draw list lifecycle is: submit → beginFrame → passes read → endFrame clears. This ordering ensures that draw calls submitted between beginFrame and pipeline.execute() are visible to all render passes.

Camera

Camera defines a viewpoint - perspective or orthographic projection, view matrix (via lookAt or direct set), clear settings, viewport rect, render target, and layer mask. Multiple cameras are supported (e.g. main camera + minimap + shadow cameras).

DrawCall

The atomic unit of rendering: a mesh + material + model transform + layer mask. Created via createDrawCall(). Sort keys are computed by DrawList.sort() for batching.

RenderContext

A per-camera, per-frame snapshot passed to render passes: view/projection/VP matrices, target dimensions, frame number, delta time, total time.

Dependencies

Package	Role
`@carrot/engine-meshes`	`Mesh` type used in draw calls and mesh upload
`@carrot/engine-buffers`	`FloatBuffer`, `IndexBuffer` used by MeshUploader for GPU upload
`@carrot/engine-materials`	`MaterialInstance` type referenced in DrawCall
`@carrot/engine-textures`	Render target interface on Camera
`@carrot/maths-geometry`	`Matrix4x4`, `Vector3`, vector/matrix types for transforms and projections
`@carrot/colors`	`ColorRgb`, `ColorRgbLike` for clear colour
`@carrot/signals`	`Signal` for frame lifecycle events

Build

bash

npm run build    # tsc

Output: dist/ (ESM + CJS, TypeScript declarations).

Using @carrot/engine-renderer

Low-level WebGL2 renderer - canvas context management, state caching, mesh upload, draw call submission.

Import

import {
  Renderer, Camera, ClearFlags,
  RenderStateCache, BlendMode, DepthFunc, CullFace, defaultRenderState,
  createDrawCall, DrawList, DrawSortMode,
  createRenderContext, MeshUploader,
} from '@carrot/engine-renderer';

import type { RenderContext, DrawCall, RenderStateDescriptor, GpuMesh } from '@carrot/engine-renderer';

Common Patterns

1. Create a renderer

const canvas = document.getElementById('game') as HTMLCanvasElement;
const renderer = new Renderer(canvas, { antialias: true, alpha: false });

2. Set up a camera

const camera = new Camera();
camera.setPerspective(60, canvas.width / canvas.height, 0.1, 1000);
camera.lookAt({ x: 0, y: 5, z: 10 }, { x: 0, y: 0, z: 0 });
camera.clearFlags = ClearFlags.All;
camera.clearColor = { r: 0.1, g: 0.1, b: 0.15, a: 1 };

3. Orthographic camera (minimap, UI)

const uiCamera = new Camera();
uiCamera.setOrthographic(0, 1920, 0, 1080, -1, 1);
uiCamera.clearFlags = ClearFlags.None;
uiCamera.renderOrder = 10; // render after main camera

4. Multi-camera with render targets

const minimap = new Camera();
minimap.setOrthographic(-50, 50, -50, 50, 0.1, 100);
minimap.target = minimapRenderTexture; // renders to texture, not screen
minimap.renderOrder = 1;

5. Submit draw calls

const call = createDrawCall(mesh, materialInstance, modelMatrix);
renderer.submit(call);

// With a specific layer mask (e.g. layer 2)
const uiCall = createDrawCall(uiMesh, uiMaterial, uiTransform, 1 << 2);
renderer.submit(uiCall);

6. Manual frame loop (without render graph)

function frame(deltaTime: number, totalTime: number) {
  renderer.beginFrame(deltaTime, totalTime);

  // Submit draw calls
  for (const entity of scene.entities) {
    renderer.submit(createDrawCall(entity.mesh, entity.material, entity.transform));
  }

  // Build context
  const ctx = renderer.createContext(camera, deltaTime);

  // Clear and set viewport
  renderer.clear(camera);
  renderer.setViewport(camera, canvas.width, canvas.height);

  // Sort and iterate
  renderer.drawList.sort(DrawSortMode.FrontToBack);
  for (const call of renderer.drawList) {
    // Bind shader, set uniforms, then:
    const gpuMesh = renderer.meshes.getOrUpload(call.mesh);
    if (gpuMesh) renderer.draw(gpuMesh);
  }

  renderer.endFrame();
}

7. Apply render state

// Apply a full state descriptor (only diffs are sent to GPU)
renderer.state.apply({
  blend: BlendMode.Alpha,
  depthTest: true,
  depthWrite: false,
  depthFunc: DepthFunc.Less,
  cullFace: CullFace.Back,
  scissorTest: false,
});

// Or set individual states
renderer.state.setBlend(BlendMode.Additive);
renderer.state.setDepthWrite(false);
renderer.state.setCullFace(CullFace.None);

// Bind shader/texture (tracked to avoid redundant binds)
renderer.state.bindShader(program);
renderer.state.bindTexture(0, gl.TEXTURE_2D, texture);

8. Filter draw calls by layer

// Get only layer 0 draw calls
const layer0Calls = renderer.drawList.filter(1);

// Get layers 0 and 3
const filtered = renderer.drawList.filter((1 << 0) | (1 << 3));

// All layers (fast path - no filtering)
const all = renderer.drawList.filter(0xFFFFFFFF);

9. Frame lifecycle signals

renderer.onBeginFrame.listen((ctx) => {
  console.log(`Frame ${ctx.frameNumber}, dt=${ctx.deltaTime}`);
});

renderer.onEndFrame.listen((ctx) => {
  // post-frame work
});

10. Cleanup

renderer.dispose(); // disposes all uploaded meshes

// Dispose a single mesh by ID
renderer.meshes.dispose(mesh.uniqueId);

Package Contents