如何捕获屏幕截图

目的。 获取一个包含当前屏幕内容（OpenGL 后台缓冲区）的 Image，无需重绘任何内容，并可选地保存它。适用于诊断、可视化测试和分享。

使用的 API

static Image Main.getScreenShot(boolean... opaque) — 捕获当前帧。opaque=true 会移除 alpha 通道（使一切不透明）。这是最常用的静态便捷方法。内部通过 runOnPaintThreadAndWait 在 paint thread 上调用实例版本。
Image Main.getScreenShot(boolean opaque)（实例）— 相同的捕获；把读取调度到 paint thread 并阻塞直到完成。
Image Main.getNextScreenShot(boolean opaque)（实例）— 强制重绘并捕获下一帧。当你刚刚更改了 UI 并希望确保该更改出现在截图中时使用；如果在 paint thread 之外调用，它会循环重绘/更新直到获取到该帧。
String Image.toPng(String... prefix) / String Image.toJpg(int... quality) — 用于保存结果（见 salvar-imagem.md）。

完整示例（复制、粘贴并运行）

package com.exemplo;

import dev.crossfly.*;                        // Main
import dev.crossfly.ui.*;                     // Window, Button
import dev.crossfly.ui.layout.*;             // VerticalLayout, LAY_AUTO
import dev.crossfly.ui.image.*;              // Image
import dev.crossfly.util.*;                  // Debug

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：gradlew :lwjgl3:run */
public class MainWindow extends Window
{
   @Override
   public void onShow() throws Exception
   {
      super.onShow();
      setLayout(new VerticalLayout());

      Button b = new Button("Capturar tela");
      b.onAction(origin ->
      {
         // 捕获当前帧，不透明（无 alpha），并保存为 PNG：
         Image shot = Main.getScreenShot(true);   // true = 移除 alpha
         String path = shot.toPng("screen_");     // 例如：.../screen_20260706153000.png
         Debug.log("Screenshot salvo em: " + path);

         // 如果你刚改了 UI，想要下一帧渲染后的画面：
         Image next = Main.instance.getNextScreenShot(false);  // 保留 alpha
      });
      add(LAY_AUTO, b);
   }
}

下面的片段仅展示核心部分。要运行它，请把它放入上面的 MainWindow 骨架中。

最小片段

// 已在源码核实：Main.java getScreenShot（533、667）和 getNextScreenShot（541）
import dev.crossfly.Main;
import dev.crossfly.ui.image.Image;

// 捕获当前帧，不透明（无 alpha），并保存为 PNG：
Image shot = Main.getScreenShot(true);   // true = 移除 alpha
String path = shot.toPng("screen_");     // 例如：.../screen_20260706153000.png

// 如果你刚改了 UI，想要下一帧渲染后的画面：
Image next = Main.instance.getNextScreenShot(false);  // 保留 alpha

实现说明（源码）：

捕获得到的图像的 alreadyScreenScaled = true 并会经过 flipY()（OpenGL 后台缓冲区在垂直方向上是翻转的）。

在 WebGL 平台上，opaque=true 不会应用 setOpaque()（代码中有显式的保护判断）；即便请求不透明，alpha 也会被保留。

getScreenShot 与 Component.toImage() 不同：这里不进行绘制/渲染——捕获的是当前帧的后台缓冲区。

对于跨平台比较（例如测试），请用 Styles.setDefaultFont(Font.getFont(false, 20)) 固定字体，因为字体渲染因设备而异。

深入了解

姊妹配方：salvar-imagem.md — 把截图保存为 PNG/JPEG。
自定义绘制 — paint thread 与 runOnPaintThreadAndWait。