Add more docs

src/drawables/drawable-descriptor.ts

@@ -4,15 +4,15 @@ 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.
+ * Each {@link drawables/drawable!Drawable} must have a static property of this type, called descriptor.
  *
  * For more information on how to create your own DrawableDescriptors, look at the
  * [complete custom drawable example](https://sdf-2d-docs.schmelczer.dev/index.html#custom-drawable-example),
- * or the code of [[CircleFactory]] or [[InvertedTunnelFactory]].
+ * or the code of {@link drawables/shapes/circle-factory!CircleFactory} or {@link drawables/shapes/inverted-tunnel-factory!InvertedTunnelFactory}.
  */
 export interface DrawableDescriptor {
   /**
-   * An object describing the relationship between the object returned by a [[Drawable]]'s
+   * An object describing the relationship between the object returned by a {@link drawables/drawable!Drawable}'s
    * getObjectToSerialize and the name of the arrays used in the GLSL code.
    */
   propertyUniformMapping: { [property: string]: string };

src/drawables/shapes/circle-factory.ts

@@ -18,6 +18,27 @@ class CircleBase extends EmptyDrawable {
 let _id = 0;
 
 /**
+ * Creates a drawable circle class with a shared color.
+ *
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @returns A class with constructor `new Circle(center: vec2, radius: number)`.
+ * `center` is the position in world coordinates; `radius` is in world units.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { CircleFactory, compile } from 'sdf-2d';
+ *
+ * const Circle = CircleFactory([1, 0.5, 0]);
+ * const circle = new Circle([160, 120], 30);
+ * const canvas = document.createElement('canvas');
+ * document.body.appendChild(canvas);
+ * const renderer = await compile(canvas, [Circle.descriptor]);
+ * renderer.addDrawable(circle);
+ * renderer.renderDrawables();
+ * ```
+ *
  * @category Drawable
  */
 export const CircleFactory = (color: vec3 | vec4 | number): typeof CircleBase => {

src/drawables/shapes/droplet-factory.ts

@@ -22,6 +22,24 @@ class DropletBase extends EmptyDrawable {
 let _id = 0;
 
 /**
+ * Creates a drawable droplet class with a shared color.
+ *
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @returns A class with constructor
+ * `new Droplet(from: vec2, to: vec2, fromRadius: number, toRadius: number)`.
+ * `from` and `to` are endpoint positions in world coordinates; `fromRadius` and
+ * `toRadius` are the radii at those endpoints in world units.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { DropletFactory } from 'sdf-2d';
+ *
+ * const Droplet = DropletFactory([1, 0.5, 0]);
+ * const droplet = new Droplet([100, 100], [200, 140], 30, 10);
+ * ```
+ *
  * @category Drawable
  */
 export const DropletFactory = (color: vec3 | vec4 | number): typeof DropletBase => {

src/drawables/shapes/hexagon-factory.ts

@@ -18,6 +18,22 @@ class HexagonBase extends EmptyDrawable {
 let _id = 0;
 
 /**
+ * Creates a drawable hexagon class with a shared color.
+ *
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @returns A class with constructor `new Hexagon(center: vec2, radius: number)`.
+ * `center` is the position in world coordinates; `radius` controls the size in world units.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { HexagonFactory } from 'sdf-2d';
+ *
+ * const Hexagon = HexagonFactory([1, 0.5, 0]);
+ * const hexagon = new Hexagon([160, 120], 30);
+ * ```
+ *
  * @category Drawable
  */
 export const HexagonFactory = (color: vec3 | vec4 | number): typeof HexagonBase => {

src/drawables/shapes/inverted-tunnel-factory.ts

@@ -22,7 +22,26 @@ class InvertedTunnelBase extends EmptyDrawable {
 let _id = 0;
 
 /**
- * Providing a noise texture is required for this drawable.
+ * Creates a drawable inverted tunnel class with a shared color.
+ *
+ * Providing a `noiseTexture` in {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.textures} is required for this
+ * drawable. A noise texture can be generated with {@link graphics/rendering/renderer/noise-renderer!renderNoise}.
+ *
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @returns A class with constructor
+ * `new InvertedTunnel(from: vec2, to: vec2, fromRadius: number, toRadius: number)`.
+ * `from` and `to` are endpoint positions in world coordinates; `fromRadius` and
+ * `toRadius` are the radii at those endpoints in world units.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { InvertedTunnelFactory } from 'sdf-2d';
+ *
+ * const InvertedTunnel = InvertedTunnelFactory([1, 0.5, 0]);
+ * const tunnel = new InvertedTunnel([100, 100], [200, 140], 30, 20);
+ * ```
  *
  * @category Drawable
  */

src/drawables/shapes/meta-circle-factory.ts

@@ -19,6 +19,23 @@ class MetaCircleBase extends EmptyDrawable {
 let _id = 0;
 
 /**
+ * Creates a drawable class of smoothly merging circles with a shared color.
+ *
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @param k Smooth union factor. Larger values produce sharper joins. Defaults to 32.
+ * @returns A class with constructor `new MetaCircle(center: vec2, radius: number)`.
+ * `center` is the position in world coordinates; `radius` is in world units.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { MetaCircleFactory } from 'sdf-2d';
+ *
+ * const MetaCircle = MetaCircleFactory([1, 0.5, 0], 32);
+ * const circle = new MetaCircle([160, 120], 30);
+ * ```
+ *
  * @category Drawable
  */
 export const MetaCircleFactory = (

src/drawables/shapes/noisy-polygon-factory.ts

@@ -11,6 +11,28 @@ interface NoisyPolygonBase extends PolygonBase {
 let _id = 0;
 
 /**
+ * Creates a drawable polygon class with a noisy outline and a shared color.
+ *
+ * Providing a `noiseTexture` in {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.textures} is required for this
+ * drawable. A noise texture can be generated with {@link graphics/rendering/renderer/noise-renderer!renderNoise}.
+ *
+ * @param vertexCount Maximum number of vertices per polygon.
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @returns A class with constructor `new NoisyPolygon(vertices: Array<vec2>)`.
+ * `vertices` contains between one and `vertexCount` positions in world coordinates,
+ * ordered around the polygon's outline. Instances also have a `randomOffset` property
+ * (default 0) for varying the sampled noise.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { NoisyPolygonFactory } from 'sdf-2d';
+ *
+ * const NoisyPolygon = NoisyPolygonFactory(3, [1, 0.5, 0]);
+ * const polygon = new NoisyPolygon([[100, 100], [200, 100], [150, 180]]);
+ * ```
+ *
  * @category Drawable
  */
 export const NoisyPolygonFactory = (

src/drawables/shapes/polygon-factory.ts

@@ -6,9 +6,15 @@ import { DrawableDescriptor } from '../drawable-descriptor';
 import { EmptyDrawable } from '../empty-drawable';
 
 /**
+ * Constructor and vertex storage shared by classes returned by {@link drawables/shapes/polygon-factory!PolygonFactory}
+ * and {@link drawables/shapes/noisy-polygon-factory!NoisyPolygonFactory}. Create drawable classes through those factories.
+ *
  * @category Drawable
  */
 export class PolygonBase extends EmptyDrawable {
+  /**
+   * @param vertices Positions in world coordinates, ordered around the polygon's outline.
+   */
   constructor(public vertices: Array<vec2>) {
     super();
   }
@@ -17,6 +23,24 @@ export class PolygonBase extends EmptyDrawable {
 let _id = 0;
 
 /**
+ * Creates a drawable polygon class with a shared color.
+ *
+ * @param vertexCount Maximum number of vertices per polygon.
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @returns A class with constructor `new Polygon(vertices: Array<vec2>)`.
+ * `vertices` contains between one and `vertexCount` positions in world coordinates,
+ * ordered around the polygon's outline. Fewer vertices are padded automatically.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { PolygonFactory } from 'sdf-2d';
+ *
+ * const Polygon = PolygonFactory(3, [1, 0.5, 0]);
+ * const polygon = new Polygon([[100, 100], [200, 100], [150, 180]]);
+ * ```
+ *
  * @category Drawable
  */
 export const PolygonFactory = (

src/drawables/shapes/rotated-rectangle-factory.ts

@@ -19,6 +19,24 @@ class RotatedRectangleBase extends EmptyDrawable {
 let _id = 0;
 
 /**
+ * Creates a drawable rotated rectangle class with a shared color.
+ *
+ * @param color RGB or RGBA color, or an index into {@link graphics/rendering/settings/runtime-settings!RuntimeSettings.colorPalette}.
+ * @returns A class with constructor
+ * `new RotatedRectangle(center: vec2, size: vec2, rotation: number)`.
+ * `center` is the position in world coordinates; `size` is `[width, height]` in world
+ * units; `rotation` is the angle in radians.
+ * Pass the class's static `descriptor` to {@link compile!compile}, then pass instances to
+ * {@link graphics/rendering/renderer/renderer!Renderer.addDrawable}.
+ *
+ * @example
+ * ```ts
+ * import { RotatedRectangleFactory } from 'sdf-2d';
+ *
+ * const RotatedRectangle = RotatedRectangleFactory([1, 0.5, 0]);
+ * const rectangle = new RotatedRectangle([160, 120], [80, 40], Math.PI / 4);
+ * ```
+ *
  * @category Drawable
  */
 export const RotatedRectangleFactory = (
@@ -27,7 +45,7 @@ export const RotatedRectangleFactory = (
   class RotatedRectangle extends RotatedRectangleBase {
     public static descriptor: DrawableDescriptor = {
       sdf: {
-        // Source: https://iquilezles.org/www/articles/distfunctions2d/distfunctions2d.htm
+        // Source: https://iquilezles.org/articles/distfunctions2d/
         shader: `
           uniform vec2 rotatedRectangleTopCenters${_id}[ROTATED_RECTANGLE_COUNT${_id}];
           uniform vec2 rotatedRectangleBottomCenters${_id}[ROTATED_RECTANGLE_COUNT${_id}];

src/graphics/rendering/renderer/renderer.ts

@@ -66,7 +66,7 @@ export interface Renderer {
    * 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]].
+   * static descriptor property of type {@link drawables/drawable-descriptor!DrawableDescriptor}.
    */
   addDrawable<T extends Drawable>(drawable: T): void;
 

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

@@ -2,7 +2,7 @@ import { vec3 } from 'gl-matrix';
 import { RuntimeSettings } from './runtime-settings';
 
 /**
- * Contains the default values used for [[RuntimeSettings]].
+ * Contains the default values used for {@link graphics/rendering/settings/runtime-settings!RuntimeSettings}.
  */
 export const defaultRuntimeSettings: RuntimeSettings = {
   enableHighDpiRendering: false,

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

@@ -2,7 +2,7 @@ import { vec4 } from 'gl-matrix';
 import { StartupSettings } from './startup-settings';
 
 /**
- * Contains the default values used for [[StartupSettings]].
+ * Contains the default values used for {@link graphics/rendering/settings/startup-settings!StartupSettings}.
  */
 export const defaultStartupSettings: StartupSettings = {
   shadowTraceCount: 16,

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

@@ -5,7 +5,7 @@ import { TextureWithOptions } from '../../graphics-library/texture/texture-optio
  * Interface for a configuration object containing the settings
  * that can be changed during runtime.
  *
- * The default values for RuntimeSettings can be found in [[defaultRuntimeSettings]].
+ * The default values for RuntimeSettings can be found in {@link graphics/rendering/settings/default-runtime-settings!defaultRuntimeSettings}.
  */
 export interface RuntimeSettings {
   /**
@@ -42,7 +42,7 @@ export interface RuntimeSettings {
    * The possible colors for the objects. Each color is referenced by its index in the
    * palette.
    *
-   * Its length should be less than the `paletteSize` specified in [[StartupSettings]].
+   * Its length should be less than the `paletteSize` specified in {@link graphics/rendering/settings/startup-settings!StartupSettings}.
    *
    * Colors can have transparency, but only if WebGL2 support is enabled.
    */
@@ -78,7 +78,7 @@ export interface RuntimeSettings {
    *
    * The keys of the object should be the names used to reference them in the GLSL code,
    * and the values should be the textures themselves, or a TextureWithOptions specifying
-   * the texture's [[TextureOptions]].
+   * the texture's {@link graphics/graphics-library/texture/texture-options!TextureOptions}.
    * A texture can be a canvas, an img element, an Image, and so on.
    */
   textures: {

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

@@ -4,7 +4,7 @@ import { vec3, vec4 } from 'gl-matrix';
  * 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]].
+ * The default values for StartupSettings can be found in {@link graphics/rendering/settings/default-startup-settings!defaultStartupSettings}.
  */
 export interface StartupSettings {
   /**

src/run-animation.ts

@@ -40,8 +40,7 @@ import { DrawableDescriptor, Renderer } from './main';
  * `renderDrawables` must not be called by the animate function. It should return `true`
  * if the animation should be continued. To break out of the animation loop, a `false` (falsy)
  * return value must be given.
- * @param startupSettingOverrides Sensible defaults are provided, but these can be overridden.
- * @param initialRuntimeSettingOverrides Sensible defaults are provided, but these can be overridden.
+ * @param settings Startup and runtime settings overrides. Sensible defaults are provided.
  * Set `enableAutoscaler` to `false` to keep the render scales exactly as configured
  * instead of letting the FPS-based autoscaler adjust them.
  */