ris-framework 0.1.0-dev.4 → 0.1.0-dev.5

package/README.md

@@ -1,11 +1,188 @@
 # ris-framework
 
-TypeScript WebGL framework. Version 0.1.0.
+`ris-framework` is a Vite TypeScript application that renders with WebGL2 in the browser. Version 0.1.0.
 
-## Release
+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) come from the `ris-framework-api` package. This repository is the application that implements them.
 
-`development` is the prerelease branch. A push publishes `<version>-dev.<run>` on the npm `next` tag.
+## Layout
 
-`main` is the release branch. A push publishes `<version>` on `latest` when that version is not already on npm, then tags `v<version>`.
+| 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/core` | `Framework`, `FrameworkConfig`, the window and input managers, content loading, the renderer base, and the sprite batch. |
+| `src/webgl` | The WebGL2 graphics device, renderer, textures, buffers, samplers, and render pipelines. |
+| `src/geometry` | `GeometryBuilder` and mesh geometry data. |
+| `src/content` | Built-in shader modules. GLSL is imported from `shaders/glsl`. |
+| `shaders/glsl` | Vertex and fragment shaders used by those built-in modules. |
 
-`package.json` `version` stays a release version with no prerelease suffix. See CONTRIBUTING.md.
+Runtime dependencies are `ris-framework-api`, `ris-ktx2`, `gl-matrix`, `tsyringe`, and `reflect-metadata`. TypeScript and Vite are dev dependencies.
+
+## 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
+
+From the repository root:
+
+```sh
+npm ci
+```
+
+`src/main.ts` imports `reflect-metadata` before it constructs the framework. Keep that import first in the entry file. `Framework` registers itself on a tsyringe child container, and tsyringe expects `reflect-metadata` to be loaded.
+
+## Create a framework instance
+
+Construct `FrameworkConfig`, then pass it to `Framework`. The constructor is `constructor(options: FrameworkConfig | null = null)`. Omitting the argument, or passing `null`, uses `new FrameworkConfig()`.
+
+No config field is required. Each field has a default.
+
+| Field | Default | What the code does with it |
+| --- | --- | --- |
+| `canvas` | `null` | The canvas the WebGL2 context is created from. `null` makes `WindowManager` create a canvas and append it to `document.body`. `src/main.ts` sets this to `#game-canvas`. |
+| `backBufferSize` | `vec2.fromValues(800, 600)` | Copied onto an internal `RenderConfiguration`. `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. |
+
+`textureFiltering` is declared optional on `FrameworkConfig`. The other three fields are always present on a new config object.
+
+```ts
+import "reflect-metadata";
+
+import { Framework } from "./core/Framework.ts";
+import { FrameworkConfig } from "./core/FrameworkConfig.ts";
+import { TextureSamplerFilteringPreset } from "./core/rendering/enums.ts";
+
+const config = new FrameworkConfig();
+config.canvas = document.getElementById("game-canvas") as HTMLCanvasElement;
+config.textureFiltering = TextureSamplerFilteringPreset.BILINEAR;
+
+const framework = new Framework(config);
+```
+
+`framework.renderingBackend` is `RenderingBackend.WEB_GL`. After `initialize()`, `framework.graphicsDevice` is the renderer's WebGL2 device.
+
+## Run, build, and preview
+
+```sh
+npm run dev
+```
+
+`dev` runs Vite. The served page is `index.html`.
+
+```sh
+npm run build
+```
+
+`build` runs `tsc && vite build`. Typecheck failures stop the production bundle. Vite writes the bundle to `dist/`. The Vite config replaces `ris-ktx2`'s Node loader with a browser stub so the client bundle does not import Node built-ins.
+
+```sh
+npm run preview
+```
+
+`preview` runs `vite preview` and serves the `dist/` build.
+
+```sh
+npm test
+```
+
+`test` runs `tsc --noEmit`. It typechecks `src`.
+
+## From startup to the first frame
+
+`src/main.ts` is the current startup path. It still fills `#app` with the Vite starter page (logos and a counter) and then starts the framework on `#game-canvas`.
+
+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:
+
+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()`.
+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`.
+
+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.
+
+Before that call, `src/main.ts` registers the listeners below. The sample loads images, creates a nearest sampler, and draws with the sprite batch:
+
+```ts
+import {
+  Color,
+  Rect,
+  SamplerDescriptor,
+  SamplerFilter,
+  TextureDescriptor,
+  TextureFormat,
+  type ISampler,
+  type ITexture2D,
+} from "ris-framework-api";
+
+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);
+});
+
+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();
+});
+
+framework.initialize();
+framework.renderer.clearColor = Color.lightPink();
+```
+
+`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.
+
+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`.
+
+`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.
+
+Setting `framework.renderer.clearColor` after `initialize()` updates later frames. The first frame has already cleared with the default light pink.
+
+## What is still unfinished
+
+These throw, or they accept a call and do not do the work the name suggests:
+
+- `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`. `loadAsync` needs the KTX module that `useKtx2` starts, and `initialize()` does not wait for that call. The `.ktx2` branch of `loadTexture2DAsync` also drops `ContentConfig`. The current entry file 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.
+
+## Version
+
+`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).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ris-framework",
-  "version": "0.1.0-dev.4",
+  "version": "0.1.0-dev.5",
   "repository": {
     "type": "git",
     "url": "https://github.com/luka712/ris-framework-ts"