Finish documentation

src/drawables/drawable-descriptor.ts

@@ -1,13 +1,63 @@
 import { Drawable } from './drawable';
 
+/**
+ * Used for containing the required information to compile drawables into
+ * shader code.
+ *
+ * Each [[Drawable]] must have a static property of this type, called descriptor.
+ *
+ * For more information on how to create your own DrawableDescriptor-s, look at the
+ * code of [[Circle]] or [[InvertedTunnel]].
+ */
 export interface DrawableDescriptor {
+  /**
+   * An object describing the relationship between the object returned by a [[Drawable]]'s
+   * getObjectToSerialize and the name of the arrays used in the GLSL code.
+   */
   propertyUniformMapping: { [property: string]: string };
+
+  /**
+   * The name of the uniform int used in the code to refer to the
+   * number of drawables of this type.
+   */
   uniformCountMacroName: string;
+
+  /**
+   * Required property for shapes having physical dimensions.
+   */
   sdf?: {
+    /**
+     * The actual GLSL code for observing the drawables represented by this descriptor.
+     *
+     * Your code should work with both version 100 and version 300 es
+     */
     shader: string;
-    isInverted?: boolean;
+    /**
+     * The name of the function defined in the value of `shader`.
+     * Its signature should look like this:
+     * ```glsl
+     *  float (in vec2 target, out float colorIndex)
+     * ```
+     */
     distanceFunctionName: string;
+
+    /**
+     * By default, drawables are not inverted.
+     */
+    isInverted?: boolean;
   };
+
+  /**
+   * Number of possible drawables around each tile.
+   *
+   * For each step, a shader will be generated. And at runtime the closes matching
+   * shader will be used to render a given part of the scene.
+   */
   shaderCombinationSteps: Array<number>;
+
+  /**
+   * When no shaderCombinationStep matches the current number of drawables exactly,
+   * the value of `empty` is used to pad out arrays.
+   */
   readonly empty: Drawable;
 }

src/drawables/drawable.ts

@@ -1,11 +1,36 @@
 import { mat2d, vec2 } from 'gl-matrix';
 import { DrawableDescriptor } from './drawable-descriptor';
 
+/**
+ * Base class of every drawable object.
+ *
+ * To create your own drawables, you need to subclass from this.
+ *
+ * > Although lights are also subclasses of Drawable, you cannot create your own light sources.
+ */
 export abstract class Drawable {
-  // This should be overriden by inherited classes
+  /**
+   * This should be defined in inherited classes.
+   */
   public static readonly descriptor: DrawableDescriptor;
 
+  /**
+   * The lower bound of the distance between the target and the object.
+   *
+   * It can return 0 by default, the only consequence of this, is a reduced performance.
+   * Because this object won't benefit from tile-based rendering.
+   * @param target
+   */
   public abstract minDistance(target: vec2): number;
+
+  /**
+   * Return the values that should be given to the shaders through uniform inputs.
+   *
+   * @param transform2d position-like properties should be transformed by this matrix
+   * before being returned.
+   * @param transform1d scalar properties should be transformed by this number
+   * before being returned.
+   */
   protected abstract getObjectToSerialize(transform2d: mat2d, transform1d: number): any;
 
   public serializeToUniforms(

src/drawables/lights/circle-light.ts

@@ -2,6 +2,9 @@ import { vec2, vec3 } from 'gl-matrix';
 import { DrawableDescriptor } from '../drawable-descriptor';
 import { LightDrawable } from './light-drawable';
 
+/**
+ * @category Drawable
+ */
 export class CircleLight extends LightDrawable {
   public static readonly descriptor: DrawableDescriptor = {
     propertyUniformMapping: {

src/drawables/lights/flashlight.ts

@@ -2,6 +2,9 @@ import { mat2d, vec2, vec3 } from 'gl-matrix';
 import { DrawableDescriptor } from '../drawable-descriptor';
 import { LightDrawable } from './light-drawable';
 
+/**
+ * @category Drawable
+ */
 export class Flashlight extends LightDrawable {
   public static readonly descriptor: DrawableDescriptor = {
     propertyUniformMapping: {

src/drawables/lights/light-drawable.ts

@@ -1,6 +1,7 @@
 import { mat2d, vec2, vec3 } from 'gl-matrix';
 import { Drawable } from '../../main';
 
+/** @internal */
 export class LightDrawable extends Drawable {
   protected lightnessRatio = 1;
 

src/drawables/shapes/circle.ts

@@ -2,6 +2,9 @@ import { mat2d, vec2 } from 'gl-matrix';
 import { Drawable } from '../drawable';
 import { DrawableDescriptor } from '../drawable-descriptor';
 
+/**
+ * @category Drawable
+ */
 export class Circle extends Drawable {
   public static descriptor: DrawableDescriptor = {
     sdf: {

src/drawables/shapes/inverted-tunnel.ts

@@ -4,6 +4,9 @@ import { mix } from '../../helper/mix';
 import { Drawable } from '../drawable';
 import { DrawableDescriptor } from '../drawable-descriptor';
 
+/**
+ * @category Drawable
+ */
 export class InvertedTunnel extends Drawable {
   public static descriptor: DrawableDescriptor = {
     sdf: {

src/drawables/shapes/tunnel.ts

@@ -4,6 +4,9 @@ import { mix } from '../../helper/mix';
 import { Drawable } from '../drawable';
 import { DrawableDescriptor } from '../drawable-descriptor';
 
+/**
+ * @category Drawable
+ */
 export class Tunnel extends Drawable {
   public static descriptor: DrawableDescriptor = {
     sdf: {

src/graphics/graphics-library/frame-buffer/default-frame-buffer.ts

@@ -1,6 +1,7 @@
 import { UniversalRenderingContext } from '../universal-rendering-context';
 import { FrameBuffer } from './frame-buffer';
 
+/** @internal */
 export class DefaultFrameBuffer extends FrameBuffer {
   constructor(gl: UniversalRenderingContext) {
     super(gl);

src/graphics/graphics-library/frame-buffer/frame-buffer.ts

@@ -1,9 +1,10 @@
 import { vec2 } from 'gl-matrix';
 import { UniversalRenderingContext } from '../universal-rendering-context';
 
+/** @internal */
 export abstract class FrameBuffer {
   public renderScale = 1;
-  public enableHighDpiRendering = false;
+  public enableHighDpiRendering!: boolean;
 
   protected size = vec2.create();
 

src/graphics/graphics-library/frame-buffer/intermediate-frame-buffer.ts

@@ -2,6 +2,7 @@ import { enableExtension } from '../helper/enable-extension';
 import { UniversalRenderingContext } from '../universal-rendering-context';
 import { FrameBuffer } from './frame-buffer';
 
+/** @internal */
 export class IntermediateFrameBuffer extends FrameBuffer {
   private frameTexture: WebGLTexture;
   private floatEnabled = false;

src/graphics/graphics-library/helper/enable-context-lost-simulator.ts

@@ -1,5 +1,7 @@
+/** @internal */
 let isEnabled = false;
 
+/** @internal */
 export const enableContextLostSimulator = (canvas: HTMLCanvasElement) => {
   if (isEnabled) {
     return;

src/graphics/graphics-library/helper/enable-extension.ts

@@ -1,6 +1,7 @@
 import { Insights } from '../../rendering/insights';
 import { UniversalRenderingContext } from '../universal-rendering-context';
 
+/** @internal */
 export const tryEnableExtension = (
   gl: UniversalRenderingContext,
   name: string
@@ -15,6 +16,7 @@ export const tryEnableExtension = (
   return extension;
 };
 
+/** @internal */
 export const enableExtension = (gl: UniversalRenderingContext, name: string): any => {
   const extension = tryEnableExtension(gl, name);
 

src/graphics/graphics-library/helper/load-uniform.ts

@@ -1,8 +1,10 @@
 import { mat3, ReadonlyVec3, ReadonlyVec4, vec2, vec3, vec4 } from 'gl-matrix';
 import { UniversalRenderingContext } from '../universal-rendering-context';
 
+/** @internal */
 const loaderMat3 = mat3.create();
 
+/** @internal */
 export const loadUniform = (
   gl: UniversalRenderingContext,
   value: any,

src/graphics/graphics-library/helper/stopwatch.ts

@@ -1,12 +1,14 @@
 import { UniversalRenderingContext } from '../universal-rendering-context';
 import { enableExtension } from './enable-extension';
 
+/** @internal */
 enum StopwatchState {
   ready = 'ready',
   running = 'running',
   waitingForResults = 'waitingForResults',
 }
 
+/** @internal */
 export class WebGlStopwatch {
   private state = StopwatchState.ready;
   private resultsInNanoSeconds = 0;

src/graphics/graphics-library/palette-texture.ts

@@ -1,6 +1,7 @@
 import { vec3, vec4 } from 'gl-matrix';
 import { UniversalRenderingContext } from './universal-rendering-context';
 
+/** @internal */
 export class PaletteTexture {
   private texture: WebGLTexture;
 

src/graphics/graphics-library/parallel-compiler.ts

@@ -3,6 +3,7 @@ import { Insights } from '../rendering/insights';
 import { tryEnableExtension } from './helper/enable-extension';
 import { UniversalRenderingContext } from './universal-rendering-context';
 
+/** @internal */
 type CompilingProgram = {
   program: WebGLProgram;
   resolvePromise: ((program: WebGLProgram) => void) | null;
@@ -10,8 +11,10 @@ type CompilingProgram = {
   fragmentShader: ShaderWithSource;
 };
 
+/** @internal */
 type ShaderWithSource = WebGLShader & { source: string };
 
+/** @internal */
 export class ParallelCompiler {
   private extension?: any;
   private gl: UniversalRenderingContext;

src/graphics/graphics-library/program/fragment-shader-only-program.ts

@@ -3,6 +3,7 @@ import { ParallelCompiler } from '../parallel-compiler';
 import { UniversalRenderingContext } from '../universal-rendering-context';
 import Program from './program';
 
+/** @internal */
 export class FragmentShaderOnlyProgram extends Program {
   private vao?: WebGLVertexArrayObject;
   private vertexArrayExtension: any;

src/graphics/graphics-library/program/i-program.ts

@@ -1,5 +1,6 @@
 import { vec2 } from 'gl-matrix';
 
+/** @internal */
 export interface IProgram {
   setDrawingRectangleUV(bottomLeft: vec2, size: vec2): void;
   draw(values: { [name: string]: any }): void;

src/graphics/graphics-library/program/program.ts

@@ -4,6 +4,7 @@ import { ParallelCompiler } from '../parallel-compiler';
 import { UniversalRenderingContext } from '../universal-rendering-context';
 import { IProgram } from './i-program';
 
+/** @internal */
 export default abstract class Program implements IProgram {
   protected program?: WebGLProgram;