Finish documentation

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;
 }