base/Frame.js

  1. /*
  2.  * Copyright 2020 WICKLETS LLC
  3.  *
  4.  * This file is part of Wick Engine.
  5.  *
  6.  * Wick Engine is free software: you can redistribute it and/or modify
  7.  * it under the terms of the GNU General Public License as published by
  8.  * the Free Software Foundation, either version 3 of the License, or
  9.  * (at your option) any later version.
  10.  *
  11.  * Wick Engine is distributed in the hope that it will be useful,
  12.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  * GNU General Public License for more details.
  15.  *
  16.  * You should have received a copy of the GNU General Public License
  17.  * along with Wick Engine.  If not, see <https://www.gnu.org/licenses/>.
  18.  */
  20. /**
  21.  * A class representing a frame.
  22.  */
  23. Wick.Frame = class extends Wick.Tickable {
  24.     /**
  25.      * Create a new frame.
  26.      * @param {number} start - The start of the frame. Optional, defaults to 1.
  27.      * @param {number} end - The end of the frame. Optional, defaults to be the same as start.
  28.      */
  29.     constructor(args) {
  30.         if (!args) args = {};
  31.         super(args);
  33.         this.start = args.start || 1;
  34.         this.end = args.end || this.start;
  36.         this._soundAssetUUID = null;
  37.         this._soundID = null;
  38.         this._soundVolume = 1.0;
  39.         this._soundLoop = false;
  40.         this._soundStart = 0;
  42.         this._originalLayerIndex = -1;
  43.     }
  45.     _serialize(args) {
  46.         var data = super._serialize(args);
  48.         data.start = this.start;
  49.         data.end = this.end;
  51.         data.sound = this._soundAssetUUID;
  52.         data.soundVolume = this._soundVolume;
  53.         data.soundLoop = this._soundLoop;
  54.         data.soundStart = this._soundStart;
  56.         data.originalLayerIndex = this.layerIndex !== -1 ? this.layerIndex : this._originalLayerIndex;
  58.         return data;
  59.     }
  61.     _deserialize(data) {
  62.         super._deserialize(data);
  64.         this.start = data.start;
  65.         this.end = data.end;
  67.         this._soundAssetUUID = data.sound;
  68.         this._soundVolume = data.soundVolume === undefined ? 1.0 : data.soundVolume;
  69.         this._soundLoop = data.soundLoop === undefined ? false : data.soundLoop;
  70.         this._soundStart = data.soundStart === undefined ? 0 : data.soundStart;
  72.         this._originalLayerIndex = data.originalLayerIndex;
  73.     }
  75.     get classname() {
  76.         return 'Frame';
  77.     }
  79.     /**
  80.      * The length of the frame.
  81.      * @type {number}
  82.      */
  83.     get length() {
  84.         return this.end - this.start + 1;
  85.     }
  87.     set length(length) {
  88.         length = Math.max(1, length);
  89.         var diff = length - this.length;
  90.         this.end += diff;
  91.     }
  93.     /**
  94.      * The midpoint of the frame.
  95.      * @type {number}
  96.      */
  97.     get midpoint() {
  98.         return this.start + (this.end - this.start) / 2;
  99.     }
  101.     /**
  102.      * Is true if the frame is currently visible.
  103.      * @type {boolean}
  104.      */
  105.     get onScreen() {
  106.         if (!this.parent) return true;
  107.         return this.inPosition(this.parentTimeline.playheadPosition) && this.parentClip.onScreen;
  108.     }
  110.     /**
  111.      * The sound attached to the frame.
  112.      * @type {Wick.SoundAsset}
  113.      */
  114.     get sound() {
  115.         var uuid = this._soundAssetUUID;
  116.         return uuid ? this.project.getAssetByUUID(uuid) : null;
  117.     }
  119.     set sound(soundAsset) {
  120.         if (!soundAsset) { 
  121.             this.removeSound();
  122.             return;
  123.         }
  125.         this._soundAssetUUID = soundAsset.uuid;
  126.     }
  128.     /**
  129.      * The volume of the sound attached to the frame.
  130.      * @type {number}
  131.      */
  132.     get soundVolume() {
  133.         return this._soundVolume
  134.     }
  136.     set soundVolume(soundVolume) {
  137.         this._soundVolume = soundVolume;
  138.     }
  140.     /**
  141.      * Whether or not the sound loops.
  142.      * @type {boolean}
  143.      */
  144.     get soundLoop() {
  145.         return this._soundLoop;
  146.     }
  148.     set soundLoop(soundLoop) {
  149.         this._soundLoop = soundLoop;
  150.     }
  152.     /**
  153.      * True if this frame should currently be onion skinned.
  154.      */
  155.     get onionSkinned () {
  156.         if (!this.project || !this.project.onionSkinEnabled) {
  157.             return false;
  158.         }
  160.         // Don't onion skin if we're in the playhead's position.
  161.         var playheadPosition = this.project.focus.timeline.playheadPosition;
  162.         if (this.inPosition(playheadPosition)) {
  163.             return false;
  164.         }
  166.         // Determine if we're in onion skinning range.
  167.         var onionSkinSeekBackwards = this.project.onionSkinSeekBackwards;
  168.         var onionSkinSeekForwards = this.project.onionSkinSeekForwards;
  169.         return this.inRange(playheadPosition - onionSkinSeekBackwards,
  170.                             playheadPosition + onionSkinSeekForwards);
  172.     }
  174.     /**
  175.      * Removes the sound attached to this frame.
  176.      */
  177.     removeSound() {
  178.         this._soundAssetUUID = null;
  179.     }
  181.     /**
  182.      * Plays the sound attached to this frame.
  183.      */
  184.     playSound() {
  185.         if (!this.sound) {
  186.             return;
  187.         }
  189.         var options = {
  190.             seekMS: this.playheadSoundOffsetMS + this.soundStart,
  191.             volume: this.soundVolume,
  192.             loop: this.soundLoop,
  193.             frame: this,
  194.         };
  196.         this._soundID = this.project.playSoundFromAsset(this.sound, options);
  197.     }
  199.     /**
  200.      * Stops the sound attached to this frame.
  201.      */
  202.     stopSound() {
  203.         if (this.sound) {
  204.             this.sound.stop(this._soundID);
  205.             this._soundID = null;
  206.         }
  207.     }
  209.     /**
  210.      * Check if the sound on this frame is playing.
  211.      * @returns {boolean} true if the sound is playing
  212.      */
  213.     isSoundPlaying() {
  214.         return this._soundID !== null;
  215.     }
  217.     /**
  218.      * The amount of time, in milliseconds, that the frame's sound should play before stopping.
  219.      * @type {number}
  220.      */
  221.     get playheadSoundOffsetMS() {
  222.         var offsetFrames = this.parentTimeline.playheadPosition - this.start;
  223.         var offsetMS = (1000 / this.project.framerate) * offsetFrames;
  224.         return offsetMS;
  225.     }
  227.     /**
  228.      * The amount of time the sound playing should be offset, in milliseconds. If this is 0,
  229.      * the sound plays normally. A negative value means the sound should start at a later point
  230.      * in the track. THIS DOES NOT DETERMINE WHEN A SOUND PLAYS.
  231.      * @type {number}
  232.      */
  233.     get soundStart() {
  234.         return this._soundStart;
  235.     }
  237.     set soundStart(val) {
  238.         this._soundStart = val;
  239.     }
  241.     /**
  242.      * When should the sound start, in milliseconds.
  243.      * @type {number}
  244.      */
  245.     get soundStartMS() {
  246.         return (1000 / this.project.framerate) * (this.start - 1);
  247.     }
  249.     /**
  250.      * When should the sound end, in milliseconds.
  251.      * @type {number}
  252.      */
  253.     get soundEndMS() {
  254.         return (1000 / this.project.framerate) * this.end;
  255.     }
  257.     /**
  258.      * Returns the frame's start position in relation to the root timeline.
  259.      */
  260.     get projectFrameStart () {
  261.         if (this.parentClip.isRoot) {
  262.             return this.start;
  263.         } else {
  264.             let val = this.start + this.parentClip.parentFrame.projectFrameStart - 1;
  265.             return val;
  266.         }
  267.     }
  269.     /**
  270.      * The paths on the frame.
  271.      * @type {Wick.Path[]}
  272.      */
  273.     get paths() {
  274.         return this.getChildren('Path');
  275.     }
  277.     /**
  278.      * The paths that are text and have identifiers, for dynamic text.
  279.      * @type {Wick.Path[]}
  280.      */
  281.     get dynamicTextPaths() {
  282.         return this.paths.filter(path => {
  283.             return path.isDynamicText;
  284.         });
  285.     }
  287.     /**
  288.      * The clips on the frame.
  289.      * @type {Wick.Clip[]}
  290.      */
  291.     get clips() {
  292.         return this.getChildren(['Clip', 'Button']);
  293.     }
  295.     /**
  296.      * The drawable objectson the frame.
  297.      * @type {Wick.Base[]}
  298.      */
  299.     get drawable() {
  300.         return this.getChildren(['Clip', 'Button', 'Path']);
  301.     }
  303.     /**
  304.      * The tweens on this frame.
  305.      * @type {Wick.Tween[]}
  306.      */
  307.     get tweens() {
  308.         // Ensure no tweens are outside of this frame's length.
  309.         var tweens = this.getChildren('Tween')
  310.         tweens.forEach(tween => {
  311.             tween.restrictToFrameSize();
  312.         });
  314.         return this.getChildren('Tween');
  315.     }
  317.     /**
  318.      * True if there are clips or paths on the frame.
  319.      * @type {boolean}
  320.      */
  321.     get contentful () {
  322.         return this.paths.filter(path => {
  323.             return !path.view.item.data._isPlaceholder;
  324.         }).length > 0 || this.clips.length > 0;
  325.     }
  327.     /**
  328.      * The index of the parent layer.
  329.      * @type {number}
  330.      */
  331.     get layerIndex() {
  332.         return this.parentLayer ? this.parentLayer.index : -1;
  333.     }
  335.     /**
  336.      * The index of the layer that this frame last belonged to. Used when copying and pasting frames.
  337.      * @type {number}
  338.      */
  339.     get originalLayerIndex() {
  340.         return this._originalLayerIndex;
  341.     }
  343.     /**
  344.      * Removes this frame from its parent layer.
  345.      */
  346.     remove() {
  347.         this.parent.removeFrame(this);
  348.     }
  350.     /**
  351.      * True if the playhead is on this frame.
  352.      * @param {number} playheadPosition - the position of the playhead.
  353.      * @return {boolean}
  354.      */
  355.     inPosition(playheadPosition) {
  356.         return this.start <= playheadPosition &&
  357.             this.end >= playheadPosition;
  358.     }
  360.     /**
  361.      * True if the frame exists within the given range.
  362.      * @param {number} start - the start of the range to check.
  363.      * @param {number} end - the end of the range to check.
  364.      * @return {boolean}
  365.      */
  366.     inRange(start, end) {
  367.         return this.inPosition(start) ||
  368.             this.inPosition(end) ||
  369.             (this.start >= start && this.start <= end) ||
  370.             (this.end >= start && this.end <= end);
  371.     }
  373.     /**
  374.      * True if the frame is contained fully within a given range.
  375.      * @param {number} start - the start of the range to check.
  376.      * @param {number} end - the end of the range to check.
  377.      * @return {boolean}
  378.      */
  379.     containedWithin(start, end) {
  380.         return this.start >= start && this.end <= end;
  381.     }
  383.     /**
  384.      * The number of frames that this frame is from a given playhead position.
  385.      * @param {number} playheadPosition
  386.      */
  387.     distanceFrom(playheadPosition) {
  388.         // playhead position is inside frame, distance is zero.
  389.         if (this.start <= playheadPosition && this.end >= playheadPosition) {
  390.             return 0;
  391.         }
  393.         // otherwise, find the distance from the nearest end
  394.         if (this.start >= playheadPosition) {
  395.             return this.start - playheadPosition;
  396.         } else if (this.end <= playheadPosition) {
  397.             return playheadPosition - this.end;
  398.         }
  399.     }
  401.     /**
  402.      * Add a clip to the frame.
  403.      * @param {Wick.Clip} clip - the clip to add.
  404.      */
  405.     addClip(clip) {
  407.         if (clip.parent) {
  408.             clip.remove();
  409.         }
  411.         this.addChild(clip);
  413.         // Pre-render the clip's frames
  414.         // (this fixes an issue where clips created from ClipAssets would be "missing" frames)
  415.         clip.timeline.getAllFrames(true).forEach(frame => {
  416.             frame.view.render();
  417.         });
  418.     }
  420.     /**
  421.      * Remove a clip from the frame.
  422.      * @param {Wick.Clip} clip - the clip to remove.
  423.      */
  424.     removeClip(clip) {
  425.         this.removeChild(clip);
  426.     }
  428.     /**
  429.      * Add a path to the frame.
  430.      * @param {Wick.Path} path - the path to add.
  431.      */
  432.     addPath(path) {
  433.         if (path.parent) {
  434.             path.remove();
  435.         }
  436.         this.addChild(path);
  437.     }
  439.     /**
  440.      * Remove a path from the frame.
  441.      * @param {Wick.Path} path - the path to remove.
  442.      */
  443.     removePath(path) {
  444.         this.removeChild(path);
  445.     }
  447.     /**
  448.      * Add a tween to the frame.
  449.      * @param {Wick.Tween} tween - the tween to add.
  450.      */
  451.     addTween(tween) {
  452.         // New tweens eat existing tweens.
  453.         var otherTween = this.getTweenAtPosition(tween.playheadPosition);
  454.         if (otherTween) {
  455.             otherTween.remove();
  456.         }
  458.         this.addChild(tween);
  459.         tween.restrictToFrameSize();
  460.     }
  462.     /**
  463.      * Automatically creates a tween at the current playhead position. Converts all objects into one clip if needed.
  464.      */
  465.     createTween() {
  466.         // Don't make a tween if one already exits
  467.         var playheadPosition = this.getRelativePlayheadPosition();
  468.         if (this.getTweenAtPosition(playheadPosition)) {
  469.             return;
  470.         }
  472.         // If more than one object exists on the frame, or if there is only one path, create a clip from those objects
  473.         var clips = this.clips;
  474.         var paths = this.paths;
  475.         if ((clips.length === 0 && paths.length === 1) || (clips.length + paths.length) > 1) {
  476.             var allDrawables = paths.concat(clips);
  477.             var center = this.project.selection.view._getObjectsBounds(allDrawables).center;
  478.             var clip = new Wick.Clip({
  479.                 transformation: new Wick.Transformation({
  480.                     x: center.x,
  481.                     y: center.y,
  482.                 }),
  483.             });
  484.             this.addClip(clip);
  485.             clip.addObjects(allDrawables);
  486.         }
  488.         // Create the tween (if there's not already a tween at the current playhead position)
  489.         var clip = this.clips[0];
  490.         this.addTween(new Wick.Tween({
  491.             playheadPosition: playheadPosition,
  492.             transformation: clip ? clip.transformation.copy() : new Wick.Transformation(),
  493.         }));
  494.     }
  496.     /**
  497.      * Remove a tween from the frame.
  498.      * @param {Wick.Tween} tween - the tween to remove.
  499.      */
  500.     removeTween(tween) {
  501.         this.removeChild(tween);
  502.     }
  504.     /**
  505.      * Remove all tweens from this frame.
  506.      */
  507.     removeAllTweens(tween) {
  508.         this.tweens.forEach(tween => {
  509.             tween.remove();
  510.         });
  511.     }
  513.     /**
  514.      * Get the tween at the given playhead position. Returns null if there is no tween.
  515.      * @param {number} playheadPosition - the playhead position to look for tweens at.
  516.      * @returns {Wick.Tween || null} the tween at the given playhead position.
  517.      */
  518.     getTweenAtPosition(playheadPosition) {
  519.         return this.tweens.find(tween => {
  520.             return tween.playheadPosition === playheadPosition;
  521.         }) || null;
  522.     }
  524.     /**
  525.      * Returns the tween at the current playhead position, if one exists on the frame. Null otherwise.
  526.      * @returns {Wick.Tween || null}
  527.      */
  528.     getTweenAtCurrentPlayheadPosition() {
  529.         let playheadPosition = this.getRelativePlayheadPosition();
  530.         return this.getTweenAtPosition(playheadPosition);
  531.     }
  533.     /**
  534.      * The tween being used to transform the objects on the frame.
  535.      * @returns {Wick.Tween || null} tween - the active tween. Null if there is no active tween.
  536.      */
  537.     getActiveTween() {
  538.         if (!this.parentTimeline) return null;
  540.         var playheadPosition = this.getRelativePlayheadPosition();
  542.         var tween = this.getTweenAtPosition(playheadPosition);
  543.         if (tween) {
  544.             return tween;
  545.         }
  547.         var seekBackwardsTween = this.seekTweenBehind(playheadPosition);
  548.         var seekForwardsTween = this.seekTweenInFront(playheadPosition);
  550.         if (seekBackwardsTween && seekForwardsTween) {
  551.            return Wick.Tween.interpolate(seekBackwardsTween, seekForwardsTween, playheadPosition);
  552.         } else if (seekForwardsTween) {
  553.             return seekForwardsTween;
  554.         } else if (seekBackwardsTween) {
  555.             return seekBackwardsTween;
  556.         } else {
  557.             return null;
  558.         }
  559.     }
  561.     /**
  562.      * Applies the transformation of current tween to the objects on the frame.
  563.      */
  564.     applyTweenTransforms() {
  565.         var tween = this.getActiveTween();
  566.         if (tween) {
  567.             this.clips.forEach(clip => {
  568.                 tween.applyTransformsToClip(clip);
  569.             });
  570.         }
  571.     }
  573.     /**
  574.      * Applies single frame positions to timelines if necessary.
  575.      */
  576.     applyClipSingleFramePositions () {
  577.         this.clips.forEach(clip => {
  578.             clip.applySingleFramePosition();
  579.         });
  580.     }
  582.     /**
  583.      * Update all clip timelines for their animation type.
  584.      */
  585.     updateClipTimelinesForAnimationType () {
  586.         this.clips.forEach(clip => {
  587.             clip.updateTimelineForAnimationType();
  588.         })
  589.     }
  591.     /**
  592.      * The asset of the sound attached to this frame, if one exists
  593.      * @returns {Wick.Asset[]}
  594.      */
  595.     getLinkedAssets() {
  596.         var linkedAssets = [];
  598.         if (this.sound) {
  599.             linkedAssets.push(this.sound);
  600.         }
  602.         return linkedAssets;
  603.     }
  605.     /**
  606.      * Cut this frame in half using the parent timeline's playhead position.
  607.      */
  608.     cut() {
  609.         // Can't cut a frame that doesn't beolong to a timeline + layer
  610.         if (!this.parentTimeline) return;
  612.         // Can't cut a frame with length 1
  613.         if (this.length === 1) return;
  615.         // Can't cut a frame that isn't under the playhead
  616.         var playheadPosition = this.parentTimeline.playheadPosition;
  617.         if (!this.inPosition(playheadPosition)) return;
  619.         // Create right half (leftover) frame
  620.         var rightHalf = this.copy();
  621.         rightHalf.identifier = null;
  622.         rightHalf.removeSound();
  623.         rightHalf.removeAllTweens();
  624.         rightHalf.start = playheadPosition = playheadPosition;
  626.         // Cut this frame shorter
  627.         this.end = playheadPosition - 1;
  629.         // Add right frame
  630.         this.parentLayer.addFrame(rightHalf);
  631.     }
  633.     /**
  634.      * Extend this frame by one and push all frames right of this frame to the right.
  635.      */
  636.     extendAndPushOtherFrames() {
  637.         this.parentLayer.getFramesInRange(this.end + 1, Infinity).forEach(frame => {
  638.             frame.start += 1;
  639.             frame.end += 1;
  640.         });
  641.         this.end += 1;
  642.     }
  644.     /**
  645.      * Shrink this frame by one and pull all frames left of this frame to the left.
  646.      */
  647.     shrinkAndPullOtherFrames() {
  648.         if (this.length === 1) return;
  650.         this.parentLayer.getFramesInRange(this.end + 1, Infinity).forEach(frame => {
  651.             frame.start -= 1;
  652.             frame.end -= 1;
  653.         });
  654.         this.end -= 1;
  655.     }
  657.     /**
  658.      * Import SVG data into this frame. SVGs containing mulitple paths will be split into multiple Wick Paths.
  659.      * @param {string} svg - the SVG data to parse and import.
  660.      */
  661.     /*
  662.     importSVG (svg) {
  663.         this.view.importSVG(svg);
  664.     }
  665.     */
  666.     /**
  667.      * Get the position of this frame in relation to the parent timeline's playhead position.
  668.      * @returns {number}
  669.      */
  670.     getRelativePlayheadPosition() {
  671.         return this.parentTimeline.playheadPosition - this.start + 1;
  672.     }
  674.     /**
  675.      * Find the first tween on this frame that exists behind the given playhead position.
  676.      * @returns {Wick.Tween}
  677.      */
  678.     seekTweenBehind(playheadPosition) {
  679.         var seekBackwardsPosition = playheadPosition;
  680.         var seekBackwardsTween = null;
  681.         while (seekBackwardsPosition > 0) {
  682.             seekBackwardsTween = this.getTweenAtPosition(seekBackwardsPosition);
  683.             seekBackwardsPosition--;
  684.             if (seekBackwardsTween) break;
  685.         }
  686.         return seekBackwardsTween;
  687.     }
  689.     /**
  690.      * Find the first tween on this frame that exists past the given playhead position.
  691.      * @returns {Wick.Tween}
  692.      */
  693.     seekTweenInFront(playheadPosition) {
  694.         var seekForwardsPosition = playheadPosition;
  695.         var seekForwardsTween = null;
  696.         while (seekForwardsPosition <= this.end) {
  697.             seekForwardsTween = this.getTweenAtPosition(seekForwardsPosition);
  698.             seekForwardsPosition++;
  699.             if (seekForwardsTween) break;
  700.         }
  701.         return seekForwardsTween;
  702.     }
  704.     _onInactive() {
  705.         super._onInactive();
  706.         this._tickChildren();
  707.     }
  709.     _onActivated() {
  710.         super._onActivated();
  711.         this.playSound();
  712.         this._tickChildren();
  713.     }
  715.     _onActive() {
  716.         super._onActive();
  717.         this._tickChildren();
  718.     }
  720.     _onDeactivated() {
  721.         super._onDeactivated();
  722.         this.stopSound();
  723.         this._tickChildren();
  724.     }
  726.     _tickChildren() {
  727.         this.clips.forEach(clip => {
  728.             clip.tick();
  729.         });
  730.     }
  732.     _attachChildClipReferences() {
  733.         this.clips.forEach(clip => {
  734.             if (clip.identifier) {
  735.                 this[clip.identifier] = clip;
  736.                 clip._attachChildClipReferences();
  737.             }
  738.         });
  739.     }
  740. }