etro 0.6.0 → 0.8.1

package/src/layer/base.ts

@@ -0,0 +1,175 @@
+import EtroObject from '../object'
+import { publish, subscribe } from '../event'
+import { watchPublic, applyOptions } from '../util'
+import { Movie } from '../movie'
+
+interface BaseOptions {
+  /** The time in the movie at which this layer starts */
+  startTime: number
+  duration: number
+}
+
+/**
+ * A layer outputs content for the movie
+ */
+class Base implements EtroObject {
+  type: string
+  publicExcludes: string[]
+  propertyFilters: Record<string, <T>(value: T) => T>
+  enabled: boolean
+  /**
+   * If the attached movie's playback position is in this layer
+   */
+  active: boolean
+
+  /**
+   * The number of times this layer has been attached to a movie minus the
+   * number of times it's been detached. (Used for the movie's array proxy with
+   * `unshift`)
+   */
+  private _occurrenceCount: number
+  private _startTime: number
+  private _duration: number
+  private _movie: Movie
+
+  /**
+   * Creates a new empty layer
+   *
+   * @param options
+   * @param options.startTime - when to start the layer on the movie's
+   * timeline
+   * @param options.duration - how long the layer should last on the
+   * movie's timeline
+   */
+  constructor (options: BaseOptions) {
+    // Set startTime and duration properties manually, because they are
+    // readonly. applyOptions ignores readonly properties.
+    this._startTime = options.startTime
+    this._duration = options.duration
+
+    // Proxy that will be returned by constructor (for sending 'modified'
+    // events).
+    const newThis = watchPublic(this) as Base
+    // Don't send updates when initializing, so use this instead of newThis
+    applyOptions(options, this)
+
+    // Whether this layer is currently being rendered
+    this.active = false
+    this.enabled = true
+
+    this._occurrenceCount = 0 // no occurances in parent
+    this._movie = null
+
+    // Propogate up to target
+    subscribe(newThis, 'layer.change', event => {
+      const typeOfChange = event.type.substring(event.type.lastIndexOf('.') + 1)
+      const type = `movie.change.layer.${typeOfChange}`
+      publish(newThis._movie, type, { ...event, target: newThis._movie, type })
+    })
+
+    return newThis
+  }
+
+  /**
+   * Attaches this layer to `movie` if not already attached.
+   * @ignore
+   */
+  tryAttach (movie: Movie): void {
+    if (this._occurrenceCount === 0)
+      this.attach(movie)
+
+    this._occurrenceCount++
+  }
+
+  attach (movie: Movie): void {
+    this._movie = movie
+  }
+
+  /**
+   * Dettaches this layer from its movie 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.movie === null)
+      throw new Error('No movie to detach from')
+
+    this._occurrenceCount--
+    // If this layer occurs in another place in a `layers` array, do not unset
+    // _movie. (For calling `unshift` on the `layers` proxy)
+    if (this._occurrenceCount === 0)
+      this.detach()
+  }
+
+  detach (): void {
+    this._movie = null
+  }
+
+  /**
+   * Called when the layer is activated
+   */
+  start (): void {} // eslint-disable-line @typescript-eslint/no-empty-function
+
+  /**
+   * Called when the movie renders and the layer is active
+   */
+  render (): void {} // eslint-disable-line @typescript-eslint/no-empty-function
+
+  /**
+  * Called when the layer is deactivated
+   */
+  stop (): void {} // eslint-disable-line @typescript-eslint/no-empty-function
+
+  // TODO: is this needed?
+  get parent (): Movie {
+    return this._movie
+  }
+
+  /**
+   */
+  get startTime (): number {
+    return this._startTime
+  }
+
+  set startTime (val: number) {
+    this._startTime = val
+  }
+
+  /**
+   * The current time of the movie relative to this layer
+   */
+  get currentTime (): number {
+    return this._movie ? this._movie.currentTime - this.startTime
+      : undefined
+  }
+
+  /**
+   */
+  get duration (): number {
+    return this._duration
+  }
+
+  set duration (val: number) {
+    this._duration = val
+  }
+
+  get movie (): Movie {
+    return this._movie
+  }
+
+  getDefaultOptions (): BaseOptions {
+    return {
+      startTime: undefined, // required
+      duration: undefined // required
+    }
+  }
+}
+// id for events (independent of instance, but easy to access when on prototype
+// chain)
+Base.prototype.type = 'layer'
+Base.prototype.publicExcludes = []
+Base.prototype.propertyFilters = {}
+
+export { Base, BaseOptions }

package/src/layer/image.ts

@@ -0,0 +1,8 @@
+import { Visual, VisualOptions } from './visual'
+import { VisualSourceMixin } from './visual-source'
+
+type ImageOptions = VisualOptions
+
+class Image extends VisualSourceMixin(Visual) {}
+
+export { Image, ImageOptions }

package/src/layer/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @module layer
+ */
+// TODO: Add aligning options, like horizontal and vertical align modes
+
+export * from './audio-source'
+export * from './audio'
+export * from './base'
+export * from './image'
+export * from './text'
+export * from './video'
+export * from './visual-source'
+export * from './visual'

package/src/layer/text.ts

@@ -0,0 +1,138 @@
+import { Dynamic, val, applyOptions } from '../util'
+import { Visual, VisualOptions } from './visual'
+
+interface TextOptions extends VisualOptions {
+  text: Dynamic<string>
+  font?: Dynamic<string>
+  color?: Dynamic<string>
+  /** The text's horizontal offset from the layer */
+  textX?: Dynamic<number>
+  /** The text's vertical offset from the layer */
+  textY?: Dynamic<number>
+  maxWidth?: Dynamic<number>
+  /**
+   * @desc The horizontal alignment
+   * @see [`CanvasRenderingContext2D#textAlign<`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign)
+   */
+  textAlign?: Dynamic<string>
+  /**
+   * @desc The vertical alignment
+   * @see [`CanvasRenderingContext2D#textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+   */
+  textBaseline?: Dynamic<string>
+  /**
+   * @see [`CanvasRenderingContext2D#direction`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+   */
+  textDirection?: Dynamic<string>
+}
+
+class Text extends Visual {
+  text: Dynamic<string>
+  font: Dynamic<string>
+  color: Dynamic<string>
+  /** The text's horizontal offset from the layer */
+  textX: Dynamic<number>
+  /** The text's vertical offset from the layer */
+  textY: Dynamic<number>
+  maxWidth: Dynamic<number>
+  /**
+   * @desc The horizontal alignment
+   * @see [`CanvasRenderingContext2D#textAlign<`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textAlign)
+   */
+  textAlign: Dynamic<string>
+  /**
+   * @desc The vertical alignment
+   * @see [`CanvasRenderingContext2D#textBaseline`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+   */
+  textBaseline: Dynamic<string>
+  /**
+   * @see [`CanvasRenderingContext2D#direction`](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/textBaseline)
+   */
+  textDirection: Dynamic<string>
+
+  private _prevText: string
+  private _prevFont: string
+  private _prevMaxWidth: number
+
+  /**
+   * Creates a new text layer
+   */
+  // TODO: add padding options
+  // TODO: is textX necessary? it seems inconsistent, because you can't define
+  // width/height directly for a text layer
+  constructor (options: TextOptions) {
+    // Default to no (transparent) background
+    super({ background: null, ...options })
+    applyOptions(options, this)
+
+    // this._prevText = undefined;
+    // // because the canvas context rounds font size, but we need to be more accurate
+    // // rn, this doesn't make a difference, because we can only measure metrics by integer font sizes
+    // this._lastFont = undefined;
+    // this._prevMaxWidth = undefined;
+  }
+
+  doRender (): void {
+    super.doRender()
+    const text = val(this, 'text', this.currentTime); const font = val(this, 'font', this.currentTime)
+    const maxWidth = this.maxWidth ? val(this, 'maxWidth', this.currentTime) : undefined
+    // // properties that affect metrics
+    // if (this._prevText !== text || this._prevFont !== font || this._prevMaxWidth !== maxWidth)
+    //     this._updateMetrics(text, font, maxWidth);
+
+    this.cctx.font = font
+    this.cctx.fillStyle = val(this, 'color', this.currentTime)
+    this.cctx.textAlign = val(this, 'textAlign', this.currentTime)
+    this.cctx.textBaseline = val(this, 'textBaseline', this.currentTime)
+    this.cctx.direction = val(this, 'textDirection', this.currentTime)
+    this.cctx.fillText(
+      text, val(this, 'textX', this.currentTime), val(this, 'textY', this.currentTime),
+      maxWidth
+    )
+
+    this._prevText = text
+    this._prevFont = font
+    this._prevMaxWidth = maxWidth
+  }
+
+  // _updateMetrics(text, font, maxWidth) {
+  //     // TODO calculate / measure for non-integer font.size values
+  //     let metrics = Text._measureText(text, font, maxWidth);
+  //     // TODO: allow user-specified/overwritten width/height
+  //     this.width = /*this.width || */metrics.width;
+  //     this.height = /*this.height || */metrics.height;
+  // }
+
+  // TODO: implement setters and getters that update dimensions!
+
+  /* static _measureText(text, font, maxWidth) {
+        // TODO: fix too much bottom padding
+        const s = document.createElement("span");
+        s.textContent = text;
+        s.style.font = font;
+        s.style.padding = "0";
+        if (maxWidth) s.style.maxWidth = maxWidth;
+        document.body.appendChild(s);
+        const metrics = {width: s.offsetWidth, height: s.offsetHeight};
+        document.body.removeChild(s);
+        return metrics;
+    } */
+
+  getDefaultOptions (): TextOptions {
+    return {
+      ...Visual.prototype.getDefaultOptions(),
+      background: null,
+      text: undefined, // required
+      font: '10px sans-serif',
+      color: '#fff',
+      textX: 0,
+      textY: 0,
+      maxWidth: null,
+      textAlign: 'start',
+      textBaseline: 'top',
+      textDirection: 'ltr'
+    }
+  }
+}
+
+export { Text, TextOptions }

package/src/layer/video.ts

@@ -0,0 +1,15 @@
+import { Visual } from './visual'
+import { VisualSourceOptions, VisualSourceMixin } from './visual-source'
+import { AudioSourceOptions, AudioSourceMixin } from './audio-source'
+
+type VideoOptions = VisualSourceOptions & AudioSourceOptions
+
+// Use mixins instead of `extend`ing two classes (which isn't supported by
+// JavaScript).
+/**
+ * @extends AudioSource
+ * @extends VisualSource
+ */
+class Video extends AudioSourceMixin(VisualSourceMixin(Visual)) {}
+
+export { Video, VideoOptions }

package/src/layer/visual-source.ts

@@ -0,0 +1,150 @@
+import { Dynamic, val, applyOptions } from '../util'
+import { Base, BaseOptions } from './base'
+import { Visual, VisualOptions } from './visual'
+
+type Constructor<T> = new (...args: unknown[]) => T
+
+interface VisualSource extends Base {
+  readonly source: HTMLImageElement | HTMLVideoElement
+}
+
+interface VisualSourceOptions extends VisualOptions {
+  source: HTMLImageElement | HTMLVideoElement
+  /** What part of {@link source} to render */
+  sourceX?: Dynamic<number>
+  /** What part of {@link source} to render */
+  sourceY?: Dynamic<number>
+  /** What part of {@link source} to render, or undefined for the entire width */
+  sourceWidth?: Dynamic<number>
+  /** What part of {@link source} to render, or undefined for the entire height */
+  sourceHeight?: Dynamic<number>
+  /** Where to render {@link source} onto the layer */
+  destX?: Dynamic<number>
+  /** Where to render {@link source} onto the layer */
+  destY?: Dynamic<number>
+  /** Where to render {@link source} onto the layer, or undefined to fill the layer's width */
+  destWidth?: Dynamic<number>
+  /** Where to render {@link source} onto the layer, or undefined to fill the layer's height */
+  destHeight?: Dynamic<number>
+}
+
+/**
+ * A layer that gets its image data from an HTML image or video element
+ * @mixin VisualSourceMixin
+ */
+function VisualSourceMixin<OptionsSuperclass extends BaseOptions> (superclass: Constructor<Visual>): Constructor<VisualSource> {
+  type MixedVisualSourceOptions = OptionsSuperclass & VisualSourceOptions
+
+  class MixedVisualSource extends superclass {
+    /**
+     * The raw html media element
+     */
+    readonly source: HTMLImageElement | HTMLVideoElement
+
+    /** What part of {@link source} to render */
+    sourceX: Dynamic<number>
+    /** What part of {@link source} to render */
+    sourceY: Dynamic<number>
+    /** What part of {@link source} to render, or undefined for the entire width */
+    sourceWidth: Dynamic<number>
+    /** What part of {@link source} to render, or undefined for the entire height */
+    sourceHeight: Dynamic<number>
+    /** Where to render {@link source} onto the layer */
+    destX: Dynamic<number>
+    /** Where to render {@link source} onto the layer */
+    destY: Dynamic<number>
+    /** Where to render {@link source} onto the layer, or undefined to fill the layer's width */
+    destWidth: Dynamic<number>
+    /** Where to render {@link source} onto the layer, or undefined to fill the layer's height */
+    destHeight: Dynamic<number>
+
+    constructor (options: MixedVisualSourceOptions) {
+      super(options)
+      applyOptions(options, this)
+    }
+
+    doRender () {
+      // Clear/fill background
+      super.doRender()
+
+      /*
+       * Source dimensions crop the image. Dest dimensions set the size that
+       * the image will be rendered at *on the layer*. Note that this is
+       * different than the layer dimensions (`this.width` and `this.height`).
+       * The main reason this distinction exists is so that an image layer can
+       * be rotated without being cropped (see iss #46).
+       */
+      this.cctx.drawImage(
+        this.source,
+        val(this, 'sourceX', this.currentTime), val(this, 'sourceY', this.currentTime),
+        val(this, 'sourceWidth', this.currentTime), val(this, 'sourceHeight', this.currentTime),
+        // `destX` and `destY` are relative to the layer
+        val(this, 'destX', this.currentTime), val(this, 'destY', this.currentTime),
+        val(this, 'destWidth', this.currentTime), val(this, 'destHeight', this.currentTime)
+      )
+    }
+
+    getDefaultOptions (): MixedVisualSourceOptions {
+      return {
+        ...superclass.prototype.getDefaultOptions(),
+        source: undefined, // required
+        sourceX: 0,
+        sourceY: 0,
+        sourceWidth: undefined,
+        sourceHeight: undefined,
+        destX: 0,
+        destY: 0,
+        destWidth: undefined,
+        destHeight: undefined
+      }
+    }
+  }
+  MixedVisualSource.prototype.propertyFilters = {
+    ...Visual.prototype.propertyFilters,
+
+    /*
+     * If no layer width was provided, fall back to the dest width.
+     * If no dest width was provided, fall back to the source width.
+     * If no source width was provided, fall back to `source.width`.
+     */
+    sourceWidth: function (sourceWidth) {
+      // != instead of !== to account for `null`
+      const width = this.source instanceof HTMLImageElement
+        ? this.source.width
+        : this.source.videoWidth
+      return sourceWidth != undefined ? sourceWidth : width // eslint-disable-line eqeqeq
+    },
+    sourceHeight: function (sourceHeight) {
+      const height = this.source instanceof HTMLImageElement
+        ? this.source.height
+        : this.source.videoHeight
+      return sourceHeight != undefined ? sourceHeight : height // eslint-disable-line eqeqeq
+    },
+    destWidth: function (destWidth) {
+      // I believe reltime is redundant, as element#currentTime can be used
+      // instead. (TODO: fact check)
+      /* eslint-disable eqeqeq */
+      return destWidth != undefined
+        ? destWidth : val(this, 'sourceWidth', this.currentTime)
+    },
+    destHeight: function (destHeight) {
+      /* eslint-disable eqeqeq */
+      return destHeight != undefined
+        ? destHeight : val(this, 'sourceHeight', this.currentTime)
+    },
+    width: function (width) {
+      /* eslint-disable eqeqeq */
+      return width != undefined
+        ? width : val(this, 'destWidth', this.currentTime)
+    },
+    height: function (height) {
+      /* eslint-disable eqeqeq */
+      return height != undefined
+        ? height : val(this, 'destHeight', this.currentTime)
+    }
+  }
+
+  return MixedVisualSource
+}
+
+export { VisualSource, VisualSourceOptions, VisualSourceMixin }

package/src/layer/visual.ts

@@ -0,0 +1,197 @@
+import { Dynamic, val, applyOptions } from '../util'
+import { Base, BaseOptions } from './base'
+import { Base as BaseEffect } from '../effect/base'
+
+interface VisualOptions extends BaseOptions {
+  x?: Dynamic<number>
+  y?: Dynamic<number>
+  width?: Dynamic<number>
+  height?: Dynamic<number>
+  background?: Dynamic<string>
+  border?: Dynamic<{
+    color: string
+    thickness?: number
+  }>
+
+  opacity?: Dynamic<number>
+}
+
+/** Any layer that renders to a canvas */
+class Visual extends Base {
+  x: Dynamic<number>
+  y: Dynamic<number>
+  width: Dynamic<number>
+  height: Dynamic<number>
+  background: Dynamic<string>
+  border: Dynamic<{
+    color: string
+    thickness: number
+  }>
+
+  opacity: Dynamic<number>
+
+  /**
+   * The layer's rendering canvas
+   */
+  readonly canvas: HTMLCanvasElement
+
+  /**
+   * The context of {@link Visual#canvas}
+   */
+  readonly cctx: CanvasRenderingContext2D
+
+  // readonly because it's a proxy
+  readonly effects: BaseEffect[]
+
+  private _effectsBack: BaseEffect[]
+
+  /**
+   * Creates a visual layer
+   */
+  constructor (options: VisualOptions) {
+    super(options)
+    // Only validate extra if not subclassed, because if subclcass, there will
+    // be extraneous options.
+    applyOptions(options, this)
+
+    this.canvas = document.createElement('canvas')
+    this.cctx = this.canvas.getContext('2d')
+
+    this._effectsBack = []
+    this.effects = new Proxy(this._effectsBack, {
+      deleteProperty: (target, property) => {
+        const value = target[property]
+        value.detach()
+        delete target[property]
+        return true
+      },
+      set: (target, property, value) => {
+        if (!isNaN(Number(property))) {
+          // The property is a number (index)
+          if (target[property])
+            target[property].detach()
+
+          value.attach(this)
+        }
+        target[property] = value
+        return true
+      }
+    })
+  }
+
+  /**
+   * Render visual output
+   */
+  render (): void {
+    this.beginRender()
+    this.doRender()
+    this.endRender()
+  }
+
+  beginRender (): void {
+    this.canvas.width = val(this, 'width', this.currentTime)
+    this.canvas.height = val(this, 'height', this.currentTime)
+    this.cctx.globalAlpha = val(this, 'opacity', this.currentTime)
+  }
+
+  doRender (): void {
+    /*
+     * If this.width or this.height is null, that means "take all available
+     * screen space", so set it to this._move.width or this._movie.height,
+     * respectively canvas.width & canvas.height are already interpolated
+     */
+    if (this.background) {
+      this.cctx.fillStyle = val(this, 'background', this.currentTime)
+      // (0, 0) relative to layer
+      this.cctx.fillRect(0, 0, this.canvas.width, this.canvas.height)
+    }
+    const border = val(this, 'border', this.currentTime)
+    if (border && border.color) {
+      this.cctx.strokeStyle = border.color
+      // This is optional.. TODO: integrate this with defaultOptions
+      this.cctx.lineWidth = border.thickness || 1
+    }
+  }
+
+  endRender (): void {
+    const w = val(this, 'width', this.currentTime) || val(this.movie, 'width', this.movie.currentTime)
+    const h = val(this, 'height', this.currentTime) || val(this.movie, 'height', this.movie.currentTime)
+    if (w * h > 0)
+      this._applyEffects()
+
+    // else InvalidStateError for drawing zero-area image in some effects, right?
+  }
+
+  _applyEffects (): void {
+    for (let i = 0; i < this.effects.length; i++) {
+      const effect = this.effects[i]
+      if (effect.enabled)
+        // Pass relative time
+        effect.apply(this, this.movie.currentTime - this.startTime)
+    }
+  }
+
+  /**
+   * Convienence method for <code>effects.push()</code>
+   * @param effect
+   * @return the layer (for chaining)
+   */
+  addEffect (effect: BaseEffect): Visual {
+    this.effects.push(effect); return this
+  }
+
+  getDefaultOptions (): VisualOptions {
+    return {
+      ...Base.prototype.getDefaultOptions(),
+      /**
+       * @name module:layer.Visual#x
+       * @desc The offset of the layer relative to the movie
+       */
+      x: 0,
+      /**
+       * @name module:layer.Visual#y
+       * @desc The offset of the layer relative to the movie
+       */
+      y: 0,
+      /**
+       * @name module:layer.Visual#width
+       */
+      width: null,
+      /**
+       * @name module:layer.Visual#height
+       */
+      height: null,
+      /**
+       * @name module:layer.Visual#background
+       * @desc The CSS color code for the background, or <code>null</code> for
+       * transparency
+       */
+      background: null,
+      /**
+       * @name module:layer.Visual#border
+       * @desc The CSS border style, or <code>null</code> for no border
+       */
+      border: null,
+      /**
+       * @name module:layer.Visual#opacity
+       */
+      opacity: 1
+    }
+  }
+}
+Visual.prototype.publicExcludes = Base.prototype.publicExcludes.concat(['canvas', 'cctx', 'effects'])
+Visual.prototype.propertyFilters = {
+  ...Base.prototype.propertyFilters,
+  /*
+   * If this.width or this.height is null, that means "take all available screen
+   * space", so set it to this._move.width or this._movie.height, respectively
+   */
+  width: function (width) {
+    return width != undefined ? width : this._movie.width // eslint-disable-line eqeqeq
+  },
+  height: function (height) {
+    return height != undefined ? height : this._movie.height // eslint-disable-line eqeqeq
+  }
+}
+
+export { Visual, VisualOptions }