The retro n-gon renderer

A low-level retro-oriented 3D software renderer for the HTML5 <canvas> (also supports rendering into an off-screen pixel buffer).

You can view various interactive render samples here.

Key features

Genuine retro aesthetics
Programmable render pipeline
Good performance for retro uses

Documentation

Suggested use cases

Being a retro-oriented software renderer written in JavaScript, the retro n-gon renderer thrives in low resolutions and low polycounts, its performance generally lacking for modern-style rendering.

I'd generally expect the renderer to find a home powering nostalgia projects reminiscent of the 1990s. Retro-themed games, model visualization, etc.

Performance

The repository provides performance benchmarks to gauge the renderer's performance on your system.

Below are benchmark results (frames per second) running in Google Chrome on an AMD Ryzen 5000 series desktop CPU.

Resolution	Rendering mode
	Wireframe	Untextured¹	Textured¹	Pixel shader²
1920 × 1080	420	70	45	5
1280 × 720	490	110	80	15
640 × 360	610	250	170	60
¹With Gouraud shading.
²Simpler pixel shaders may impact performance by as little as 10%.

Pixel shaders can have a large impact on the frame rate, but otherwise this 800-polygon scene with texturing and Gouraud shading is renderable at a high rate.*

*The renderer performs no pre-rasterization visibility culling other than back-face removal and frustum clipping. It's at the discretion of the host application to apply more sophisticated culling techniques to maximize performance.

Installation

After downloading the repository, follow these steps to build the code into a single-file distributable that you can use in your apps.

Install the required developer dependencies
```
$ yarn install
```
These dependencies are needed only to build the distributable. They don't need to be bundled with your application.
Build the distributable
```
$ yarn run build
```
For additional run-time data validation and error reporting (at the cost of performance), build with $ yarn run build:dev and see your browser's developer console.
Import the distributable into your app

The build process from step 2 should produce a distributable in two flavors:
- distributable/rngon.global.js
- distributable/rngon.module.js
The first file can be imported globally:
```
<script src="rngon.global.js"></script>
```
The second file can be imported into a module:
```
<script type="module">
    import {Rngon} from "rngon.module.js";
</script>
```
Both methods expose the rendering API as an Rngon object.
To learn how to use the API, head over to the quick-start guide or have a look at the API reference.

Testing

Unit tests

$ yarn run test:unit

The unit tests are currently a bare minimum.

Performance benchmarks

$ yarn run test:perf:wireframe
$ yarn run test:perf:untextured
$ yarn run test:perf:textured
$ yarn run test:perf:shader

These benchmarks run in a headless Google Chrome using Puppeteer, at a render resolution of 640 × 360. They require the files of the repository to be hosted on a web server (e.g. localhost).

By default, the benchmarks attempt to run on http://localhost:8222, but you can set a different URL via the RESOURCE_ORIGIN environment variable.

You can also run the benchmarks in a browser window (after hosting the files on a web server):

test:perf:wireframe: /tests/performance/quake/wireframe.html
test:perf:untextured: /tests/performance/quake/untextured.html
test:perf:textured: /tests/performance/quake/textured.html
test:perf:shader: /tests/performance/quake/shader.html

The benefits of running them this way is that you get to see the render output and at the end a graph showing the frame rate as a function of time.

When run in a browser window, the benchmarks' render resoluton is determined by the size of the viewport as well as the scale URL parameter: for example, with a viewport of 1920 × 1080 and scale=0.25, the render resolution will be 480 × 270.

leikareipa/retro-ngon