From fb40343c408b8081ea1de9db5f425b63b283702f Mon Sep 17 00:00:00 2001 From: Andras Schmelczer Date: Wed, 10 Jun 2026 22:29:50 +0100 Subject: [PATCH] Improve docs language --- src/compile.ts | 8 +++--- src/drawables/drawable-descriptor.ts | 10 +++---- src/drawables/drawable.ts | 4 +-- .../texture/texture-options.ts | 4 +-- .../rendering/fps-quality-autoscaler.ts | 5 ++-- .../rendering/renderer/noise-renderer.ts | 9 +++---- src/graphics/rendering/renderer/renderer.ts | 8 +++--- .../rendering/settings/runtime-settings.ts | 26 +++++++++---------- .../rendering/settings/startup-settings.ts | 6 ++--- src/helper/delta-time-calculator.ts | 4 +-- src/run-animation.ts | 6 ++--- 11 files changed, 45 insertions(+), 45 deletions(-) diff --git a/src/compile.ts b/src/compile.ts index 72b8bd5..37f296c 100644 --- a/src/compile.ts +++ b/src/compile.ts @@ -4,12 +4,12 @@ import { StartupSettings } from './graphics/rendering/settings/startup-settings' import { DrawableDescriptor, Renderer } from './main'; /** - * Compiles a new renderer instance. There can multiple renderers on a single page. + * Compiles a new renderer instance. There can be multiple renderers on a single page. * > Asynchronous behaviour is required for parallel shader compiling. - * > Trying to draw before the returned promise resolves, results in no action taken. - * > Settings can be set before promise resolution and they will be applied later. + * > Trying to draw before the returned promise resolves results in no action being taken. + * > Settings can be set before the promise resolves and they will be applied later. * - * The descriptors of every to-be-drawn objects are required before creating the renderer, + * The descriptors of all to-be-drawn objects are required before creating the renderer, * allowing the compiler to only create the shaders that will actually be used. * * Example usage: diff --git a/src/drawables/drawable-descriptor.ts b/src/drawables/drawable-descriptor.ts index 4ebcd8a..1f98519 100644 --- a/src/drawables/drawable-descriptor.ts +++ b/src/drawables/drawable-descriptor.ts @@ -6,7 +6,7 @@ import { Drawable } from './drawable'; * * 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 + * For more information on how to create your own DrawableDescriptors, look at the * code of [[CircleFactory]] or [[InvertedTunnelFactory]]. */ export interface DrawableDescriptor { @@ -27,9 +27,9 @@ export interface DrawableDescriptor { */ sdf?: { /** - * The actual GLSL code for observing the drawables represented by this descriptor. + * The actual GLSL code that defines the drawables represented by this descriptor. * - * Your code should work with both version 100 and version 300 es + * Your code should work with both GLSL version 100 and version 300 es. */ shader: string; /** @@ -59,8 +59,8 @@ export interface DrawableDescriptor { /** * 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. + * For each step, a shader is generated, and at runtime the closest matching + * shader is used to render a given part of the scene. * * Must contain 0 as a value. */ diff --git a/src/drawables/drawable.ts b/src/drawables/drawable.ts index 137c4fb..0ed22fb 100644 --- a/src/drawables/drawable.ts +++ b/src/drawables/drawable.ts @@ -17,8 +17,8 @@ export abstract class Drawable { /** * 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. + * It can return 0 by default; the only consequence is reduced performance, + * because this object won't benefit from tile-based rendering. * @param target */ public abstract minDistance(target: vec2): number; diff --git a/src/graphics/graphics-library/texture/texture-options.ts b/src/graphics/graphics-library/texture/texture-options.ts index 0b8d62f..827aff3 100644 --- a/src/graphics/graphics-library/texture/texture-options.ts +++ b/src/graphics/graphics-library/texture/texture-options.ts @@ -2,12 +2,12 @@ export enum WrapOptions { CLAMP_TO_EDGE = 'CLAMP_TO_EDGE', /** - * On WebGL it only work with power of 2 texture sizes. + * On WebGL, this only works with power-of-2 texture sizes. */ REPEAT = 'REPEAT', /** - * On WebGL it only work with power of 2 texture sizes. + * On WebGL, this only works with power-of-2 texture sizes. */ MIRRORED_REPEAT = 'MIRRORED_REPEAT', } diff --git a/src/graphics/rendering/fps-quality-autoscaler.ts b/src/graphics/rendering/fps-quality-autoscaler.ts index 56f16aa..5889bb0 100644 --- a/src/graphics/rendering/fps-quality-autoscaler.ts +++ b/src/graphics/rendering/fps-quality-autoscaler.ts @@ -6,7 +6,7 @@ import { RuntimeSettings } from './settings/runtime-settings'; /** * Set the quality of rendering based on FPS values. * - * When using this the size of the canvas must be fixed with CSS. + * When using this, the size of the canvas must be fixed with CSS. * * The `addDeltaTime` method should be called once every frame. * @@ -52,7 +52,8 @@ export class FpsQualityAutoscaler { private deltaTimeSinceLastAdjustment = 0; /** - * Autoscaling is also done by calling this function + * Record the time taken by the latest frame. Autoscaling is also performed + * as part of this call. * @param deltaTimeInMilliseconds */ public addDeltaTime(deltaTimeInMilliseconds: DOMHighResTimeStamp) { diff --git a/src/graphics/rendering/renderer/noise-renderer.ts b/src/graphics/rendering/renderer/noise-renderer.ts index e1f8a6c..0eac994 100644 --- a/src/graphics/rendering/renderer/noise-renderer.ts +++ b/src/graphics/rendering/renderer/noise-renderer.ts @@ -10,13 +10,12 @@ import randomVertex100 from '../shaders/random-vs-100.glsl'; import randomVertex from '../shaders/random-vs.glsl'; /** - * Create a renderer, draw a 2D noise texture with it, - * then destroy the used resources, - * while returning the generated texture in the form of a canvas. + * Create a renderer, draw a 2D noise texture with it, then destroy the + * resources it used, returning the generated texture in the form of a canvas. * * @param textureSize The resolution of the end result - * @param scale A starting value can be 15 - * @param amplitude A starting value can be 1 + * @param scale A good starting value is 15 + * @param amplitude A good starting value is 1 * @param ignoreWebGL2 Ignore WebGL2, even when it's available */ export const renderNoise = async ( diff --git a/src/graphics/rendering/renderer/renderer.ts b/src/graphics/rendering/renderer/renderer.ts index 2e834a4..f3a4c0b 100644 --- a/src/graphics/rendering/renderer/renderer.ts +++ b/src/graphics/rendering/renderer/renderer.ts @@ -12,7 +12,7 @@ export interface Renderer { /** * Get the actual resolution of the canvas without triggering a reflow. * - * A ResizeObserver is utilised fot achieving this. + * A ResizeObserver is used to achieve this. */ readonly canvasSize: ReadonlyVec2; @@ -26,7 +26,7 @@ export interface Renderer { /** * Set the camera transformation. * - * @param topLeft top (!) left. By default, equals to [0, canvasHeight]. + * @param topLeft top (!) left. By default, equal to [0, canvasHeight]. * @param size need not be equal to the canvas size, though their aspect ratio * should be the same to avoid stretching. */ @@ -89,9 +89,9 @@ export interface Renderer { /** * Get useful information about the hardware and the SDF2D renderer. * - * Its scheme is subject to change. + * Its schema is subject to change. * - * During context lost it might be null. + * During a context-lost event, it might be null. */ readonly insights: RendererInfo | null; } diff --git a/src/graphics/rendering/settings/runtime-settings.ts b/src/graphics/rendering/settings/runtime-settings.ts index 14212fd..5fc24c9 100644 --- a/src/graphics/rendering/settings/runtime-settings.ts +++ b/src/graphics/rendering/settings/runtime-settings.ts @@ -9,16 +9,16 @@ import { TextureWithOptions } from '../../graphics-library/texture/texture-optio */ export interface RuntimeSettings { /** - * When set to `true` rendering will be done on the screen's real resolution. + * When set to `true`, rendering will be done at 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. + * To speed this process up, the screen is divided into tiles, + * so each one has to deal with fewer objects. * - * For each tile, it is decided which objects are near its close vicinity. + * For each tile, it is decided which objects are in its 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. @@ -27,24 +27,24 @@ export interface RuntimeSettings { /** * 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 + * result in every pixel being inside a large object. From then on, 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. + * When lights reach the edge of the display, they are slowly faded out. The length + * of this fade-out can be set through this value. */ lightCutoffDistance: number; /** - * 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, but only if WebGL2 support is enabled. + * Its length should be less than the `paletteSize` specified in [[StartupSettings]]. + * + * Colors can have transparency, but only if WebGL2 support is enabled. */ colorPalette: Array; @@ -76,10 +76,10 @@ export interface RuntimeSettings { /** * It is possible to use your own textures in your SDF definitions. * - * The keys of the object should be the name used to reference them in the GLSL code, - * and the values should be the textures themselves or a TextureWithOptions specifying + * 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]]. - * It can be a canvas, img element, Image and so on. + * A texture can be a canvas, an img element, an Image, and so on. */ textures: { [textureName: string]: TexImageSource | TextureWithOptions; diff --git a/src/graphics/rendering/settings/startup-settings.ts b/src/graphics/rendering/settings/startup-settings.ts index 6447fbb..de99a7d 100644 --- a/src/graphics/rendering/settings/startup-settings.ts +++ b/src/graphics/rendering/settings/startup-settings.ts @@ -11,7 +11,7 @@ export interface StartupSettings { * Creates a stopwatch used for measuring the GPU render time * when its required extension is available. * - * You should only have one renderer with enabled stopwatch. + * You should only have one renderer with the stopwatch enabled. */ enableStopwatch: boolean; @@ -20,7 +20,7 @@ export interface StartupSettings { * 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. + * Some ambient-occlusion-like effects can be visible at lower trace counts. */ shadowTraceCount: number; @@ -55,7 +55,7 @@ export interface StartupSettings { paletteSize: number; /** - * Many context lost event will be simulated when enabled. + * Many context-lost events will be simulated when enabled. * * Useful for testing. */ diff --git a/src/helper/delta-time-calculator.ts b/src/helper/delta-time-calculator.ts index 87fd4c3..08a4074 100644 --- a/src/helper/delta-time-calculator.ts +++ b/src/helper/delta-time-calculator.ts @@ -1,8 +1,8 @@ /** * A helper class for calculating the elapsed time between frames. * - * Handles the case, where the browser tab is not in focus and `requestAnimationFrame` - * does not get called for performance reasons. In this case, the return deltaTime won't be + * Handles the case where the browser tab is not in focus and `requestAnimationFrame` + * does not get called for performance reasons. In this case, the returned deltaTime won't be * an unreasonably large value. */ export class DeltaTimeCalculator { diff --git a/src/run-animation.ts b/src/run-animation.ts index f426438..a09f730 100644 --- a/src/run-animation.ts +++ b/src/run-animation.ts @@ -8,8 +8,8 @@ import { DrawableDescriptor, Renderer } from './main'; /** * Implements the boilerplate code required to run real-time animations - * in the browser. An FPS based autoscaler is also used. This creates an additional `fps` - * key in the renderers `insights` property. + * in the browser. An FPS-based autoscaler is also used. This creates an additional `fps` + * key in the renderer's `insights` property. * * Example usage: * @@ -17,7 +17,7 @@ import { DrawableDescriptor, Renderer } from './main'; * * ``` * > The canvas needs to have a fixed size specified by CSS. - + * * ```js * import { CircleFactory, CircleLight, hsl, runAnimation } from 'sdf-2d'; *