🎨 @certe/atmos-renderer

WebGPU-first rendering package for the Atmos Engine. Handles GPU initialization, PBR shading, multi-light systems, cascaded shadow maps, skeletal animation (GPU skinning), terrain rendering, and a full HDR post-processing pipeline.

🔑 Key Features

• PBR Cook-Torrance shading with albedo, metallic, roughness, normal, and emissive maps
• 3 light types — Directional, Point, Spot (up to 4 each)
• Cascaded Shadow Maps (2-cascade CSM) + point cube shadows + spot shadows
• HDR pipeline — MSAA 4× → HDR resolve → Bloom → SSAO → Tonemapping (ACES)
• GPU skinning — separate skinned pipeline with bone matrix storage buffer
• Terrain pipeline — splat-textured terrain with 3-layer blending
• Geometry primitives — cube, sphere, cylinder, plane

🚀 Quick Start

import { initWebGPU, createRenderPipeline, createMesh, createMaterial,
         RenderSystem, Camera, MeshRenderer, createCubeGeometry } from '@certe/atmos-renderer';

const gpu = await initWebGPU(canvas);
const pipeline = createRenderPipeline(gpu);

// Create a mesh + material
const mesh = createMesh(gpu.device, createCubeGeometry());
const material = createMaterial(gpu.device, pipeline, {
  albedo: [0.8, 0.2, 0.2, 1],
  metallic: 0.0,
  roughness: 0.5,
});

// Attach to a GameObject
const cube = new GameObject('Cube');
const mr = cube.addComponent(MeshRenderer);
mr.init({ mesh, material, device: gpu.device, pipelineResources: pipeline });

// Render
const renderSystem = new RenderSystem(gpu, pipeline, scene);

📖 API Overview

Initialization

| Function | Description | |---|---| | initWebGPU(canvas) | Request adapter + device, configure canvas | | resizeGPU(gpu) | Sync canvas pixel size, recreate depth/MSAA/HDR textures | | createRenderPipeline(gpu) | Create the PBR render pipeline + bind group layouts |

Geometry & Mesh

| Function | Description | |---|---| | createCubeGeometry() | 32B/vertex (pos+normal+uv) | | createSphereGeometry(seg?) | Latitude-longitude sphere | | createCylinderGeometry(seg?) | With top/bottom caps | | createPlaneGeometry(size?) | XZ plane | | createMesh(device, geo) | Upload to GPU, retains CPU data for picking |

Materials

const mat = createMaterial(device, pipeline, {
  albedo: [1, 1, 1, 1],
  metallic: 0.5,
  roughness: 0.3,
  emissive: [1, 0.5, 0],
  emissiveIntensity: 2.0,
});
// Textures: mat.albedoTexture, mat.normalTexture, mat.metallicRoughnessTexture

Lights

// Add as components to GameObjects
const light = obj.addComponent(DirectionalLight);
light.color = new Float32Array([1, 1, 1]);
light.intensity = 1.5;
light.castShadows = true;

obj.addComponent(PointLight);   // color, intensity, range
obj.addComponent(SpotLight);    // + innerAngle, outerAngle

Camera

const cam = obj.addComponent(Camera);
cam.fov = 60;
cam.near = 0.1;
cam.far = 1000;

// Screen-to-world unprojection
const worldPos = Camera.screenToWorldPoint(sx, sy, depth, camera, canvas);

Post-Processing

The RenderSystem exposes controls for the full post-fx chain:

| Property | Default | Description | |---|---|---| | exposure | 1.0 | Pre-tonemap multiplier | | bloomIntensity | 0.04 | Bloom strength | | bloomThreshold | 1.0 | HDR threshold for bloom | | ssaoEnabled | false | Toggle SSAO | | ssaoRadius / ssaoBias / ssaoIntensity | — | SSAO tuning | | vignetteIntensity / vignetteRadius | — | Screen-edge darkening |

Render Pipeline Flow

Depth Pre-pass
Shadow Passes (CSM × 2 + Point + Spot)
Main Pass (MSAA 4× → HDR resolve)
SSAO (half-res, 16 samples)
Bloom (5-level downsample/upsample)
Tonemap (ACES + gamma 2.2 + vignette) → Swapchain

📁 Structure

packages/renderer/src/
  index.ts                # Public API
  pipeline.ts             # PBR pipeline, constants (HDR_FORMAT, MSAA_SAMPLE_COUNT)
  shader.ts               # PBR WGSL vertex + fragment shaders
  material.ts             # Material creation + uniform writes
  camera.ts               # Camera component
  render-system.ts        # Frame orchestration
  directional-light.ts    # DirectionalLight component
  point-light.ts          # PointLight component
  spot-light.ts           # SpotLight component
  geometry.ts             # Primitive factories
  mesh.ts                 # GPU mesh creation
  mesh-renderer.ts        # MeshRenderer component
  skinned-pipeline.ts     # GPU skinning pipeline
  skinned-mesh-renderer.ts # SkinnedMeshRenderer component
  bloom-pass.ts           # 5-level bloom
  tonemap-pass.ts         # ACES tonemapping + vignette
  ssao-pass.ts            # Screen-space ambient occlusion
  depth-prepass.ts        # Non-MSAA depth for SSAO
  directional-shadow-pass.ts # Cascaded shadow maps
  point-shadow-pass.ts    # Cube shadow maps
  spot-shadow-pass.ts     # Spot light shadows
  texture.ts              # Texture creation + decoding
  mipmap-generator.ts     # Blit-based mipmap generation
  grid-renderer.ts        # Infinite XZ grid overlay

🔗 Dependencies

• @certe/atmos-core — Component, GameObject, Transform, Scene
• @certe/atmos-math — Vec3, Mat4, Quat for camera/light math