Update README, write comments

Author: dulnan

README.md

@@ -2,61 +2,100 @@
 
 **[Demo drawing app](https://lazybrush.dulnan.net)**
 
-[Example repository](https://github.com/dulnan/lazy-brush-demo)
+__The demo app also uses
+[catenary-curve](https://github.com/dulnan/catenary-curve) to draw the little
+"rope" between mouse and brush.__
 
 This library provides the math required to implement a "lazy brush".
 It takes a radius and the {x,y} coordinates of a mouse/pointer and calculates
 the position of the brush.
+
 The brush will only move when the pointer is outside the "lazy area" of the
 brush. With this technique it's possible to freely draw smooth lines and curves
 with just a mouse or finger.
 
-# How it works
+## How it works
+
 When the position of the pointer is updated, the distance to the brush is
 calculated. If this distance is larger than the defined radius, the brush will
 be moved by `distance - radius` pixels in the direction where the pointer is.
 
-# Usage
+## Usage
+
 lazy-brush is on npm so you can install it with your favorite package manager.
 
 lazy-brush can be easily added in any canvas drawing scenario. It acts like a
 "proxy" between user input and drawing.
 
+It exports a `LazyBrush` class. Create a single instance of the class:
+
 ```javascript
 const lazy = new LazyBrush({
   radius: 30,
   enabled: true,
   initialPoint: { x: 0, y: 0 }
-}) // default
+})
+```
 
-lazy.update({ x: 50, y: 0 })
+You can now use the `update()` method whenever the position of the mouse (or
+touch) changes:
+
+```javascript
+// Move mouse 20 pixels to the right.
+lazy.update({ x: 20, y: 0 })
+// Brush is not moved, because 20 is less than the radius (30).
 console.log(lazy.getBrushCoordinates()) // { x: 0, y: 0 }
 
-lazy.update({ x: 200, y: 50 })
-console.log(lazy.getBrushCoordinates()) // { x: 100, y: 0 }
+// Move mouse 40 pixels to the right.
+lazy.update({ x: 40, y: 0 })
+// Brush is now moved by 10 pixels because 40 (mouse X) - 30 (radius) = 10.
+console.log(lazy.getBrushCoordinates()) // { x: 10, y: 0 }
 ```
 
-Use the `LazyBrush.update()` function to update the pointer position. That
-would be when the mouse is moved. The function returns a boolean to indicate
-whether any of the values (brush or pointer) have changed. This can be used to
-prevent unneccessary canvas redrawing.
+The function returns a boolean to indicate whether any of the values (brush or
+pointer) have changed. This can be used to prevent unneccessary canvas
+redrawing.
+
 If you need to know if the position of the brush was changed, you can get that
-boolean via LazyBrush.brushHasMoved().
+boolean via `LazyBrush.brushHasMoved()`. Use this information to decide if you
+need to redraw the brush on the canvas.
 
-To get the coordinates , use `LazyBrush.getBrushCoordinates()` or
-`LazyBrush.getPointerCoordinates()`. This will return an object with x and y
-properties.
+To get the current brush coordinates, use `LazyBrush.getBrushCoordinates()`.
+For the pointer coordinates use `LazyBrush.getPointerCoordinates()`. This will
+return a `Point` object with x and y properties.
 
 The functions `getBrush()` and `getPointer()` will return a `LazyPoint`, which
-has some functions like getDistanceTo, getAngleTo or equalsTo.
+has some additional functions like `getDistanceTo`, `getAngleTo` or `equalsTo`.
+
+### With Friction
+
+You can also pass a friction value (number between 0 and 1) when calling `update()`:
+
+```javascript
+lazy.update({ x: 40, y: 0 }, { friction: 0.5 })
+```
+
+This will reduce the speed at which the brush moves towards the pointer. A
+value of 0 means "no friction", which is the same as not passing a value. 1
+means "inifinte friction", the brush won't move at all.
+
+You can define a constant value or make it dynamic, for example using a pressur
+value from a touch event.
+
+### Updating both values
+
+You can also update the pointer and the brush coordinates at the same time:
+
+```javascript
+lazy.update({ x: 40, y: 0 }, { both: true })
+```
 
-# Example
+This can be used when supporting touch events: On touch start you would update
+both the pointer and the brush so that the pointer can be "moved" away from the
+brush until the lazy radius is reached. This is how it's implemented in the
+demo page.
 
-## Performance
-For performance reasons it's best to decouple calculations and canvas rendering
-from mousemove/touchmove events: One way is to store the current coordinates in
-a variable. Then, using an animation loop (typically requestAnimationFrame),
-call the `LazyBrush.update()` function on every frame with the latest
-coordinates from the variable.
+## Examples
 
-The library will only do calculations if the pointer or brush values changed.
+Check out the [basic example](examples/basic.html) for a simple starting point
+on how to use this library.

demo-src/App.vue

@@ -18,10 +18,11 @@
       <Slider
         v-model="friction"
         label="Friction"
+        :value-text="frictionValueText"
         id="friction"
-        description="Makes the brush lag behind the cursor. 100 = no lag, 1 = extreme lag."
-        :min="1"
-        :max="100"
+        description="Makes the brush lag behind the cursor. 0 = no lag, 1 = infinite lag."
+        :min="0"
+        :max="99"
         :disabled="!enabled"
       />
       <Slider
@@ -55,7 +56,7 @@
 </template>
 
 <script setup lang="ts">
-import { ref } from 'vue'
+import { computed, ref } from 'vue'
 import Sidebar from './components/Sidebar.vue'
 import Scene from './components/Scene.vue'
 import Slider from './components/Slider.vue'
@@ -64,9 +65,13 @@ import Toggle from './components/Toggle.vue'
 
 const brushRadius = ref(12.5)
 const lazyRadius = ref(60)
-const friction = ref(90)
+const friction = ref(10)
 const enabled = ref(true)
 const clear = ref(0)
 
+const frictionValueText = computed(() => {
+  return (friction.value / 100).toFixed(2)
+})
+
 const container = ref(null as HTMLDivElement)
 </script>

demo-src/components/Slider.vue

@@ -58,6 +58,10 @@ const props = defineProps({
     type: Number,
     default: 0
   },
+  valueText: {
+    type: String,
+    default: ''
+  },
   disabled: {
     type: Boolean,
     default: false
@@ -69,7 +73,7 @@ const step = computed(() => {
 })
 
 const value = computed(() => {
-  return Math.round(props.modelValue).toString()
+  return props.valueText || Math.round(props.modelValue).toString()
 })
 
 function getSliderValue(e: Event) {

examples/basic.html

@@ -33,6 +33,9 @@
       canvas.width = window.innerWidth
       canvas.height = window.innerHeight
 
+      // While not always reccommended, we can directly draw in your event
+      // handler here. Generally it is better to do that in an animation loop.
+      // See the "friction.html" example on how to do that.
       canvas.addEventListener('mousemove', function (e) {
         const x = e.clientX
         const y = e.clientY

examples/friction.html

@@ -43,6 +43,9 @@
 
       function loop() {
         // Update the current mouse coordinates.
+        // When using friction we have to continously call the update method
+        // because the brush can move even if the cursor position remains the
+        // same.
         lazy.update({ x, y }, { friction: 0.5 })
 
         // Get the updated brush coordinates.

src/LazyBrush.ts

@@ -9,23 +9,62 @@ interface LazyBrushOptions {
 }
 
 interface LazyBrushUpdateOptions {
+  /**
+   * Update both pointer and brush at the same time.
+   *
+   * This can be used when supporting touch events: On touch start you would
+   * update both the pointer and the brush so that the pointer can be "moved"
+   * away from the brush until the lazy radius is reached.
+   */
   both?: boolean
+
+  /**
+   * Define the friction (value between 0 and 1) for the brush.
+   *
+   * A value of 0 means "no friction" (default when not set). A value of "1"
+   * means infinite friction (the brush won't move at all).
+   */
   friction?: number
 }
 
 class LazyBrush {
+  /**
+   * If the lazy brush should be enabled.
+   */
   _isEnabled: boolean
+
+  /**
+   * Indicates if the brush has moved in the last update cycle.
+   */
   _hasMoved: boolean
+
+  /**
+   * The lazy radius.
+   */
   radius: number
+
+  /**
+   * Coordinates of the pointer.
+   */
   pointer: LazyPoint
+
+  /**
+   * Coordinates of the brush.
+   */
   brush: LazyPoint
+
+  /**
+   * The angle between pointer and brush in the last update cycle.
+   */
   angle: number
-  distance: number
 
-  velocity: LazyPoint
+  /**
+   * The distance between pointer and brush in the last update cycle.
+   */
+  distance: number
 
   /**
-   * constructor
+   * Constructs a new LazyBrush.
    */
   constructor(options: LazyBrushOptions = {}) {
     const initialPoint = options.initialPoint || { x: 0, y: 0 }
@@ -34,7 +73,6 @@ class LazyBrush {
 
     this.pointer = new LazyPoint(initialPoint.x, initialPoint.y)
     this.brush = new LazyPoint(initialPoint.x, initialPoint.y)
-    this.velocity = new LazyPoint(initialPoint.x, initialPoint.y)
 
     this.angle = 0
     this.distance = 0
@@ -175,8 +213,8 @@ class LazyBrush {
 
       const isOutside = Math.round((this.distance - this.radius) * 10) / 10 > 0
       const friction =
-        options.friction && options.friction < 1
-          ? Math.min(Math.max(options.friction, 0.01), 1)
+        options.friction && options.friction < 1 && options.friction > 0
+          ? options.friction
           : undefined
 
       if (isOutside) {

src/LazyPoint.ts

@@ -42,8 +42,8 @@ export class LazyPoint implements Point {
     const angleRotated = angle + Math.PI / 2
 
     if (friction) {
-      this.x = this.x + Math.sin(angleRotated) * distance * ease(friction)
-      this.y = this.y - Math.cos(angleRotated) * distance * ease(friction)
+      this.x = this.x + Math.sin(angleRotated) * distance * ease(1 - friction)
+      this.y = this.y - Math.cos(angleRotated) * distance * ease(1 - friction)
     } else {
       this.x = this.x + Math.sin(angleRotated) * distance
       this.y = this.y - Math.cos(angleRotated) * distance