scrawl-canvas

<!DOCTYPE html> <html> <head> <title>Picture factory</title> <meta http-equiv="content-type" content="text/html; charset=UTF-8"> <meta name="viewport" content="width=device-width, target-densitydpi=160dpi, initial-scale=1.0; maximum-scale=1.0; user-scalable=0;"> <link rel="stylesheet" media="all" href="../../docco.css" /> </head> <body> <div id="container"> <div id="background"></div> <ul id="jump_to"> <li> <a class="large" href="javascript:void(0);">Jump To …</a> <a class="small" href="javascript:void(0);">+</a> <div id="jump_wrapper"> <div id="jump_page_wrapper"> <div id="jump_page"> <a class="source" href="../core/animationloop.html"> ./source/core/animationloop.js </a> <a class="source" href="../core/document.html"> ./source/core/document.js </a> <a class="source" href="../core/events.html"> ./source/core/events.js </a> <a class="source" href="../core/init.html"> ./source/core/init.js </a> <a class="source" href="../core/library.html"> ./source/core/library.js </a> <a class="source" href="../core/random-seed.html"> ./source/core/random-seed.js </a> <a class="source" href="../core/snippets.html"> ./source/core/snippets.js </a> <a class="source" href="../core/userInteraction.html"> ./source/core/userInteraction.js </a> <a class="source" href="../core/utilities.html"> ./source/core/utilities.js </a> <a class="source" href="action.html"> ./source/factory/action.js </a> <a class="source" href="anchor.html"> ./source/factory/anchor.js </a> <a class="source" href="animation.html"> ./source/factory/animation.js </a> <a class="source" href="bezier.html"> ./source/factory/bezier.js </a> <a class="source" href="block.html"> ./source/factory/block.js </a> <a class="source" href="canvas.html"> ./source/factory/canvas.js </a> <a class="source" href="cell.html"> ./source/factory/cell.js </a> <a class="source" href="cog.html"> ./source/factory/cog.js </a> <a class="source" href="color.html"> ./source/factory/color.js </a> <a class="source" href="conicGradient.html"> ./source/factory/conicGradient.js </a> <a class="source" href="coordinate.html"> ./source/factory/coordinate.js </a> <a class="source" href="crescent.html"> ./source/factory/crescent.js </a> <a class="source" href="element.html"> ./source/factory/element.js </a> <a class="source" href="emitter.html"> ./source/factory/emitter.js </a> <a class="source" href="filter.html"> ./source/factory/filter.js </a> <a class="source" href="filterEngine-bluenoiseData.html"> ./source/factory/filterEngine-bluenoiseData.js </a> <a class="source" href="filterEngine.html"> ./source/factory/filterEngine.js </a> <a class="source" href="fontAttributes.html"> ./source/factory/fontAttributes.js </a> <a class="source" href="gradient.html"> ./source/factory/gradient.js </a> <a class="source" href="grid.html"> ./source/factory/grid.js </a> <a class="source" href="group.html"> ./source/factory/group.js </a> <a class="source" href="imageAsset.html"> ./source/factory/imageAsset.js </a> <a class="source" href="line.html"> ./source/factory/line.js </a> <a class="source" href="lineSpiral.html"> ./source/factory/lineSpiral.js </a> <a class="source" href="loom.html"> ./source/factory/loom.js </a> <a class="source" href="mesh.html"> ./source/factory/mesh.js </a> <a class="source" href="net.html"> ./source/factory/net.js </a> <a class="source" href="noiseAsset.html"> ./source/factory/noiseAsset.js </a> <a class="source" href="oval.html"> ./source/factory/oval.js </a> <a class="source" href="palette.html"> ./source/factory/palette.js </a> <a class="source" href="particle.html"> ./source/factory/particle.js </a> <a class="source" href="particleForce.html"> ./source/factory/particleForce.js </a> <a class="source" href="particleHistory.html"> ./source/factory/particleHistory.js </a> <a class="source" href="particleSpring.html"> ./source/factory/particleSpring.js </a> <a class="source" href="particleWorld.html"> ./source/factory/particleWorld.js </a> <a class="source" href="pattern.html"> ./source/factory/pattern.js </a> <a class="source" href="phrase.html"> ./source/factory/phrase.js </a> <a class="source" href="picture.html"> ./source/factory/picture.js </a> <a class="source" href="polygon.html"> ./source/factory/polygon.js </a> <a class="source" href="polyline.html"> ./source/factory/polyline.js </a> <a class="source" href="quadratic.html"> ./source/factory/quadratic.js </a> <a class="source" href="quaternion.html"> ./source/factory/quaternion.js </a> <a class="source" href="radialGradient.html"> ./source/factory/radialGradient.js </a> <a class="source" href="rawAsset.html"> ./source/factory/rawAsset.js </a> <a class="source" href="rdAsset.html"> ./source/factory/rdAsset.js </a> <a class="source" href="rectangle.html"> ./source/factory/rectangle.js </a> <a class="source" href="renderAnimation.html"> ./source/factory/renderAnimation.js </a> <a class="source" href="shape.html"> ./source/factory/shape.js </a> <a class="source" href="spiral.html"> ./source/factory/spiral.js </a> <a class="source" href="spriteAsset.html"> ./source/factory/spriteAsset.js </a> <a class="source" href="stack.html"> ./source/factory/stack.js </a> <a class="source" href="star.html"> ./source/factory/star.js </a> <a class="source" href="state.html"> ./source/factory/state.js </a> <a class="source" href="tetragon.html"> ./source/factory/tetragon.js </a> <a class="source" href="ticker.html"> ./source/factory/ticker.js </a> <a class="source" href="tracer.html"> ./source/factory/tracer.js </a> <a class="source" href="tween.html"> ./source/factory/tween.js </a> <a class="source" href="unstackedElement.html"> ./source/factory/unstackedElement.js </a> <a class="source" href="vector.html"> ./source/factory/vector.js </a> <a class="source" href="videoAsset.html"> ./source/factory/videoAsset.js </a> <a class="source" href="wheel.html"> ./source/factory/wheel.js </a> <a class="source" href="../mixin/anchor.html"> ./source/mixin/anchor.js </a> <a class="source" href="../mixin/asset.html"> ./source/mixin/asset.js </a> <a class="source" href="../mixin/assetAdvancedFunctionality.html"> ./source/mixin/assetAdvancedFunctionality.js </a> <a class="source" href="../mixin/assetConsumer.html"> ./source/mixin/assetConsumer.js </a> <a class="source" href="../mixin/base.html"> ./source/mixin/base.js </a> <a class="source" href="../mixin/cascade.html"> ./source/mixin/cascade.js </a> <a class="source" href="../mixin/delta.html"> ./source/mixin/delta.js </a> <a class="source" href="../mixin/displayShape.html"> ./source/mixin/displayShape.js </a> <a class="source" href="../mixin/dom.html"> ./source/mixin/dom.js </a> <a class="source" href="../mixin/entity.html"> ./source/mixin/entity.js </a> <a class="source" href="../mixin/filter.html"> ./source/mixin/filter.js </a> <a class="source" href="../mixin/mimic.html"> ./source/mixin/mimic.js </a> <a class="source" href="../mixin/path.html"> ./source/mixin/path.js </a> <a class="source" href="../mixin/pattern.html"> ./source/mixin/pattern.js </a> <a class="source" href="../mixin/pivot.html"> ./source/mixin/pivot.js </a> <a class="source" href="../mixin/position.html"> ./source/mixin/position.js </a> <a class="source" href="../mixin/shapeBasic.html"> ./source/mixin/shapeBasic.js </a> <a class="source" href="../mixin/shapeCurve.html"> ./source/mixin/shapeCurve.js </a> <a class="source" href="../mixin/shapePathCalculation.html"> ./source/mixin/shapePathCalculation.js </a> <a class="source" href="../mixin/styles.html"> ./source/mixin/styles.js </a> <a class="source" href="../mixin/tween.html"> ./source/mixin/tween.js </a> </div> </div> </li> </ul> <ul class="sections"> <li id="section-1"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-1">§</a> </div> <h1 id="picture-factory">Picture factory</h1> Picture entitys are image, video or canvas-based rectangles rendered onto a DOM <canvas> element using the Canvas API’s <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D">CanvasRenderingContext2D interface</a> - in particular the <a href="https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/drawImage">drawImage</a> method. <ul> <li>Positioning and dimensions functionality for the Picture is supplied by the position mixin, while rendering functionality comes from the entity mixin. </li> <li>Pictures can use <a href="./imageAsset.html">ImageAsset</a>, <a href="./spriteAsset.html">SpriteAsset</a>, <a href="./videoAsset.html">VideoAsset</a>, or <a href="./cell.html">Cells</a> for the source of the image they display.</li> <li>Additionally, we can restrict the display to a portion of the source by defining and updating <code>copy</code> attributes.</li> </ul> We define the source copy area in a similar way to how we position and dimension the Picture entity on its Cell host, using two additional <a href="./coordinate.html">Coordinate</a> Arrays to hold our data. <ul> <li>for both positioning and dimensions, we can define the coordinate in absolute, or relative, terms</li> <li>absolute positioning and dimensions - where we give the artefact a Number coordinate measured in pixels. </li> <li>relative positioning and dimensions - where we use String percentage coordinates, with <code>['0%', '0%']</code> representing the top left corner of the source, and <code>['100%', '100%']</code> its bottom right corner.</li> </ul> Source dimensions are the natural width and height of the image or video <ul> <li>The code will check automatically to make sure that any combination of start and dimensions values does not lead to an attempt to copy image data that does not exist (which otherwise throws an error).</li> <li>Where <code>copyStartX + width</code> values are greater than the source width, the start value will be reduced until the copy frame fits within the bounds of the source dimensions.</li> <li>Where <code>copyStartY + height</code> values are greater than the source height, the start value will be reduced until the copy frame fits within the bounds of the source dimensions.</li> </ul> Loading sources is an asynchronous action. If we attempt to stamp a Picture entity whose source has not yet been fetched or loaded, the Picture will skip its stamp functionality for that Display cycle. <ul> <li>Stamping a Picture entity directly, immediately after defining it, will (almost certainly) lead to the image not displaying on the canvas.</li> <li>For this reason, its best to use Picture entitys inside a Display cycle animation. As soon as the source finishes loading, the Picture entity will display as expected.</li> </ul> Also: <ul> <li>Pictures can use CSS color Strings for their strokeStyle values, alongside Gradient, RadialGradient, Color and Pattern objects. </li> <li>They will also accept Filter objects.</li> <li>They can use Anchor objects for user navigation. </li> <li>They can be rendered to the canvas by including them in a Cell object’s Group. </li> <li>They can be animated directly, or using delta animation, or act as the target for Tween animations.</li> <li>Pictures (but not their source assets) can be cloned, and killed.</li> </ul> </div> </li> <li id="section-2"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-2">§</a> </div> <h4 id="demos">Demos:</h4> <ul> <li><a href="../../demo/canvas-008.html">Canvas-008</a> - Picture entity position; manipulate copy attributes</li> <li><a href="../../demo/canvas-010.html">Canvas-010</a> - Use video sources and media streams for Picture entitys</li> <li><a href="../../demo/canvas-021.html">Canvas-021</a> - Import and use spritesheets</li> <li><a href="../../demo/canvas-023.html">Canvas-023</a> - Grid entity - using picture-based assets (image, video, sprite)</li> <li><a href="../../demo/canvas-024.html">Canvas-024</a> - Loom entity functionality</li> <li><a href="../../demo/canvas-025.html">Canvas-025</a> - Responsive images</li> <li><a href="../../demo/packets-002.html">Packets-002</a> - Scrawl-canvas packets - save and load a range of different entitys</li> </ul> </div> </li> <li id="section-3"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-3">§</a> </div> <h4 id="imports">Imports</h4> </div> <div class="content"><div class='highlight'><pre>import { constructors, asset, artefact } from '../core/library.js'; import { mergeOver, xta, addStrings, pushUnique, removeItem, isa_obj, Ωempty } from '../core/utilities.js'; import { gettableVideoAssetAtributes, settableVideoAssetAtributes } from './videoAsset.js'; import { gettableImageAssetAtributes, settableImageAssetAtributes } from './imageAsset.js'; import { stateKeys } from './state.js'; import { makeCoordinate } from './coordinate.js'; import baseMix from '../mixin/base.js'; import entityMix from '../mixin/entity.js'; import assetConsumerMix from '../mixin/assetConsumer.js';</pre></div></div> </li> <li id="section-4"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-4">§</a> </div> <h4 id="picture-constructor">Picture constructor</h4> </div> <div class="content"><div class='highlight'><pre>const Picture = function (items = Ωempty) { this.copyStart = makeCoordinate(); this.currentCopyStart = makeCoordinate(); this.copyDimensions = makeCoordinate(); this.currentCopyDimensions = makeCoordinate(); this.copyArray = []; this.pasteArray = []; this.entityInit(items); if (!items.copyStart) { if (!items.copyStartX) this.copyStart[0] = 0; if (!items.copyStartY) this.copyStart[1] = 0; } if (!items.copyDimensions) { if (!items.copyWidth) this.copyDimensions[0] = 1; if (!items.copyHeight) this.copyDimensions[1] = 1; } this.imageSubscribers = []; this.dirtyCopyStart = true; this.dirtyCopyDimensions = true; this.dirtyImage = true; return this; };</pre></div></div> </li> <li id="section-5"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-5">§</a> </div> <h4 id="picture-prototype">Picture prototype</h4> </div> <div class="content"><div class='highlight'><pre>let P = Picture.prototype = Object.create(Object.prototype); P.type = 'Picture'; P.lib = 'entity'; P.isArtefact = true; P.isAsset = false;</pre></div></div> </li> <li id="section-6"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-6">§</a> </div> <h4 id="mixins">Mixins</h4> <ul> <li><a href="../mixin/base.html">base</a></li> <li><a href="../mixin/entity.html">entity</a></li> <li><a href="../mixin/assetConsumer.html">assetConsumer</a></li> </ul> </div> <div class="content"><div class='highlight'><pre>P = baseMix(P); P = entityMix(P); P = assetConsumerMix(P);</pre></div></div> </li> <li id="section-7"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-7">§</a> </div> <h4 id="picture-attributes">Picture attributes</h4> <ul> <li>Attributes defined in the <a href="../mixin/base.html">base mixin</a>: name.</li> <li>Attributes defined in the <a href="../mixin/position.html">position mixin</a>: group, visibility, order, calculateOrder, stampOrder, start, startX, startY, handle, handleX, handleY, offset, offsetX, offsetY, dimensions, width, height, pivoted, mimicked, lockTo, lockXTo, lockYTo, scale, roll, noUserInteraction, noPositionDependencies, noCanvasEngineUpdates, noFilters, noPathUpdates, purge, bringToFrontOnDrag.</li> <li>Attributes defined in the <a href="../mixin/delta.html">delta mixin</a>: delta, noDeltaUpdates.</li> <li>Attributes defined in the <a href="../mixin/pivot.html">pivot mixin</a>: pivot, pivotCorner, addPivotHandle, addPivotOffset, addPivotRotation.</li> <li>Attributes defined in the <a href="../mixin/mimic.html">mimic mixin</a>: mimic, useMimicDimensions, useMimicScale, useMimicStart, useMimicHandle, useMimicOffset, useMimicRotation, useMimicFlip, addOwnDimensionsToMimic, addOwnScaleToMimic, addOwnStartToMimic, addOwnHandleToMimic, addOwnOffsetToMimic, addOwnRotationToMimic.</li> <li>Attributes defined in the <a href="../mixin/path.html">path mixin</a>: path, pathPosition, addPathHandle, addPathOffset, addPathRotation, constantPathSpeed.</li> <li>Attributes defined in the <a href="../mixin/entity.html">entity mixin</a>: method, pathObject, winding, flipReverse, flipUpend, scaleOutline, lockFillStyleToEntity, lockStrokeStyleToEntity, onEnter, onLeave, onDown, onUp, fillStyle, strokeStyle, globalAlpha, globalCompositeOperation, lineWidth, lineCap, lineJoin, lineDash, lineDashOffset, miterLimit, shadowOffsetX, shadowOffsetY, shadowBlur, shadowColor, filter.</li> <li>Attributes defined in the <a href="../mixin/anchor.html">anchor mixin</a>: anchor.</li> <li>Attributes defined in the <a href="../mixin/filter.html">filter mixin</a>: filters, isStencil.</li> <li>Attributes defined in the <a href="../mixin/assetConsumer.html">assetConsumer mixin</a>: asset, spriteTrack, imageSource, spriteSource, videoSource, source.</li> </ul> </div> <div class="content"><div class='highlight'><pre>let defaultAttributes = {</pre></div></div> </li> <li id="section-8"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-8">§</a> </div> copyStart - Coordinate array <ul> <li>We can use the pseudo-attributes copyStartX and copyStartY to make working with the Coordinate easier.</li> </ul> </div> <div class="content"><div class='highlight'><pre> copyStart: null,</pre></div></div> </li> <li id="section-9"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-9">§</a> </div> copyDimensions - Coordinate array <ul> <li>We can use the pseudo-attributes copyWidth and copyHeight to make working with the Coordinate easier.</li> </ul> </div> <div class="content"><div class='highlight'><pre> copyDimensions: null,</pre></div></div> </li> <li id="section-10"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-10">§</a> </div> checkHitIgnoreTransparency - Boolean - when set, will check the stashedImage data to return whether a coordinate is hitting the image; otherwise checkHit will use the Picture entity’s dimensions to calculate the hit </div> <div class="content"><div class='highlight'><pre> checkHitIgnoreTransparency: false,</pre></div></div> </li> <li id="section-11"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-11">§</a> </div> Additional attributes and pseudo-attributes are defined in the <a href="../mixin/assetConsumer.html">assetConsumer mixin</a> </div> <div class="content"><div class='highlight'><pre>}; P.defs = mergeOver(P.defs, defaultAttributes);</pre></div></div> </li> <li id="section-12"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-12">§</a> </div> <h4 id="packet-management">Packet management</h4> </div> <div class="content"><div class='highlight'><pre>P.packetCoordinates = pushUnique(P.packetCoordinates, ['copyStart', 'copyDimensions']); P.packetObjects = pushUnique(P.packetObjects, ['asset']);</pre></div></div> </li> <li id="section-13"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-13">§</a> </div> <h4 id="clone-management">Clone management</h4> No additional clone functionality required </div> </li> <li id="section-14"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-14">§</a> </div> <h4 id="kill-management">Kill management</h4> </div> <div class="content"><div class='highlight'><pre>P.factoryKill = function (killAsset = false) { let { asset, removeAssetOnKill } = this; if (isa_obj(asset)) asset.unsubscribe(this);</pre></div></div> </li> <li id="section-15"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-15">§</a> </div> Cascade kill invocation to the asset object, if required </div> <div class="content"><div class='highlight'><pre> if (removeAssetOnKill) { if (removeAssetOnKill.substring) asset.kill(true); else asset.kill(); } };</pre></div></div> </li> <li id="section-16"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-16">§</a> </div> <h4 id="get-set-deltaset">Get, Set, deltaSet</h4> </div> <div class="content"><div class='highlight'><pre>let G = P.getters, S = P.setters, D = P.deltaSetters;</pre></div></div> </li> <li id="section-17"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-17">§</a> </div> copyStart <ul> <li>Including copyStartX, copyStartY</li> </ul> </div> <div class="content"><div class='highlight'><pre>G.copyStart = function () { return [].concat(this.currentCopyStart); }; G.copyStartX = function () { return this.currentCopyStart[0]; }; G.copyStartY = function () { return this.currentCopyStart[1]; }; S.copyStartX = function (coord) { if (coord != null) { this.copyStart[0] = coord; this.dirtyCopyStart = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; } }; S.copyStartY = function (coord) { if (coord != null) { this.copyStart[1] = coord; this.dirtyCopyStart = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; } }; S.copyStart = function (x, y) { this.setCoordinateHelper('copyStart', x, y); this.dirtyCopyStart = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; }; D.copyStartX = function (coord) { let c = this.copyStart; c[0] = addStrings(c[0], coord); this.dirtyCopyStart = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; }; D.copyStartY = function (coord) { let c = this.copyStart; c[1] = addStrings(c[1], coord); this.dirtyCopyStart = true; this.dirtyFilterIdentifier = true; }; D.copyStart = function (x, y) { this.setDeltaCoordinateHelper('copyStart', x, y); this.dirtyCopyStart = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; };</pre></div></div> </li> <li id="section-18"> <div class="annotation"> <div class="sswrap "> <a class="ss" href="#section-18">§</a> </div> copyDimensions <ul> <li>Including copyWidth, copyHeight</li> </ul> </div> <div class="content"><div class='highlight'><pre>G.copyWidth = function () { return this.currentCopyDimensions[0]; }; G.copyHeight = function () { return this.currentCopyDimensions[1]; }; G.copyDimensions = function (w, h) { return [].concat(this.currentCopyDimensions); }; S.copyWidth = function (val) { if (val != null) { this.copyDimensions[0] = val; this.dirtyCopyDimensions = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; } }; S.copyHeight = function (val) { if (val != null) { this.copyDimensions[1] = val; this.dirtyCopyDimensions = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; } }; S.copyDimensions = function (w, h) { this.setCoordinateHelper('copyDimensions', w, h); this.dirtyCopyDimensions = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; }; D.copyWidth = function (val) { let c = this.copyDimensions; c[0] = addStrings(c[0], val); this.dirtyCopyDimensions = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; }; D.copyHeight = function (val) { let c = this.copyDimensions; c[1] = addStrings(c[1], val); this.dirtyCopyDimensions = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; }; D.copyDimensions = function (w, h) { this.setDeltaCoordinateHelper('copyDimensions', w, h); this.dirtyCopyDimensions = true; this.dirtyImageSubscribers = true; this.dirtyFilterIdentifier = true; }; S.checkHitIgnoreTransparency = function (item) { <span class