Record the stage, not the window, when the window is bigger

Windows lets students maximize a stage's window although the library asks
for a fixed size. The stage is letterboxed into the bigger window, but the
recorders still took the whole window: a GIF started before maximizing kept
only the window's top-left corner afterwards (the encoder crops every frame
to the first one's size), and a maximized window was encoded at full size on
the render thread, which slowed a program down to about one frame per
second under software rendering.

GifRecorder, FrameRecorder and FFmpegRecorder now save the stage at its own
size, cut out of the window the way the stage designer's capture already
did. That cut-out moves from Preview to Applet.getStageImage(), so all of
them share it. With the window at the stage's size the pictures are the same
as before.

Author: mikebarkmin

.changeset/record-the-stage.md

@@ -0,0 +1,10 @@
+---
+type: patch
+---
+
+Recordings show the stage when the window is bigger than it, for example after
+maximizing it: `GifRecorder`, `FrameRecorder` and `FFmpegRecorder` save the stage
+at its own size, without the bars around it. A GIF that was started before the
+window was maximized no longer shows only the window's top-left corner after it,
+and recording a maximized window slows the program down far less, because the
+frames are encoded at the stage's size.

src/main/java/org/openpatch/scratch/extensions/recorder/FFmpegRecorder.java

@@ -49,7 +49,9 @@ public FFmpegRecorder(String path) {
   /** Saves the current frame using the specified pattern. */
   @Override
   public void saveFrame() {
-    Applet.getInstance().saveFrame(pattern);
+    // the stage at its own size: every frame of a video has to be the same size
+    Applet applet = Applet.getInstance();
+    applet.getStageImage().save(applet.savePath(applet.insertFrame(pattern)));
   }
 
   /**

src/main/java/org/openpatch/scratch/extensions/recorder/FrameRecorder.java

@@ -31,13 +31,16 @@ public FrameRecorder(String outputFolder) {
   }
 
   /**
-   * Saves the current frame of the applet to the specified output folder. The frame is saved as a
+   * Saves the current frame of the stage to the specified output folder. The frame is saved as a
    * PNG file with a filename pattern "#######.png". The exact filename will be generated based on
-   * the current frame number.
+   * the current frame number. The picture is the stage at its own size, also when the window is
+   * bigger.
    */
   @Override
   public void saveFrame() {
-    Applet.getInstance().saveFrame(Paths.get(this.outputFolder, "#######.png").toString());
+    Applet applet = Applet.getInstance();
+    String file = applet.insertFrame(Paths.get(this.outputFolder, "#######.png").toString());
+    applet.getStageImage().save(applet.savePath(file));
   }
 
   /**
@@ -46,6 +49,7 @@ public void saveFrame() {
    * @param filename the name of the file to save the snapshot to
    */
   public void snapshot(String filename) {
-    Applet.getInstance().save(Paths.get(this.outputFolder, filename).toString());
+    Applet applet = Applet.getInstance();
+    applet.getStageImage().save(applet.savePath(Paths.get(this.outputFolder, filename).toString()));
   }
 }

src/main/java/org/openpatch/scratch/extensions/recorder/GifRecorder.java

@@ -3,6 +3,7 @@
 import org.openpatch.scratch.Color;
 import org.openpatch.scratch.internal.AnimatedGifEncoder;
 import org.openpatch.scratch.internal.Applet;
+import processing.core.PImage;
 
 /**
  * The GifRecorder class is responsible for recording and saving frames as GIF images. It extends
@@ -44,23 +45,25 @@ public GifRecorder(String filePath) {
   }
 
   /**
-   * Saves the current frame of the applet as a GIF image.
+   * Saves the current frame of the stage as a GIF image.
    *
-   * <p>This method captures the current frame from the applet, sets the frame rate, and adds the
-   * frame to the GIF encoder. If the applet's pixels are null, the frame is not saved.
+   * <p>This method captures the stage at its own size, sets the frame rate, and adds the frame to
+   * the GIF encoder. A window that is bigger than the stage (maximized, say) records the stage
+   * without the bars around it, and the frames keep their size when the window changes during the
+   * recording.
    *
    * <p>Note: This method catches and ignores any NullPointerException that may occur.
    */
   @Override
   public void saveFrame() {
     try {
       Applet applet = Applet.getInstance();
-      applet.loadPixels();
-      int[] pixels = applet.pixels;
-      if (pixels != null) {
+      PImage stage = applet.getStageImage();
+      stage.loadPixels();
+      if (stage.pixels != null) {
         this.gifEncoder.setFrameRate(applet.frameRate);
         this.gifEncoder.setRepeat(0);
-        this.gifEncoder.addFrame(pixels, applet.pixelWidth, applet.pixelHeight);
+        this.gifEncoder.addFrame(stage.pixels, stage.pixelWidth, stage.pixelHeight);
       }
     } catch (NullPointerException e) {
 

src/main/java/org/openpatch/scratch/internal/Applet.java

@@ -206,6 +206,27 @@ public int getRenderHeight() {
     return this.RENDER_HEIGHT;
   }
 
+  /**
+   * The stage as it is in the window, without the bars around it and at the
+   * stage's own size. The window can be bigger than the stage (maximized, a
+   * high-resolution screen, a desktop that sizes windows itself), and then the
+   * stage is letterboxed into it. Call it on the render thread, after drawing.
+   *
+   * @return the stage's picture, {@link #getRenderWidth()} by
+   *         {@link #getRenderHeight()}
+   */
+  public PImage getStageImage() {
+    float ratio = Math.min((float) this.width / this.RENDER_WIDTH,
+        (float) this.height / this.RENDER_HEIGHT);
+    int width = Math.round(this.RENDER_WIDTH * ratio);
+    int height = Math.round(this.RENDER_HEIGHT * ratio);
+    var area = this.get((this.width - width) / 2, (this.height - height) / 2, width, height);
+    if (width != this.RENDER_WIDTH || height != this.RENDER_HEIGHT) {
+      area.resize(this.RENDER_WIDTH, this.RENDER_HEIGHT);
+    }
+    return area;
+  }
+
   /**
    * Returns the height of the current window.
    *

src/main/java/org/openpatch/scratch/internal/Preview.java

@@ -179,7 +179,7 @@ private static void snapshot(Applet applet, Stage stage, StageHooks hooks, PGrap
       hooks.draw(graphics);
       Files.createDirectories(folder);
       // the picture first: an editor waiting for stage.json then finds both
-      stageArea(applet).save(folder.resolve("frame.png").toAbsolutePath().toString());
+      applet.getStageImage().save(folder.resolve("frame.png").toAbsolutePath().toString());
       write(folder, describe(stage, sprites, visible, fields, applet, omit));
     } finally {
       for (int i = 0; i < sprites.size(); i++) {
@@ -188,26 +188,6 @@ private static void snapshot(Applet applet, Stage stage, StageHooks hooks, PGrap
     }
   }
 
-  /**
-   * The stage as it is in the window, without the bars around it and at the
-   * stage's own size: the window may be scaled (a high-resolution screen, a
-   * desktop that sizes windows itself), the stage is letterboxed into it.
-   */
-  private static processing.core.PImage stageArea(Applet applet) {
-    int targetWidth = applet.getRenderWidth();
-    int targetHeight = applet.getRenderHeight();
-    float ratio = Math.min((float) applet.getWidth() / targetWidth,
-        (float) applet.getHeight() / targetHeight);
-    int width = Math.round(targetWidth * ratio);
-    int height = Math.round(targetHeight * ratio);
-    var area = applet.get((applet.getWidth() - width) / 2, (applet.getHeight() - height) / 2,
-        width, height);
-    if (width != targetWidth || height != targetHeight) {
-      area.resize(targetWidth, targetHeight);
-    }
-    return area;
-  }
-
   /** The requested stage, made the way {@code new MyStage()} would make it. */
   private static Stage make(ClassLoader loader, String packageName) {
     List<String> names = new ArrayList<>();