chorama 0.0.0

package/astro.config.mjs

@@ -0,0 +1,45 @@
+import { defineConfig } from "astro/config";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import remarkGfm from "remark-gfm";
+import remarkGithubBlockquoteAlert from "remark-github-blockquote-alert";
+import remarkLinkBase from "./website/plugins/remark-link-base.js";
+
+function glsl() {
+  return {
+    name: "glsl",
+    enforce: "pre",
+    load(id) {
+      if (!id.endsWith(".glsl")) {
+        return null;
+      }
+
+      return `export default ${JSON.stringify(readFileSync(id, "utf8"))}`;
+    },
+  };
+}
+
+export default defineConfig({
+  output:'static',
+  srcDir: "./website",
+  publicDir: "./assets",
+  outDir: "./dist/website",
+  vite: {
+    plugins: [glsl()],
+    resolve: {
+      alias: {
+        "chorama": path.resolve("./src/index.js"),
+        "@configs": path.resolve("./website/config"),
+        "@layouts": path.resolve("./website/layouts"),
+        "@components": path.resolve("./website/components"),
+      }
+    }
+  },
+  markdown: {
+    remarkPlugins: [
+      remarkGfm,
+      remarkGithubBlockquoteAlert,
+      remarkLinkBase,
+    ],
+  },
+});

package/content/guide/api-map.md

@@ -0,0 +1,89 @@
+---
+title: "API Map"
+---
+
+# API Map
+
+This is a high-level map of the public surface exported from `src/index.js`.
+
+## Quick Import Example
+
+```js
+import {
+  WebGLRenderDevice,
+  WebGLRenderer,
+  Camera,
+  MeshMaterial3D,
+  MeshMaterialPlugin,
+  CameraPlugin
+} from "chorama";
+```
+
+## Rendering Core
+
+- `WebGLRenderDevice`
+- `WebGLRenderer`
+- Core descriptors/pipeline types from `core`
+
+## Scene Objects
+
+- `Object3D`
+- `MeshMaterial3D`
+- `Camera`
+- `SkyBox`
+- `Bone3D`
+
+## Materials
+
+- `BasicMaterial`
+- `LambertMaterial`
+- `PhongMaterial`
+- `StandardMaterial`
+- `RawMaterial`
+- Debug variants (`NormalMaterial`, `DepthMaterial`)
+
+## Lighting
+
+- `AmbientLight`
+- `DirectionalLight`
+- `PointLight`
+- `SpotLight`
+- Shadow helpers
+
+## Geometry and Mesh
+
+- `Mesh`
+- Mesh builders: `PlaneMeshBuilder`, `CuboidMeshBuilder`, `UVSphereMeshBuilder`, etc.
+- `Attribute` and attribute-data utilities
+
+## Camera and Control
+
+- `PerspectiveProjection`
+- `OrthographicProjection`
+- `OrbitCameraControls`
+
+## Assets and Textures
+
+- `TextureLoader`
+- `OBJLoader`
+- `GLTFLoader`
+- `Texture`, `Sampler`
+
+## Render Targets
+
+- `CanvasTarget`
+- `ImageTarget`
+- `RenderTarget`
+
+## Plugins
+
+- `CameraPlugin`
+- `MeshMaterialPlugin`
+- `LightPlugin`
+- `ShadowPlugin`
+- `SkyboxPlugin`
+
+For real usage patterns:
+
+- [Rotating Cube](/examples/other/rotatingCube)
+- [Examples Overview](/examples)

package/content/guide/camera-and-controls.md

@@ -0,0 +1,98 @@
+---
+title: "Camera and Controls"
+---
+
+# Camera and Controls
+
+This guide assumes you already have a working render loop from [First Scene](/guide/first-scene).
+Here, we only focus on camera setup and controls.
+
+## What You Will Add
+
+- one camera bound to a render target
+- a perspective projection setup
+- orbit controls for mouse/touch navigation
+
+## Step 1: Import Camera APIs
+
+```js
+import {
+  Camera,
+  PerspectiveProjection,
+  OrthographicProjection,
+  OrbitCameraControls
+} from "chorama";
+```
+
+You only need `OrthographicProjection` if you plan to switch projection type.
+
+## Step 2: Create a Camera
+
+```js
+const camera = new Camera(target);
+camera.transform.position.z = 3;
+```
+
+`target` should be your existing `CanvasTarget`.
+The `z` offset keeps objects visible in front of the camera.
+
+## Step 3: Configure Perspective Projection
+
+```js
+if (camera.projection instanceof PerspectiveProjection) {
+  camera.projection.fov = Math.PI / 3;
+  camera.projection.aspect = innerWidth / innerHeight;
+}
+```
+
+Use this as the default for most real-time 3D scenes.
+
+## Step 4: Add Orbit Controls
+
+```js
+const controls = new OrbitCameraControls(camera, canvas);
+controls.distance = 4;
+```
+
+`canvas` should be the element receiving pointer input.
+`distance` controls how far the orbit camera stays from its target.
+
+## Step 5: Update Controls in the Frame Loop
+
+```js
+function frame() {
+  controls.update();
+  renderer.render([object, camera], device);
+  requestAnimationFrame(frame);
+}
+
+requestAnimationFrame(frame);
+```
+
+Call `controls.update()` every frame before rendering.
+If you skip it, input changes will not be applied.
+
+## Switch to Orthographic Projection
+
+Use orthographic projection when you need no perspective foreshortening.
+
+```js
+const ortho = new OrthographicProjection();
+ortho.left = -5;
+ortho.right = 5;
+ortho.top = 5;
+ortho.bottom = -5;
+
+camera.projection = ortho;
+```
+
+For orthographic cameras, update bounds yourself when viewport shape changes.
+
+## Reference Examples
+
+If you want to compare against an example, see:
+
+- [Perspective Camera](/examples/camera/perspective)
+- [Orthographic Camera](/examples/camera/orthographic)
+
+After this works, continue with [Materials and Lighting](/guide/materials-and-lighting).

package/content/guide/first-scene.md

@@ -0,0 +1,176 @@
+---
+title: "First Scene"
+---
+
+# First Scene
+
+This guide helps you render your first object on screen with the smallest useful setup.
+You will build one scene with:
+
+- one canvas
+- one render device
+- one renderer
+- one camera
+- one cube mesh
+- one animation loop
+
+The goal is to get a stable baseline you can reuse in every new project.
+
+## What You Will Build
+
+At the end, you will have a rotating cube rendered each frame.
+No lighting setup, model loading, or advanced scene graph features are required here.
+Those topics are covered in other dedicated guides.
+
+## Before You Start
+
+Make sure you already have a working local install from [Installation](/guide/installation).
+You should be able to import from `chorama` or your local alias path.
+
+## Build Your first scene
+
+In your source file, do the following:
+
+### Step 1: Import what you need
+
+```js
+import {
+  WebGLRenderDevice,
+  CanvasTarget,
+  WebGLRenderer,
+  Camera,
+  PerspectiveProjection,
+  MeshMaterial3D,
+  BasicMaterial,
+  CuboidMeshBuilder,
+  Quaternion,
+  MeshMaterialPlugin,
+  CameraPlugin
+} from "chorama";
+```
+
+This imports all the items we require for this setup.
+
+### Step 2: Create and mount a canvas
+
+```js
+const canvas = document.createElement("canvas");
+document.body.append(canvas);
+```
+Create the canvas and appends it to the body of the html document
+
+### Step 3: Create device and render target
+
+```js
+const device = new WebGLRenderDevice(canvas, { depth: true });
+const target = new CanvasTarget(canvas);
+```
+
+The `device` manages GPU-side rendering operations.
+The `target` is the camera output surface.
+
+### Step 4: Create renderer and required plugins
+
+```js
+const renderer = new WebGLRenderer({
+  plugins: [new MeshMaterialPlugin(), new CameraPlugin()]
+});
+```
+
+These two plugins are required for this scene:
+
+- `MeshMaterialPlugin` draws mesh plus material objects.
+- `CameraPlugin` enables camera processing in the render pass.
+
+### Step 5: Create and position a camera
+
+```js
+const camera = new Camera(target);
+camera.transform.position.z = 2.5;
+
+if (camera.projection instanceof PerspectiveProjection) {
+  camera.projection.fov = Math.PI / 3;
+  camera.projection.aspect = 1;
+}
+```
+
+Moving camera on `z` ensures the cube is in front of the view.
+The initial `aspect` is a temporary placeholder; resize will set the real value.
+
+### Step 6: Create a cube object
+
+```js
+const cubeMesh = new CuboidMeshBuilder().build();
+const cubeMaterial = new BasicMaterial();
+const cube = new MeshMaterial3D(cubeMesh, cubeMaterial);
+```
+
+This creates one drawable object with default shading.
+Using `BasicMaterial` for an object that has no lighting applied to it.
+
+### Step 7: Define per-frame rotation
+
+```js
+const stepRotation = Quaternion.fromEuler(0.01, 0.01, 0.0);
+```
+
+This rotation is multiplied into cube orientation each frame to animate motion.
+
+### Step 8: Add resize handling
+
+```js
+function resize() {
+  const cssWidth = window.innerWidth;
+  const cssHeight = window.innerHeight;
+  const dpr = window.devicePixelRatio || 1;
+
+  canvas.style.width = cssWidth + "px";
+  canvas.style.height = cssHeight + "px";
+  canvas.width = Math.floor(cssWidth * dpr);
+  canvas.height = Math.floor(cssHeight * dpr);
+
+  if (camera.projection instanceof PerspectiveProjection) {
+    camera.projection.aspect = cssWidth / cssHeight;
+  }
+}
+
+window.addEventListener("resize", resize);
+resize();
+```
+
+This keeps render resolution sharp and camera projection correct.
+If you skip this, stretching and blur are likely on resize or high-DPI screens.
+
+### Step 9: Start the render loop
+
+```js
+function frame() {
+  cube.transform.orientation.multiply(stepRotation);
+  renderer.render([cube, camera], device);
+  requestAnimationFrame(frame);
+}
+
+requestAnimationFrame(frame);
+```
+
+Each frame does three things: update state, render, schedule next frame.
+
+## What You Can Try Next
+
+Change only one variable at a time:
+
+- move camera: `camera.transform.position.z = 4`
+- stop rotation: remove `cube.transform.orientation.multiply(stepRotation)`
+- rotate one axis only: `Quaternion.fromEuler(0.0, 0.01, 0.0)`
+- change shape: replace `CuboidMeshBuilder` with another mesh builder
+
+These changes help verify your scene wiring before adding complexity.
+
+## Reference Example
+
+If you want to compare against an example, see:
+
+- [Rotating Cube](/examples/other/rotatingCube)
+
+After this works, continue with [Camera and Controls](/guide/camera-and-controls).
+

package/content/guide/index.md

@@ -0,0 +1,72 @@
+---
+title: "Guide"
+---
+
+# Guide
+
+This guide helps you build scenes with Chorama using practical, task-first steps.
+
+## Overview
+
+Chorama is a modular WebGL2 rendering library focused on explicit control: you compose render behavior with plugins, build scenes from reusable object/material/light primitives, and keep direct visibility into the render flow.
+
+> [!WARNING]
+> Chorama is currently experimental and is not recommended for production use.
+> Expect API changes, behavior changes and breaking changes as the library evolves.
+
+This guide is structured to take you from first render to production-style scene setup. Instead of covering every class in isolation first, each chapter is anchored to a concrete task and points you to full runnable examples.
+
+By the end of this guide, you should be able to:
+
+- Set up a render loop with `WebGLRenderDevice`, `CanvasTarget`, and `WebGLRenderer`
+- Build and animate scene objects with camera, materials, and lights
+- Load texture/model assets and handle async content safely
+- Use render targets and view configuration for offscreen and multi-view scenarios
+- Understand the plugin-driven pipeline enough to debug and extend behavior
+
+## Who This Guide Is For
+
+Use this if you want direct WebGL2 control but still want reusable building blocks.
+
+## How To Use This Guide
+
+- New to Chorama: follow the reading order from top to bottom.
+- Migrating from another renderer: start at [First Scene](/guide/first-scene), then jump to [Plugins and Render Pipeline](/guide/plugins-and-render-pipeline).
+- Looking for a specific API: use [API Map](/guide/api-map) as an index, then return to task pages for applied usage.
+- Blocked on behavior: check [Troubleshooting](/guide/troubleshooting), then compare your setup against a matching example route.
+
+## Reading Order
+
+1. [Installation](/guide/installation)
+2. [First Scene](/guide/first-scene)
+3. [Camera and Controls](/guide/camera-and-controls)
+4. [Materials and Lighting](/guide/materials-and-lighting)
+5. [Textures and Assets](/guide/textures-and-assets)
+6. [Render Targets and Views](/guide/render-targets-and-views)
+7. [Scene Graph and Transforms](/guide/scene-graph-and-transforms)
+8. [Plugins and Render Pipeline](/guide/plugins-and-render-pipeline)
+9. [API Map](/guide/api-map)
+10. [Troubleshooting](/guide/troubleshooting)
+
+## Core Flow
+
+The snippet below creates the minimum pieces needed to render a scene:
+
+```js
+import { WebGLRenderDevice, CanvasTarget, WebGLRenderer, Camera } from "chorama";
+
+const canvas = document.createElement("canvas");
+const device = new WebGLRenderDevice(canvas, { depth: true });
+const target = new CanvasTarget(canvas);
+const renderer = new WebGLRenderer();
+const camera = new Camera(target);
+```
+The `canvas` is the HTML surface where we draw on (or in a more technical terms, render to).
+The `WebGLRenderDevice` executes our draw commands.
+The `CanvasTarget` tells the camera where to render to. There is another type of target but thats for later.
+The `WebGLRenderer` runs the render pipeline each frame.
+The `Camera` provides view/projection data the renderer needs.
+
+This snippet exists to show the baseline setup used in almost every example, so later chapters can add one concept at a time without repeating setup details.
+
+For a complete runnable example, start with [Rotating Cube](/examples/other/rotatingCube).

package/content/guide/installation.md

@@ -0,0 +1,179 @@
+---
+title: "Installation"
+---
+
+# Installation
+
+Choose how you want to use the library:
+
+- If you want to use it now: use **Manual Installation**.
+- If you are waiting for package distribution: see **NPM** or **CDN**.
+
+## NPM
+
+> [!Note]
+> This method is not yet available.
+
+## CDN
+
+> [!Note]
+> This method is not yet available.
+
+## Manual Installation
+
+### 1) Requirements
+
+Install these first:
+
+- [Git](https://git-scm.com/downloads) to clone the source code
+- [Node.js 18+](https://nodejs.org/) (includes npm) to install dependencies and build
+- A browser with WebGL2 support to run your app/examples
+
+### 2) Clone the repository and install dependencies
+
+```bash
+git clone https://github.com/waynemwashuma/chorama.git
+cd chorama
+npm install
+```
+
+### 3) Build the library files
+
+```bash
+npm run build-src
+```
+
+This creates build output in `dist/`, including:
+
+- `dist/index.umd.js`
+- `dist/index.module.js`
+
+Optional: if you also want local docs/examples output, run:
+
+```bash
+npm run build
+```
+
+### 4) Copy files to your project
+
+Copy one or both build files into your own project.
+
+- Use `dist/index.module.js` for ESM usage (recommended).
+- Use `dist/index.umd.js` for plain script-tag usage.
+
+Example layout used below:
+
+```text
+your-project/
+  libs/
+    chorama/
+      index.module.js
+      index.umd.js
+```
+
+### 5) Use in your project
+
+#### ESM (recommended)
+
+If you use a bundler, set an alias so your app can import from `"chorama"` directly.
+
+##### Vite (`vite.config.js`)
+
+```js
+import { defineConfig } from "vite";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default defineConfig({
+  resolve: {
+    alias: {
+      chorama: path.resolve(__dirname, "libs/chorama/index.module.js")
+    }
+  }
+});
+```
+
+##### Webpack (`webpack.config.js`)
+
+```js
+const path = require("node:path");
+
+module.exports = {
+  resolve: {
+    alias: {
+      chorama: path.resolve(__dirname, "libs/chorama/index.module.js")
+    }
+  }
+};
+```
+
+Then import in app code:
+
+```js
+import { WebGLRenderer, MeshMaterialPlugin, CameraPlugin } from "chorama";
+```
+
+#### Plain HTML with browser import maps (no bundler)
+
+Use the ESM file with an import map:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Chorama - Import Map</title>
+    <script type="importmap">
+      {
+        "imports": {
+          "chorama": "./libs/chorama/index.module.js"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <canvas id="app"></canvas>
+    <script type="module">
+      import { WebGLRenderer, MeshMaterialPlugin, CameraPlugin } from "chorama";
+
+      const canvas = document.getElementById("app");
+      const renderer = new WebGLRenderer({
+        canvas,
+        plugins: [new MeshMaterialPlugin(), new CameraPlugin()]
+      });
+    </script>
+  </body>
+</html>
+```
+
+#### Plain HTML with script tag (UMD)
+
+Use the UMD build if you do not want modules:
+
+```html
+<!doctype html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Chorama - Plain HTML</title>
+    <script src="./libs/chorama/index.umd.js"></script>
+  </head>
+  <body>
+    <canvas id="app"></canvas>
+    <script>
+      const { WebGLRenderer, MeshMaterialPlugin, CameraPlugin } = window.CHORAMA;
+      const canvas = document.getElementById("app");
+
+      const renderer = new WebGLRenderer({
+        canvas,
+        plugins: [new MeshMaterialPlugin(), new CameraPlugin()]
+      });
+    </script>
+  </body>
+</html>
+```