etro 0.9.1 → 0.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "etro",
-  "version": "0.9.1",
-  "description": "An extendable video-editing framework for the browser and Node",
+  "version": "0.10.0",
+  "description": "An extendable video-editing framework for the browser",
   "browser": "dist/etro-cjs.js",
   "types": "dist/index.d.ts",
   "directories": {
@@ -14,6 +14,7 @@
     "@types/jest": "^29.0.0",
     "@typescript-eslint/eslint-plugin": "^5.30.7",
     "@typescript-eslint/parser": "^5.30.7",
+    "canvas": "^2.11.2",
     "docdash": "^1.1.1",
     "ecstatic": ">=4.1.3",
     "eslint": "^8.20.0",
@@ -40,7 +41,7 @@
     "rollup-plugin-node-resolve": "^5.2.0",
     "rollup-plugin-typescript2": "^0.29.0",
     "rollup-plugin-uglify-es": "^0.0.1",
-    "shipjs": "^0.24.4",
+    "shipjs": "^0.26.3",
     "typedoc": "^0.23.8",
     "typescript": "^4.7.4"
   },
@@ -48,11 +49,11 @@
     "build": "rollup -c",
     "doc": "rm -rf docs && npx typedoc src/etro.ts --excludePrivate --readme none",
     "assets": "git fetch origin example-assets:example-assets && git cherry-pick example-assets && git reset --soft HEAD^ && git reset HEAD examples/assets",
-    "effects": "node scripts/save-effect-samples.js",
+    "effects": "node scripts/effect/save-effect-samples.js",
     "lint": "npm run --silent lint:main && npm run --silent lint:test && npm run --silent lint:examples",
-    "lint:main": "eslint -c eslint.typescript-conf.js --ext .ts src",
-    "lint:test": "eslint -c eslint.test-conf.js --ext .ts spec",
-    "lint:examples": "eslint -c eslint.example-conf.js --ext .html examples",
+    "lint:main": "eslint -c eslint.typescript-conf.js --ext .ts --fix src",
+    "lint:test": "eslint -c eslint.test-conf.js --ext .ts --fix spec",
+    "lint:examples": "eslint -c eslint.example-conf.js --ext .html --fix examples",
     "start": "http-server",
     "test": "karma start",
     "release": "shipjs prepare"

package/src/custom-array.ts

@@ -0,0 +1,43 @@
+export abstract class CustomArrayListener<T> {
+  abstract onAdd(item: T): void
+  abstract onRemove(item: T): void
+}
+
+/**
+ * An array that notifies a listener when items are added or removed.
+ */
+export class CustomArray<T> extends Array<T> {
+  constructor (target: T[], listener: CustomArrayListener<T>) {
+    super()
+
+    for (const item of target) {
+      listener.onAdd(item)
+    }
+
+    // Create proxy
+    return new Proxy(target, {
+      deleteProperty (target, property): boolean {
+        const value = target[property]
+        delete target[property]
+        listener.onRemove(value)
+        return true
+      },
+
+      set (target, property, value): boolean {
+        const oldValue = target[property]
+        target[property] = value
+
+        // Check if property is a number (index)
+        if (!isNaN(Number(property))) {
+          if (oldValue !== undefined) {
+            listener.onRemove(oldValue)
+          }
+
+          listener.onAdd(value)
+        }
+
+        return true
+      }
+    }) as T[]
+  }
+}

package/src/effect/base.ts

@@ -1,5 +1,3 @@
-import { watchPublic } from '../util'
-import { publish, subscribe } from '../event'
 import { Movie } from '../movie'
 import { Base as BaseLayer } from '../layer/index'
 import BaseObject from '../object'
@@ -23,31 +21,24 @@ export class Base implements BaseObject {
   private _occurrenceCount: number
 
   constructor () {
-    const newThis = watchPublic(this) as Base // proxy that will be returned by constructor
-
-    newThis.enabled = true
-    newThis._occurrenceCount = 0
-    newThis._target = null
-
-    // Propogate up to target
-    subscribe(newThis, 'effect.change.modify', event => {
-      if (!newThis._target)
-        return
-
-      const type = `${newThis._target.type}.change.effect.modify`
-      publish(newThis._target, type, { ...event, target: newThis._target, source: newThis, type })
-    })
-
-    return newThis
+    this.enabled = true
+    this._occurrenceCount = 0
+    this._target = null
   }
 
+  /**
+   * Wait until this effect is ready to be applied
+   */
+  async whenReady (): Promise<void> {} // eslint-disable-line @typescript-eslint/no-empty-function
+
   /**
    * Attaches this effect to `target` if not already attached.
    * @ignore
    */
   tryAttach (target: Movie | BaseLayer): void {
-    if (this._occurrenceCount === 0)
+    if (this._occurrenceCount === 0) {
       this.attach(target)
+    }
 
     this._occurrenceCount++
   }
@@ -57,21 +48,23 @@ export class Base implements BaseObject {
   }
 
   /**
-   * Dettaches this effect from its target if the number of times `tryDetach`
+   * Detaches this effect from its target if the number of times `tryDetach`
    * has been called (including this call) equals the number of times
    * `tryAttach` has been called.
    *
    * @ignore
    */
   tryDetach (): void {
-    if (this._target === null)
+    if (this._target === null) {
       throw new Error('No movie to detach from')
+    }
 
     this._occurrenceCount--
     // If this effect occurs in another place in the containing array, do not
     // unset _target. (For calling `unshift` on the `layers` proxy)
-    if (this._occurrenceCount === 0)
+    if (this._occurrenceCount === 0) {
       this.detach()
+    }
   }
 
   detach (): void {
@@ -96,6 +89,11 @@ export class Base implements BaseObject {
     return this._target ? this._target.currentTime : undefined
   }
 
+  /** `true` if this effect is ready to be applied */
+  get ready (): boolean {
+    return true
+  }
+
   get parent (): Movie | BaseLayer {
     return this._target
   }
@@ -104,6 +102,9 @@ export class Base implements BaseObject {
     return this._target ? this._target.movie : undefined
   }
 
+  /**
+   * @deprecated See {@link https://github.com/etro-js/etro/issues/131}
+   */
   getDefaultOptions (): Record<string, unknown> {
     return {}
   }

package/src/effect/gaussian-blur.ts

@@ -12,7 +12,7 @@ export interface GaussianBlurOptions {
  * Applies a Gaussian blur
  */
 // TODO: Improve performance
-// TODO: Make sure this is truly gaussian even though it doens't require a
+// TODO: Make sure this is truly gaussian even though it doesn't require a
 // standard deviation
 export class GaussianBlur extends Stack {
   constructor (options: GaussianBlurOptions) {
@@ -63,11 +63,12 @@ class GaussianBlurComponent extends Shader {
 
   apply (target: Movie | Visual, reltime: number): void {
     const radiusVal = val(this, 'radius', reltime)
-    if (radiusVal !== this._radiusCache)
+    if (radiusVal !== this._radiusCache) {
       // Regenerate gaussian distribution canvas.
       this.shape = GaussianBlurComponent._render1DKernel(
         GaussianBlurComponent._gen1DKernel(radiusVal)
       )
+    }
 
     this._radiusCache = radiusVal
 
@@ -106,18 +107,21 @@ class GaussianBlurComponent extends Shader {
     const pascal = GaussianBlurComponent._genPascalRow(2 * radius + 1)
     // don't use `reduce` and `map` (overhead?)
     let sum = 0
-    for (let i = 0; i < pascal.length; i++)
+    for (let i = 0; i < pascal.length; i++) {
       sum += pascal[i]
+    }
 
-    for (let i = 0; i < pascal.length; i++)
+    for (let i = 0; i < pascal.length; i++) {
       pascal[i] /= sum
+    }
 
     return pascal
   }
 
   private static _genPascalRow (index: number): number[] {
-    if (index < 0)
+    if (index < 0) {
       throw new Error(`Invalid index ${index}`)
+    }
 
     let currRow = [1]
     for (let i = 1; i < index; i++) {
@@ -125,8 +129,9 @@ class GaussianBlurComponent extends Shader {
       nextRow.length = currRow.length + 1
       // edges are always 1's
       nextRow[0] = nextRow[nextRow.length - 1] = 1
-      for (let j = 1; j < nextRow.length - 1; j++)
+      for (let j = 1; j < nextRow.length - 1; j++) {
         nextRow[j] = currRow[j - 1] + currRow[j]
+      }
 
       currRow = nextRow
     }

package/src/effect/pixelate.ts

@@ -43,15 +43,15 @@ export class Pixelate extends Shader {
         pixelSize: '1i'
       }
     })
-    /**
-     */
+
     this.pixelSize = options.pixelSize || 1
   }
 
   apply (target: Movie | Visual, reltime: number): void {
     const ps = val(this, 'pixelSize', reltime)
-    if (ps % 1 !== 0 || ps < 0)
+    if (ps % 1 !== 0 || ps < 0) {
       throw new Error('Pixel size must be a nonnegative integer')
+    }
 
     super.apply(target, reltime)
   }

package/src/effect/shader.ts

@@ -4,6 +4,9 @@ import { val } from '../util'
 import { Visual } from './visual'
 
 export interface UniformOptions {
+  /**
+   * The type of the uniform.
+   */
   type?: string
   defaultFloatComponent?: number
 }
@@ -117,8 +120,9 @@ export class Shader extends Visual {
   private _initGl () {
     this._canvas = document.createElement('canvas')
     const gl = this._canvas.getContext('webgl')
-    if (gl === null)
+    if (gl === null) {
       throw new Error('Unable to initialize WebGL. Your browser or machine may not support it.')
+    }
 
     this._gl = gl
     return gl
@@ -127,8 +131,9 @@ export class Shader extends Visual {
   private _initTextures (userUniforms, userTextures, sourceTextureOptions) {
     const gl = this._gl
     const maxTextures = gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS)
-    if (userTextures.length > maxTextures)
+    if (userTextures.length > maxTextures) {
       console.warn('Too many textures!')
+    }
 
     this._userTextures = {}
     for (const name in userTextures) {
@@ -143,8 +148,9 @@ export class Shader extends Visual {
          * textures, without having to define multiple properties in the effect
          * object.
          */
-        if (userUniforms[name])
+        if (userUniforms[name]) {
           throw new Error(`Texture - uniform naming conflict: ${name}!`)
+        }
 
         // Add this as a "user uniform".
         userUniforms[name] = '1i' // texture pointer
@@ -183,19 +189,6 @@ export class Shader extends Visual {
     }
   }
 
-  // Not needed, right?
-  /* watchWebGLOptions() {
-        const pubChange = () => {
-            this.publish("change", {});
-        };
-        for (let name in this._userTextures) {
-            watch(this, name, pubChange);
-        }
-        for (let name in this._userUniforms) {
-            watch(this, name, pubChange);
-        }
-    } */
-
   apply (target: Movie | VisualLayer, reltime: number): void {
     this._checkDimensions(target)
     this._refreshGl()
@@ -303,18 +296,24 @@ export class Shader extends Visual {
     }
   }
 
+  /**
+   * Set the shader's uniforms.
+   * @param target The movie or layer to apply the shader to.
+   * @param reltime The relative time of the movie or layer.
+   */
   private _prepareUniforms (target, reltime) {
     const gl = this._gl
-    // Set the shader uniforms.
 
     // Tell the shader we bound the texture to texture unit 0.
     // All base (Shader class) uniforms are optional.
-    if (this._uniformLocations.source)
+    if (this._uniformLocations.source) {
       gl.uniform1i(this._uniformLocations.source, 0)
+    }
 
     // All base (Shader class) uniforms are optional.
-    if (this._uniformLocations.size)
+    if (this._uniformLocations.size) {
       gl.uniform2iv(this._uniformLocations.size, [target.canvas.width, target.canvas.height])
+    }
 
     for (const unprefixed in this._userUniforms) {
       const options = this._userUniforms[unprefixed] as UniformOptions
@@ -343,11 +342,13 @@ export class Shader extends Visual {
   /**
    * Converts a value of a standard type for javascript to a standard type for
    * GLSL
+   *
    * @param value - the raw value to prepare
    * @param outputType - the WebGL type of |value|; example:
    * <code>1f</code> for a float
    * @param reltime - current time, relative to the target
-   * @param [options] - Optional config
+   * @param [options]
+   * @returns the prepared value
    */
   private _prepareValue (value, outputType, reltime, options: UniformOptions = {}) {
     const def = options.defaultFloatComponent || 0
@@ -369,8 +370,9 @@ export class Shader extends Visual {
       let i = 0
       for (const name in this._userTextures) {
         const testValue = val(this, name, reltime)
-        if (value === testValue)
+        if (value === testValue) {
           value = Shader.INTERNAL_TEXTURE_UNITS + i // after the internal texture units
+        }
 
         i++
       }
@@ -378,32 +380,36 @@ export class Shader extends Visual {
 
     if (outputType === '3fv') {
       // allow 4-component vectors; TODO: why?
-      if (Array.isArray(value) && (value.length === 3 || value.length === 4))
+      if (Array.isArray(value) && (value.length === 3 || value.length === 4)) {
         return value
+      }
 
       // kind of loose so this can be changed if needed
-      if (typeof value === 'object')
+      if (typeof value === 'object') {
         return [
           value.r !== undefined ? value.r : def,
           value.g !== undefined ? value.g : def,
           value.b !== undefined ? value.b : def
         ]
+      }
 
       throw new Error(`Invalid type: ${outputType} or value: ${value}`)
     }
 
     if (outputType === '4fv') {
-      if (Array.isArray(value) && value.length === 4)
+      if (Array.isArray(value) && value.length === 4) {
         return value
+      }
 
       // kind of loose so this can be changed if needed
-      if (typeof value === 'object')
+      if (typeof value === 'object') {
         return [
           value.r !== undefined ? value.r : def,
           value.g !== undefined ? value.g : def,
           value.b !== undefined ? value.b : def,
           value.a !== undefined ? value.a : def
         ]
+      }
 
       throw new Error(`Invalid type: ${outputType} or value: ${value}`)
     }
@@ -509,8 +515,9 @@ export class Shader extends Visual {
     } else {
       // No, it's not a power of 2. Turn off mips and set
       // wrapping to clamp to edge
-      if (wrapS !== gl.CLAMP_TO_EDGE || wrapT !== gl.CLAMP_TO_EDGE)
+      if (wrapS !== gl.CLAMP_TO_EDGE || wrapT !== gl.CLAMP_TO_EDGE) {
         console.warn('Wrap mode is not CLAMP_TO_EDGE for a non-power-of-two texture. Defaulting to CLAMP_TO_EDGE')
+      }
 
       gl.texParameteri(target, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE)
       gl.texParameteri(target, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE)
@@ -552,6 +559,5 @@ export class Shader extends Visual {
     return shader
   }
 }
-// Shader.prototype.getpublicExcludes = () =>
 
 const isPowerOf2 = value => (value && (value - 1)) === 0

package/src/effect/stack.ts

@@ -1,6 +1,40 @@
 import { Movie } from '../movie'
 import { Visual } from './visual'
 import { Visual as VisualLayer } from '../layer'
+import { CustomArray, CustomArrayListener } from '../custom-array'
+
+class StackEffectsListener extends CustomArrayListener<Visual> {
+  // eslint-disable-next-line no-use-before-define
+  private _stack: Stack
+
+  constructor (stack: Stack) {
+    super()
+    this._stack = stack
+  }
+
+  onAdd (effect: Visual) {
+    if (!this._stack.parent) {
+      return
+    }
+
+    effect.tryAttach(this._stack.parent)
+  }
+
+  onRemove (effect: Visual) {
+    if (!this._stack.parent) {
+      return
+    }
+
+    effect.tryDetach()
+  }
+}
+
+class StackEffects extends CustomArray<Visual> {
+  // eslint-disable-next-line no-use-before-define
+  constructor (target: Visual[], stack: Stack) {
+    super(target, new StackEffectsListener(stack))
+  }
+}
 
 export interface StackOptions {
   effects: Visual[]
@@ -11,58 +45,37 @@ export interface StackOptions {
  * for defining reused effect sequences as one effect.
  */
 export class Stack extends Visual {
-  readonly effects: Visual[]
-
-  private _effectsBack: Visual[]
+  readonly effects: StackEffects
 
   constructor (options: StackOptions) {
     super()
 
-    this._effectsBack = []
-    // TODO: Throw 'change' events in handlers
-    this.effects = new Proxy(this._effectsBack, {
-      deleteProperty: function (target: Visual[], property: string | symbol): boolean {
-        const value = target[property]
-        value.detach() // Detach effect from movie
-        delete target[property]
-        return true
-      },
-      set: function (target: Visual[], property: string | symbol, value: Visual): boolean {
-        // TODO: make sure type check works
-        if (!isNaN(Number(property))) { // if property is a number (index)
-          if (target[property])
-            target[property].detach() // Detach old effect from movie
-
-          value.attach(this._target) // Attach effect to movie
-        }
-        target[property] = value
-        return true
-      }
-    })
+    this.effects = new StackEffects(options.effects, this)
     options.effects.forEach(effect => this.effects.push(effect))
-
-    // TODO: Propogate 'change' events from children up
   }
 
   attach (movie: Movie): void {
     super.attach(movie)
+
     this.effects.filter(effect => !!effect).forEach(effect => {
-      effect.detach()
-      effect.attach(movie)
+      effect.tryAttach(movie)
     })
   }
 
   detach (): void {
     super.detach()
+
     this.effects.filter(effect => !!effect).forEach(effect => {
-      effect.detach()
+      effect.tryDetach()
     })
   }
 
   apply (target: Movie | VisualLayer, reltime: number): void {
     for (let i = 0; i < this.effects.length; i++) {
       const effect = this.effects[i]
-      if (!effect) continue
+      if (!effect) {
+        continue
+      }
       effect.apply(target, reltime)
     }
   }

package/src/effect/transform.ts

@@ -36,11 +36,13 @@ class Transform extends Visual {
   }
 
   apply (target: Movie | VisualLayer, reltime: number): void {
-    if (target.canvas.width !== this._tmpCanvas.width)
+    if (target.canvas.width !== this._tmpCanvas.width) {
       this._tmpCanvas.width = target.canvas.width
+    }
 
-    if (target.canvas.height !== this._tmpCanvas.height)
+    if (target.canvas.height !== this._tmpCanvas.height) {
       this._tmpCanvas.height = target.canvas.height
+    }
 
     // Use data, since that's the underlying storage
     this._tmpMatrix.data = val(this, 'matrix.data', reltime)
@@ -81,8 +83,9 @@ namespace Transform { // eslint-disable-line @typescript-eslint/no-namespace
     }
 
     identity (): Matrix {
-      for (let i = 0; i < this.data.length; i++)
+      for (let i = 0; i < this.data.length; i++) {
         this.data[i] = Matrix.IDENTITY.data[i]
+      }
 
       return this
     }
@@ -93,8 +96,9 @@ namespace Transform { // eslint-disable-line @typescript-eslint/no-namespace
      * @param [val]
      */
     cell (x: number, y: number, val?: number): number {
-      if (val !== undefined)
+      if (val !== undefined) {
         this.data[3 * y + x] = val
+      }
 
       return this.data[3 * y + x]
     }
@@ -130,18 +134,21 @@ namespace Transform { // eslint-disable-line @typescript-eslint/no-namespace
      */
     multiply (other: Matrix): Matrix {
       // copy to temporary matrix to avoid modifying `this` while reading from it
-      for (let x = 0; x < 3; x++)
+      for (let x = 0; x < 3; x++) {
         for (let y = 0; y < 3; y++) {
           let sum = 0
-          for (let i = 0; i < 3; i++)
+          for (let i = 0; i < 3; i++) {
             sum += this.cell(x, i) * other.cell(i, y)
+          }
 
           Matrix._TMP_MATRIX.cell(x, y, sum)
         }
+      }
 
       // copy data from TMP_MATRIX to this
-      for (let i = 0; i < Matrix._TMP_MATRIX.data.length; i++)
+      for (let i = 0; i < Matrix._TMP_MATRIX.data.length; i++) {
         this.data[i] = Matrix._TMP_MATRIX.data[i]
+      }
 
       return this
     }