Finish documentation

src/graphics/rendering/fps-autoscaler.ts

@@ -3,6 +3,7 @@ import { exponentialDecay } from '../../helper/exponential-decay';
 import { mix } from '../../helper/mix';
 import { Insights } from './insights';
 
+/** @internal */
 const settings = {
   targetDeltaTimeInMilliseconds: 20,
   deltaTimeErrorInMilliseconds: 3,
@@ -30,6 +31,7 @@ const settings = {
   qualityStepDecrese: 0.2,
 };
 
+/** @internal */
 export class FpsAutoscaler {
   private timeSinceLastAdjusment = 0;
   private exponentialDecayedDeltaTime = settings.targetDeltaTimeInMilliseconds;

src/graphics/rendering/insights.ts

@@ -1,6 +1,7 @@
 import { last } from '../../helper/last';
 import { msToString } from '../../helper/ms-to-string';
 
+/** @internal */
 export class Insights {
   private static insights: any = {};
 

src/graphics/rendering/render-pass/distance-render-pass.ts

@@ -3,9 +3,10 @@ import { Drawable } from '../../../drawables/drawable';
 import { Insights } from '../insights';
 import { RenderPass } from './render-pass';
 
+/** @internal */
 export class DistanceRenderPass extends RenderPass {
-  public tileMultiplier = 8;
-  public isWorldInverted = false;
+  public tileMultiplier!: number;
+  public isWorldInverted!: boolean;
 
   private drawables: Array<Drawable> = [];
 

src/graphics/rendering/render-pass/lights-render-pass.ts

@@ -4,8 +4,9 @@ import { clamp01 } from '../../../helper/clamp';
 import { Insights } from '../insights';
 import { RenderPass } from './render-pass';
 
+/** @internal */
 export class LightsRenderPass extends RenderPass {
-  public lightCutoffDistance = 400;
+  public lightCutoffDistance!: number;
   private drawables: Array<LightDrawable> = [];
 
   public addDrawable(drawable: LightDrawable) {

src/graphics/rendering/render-pass/render-pass.ts

@@ -4,6 +4,7 @@ import { ParallelCompiler } from '../../graphics-library/parallel-compiler';
 import { UniformArrayAutoScalingProgram } from '../../graphics-library/program/uniform-array-autoscaling-program';
 import { UniversalRenderingContext } from '../../graphics-library/universal-rendering-context';
 
+/** @internal */
 export abstract class RenderPass {
   protected program: UniformArrayAutoScalingProgram;
 

src/graphics/rendering/renderer/context-aware-renderer.ts

@@ -1,10 +1,12 @@
 import { vec2 } from 'gl-matrix';
-import { Drawable, DrawableDescriptor } from '../../../main';
+import { Drawable } from '../../../drawables/drawable';
+import { DrawableDescriptor } from '../../../drawables/drawable-descriptor';
 import { RuntimeSettings } from '../settings/runtime-settings';
 import { StartupSettings } from '../settings/startup-settings';
 import { Renderer } from './renderer';
 import { RendererImplementation } from './renderer-implementation';
 
+/** @internal */
 export class ContextAwareRenderer implements Renderer {
   private renderer?: RendererImplementation;
   private isRendererReady = false;

src/graphics/rendering/renderer/renderer-implementation.ts

@@ -16,6 +16,7 @@ import { FpsAutoscaler } from '../fps-autoscaler';
 import { Insights } from '../insights';
 import { DistanceRenderPass } from '../render-pass/distance-render-pass';
 import { LightsRenderPass } from '../render-pass/lights-render-pass';
+import { defaultRuntimeSettings } from '../settings/default-runtime-settings';
 import { defaultStartupSettings } from '../settings/default-startup-settings';
 import { RuntimeSettings } from '../settings/runtime-settings';
 import { StartupSettings } from '../settings/startup-settings';
@@ -30,6 +31,7 @@ import lightsVertexShader from '../shaders/shading-vs.glsl';
 import { UniformsProvider } from '../uniforms-provider';
 import { Renderer } from './renderer';
 
+/** @internal */
 export class RendererImplementation implements Renderer {
   private readonly gl: UniversalRenderingContext;
   private stopwatch?: WebGlStopwatch;
@@ -38,7 +40,7 @@ export class RendererImplementation implements Renderer {
   private distancePass: DistanceRenderPass;
   private lightingFrameBuffer: DefaultFrameBuffer;
   private lightsPass: LightsRenderPass;
-  private palette?: PaletteTexture;
+  private palette!: PaletteTexture;
   private autoscaler: FpsAutoscaler;
 
   private applyRuntimeSettings: {
@@ -53,7 +55,7 @@ export class RendererImplementation implements Renderer {
     backgroundColor: (v) => (this.uniformsProvider.backgroundColor = v),
     ambientLight: (v) => (this.uniformsProvider.ambientLight = v),
     lightCutoffDistance: (v) => (this.lightsPass.lightCutoffDistance = v),
-    colorPalette: (v) => this.palette!.setPalette(v),
+    colorPalette: (v) => this.palette.setPalette(v),
   };
 
   setRuntimeSettings(overrides: Partial<RuntimeSettings>): void {
@@ -103,6 +105,8 @@ export class RendererImplementation implements Renderer {
     };
 
     this.palette = new PaletteTexture(this.gl, settings.paletteSize);
+    this.setRuntimeSettings(defaultRuntimeSettings);
+
     const promises: Array<Promise<void>> = [];
 
     const compiler = new ParallelCompiler(this.gl);
@@ -219,7 +223,7 @@ export class RendererImplementation implements Renderer {
     this.lightsPass.render(
       this.uniformsProvider.getUniforms(common),
       this.distanceFieldFrameBuffer.colorTexture,
-      this.palette!.colorTexture
+      this.palette.colorTexture
     );
     this.gl.disable(this.gl.BLEND);
 
@@ -243,6 +247,6 @@ export class RendererImplementation implements Renderer {
   public destroy(): void {
     this.distancePass.destroy();
     this.lightsPass.destroy();
-    this.palette!.destroy();
+    this.palette.destroy();
   }
 }

src/graphics/rendering/renderer/renderer.ts

@@ -2,15 +2,79 @@ import { vec2 } from 'gl-matrix';
 import { Drawable } from '../../../drawables/drawable';
 import { RuntimeSettings } from '../settings/runtime-settings';
 
+/**
+ * The main interface through which rendering can be achieved.
+ *
+ * Multiple renderers are permitted on a single page.
+ */
 export interface Renderer {
+  /**
+   * Get the actual resolution of the canvas.
+   */
   readonly canvasSize: vec2;
+
+  /**
+   * Get the viewArea size set by the last `setViewArea`.
+   *
+   * By default, `canvasSize` is used for the view area size.
+   */
   readonly viewAreaSize: vec2;
+
+  /**
+   * Set the camera transformation.
+   *
+   * @param topLeft top (!) left. By default, equals to [0, canvasHeight].
+   * @param size need not be equal to the canvas size, though their aspect ratio
+   * should be the same to avoid stretching.
+   */
+  setViewArea(topLeft: vec2, size: vec2): void;
+
+  /**
+   * Patch the current runtime settings with new values.
+   * @param overrides
+   */
+  setRuntimeSettings(overrides: Partial<RuntimeSettings>): void;
+
+  /**
+   * Schedule a drawable to be rendered during the next `renderDrawables` call.
+   *
+   * @param drawable Must be a subclass of drawable and its class must contain a
+   * static descriptor property of type [[DrawableDescriptor]].
+   */
+  addDrawable<T extends Drawable>(drawable: T): void;
+
+  /**
+   * Render every drawable added since the last `renderDrawables` call.
+   *
+   * Resizing of framebuffers and the canvas also takes effect
+   * when calling `renderDrawables`.
+   */
+  renderDrawables(): void;
+
+  /**
+   * Let go of every GPU resource held by the renderer.
+   *
+   * It's up to the browser and driver whether these resources are actually freed.
+   * Nonetheless, when a renderer is no longer needed, this method should be called.
+   */
+  destroy(): void;
+
+  /**
+   * @experimental
+   *
+   * Debug information updated on each `renderDrawables` call.
+   * Its scheme is not yet defined. The main purpose of this is
+   * human debugging.
+   */
   readonly insights: any;
 
-  setViewArea(topLeft: vec2, size: vec2): void;
-  setRuntimeSettings(overrides: Partial<RuntimeSettings>): void;
-  addDrawable(drawable: Drawable): void;
+  /**
+   * @experimental
+   *
+   * Scale the render scale for both the canvas and the SDF memoization based
+   * on the current and historical FPS values.
+   *
+   * @param deltaTime since the last frame, in milliseconds.
+   */
   autoscaleQuality(deltaTime: DOMHighResTimeStamp): void;
-  renderDrawables(): void;
-  destroy(): void;
 }

src/graphics/rendering/settings/default-runtime-settings.ts

@@ -0,0 +1,15 @@
+import { vec3, vec4 } from 'gl-matrix';
+import { RuntimeSettings } from './runtime-settings';
+
+/**
+ * Contains the default values used for [[RuntimeSettings]].
+ */
+export const defaultRuntimeSettings: RuntimeSettings = {
+  enableHighDpiRendering: true,
+  tileMultiplier: 8,
+  isWorldInverted: false,
+  lightCutoffDistance: 400,
+  backgroundColor: vec4.fromValues(1, 1, 1, 1),
+  colorPalette: [],
+  ambientLight: vec3.fromValues(0.25, 0.15, 0.25),
+};

src/graphics/rendering/settings/default-startup-settings.ts

@@ -1,5 +1,8 @@
 import { StartupSettings } from './startup-settings';
 
+/**
+ * Contains the default values used for [[StartupSettings]].
+ */
 export const defaultStartupSettings: StartupSettings = {
   shadowTraceCount: 16,
   paletteSize: 256,

src/graphics/rendering/settings/runtime-settings.ts

@@ -1,11 +1,59 @@
 import { vec3, vec4 } from 'gl-matrix';
 
+/**
+ * Interface for a configuration object containing the settings
+ * that can be changed during runtime.
+ *
+ * The default values for RuntimeSettings can be found in [[defaultRuntimeSettings]].
+ */
 export interface RuntimeSettings {
+  /**
+   * When set to `true` rendering will be done on the screen's real resolution.
+   */
   enableHighDpiRendering: boolean;
+
+  /**
+   * First, the SDF of the scene is evaluated at every single pixel.
+   * For speeding this process up, the screen is divided up into tiles,
+   * this way each having to deal with a fewer objects.
+   *
+   * For each tile, it is decided which objects are near its close vicinity.
+   * This comes with some overhead for the CPU, while saving the GPU from loads of
+   * calculations. The workload can be balanced between the CPU and the GPU by setting
+   * this number.
+   */
   tileMultiplier: number;
+
+  /**
+   * By default, every pixel is outside of objects. Flipping this value to `true` will
+   * result in every pixel being inside a large object. From then it only makes sense to
+   * draw inverted objects.
+   */
   isWorldInverted: boolean;
+
+  /**
+   * When lights reach the end of the display, they are slowly faded out. The length
+   * of this phaseout can be set through this value.
+   */
   lightCutoffDistance: number;
+
+  /**
+   * The default background color of the scene, can have transparency.
+   */
   backgroundColor: vec3 | vec4;
+
+  /**
+   * Its length should be less than the one specified in [[StartupSettings]].paletteSize.
+   *
+   * The possible colors for the objects. Each color is referenced by its index in the
+   * palette.
+   *
+   * Can have transparency.
+   */
   colorPalette: Array<vec3 | vec4>;
+
+  /**
+   * A light affecting every pixel (even the ones inside objects).
+   */
   ambientLight: vec3;
 }

src/graphics/rendering/settings/startup-settings.ts

@@ -1,5 +1,33 @@
+/**
+ * Interface for a configuration object containing the settings
+ * that need to be given before shader compilation.
+ *
+ * The default values for StartupSettings can be found in [[defaultStartupSettings]].
+ */
 export interface StartupSettings {
+  /**
+   * The raytracing algorithm used for shadows requires a step count.
+   * Sensible values for this are between 8 and 32.
+   *
+   * The higher the number, the harder the shadows will get.
+   * Some ambient occlusion like effects can be visible on lower trace counts.
+   */
   shadowTraceCount: number;
+
+  /**
+   * Gives the number of possible object colors for the scene.
+   *
+   * When using WebGL, only 256 different colors can be used.
+   * On WebGL2, its value should not be larger than 4096 for
+   * maintaining compatibility with low-end devices.
+   */
   paletteSize: number;
+
+  /**
+   * When set to `true`, rendering will fall back to WebGL
+   * even when WebGL2 is present.
+   *
+   * Useful for testing compatibility.
+   */
   ignoreWebGL2: boolean;
 }

src/graphics/rendering/uniforms-provider.ts

@@ -1,9 +1,10 @@
 import { mat2d, vec2, vec3, vec4 } from 'gl-matrix';
 import { UniversalRenderingContext } from '../graphics-library/universal-rendering-context';
 
+/** @internal */
 export class UniformsProvider {
-  public ambientLight = vec3.fromValues(0.25, 0.15, 0.25);
-  public _backgroundColor = vec4.fromValues(1, 1, 1, 1);
+  public ambientLight!: vec3;
+  public _backgroundColor!: vec4;
 
   private scaleWorldLengthToNDC = 1;
   private transformWorldToNDC = mat2d.create();