documented new canvas architecture for sprites

HISTORY.md

@@ -13,6 +13,7 @@
 
 ### 2019-10-30
 * threads: optimized HOF primitives to only assert input types once
+* objects: documented new canvas architecture for sprites
 
 ### 2019-10-29
 * threads: added support for counting down using the "numbers" reporter

snap.html

@@ -7,9 +7,9 @@
         <script type="text/javascript" src="src/morphic.js?version=2019-10-29"></script>
         <script type="text/javascript" src="src/widgets.js?version=2019-10-16"></script>
         <script type="text/javascript" src="src/blocks.js?version=2019-10-28"></script>
-        <script type="text/javascript" src="src/threads.js?version=2019-10-29"></script>
-        <script type="text/javascript" src="src/objects.js?version=2019-10-29"></script>
-        <script type="text/javascript" src="src/gui.js?version=2019-10-30"></script>
+        <script type="text/javascript" src="src/threads.js?version=2019-10-30"></script>
+        <script type="text/javascript" src="src/objects.js?version=2019-10-30"></script>
+        <script type="text/javascript" src="src/gui.js?version=2019-10-28"></script>
         <script type="text/javascript" src="src/paint.js?version=2019-06-27"></script>
         <script type="text/javascript" src="src/lists.js?version=2019-10-23"></script>
         <script type="text/javascript" src="src/byob.js?version=2019-07-24"></script>

src/objects.js

@@ -84,7 +84,7 @@ BlockEditorMorph, BlockDialogMorph, PrototypeHatBlockMorph,  BooleanSlotMorph,
 localize, TableMorph, TableFrameMorph, normalizeCanvas, VectorPaintEditorMorph,
 HandleMorph, AlignmentMorph, Process, XML_Element, WorldMap*/
 
-modules.objects = '2019-October-29';
+modules.objects = '2019-October-30';
 
 var SpriteMorph;
 var StageMorph;
@@ -1890,6 +1890,18 @@ SpriteMorph.prototype.drawNew = function () {
         // create a new, adequately dimensioned canvas
         // and draw the costume on it
         if (this.rotationStyle === 1) { // rotate freely in all directions
+            // create a canvas that is big enough, so the sprite's current
+            // costume can be fully rotated inside, so we can recycle
+            // the canvas for re-rendering until the sprite's or the stage's
+            // scale changes.
+            // note that the canvas will be too big for most situations, but
+            // the sprite's bounds indicate the actually visible area.
+            // recycling canvas elements instead of creating new ones whenever
+            // we render a sprite boosts performance for recent browser
+            // architectures that move canvas elements to the GPU for
+            // rendering (which is a pain in the ass and an altogether
+            // bad idea for any serious GUI but looks oh-so-nice for
+            // some flashy graphic effects in the Apple store).
             imageSide = Math.sqrt(
                 Math.pow(pic.width(), 2) + Math.pow(pic.height(), 2)
             ) * this.scale * stageScale;