- Jump To … +
  ./source/core/animation-loop.js ./source/core/display-cycle.js ./source/core/document-root-elements.js ./source/core/document.js ./source/core/events.js ./source/core/init.js ./source/core/library.js ./source/core/random-seed.js ./source/core/shared-vars.js ./source/core/snippets.js ./source/core/system-flags.js ./source/core/user-interaction.js ./source/core/utilities.js ./source/factory/action.js ./source/factory/anchor.js ./source/factory/animation.js ./source/factory/array-pool.js ./source/factory/bezier.js ./source/factory/block.js ./source/factory/canvas.js ./source/factory/cell-fragment.js ./source/factory/cell.js ./source/factory/cog.js ./source/factory/color.js ./source/factory/conic-gradient.js ./source/factory/coordinate.js ./source/factory/crescent.js ./source/factory/drag-zone.js ./source/factory/element.js ./source/factory/emitter.js ./source/factory/filter-engine-bluenoise-data.js ./source/factory/filter-engine.js ./source/factory/filter.js ./source/factory/font-attributes.js ./source/factory/gradient.js ./source/factory/grid.js ./source/factory/group.js ./source/factory/image-asset.js ./source/factory/keyboard-zone.js ./source/factory/line-spiral.js ./source/factory/line.js ./source/factory/loom.js ./source/factory/mesh.js ./source/factory/net.js ./source/factory/noise-asset.js ./source/factory/observe-update.js ./source/factory/oval.js ./source/factory/palette.js ./source/factory/particle-force.js ./source/factory/particle-history.js ./source/factory/particle-spring.js ./source/factory/particle-world.js ./source/factory/particle.js ./source/factory/pattern.js ./source/factory/phrase.js ./source/factory/picture.js ./source/factory/polygon.js ./source/factory/polyline.js ./source/factory/quadratic.js ./source/factory/quaternion.js ./source/factory/radial-gradient.js ./source/factory/raw-asset.js ./source/factory/reaction-diffusion-asset.js ./source/factory/rectangle.js ./source/factory/render-animation.js ./source/factory/shape.js ./source/factory/spiral.js ./source/factory/sprite-asset.js ./source/factory/stack.js ./source/factory/star.js ./source/factory/state.js ./source/factory/tetragon.js ./source/factory/ticker.js ./source/factory/tracer.js ./source/factory/tween.js ./source/factory/unstacked-element.js ./source/factory/vector.js ./source/factory/video-asset.js ./source/factory/wheel.js ./source/mixin/anchor.js ./source/mixin/asset-advanced-functionality.js ./source/mixin/asset-consumer.js ./source/mixin/asset.js ./source/mixin/base.js ./source/mixin/cascade.js ./source/mixin/cell-key-functions.js ./source/mixin/delta.js ./source/mixin/display-shape.js ./source/mixin/dom.js ./source/mixin/entity.js ./source/mixin/filter.js ./source/mixin/mimic.js ./source/mixin/path.js ./source/mixin/pattern.js ./source/mixin/pivot.js ./source/mixin/position.js ./source/mixin/shape-basic.js ./source/mixin/shape-curve.js ./source/mixin/shape-path-calculation.js ./source/mixin/styles.js ./source/mixin/tween.js

- §

  # ParticleHistory factory

  The Scrawl-canvas particle physics engine is a simple system designed to allow developers a way to add particle-based effects to their canvas animation scenes. The physics engine is built on top of the following components:

  - Particle objects, which represent a 3-dimensional coordinate - based on a Scrawl-canvas Vector object - and include a history of recent positions which we can use to determine how to display that particle on screen.
  - History arrays which can be pooled (reused) to cut down on Array creation and distruction during the animation.
  - Force objects which define the general and occasional forces to be applied to each particle in the system as the animation progresses - a gravity force object is pre-defined by Scrawl-canvas.
  - Spring objects used to define a constraint (connection) between two particles in a system.
  - World objects where we can store attributes and values used by various objects; these attributes can be set up so that they will be inherited by clones of the World object. We can also influence the speed of the physics animation here.

  We do not have to handle particle generation and manipulation ourselves. Instead, Scrawl-canvas gives us three dedicated entitys which we use to add particle animation effects to the canvas scene. These entitys are:

  - Tracer - this entity generates a single non-recycled (in other words: long lasting) particle with a history, which we can use to display trace effects in the animation.
  - Emitter - an entity which generates a stream of short-lived, recycled particles, each with its own history. Emitters are highly versatile entitys which can generate a wide range of effects.
  - Net - a (generally) larger entity which uses both forces and springs to manage the animation of its non-recycled particles. Note that other artefacts can use Net particles as a reference for their own positioning.

  ParticleHistory objects are Arrays in which Scrawl-canvas records history data for a given particle at a specified time. The array holds data in the following format:

      [
          Number:particle-life-time-remaining,
          Number:particle-z-position,
          Number:particle-x-position,
          Number:particle-y-position
      ]

  Because of the number of ParticleHistory arrays that can be generated and discarded in even a simple particle physics animation, Scrawl-canvas includes functionality to pool and reuse ParticleHistory arrays. The exported functions `requestParticleHistoryObject` and `releaseParticleHistoryObject` give us access to the pool mechanism.

- §

  #### Demos:

  - particles-001 - Emitter entity, and Particle World, basic functionality
  - particles-002 - Emitter using artefacts
  - particles-005 - Emit particles from inside an artefact’s area
  - particles-011 - Tracer entity: basic functionality
  - particles-012 - Use Net entity particles as reference coordinates for other artefacts
- §

  #### Imports

      import { constructors } from '../core/library.js';

      import { _create, _seal, _setPrototypeOf, T_PARTICLE_HISTORY } from '../core/shared-vars.js';

- §

  #### ParticleHistory constructor

      const ParticleHistory = function () {

          const h = Array(4).fill(0);

          _setPrototypeOf(h, ParticleHistory.prototype);

          return _seal(h);
      };

- §

  #### ParticleHistory prototype

      const P = ParticleHistory.prototype = _create(Array.prototype);
      P.constructor = ParticleHistory;
      P.type = T_PARTICLE_HISTORY;

- §

  #### Mixins

  ParticleHistory Arrays do not use mixins - they are regular Javascript Arrays. As such, they do not possess packet, clone or kill functionality.

- §

  #### ParticleHistory attributes

  There are no attributes. The constructor returns an Array containing two members, whose prototype object includes functions for manipulating those members in various ways.

- §

  #### Get, Set, deltaSet

  There are no getter or setter functions.

- §

  #### Prototype functions

  There are no additional prototype functions.

- §

  #### ParticleHistory pool

  An attempt to reuse history arrays rather than constantly creating and deleting them

      const particleHistoryPool = [];

- §

  `exported function` - retrieve a ParticleHistory from the history pool

      export const requestParticleHistory = function () {

          if (!particleHistoryPool.length) particleHistoryPool.push(new ParticleHistory());

          return particleHistoryPool.shift();
      };

- §

  `exported function` - return a ParticleHistory array to the history pool. Failing to return arrays to the pool may lead to more inefficient code and possible memory leaks.

      export const releaseParticleHistory = function (h) {

          if (h && h.type == T_PARTICLE_HISTORY) {

              h.fill(0);
              particleHistoryPool.push(h);

- §

  Do not keep excessive numbers of under-utilised arrays in the pool

              if (particleHistoryPool.length > 100) particleHistoryPool.length = 0;
          }
      };

- §

  #### Factory

      export const makeParticleHistory = function (items) {

          if (!items) return false;
          return new ParticleHistory(items);
      };

      constructors.ParticleHistory = ParticleHistory;