ris-framework 0.2.0-dev.12 → 0.2.0-dev.13

package/CHANGELOG.md

@@ -19,7 +19,6 @@ Compared with `main` (0.1.0).
 
 ### Added
 
-- WebGPU backend (preview): set `renderingBackend` and call `framework.initializeAsync()`. Only unlit materials are supported so far; WebGL stays the default and is used as a fallback.
 - `Scene` with `add`/`remove` for meshes, lights and the camera, plus `SceneMesh` for owning a mesh and its materials.
 - Lights: `AmbientLight`, `DirectionalLight` and `PointLight`.
 - `ForwardBlinnPhongMaterial`, `SpriteMaterial`, and the `ICameraMaterial`/`ILightsMaterial` interfaces.
@@ -27,7 +26,7 @@ Compared with `main` (0.1.0).
 - OBJ/MTL loading through `framework.objLoader`, `ObjParser`, and `content.loadMeshAsync`, `loadUnlitMeshAsync` and `loadBlinnPhongMeshAsync`.
 - `geometryBuilder.create(descriptor)` and the exported `BaseGeometry`.
 - sRGB compressed texture formats (BC1, BC3, BC7, ETC2), with KTX2 loading choosing sRGB automatically.
-- Examples: `unlit_mesh`, `unlit_mesh_webgpu`, `blinn_phong_mesh` and `sprite_batch`.
+- Examples: `unlit_mesh`, `blinn_phong_mesh` and `sprite_batch`.
 
 ### Changed
 

package/README.md

@@ -1,212 +1,149 @@
 # ris-framework
 
-`ris-framework` is a browser WebGL2 framework, published as an ES module. Version 0.1.0. An application imports the compiled package. This repository also contains a sample page that runs the framework.
-
-Open `index.html`. The module script is `src/main.ts`. That file builds the page, constructs a `Framework`, and starts the frame loop. Shared interfaces and value types (`IFramework`, `Color`, `Rect`, `TextureDescriptor`, and the rest) ship from this package. They used to live in `ris-framework-api`. This repository implements them.
-
-## Layout
-
-| Path | What lives there |
-| --- | --- |
-| `index.html` | The page. It has `#app` and `<canvas id="game-canvas" width="800" height="600">`. |
-| `src/main.ts` | Application entry. |
-| `src/index.ts` | Package entry. Exports `Framework`, `FrameworkConfiguration`, `TextureSamplerFilteringPreset`, and everything under `src/api`. |
-| `src/Framework.ts` | `Framework`, which wires the renderer, factories, managers, and the frame loop together. |
-| `src/api` | Interfaces and value types formerly published as `ris-framework-api` (input, textures, cameras, `TextureUtilities`, and the rest). It also holds `FrameworkConfiguration` and the backend-independent implementations: `WindowManager`, `InputManager`, `ContentManager`, `SpriteBatch`, `GeometryBuilder`, and `BaseGeometry`. `src/api/content/ShaderModuleContent.ts` maps the built-in shader module ids to GLSL from `shaders/glsl`. |
-| `src/core` | Renderer and graphics-device base classes (`ARenderer`, `AGraphicsDevice`), the texture base class, blend and sampler descriptors, `VertexBufferLayout`, and `TextureSamplerFilteringPreset`. |
-| `src/webgl` | The WebGL2 graphics device, renderer, textures, buffers, samplers, and render pipelines. |
-| `shaders/glsl` | Vertex and fragment shaders used by the built-in shader modules. |
-| `tests` | Vitest tests for the types under `src/api`. |
-
-Runtime dependencies are `ris-ktx2` and `gl-matrix`. The KTX2 types (`IKtx2Texture`, `VkFormat`, `KtxTranscodeFormat`, and the rest) are imported from `ris-ktx2`. The library build includes the browser portion of `ris-ktx2`, with its Node loader replaced by a stub, so the published entry does not import Node built-ins. TypeScript, Vite, and Vitest are dev dependencies. Notices for the bundled KTX loader are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The package license is Apache License 2.0. Copyright 2026 Luka Erkapic. See [LICENSE](LICENSE) and [NOTICE](NOTICE).
-
-## Prerequisites
-
-- Node.js 22. Continuous integration uses Node.js 22. Vite 7 in this repo requires `^20.19.0` or `>=22.12.0`.
-- npm.
-- A browser that can create a WebGL2 context. If `canvas.getContext("webgl2")` fails, startup throws `WebGL not supported.`
-
-## Install
-
-Install the package in an application:
+A browser WebGL2 framework for TypeScript, published as an ES module (version 0.2.0). Runtime dependencies are `gl-matrix` and `ris-ktx2`.
 
 ```sh
 npm install ris-framework
 ```
 
-The published entry is compiled JavaScript and TypeScript declarations (`dist/index.js` and `dist/index.d.ts`). Import the public surface by package name:
+Everything public is exported from the package entry: `Framework`, `TextureSamplerFilteringPreset`, and the API types (scenes, meshes, materials, lights, cameras, textures, loaders, input).
 
-```ts
-import { Framework, FrameworkConfiguration, TextureSamplerFilteringPreset } from "ris-framework";
-```
+## Create and start a framework
 
-The same entry re-exports the former `ris-framework-api` surface, so a consumer can import those names from `ris-framework`:
+Pass an `IFrameworkConfiguration` object. Every field is optional.
 
 ```ts
-import { Color, Rect, TextureFormat, TextureUtilities, type IInputManager } from "ris-framework";
-```
+import { Color, Framework, type IFrameworkConfiguration, TextureSamplerFilteringPreset } from "ris-framework";
 
-`Framework`, `FrameworkConfiguration`, `TextureSamplerFilteringPreset`, and that API surface are the public entry. Built-in GLSL is compiled into `dist/index.js`, so a consumer does not load this repository's `shaders/` directory at runtime. The same file includes the browser KTX2 loader. A consuming Vite app can import the package and build without adding a Node stub of its own.
+const config: IFrameworkConfiguration = {
+    canvas: document.querySelector<HTMLCanvasElement>("#game-canvas")!,
+    textureFiltering: TextureSamplerFilteringPreset.BILINEAR,
+    useKtx2: true,
+};
 
-To work in this repository:
-
-```sh
-npm ci
-```
-
-`Framework` creates its services itself and passes dependencies through their constructors; no dependency-injection container or `reflect-metadata` import is needed.
-
-## Create a framework instance
-
-Construct `FrameworkConfiguration`, then pass it to `Framework`. The constructor is `constructor(options?: IFrameworkConfiguration)`. Omitting the argument uses `new FrameworkConfiguration()`. The constructor writes the resolved `backBufferSize` back onto the object you pass.
+const framework = new Framework(config);
 
-Another project imports that public entry by package name: `import { Framework, FrameworkConfiguration, TextureSamplerFilteringPreset } from "ris-framework"`.
+framework.addOnLoadContentListener(async () => { /* load content */ });
+framework.addOnUpdateListener(time => { /* update, time.deltaTimeSec */ });
+framework.addOnRenderListener(() => { /* draw */ });
 
-No config field is required. Each field has a default.
+framework.initialize();
+framework.renderer.clearColor = Color.cornerFlowerBlue();
+```
 
-| Field | Default | What the code does with it |
+| Field | Default | Meaning |
 | --- | --- | --- |
-| `canvas` | `undefined` | The canvas the WebGL2 context is created from. When unset, `Framework` logs a warning and `WindowManager` creates a canvas and appends it to `document.body`. `src/main.ts` sets this to `#game-canvas`. |
-| `backBufferSize` | `undefined` (the constructor uses `vec2.fromValues(800, 600)`) | Copied onto an internal `IRendererConfiguration`. `WebGlRenderer` leaves that copy unused. The main render target starts at the canvas element's `width` and `height`. The canvas in `index.html` is 800 by 600. |
-| `textureFiltering` | `TextureSamplerFilteringPreset.BILINEAR` | Preset for the graphics device's default texture sampler. `POINT` is nearest filtering with no mipmaps. `BILINEAR` is linear filtering with no mipmaps. `TRILINEAR` is linear filtering with linear mipmaps. `undefined` is treated as `BILINEAR`. |
-| `useKtx2` | `false` | When `true`, the constructor sets `framework.ktx2Factory` to a `Ktx2Factory`. `initialize()` then calls `initializeAsync()` on it and does not wait. When `false`, `ktx2Factory` stays unset. |
-| `alpha` | `false` | Passed as the WebGL2 context's `alpha` attribute, so it decides whether the canvas back buffer has an alpha channel. |
-| `powerPreference` | `PowerPreferenceType.DEFAULT` | Passed as the WebGL2 context's `powerPreference` (`"default"`, `"low-power"`, or `"high-performance"`). It only matters on machines with more than one GPU. |
-
-Every field is optional on `IFrameworkConfiguration`. A new `FrameworkConfiguration` sets `useKtx2`, `textureFiltering`, `alpha`, and `powerPreference`. `canvas` and `backBufferSize` start unset.
+| `canvas` | created and appended | The canvas to render into. |
+| `backBufferSize` | `800 × 600` | Back buffer size. |
+| `textureFiltering` | `BILINEAR` | Default sampler preset. |
+| `textureColorSpace` | `SRGB` | Default texture colour space. |
+| `useKtx2` | `false` | Creates `framework.ktx2Factory`. |
+| `alpha` | `false` | Whether the back buffer has an alpha channel. |
+| `powerPreference` | `DEFAULT` | GPU preference on multi-GPU systems. |
 
-```ts
-import { Framework, FrameworkConfiguration, TextureSamplerFilteringPreset } from "ris-framework";
-
-const config = new FrameworkConfiguration();
-config.canvas = document.getElementById("game-canvas") as HTMLCanvasElement;
-config.textureFiltering = TextureSamplerFilteringPreset.BILINEAR;
+Register listeners before `initialize()`. Load-content and initialized listeners run inside that call.
 
-const framework = new Framework(config);
-```
+## Scenes, cameras and lights
 
-`src/main.ts` constructs the sample the same way, but it imports those three symbols from the source files under `src/` instead of from the package name.
+```ts
+import { Color, DirectionalLight, PointLight, Scene } from "ris-framework";
 
-`framework.renderingBackend` is `RenderingBackend.WEB_GL`. After `initialize()`, `framework.graphicsDevice` is the renderer's WebGL2 device.
+const scene = new Scene(framework);
 
+// Passing the scene makes this the scene's camera.
+const camera = framework.cameraFactory.createPerspectiveCamera({
+    aspectRatio: canvas.width / canvas.height,
+    eye: [0, 0, 3],
+}, scene);
 
-## From startup to the first frame
+scene.activeAmbientLight.color = new Color(0.4, 0.4, 0.4);
+// Lights take an optional scene; passing it adds them.
+new DirectionalLight({ color: new Color(1, 1, 1), intensity: 0.8, direction: [-0.4, -0.6, 1] }, scene);
+new PointLight({ color: new Color(1, 0.5, 0.2), intensity: 1.2, linear: 0.35, quadratic: 0.44 }, scene);
 
-`src/main.ts` is the current startup path. It still fills `#app` with the Vite starter page (logos and a heading) and then starts the framework on `#game-canvas`.
+framework.addOnUpdateListener(time => {
+    camera.update(time);
+    scene.update(time);
+});
+framework.addOnRenderListener(() => scene.render());
+```
 
-Register listeners before `initialize()`. Load-content and initialized listeners run only inside that call. Update and render listeners stay on the loop, so a listener added later still runs on a following frame. `initialize()` does this:
+`scene.add(item)` and `scene.remove(item)` accept a renderable mesh, a `SceneMesh`, a light or a camera. Blinn-Phong materials support up to 3 directional and 5 point lights.
 
-1. Starts KTX2 initialization when `useKtx2` is set, without awaiting it.
-2. Creates the WebGL2 context, swap chain, and default sampler, blend state, and primitive state.
-3. Initializes the sprite batch (a default orthographic camera and a 1×1 white texture).
-4. Initializes input. Mouse move, mouse buttons, and wheel events on the canvas update `framework.input.getMouseState()`. Touch start, move, end, and cancel events on the canvas update `framework.input.getTouchCollection()`, using the same viewport `clientX` / `clientY` coordinates as the mouse. A cancel is `TouchLocationState.CANCELLED`, which is not a finger lift. The canvas `touch-action` is set to `none`, and touch start and move call `preventDefault`, so the browser does not scroll or pinch-zoom that canvas.
-5. Prepares the time manager.
-6. Calls every `addOnLoadContentListener` callback. Async callbacks are not awaited.
-7. Calls every `addOnInitializedListener` callback.
-8. Creates the main render target at the canvas size and a swap-chain pass. The clear color at this moment is `Color.lightPink()`, the renderer default.
-9. Subscribes an update callback and a render callback, then runs both once before returning. Later frames are scheduled with `requestAnimationFrame`.
+## Meshes and materials
 
-Each update calls `timeManager.frameStart()`, updates input, then calls `addOnUpdateListener` callbacks with that frame's `GameTime`. `src/main.ts` registers no update listener. Each render begins the main pass, calls `addOnRenderListener` callbacks, calls `spriteBatch.frameEnd()`, and presents.
+- `IMesh` / `Mesh` hold geometry and the vertex and index buffers.
+- `IRenderableMesh` / `RenderableMesh` add a material, an index range and sub meshes (`mesh.addSubMesh(material, start, count)` or `meshFactory.createWithSubMeshes`). The root mesh owns the transform and one model buffer, which all its sub meshes share.
+- Transforms: `mesh.position`, `mesh.rotation` (Euler radians, applied Y, then X, then Z) and `mesh.scale`. `mesh.modelMatrix` is recomputed only when one of them changes.
+- `SceneMesh`: `scene.add(mesh)` wraps a renderable mesh in a `SceneMesh`, which owns its materials. `sceneMesh.dispose()` and `scene.dispose()` dispose the mesh and each material once.
+- Materials come from `framework.materialFactory`. They include unlit, `ForwardBlinnPhongMaterial` and `SpriteMaterial`.
 
-Before that call, `src/main.ts` registers the listeners below. The sample loads images, creates a nearest sampler, and draws with the sprite batch:
+## Loading OBJ/MTL
 
 ```ts
-import {
-  Color,
-  Rect,
-  SamplerDescriptor,
-  SamplerFilter,
-  TextureDescriptor,
-  TextureFormat,
-  type ISampler,
-  type ITexture2D,
-} from "ris-framework";
-
-const rect = new Rect(200, 200, 200, 200);
-const texRect = new Rect(500, 200, 200, 200);
-const color = Color.blue();
-const white = Color.white();
-let tex: ITexture2D;
-let sampler: ISampler;
-
-framework.addOnLoadContentListener(async () => {
-  const texDesc = new TextureDescriptor();
-  texDesc.generateMipmaps = true;
-  texDesc.textureFormat = TextureFormat.RGBA_8_UNORM;
-
-  tex = await framework.content.loadTexture2DAsync("/assets/test.png", texDesc);
-});
+// Unlit or Blinn-Phong materials (one per usemtl), coloured from the .mtl.
+const cube = await framework.content.loadBlinnPhongMeshAsync("/assets/cube.obj", camera);
+const flat = await framework.content.loadUnlitMeshAsync("/assets/cube.obj", camera);
+scene.add(cube);
 
-framework.addOnInitializedListener(() => {
-  const desc = new SamplerDescriptor();
-  desc.minFilter = SamplerFilter.NEAREST;
-  desc.magFilter = SamplerFilter.NEAREST;
-  sampler = framework.graphicsDevice.createSampler(desc);
-});
-
-framework.addOnRenderListener(() => {
-  const spriteBatch = framework.spriteBatch;
-  spriteBatch.begin(undefined, sampler);
-  spriteBatch.drawRect(rect, color);
-  if (tex != null) {
-    spriteBatch.draw(tex, texRect, white);
-  }
-  spriteBatch.end();
+// Lower level: pass a Blinn-Phong descriptor or a material factory per sub mesh.
+const mesh = await framework.objLoader.loadAsync("/assets/cube.obj", {
+    projectionViewBuffer: camera.projectionViewBuffer,
+    cameraPositionBuffer: camera.positionBuffer,
 });
 
-framework.initialize();
-framework.renderer.clearColor = Color.lightPink();
+// Geometry only, with no materials (GeometryFormat is exported from "ris-framework").
+const geometry = await framework.content.loadMeshAsync("/assets/cube.obj", GeometryFormat.POS3_COLOR4_TEXTURECOORDS2);
 ```
 
-`loadTexture2DAsync(path, textureDescriptor?, contentConfig?)` is the image path used above. For a path that does not end in `.ktx2`, the descriptor's `textureFormat` is used when it is not `TextureFormat.UNDEFINED`; otherwise the renderer's preferred format is used. `generateMipmaps` is passed through. Width, height, pixel data, usage, label, and block size on that descriptor are not applied to this load. An optional `ContentConfig` only forwards `keepDataCached` to the image loader.
+`ObjLoader.parseAsync(path)` and `ObjParser` return plain data without creating GPU resources.
 
-The first `begin` / `drawRect` / `end` runs inside `initialize()`, before the texture promise resolves, so the blue rectangle is the first draw. Later frames draw the texture once `tex` is set. `spriteBatch.begin` with no matrix keeps the default orthographic camera. The sampler argument overrides the device's default sampler for that batch. `drawRect` draws the 1×1 white texture tinted by `color`.
+## Textures and KTX2
 
-`src/main.ts` also loads `/assets/cat.jpg` the same way and draws it at `new Rect(200, 500, 200, 200)`. Those two files are absent from this repository. Put them under `public/assets/` before those loads can succeed. The blue rectangle still draws when the image loads fail.
+```ts
+const png = await framework.content.loadTexture2DAsync("/assets/test.png");
+const ktx = await framework.content.loadTexture2DAsync("/assets/kodim23.ktx2");
+```
 
-Setting `framework.renderer.clearColor` after `initialize()` updates later frames. The first frame has already cleared with the default light pink.
+Paths ending in `.ktx2` are loaded through `ris-ktx2`.
 
-## Scene
+- **Basis Universal files** are transcoded to the best format the GPU supports, in this order: BC7, ASTC 4×4, BC3, ETC2, PVRTC, and RGBA8 as a last resort.
+- **Other KTX2 files** are uploaded in their stored format.
+- **sRGB:** sRGB files load as sRGB formats (`BC7_RGBA_SRGB`, `BC3_RGBA_SRGB`, `BC1_RGB_SRGB`, `ETC2_RGBA8_SRGB`, `ETC2_RGB8_SRGB`, `ASTC_*_RGBA_SRGB`, `RGBA_8_UNORM_SRGB`), so the GPU decodes them to linear.
+- **sRGB fallback:** if `WEBGL_compressed_texture_s3tc_srgb` is missing, sRGB BC1 and BC3 textures fall back to linear with a warning.
 
-`new Scene(framework)` holds meshes, lights and the camera. `scene.add(item)` and `scene.remove(item)` accept a renderable mesh (wrapped in a `SceneMesh`, which owns and disposes its materials), an `AmbientLight`, `DirectionalLight`, `PointLight` or a camera; adding twice does nothing. Lights and the perspective camera given a scene in their constructor add themselves. Adding a camera makes it `scene.camera`; removing the active camera clears it. `scene.update(time)` hands the camera, the active ambient light and the scene's light lists (by reference) to the materials. `addLight`/`removeLight` remain as deprecated aliases.
+`framework.graphicsDevice.features` reports compression support: `supportsTextureCompressionBC` (BPTC/BC7), `supportsTextureCompressionS3TC`, `supportsTextureCompressionS3TCSrgb`, `supportsTextureCompressionETC2`, `supportsTextureCompressionASTC` and `supportsTextureCompressionPVRTC`.
 
-Meshes follow the C# framework: `IMesh`/`Mesh` hold geometry and buffers only; `IRenderableMesh`/`RenderableMesh` add an optional material, an index range (`indexStart`, `indexCount`, -1 for all), sub meshes that share the root's buffers, and the transform with one model buffer per root. OBJ files load through `framework.objLoader`:
+## Sprites
 
 ```ts
-const mesh = await framework.objLoader.loadAsync(url, {
-    projectionViewBuffer: camera.projectionViewBuffer,
-    cameraPositionBuffer: camera.positionBuffer,
-}); // one ForwardBlinnPhongMaterial per usemtl material
-// or: framework.objLoader.loadAsync(url, subMesh => myMaterial(subMesh.material))
-// or: await ObjLoader.parseAsync(url) for plain data without GPU resources
-scene.add(mesh);
+framework.addOnRenderListener(() => {
+    framework.spriteBatch.begin();
+    framework.spriteBatch.draw(texture, new Rect(200, 200, 200, 200), Color.white());
+    framework.spriteBatch.drawRect(new Rect(500, 200, 100, 100), Color.blue());
+    framework.spriteBatch.end();
+});
 ```
 
-## Examples
+## Examples and scripts
 
-Browser examples live in [`examples/`](examples/), one folder per example. See [`examples/README.md`](examples/README.md).
+Examples live in [`examples/`](examples/): `unlit_mesh`, `blinn_phong_mesh` and `sprite_batch` (see [`examples/README.md`](examples/README.md)).
 
 ```sh
-npm run dev:examples      # serve the examples index, e.g. /sprite_batch/
-npm run build:examples    # build every example into examples/dist/
+npm ci
+npm run dev:examples     # serve the examples
+npm run build:examples   # build them into examples/dist/
+npm run dev              # src/main.ts playground
+npm test                 # type-check and Vitest
+npm run build            # library (dist/) and app build
 ```
 
-## What is still unfinished
-
-These throw, or they accept a call and do not do the work the name suggests:
+Requires Node.js 22 (or `^20.19.0`) and a WebGL2-capable browser.
 
-- `WindowManager.addOnResizeListener`, `removeOnResizeListener`, `initializeForWebGPU`, `initializeForWebGl`, and `dispose` throw `Method not implemented.` `title` and `windowBounds` are stored and never applied. There is no WebGPU backend.
-- `Framework.dispose()` is empty. It does not release the window, device, or GPU resources.
-- `renderer.beginComputePass()` and `renderer.endComputePass()` throw `Method not implemented.` `ARenderer.limits` throws the same error.
-- `graphicsDevice.setupDebugCallback()`, `frameEnd()`, `pushDebugGroup()`, and `popDebugGroup()` throw `Method not implemented.`
-- `ITexture2D.createView()` throws `Method not implemented.`
-- `content.loadShaderModule` only resolves the built-in ids `sprite`, `unlit_material`, `inspect_texture_mips`, and `main_render_target_flip_y`. Any other id throws `Not implemented`.
-- `SpriteBatch.draw` and `drawRect` accept rotation arguments and do not use them. `layerDepth` is written as the sprite's z position.
-- Keyboard and gamepad queries return empty state. `getKeyboardState()` is an empty `KeyboardState`. `getGamePadState()` is a disconnected `GamePadState`. `thumbstickDeadZone` is stored and not applied.
-- A render pass that enables stencil without depth throws `Not implemented`.
-- Paths ending in `.ktx2` go through `content.loadKtx2Async`, which uses its own `Ktx2Factory` and does not call `initializeAsync`. The libktx module is shared by every `Ktx2Factory`, so `loadAsync` works only after some factory has finished `initializeAsync()`. `useKtx2` starts that call in `initialize()` but does not wait for it. To load a `.ktx2` file, set `useKtx2`, await `framework.ktx2Factory.initializeAsync()` before `initialize()`, and then call `loadTexture2DAsync` from a load-content listener. `src/main.ts` does not load a `.ktx2` file.
-- The geometry and unlit-pipeline steps at the bottom of `src/main.ts` are comments. `geometryBuilder.quadGeometry()` can build quad data; the entry file does not upload it or draw it.
+## Known limitations
 
-## Version
+- Window resize listeners and compute passes throw `Method not implemented.`
+- Keyboard and gamepad state are stubs.
+- `SpriteBatch` ignores rotation.
 
-`package.json` `version` stays a release version with no prerelease suffix. It is `0.1.0`. Branch and publish rules are in [CONTRIBUTING.md](CONTRIBUTING.md).
+Branch and publish rules are in [CONTRIBUTING.md](CONTRIBUTING.md). Changes are listed in [CHANGELOG.md](CHANGELOG.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ris-framework",
-  "version": "0.2.0-dev.12",
+  "version": "0.2.0-dev.13",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",