@novorender/api

This package contains all the various APIs relevant for developing a Novorender web app.

Getting Started

Install @novorender/api using your favorite package manager.

npm i @novorender/api

This npm package contains pre-built ESM bundle and typescript definitions. It is meant to be used with modern javascript bundlers such as vite or webpack or directly in a modern browser.

Avoid deep imports! Everything you need should be available from the package root: @novorender/api.

Development

To build the package, run the following command:

npm run build

This will create a dist folder with the following files:

• novorender-api.js - the main ESM bundle
• novorender-api.d.ts - the TypeScript definitions

To run the build in a watch mode, use:

npm run build:watch

This will watch for changes and rebuild the package automatically.

To lint and automatically fix the code with eslint:

npm run lint

To format the code using prettier:

npm run fmt

The package is using pre-commit hooks in order to lint and format the code before committing. This is done using husky and lint-staged.

Dependencies

We use gl-matrix for linear algebra.

Double precision matrices glMatrix.setMatrixArrayType(Array) are required. Don't change back to Float32Array!

Server requirements

Our API uses advanced, cutting edge JavaScript APIs, many of which come with certain security requirements. In general, the following two global properties have to be true: globalThis.isSecureContext and globalThis.crossOriginIsolated.

To make it all work, your server has to ensure:

1. A secure context. In practice, this means HTTP on localhost (for debugging only) and HTTPS everywhere else, including LAN.

2. Cross origin HTTP headers for top level documents.

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

3. Correct MIME types - text/javascript for JavaScript files and application/wasm for WebAssembly files.

4. Any resources loaded from a separate domain have to be configured with CORS to allow your domain.

5. The service workers script should be at the appropriate location, preferably at the root of your domain. See MDN for more.

Usage

A minimal app might look something like this:

import { View, getDeviceProfile } from "@novorender/api";

async function main(canvas: HTMLCanvasElement) {
  const gpuTier = 2; // laptop with reasonably new/powerful GPU.
  const deviceProfile = getDeviceProfile(gpuTier);
  const view = await View.create(canvas, deviceProfile);
  await view.run();
  view.dispose();
}

main(document.getElementById("render_canvas"));

If everything succeeds, this should render an image with a minor gradient of gray. To make it a little more interesting, we can change the RenderState to include a grid.

// ... snip...
const view = await View.create(canvas, deviceProfile);
view.modifyRenderState({ grid: { enabled: true } });
await view.run();
// ...snip...

The view already has camera controller built in, so you can move around and enjoy your grid with the mouse and/or keyboard, or even touch gestures.

The view will automatically resize your canvas' pixel size when the css layout and/or the render state output settings changes. This could lead to a runaway recursive feedback loop. To avoid this issue, you must assign a css width and height to your canvas!

<canvas style="width: 100%; height: 100%;"></canvas>

Next steps

Getting that first view up and running is an important step. Now you can actually start to make your application. Please see the documentation for tutorials, examples and a detailed reference manual!