Como capturar um screenshot da tela

Propósito. Obter uma Image com o conteúdo atual da tela (o backbuffer OpenGL), sem repintar nada, e opcionalmente salvá-la. Útil para diagnóstico, testes visuais e compartilhamento.

APIs usadas

static Image Main.getScreenShot(boolean... opaque) — captura o quadro atual. opaque=true remove o canal alpha (torna tudo opaco). É a conveniência estática mais comum. Internamente chama a versão de instância na paint thread via runOnPaintThreadAndWait.
Image Main.getScreenShot(boolean opaque) (instância) — mesma captura; agenda a leitura na paint thread e bloqueia até terminar.
Image Main.getNextScreenShot(boolean opaque) (instância) — força repintura e captura o próximo quadro. Use quando você acabou de mudar a UI e quer garantir que a mudança apareça no screenshot; se chamado fora da paint thread, ele repinta/atualiza em laço até obter o quadro.
String Image.toPng(String... prefix) / String Image.toJpg(int... quality) — para salvar o resultado (ver salvar-imagem.md).

Exemplo completo (copiar, colar e rodar)

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

/** Tela principal executável. Aponte o launcher (classname) e rode: 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 ->
      {
         // Captura o quadro atual, opaco (sem alpha), e salva um PNG:
         Image shot = Main.getScreenShot(true);   // true = remove alpha
         String path = shot.toPng("screen_");     // ex.: .../screen_20260706153000.png
         Debug.log("Screenshot salvo em: " + path);

         // Se você acabou de alterar a UI e quer o PRÓXIMO quadro renderizado:
         Image next = Main.instance.getNextScreenShot(false);  // mantém alpha
      });
      add(LAY_AUTO, b);
   }
}

O trecho abaixo mostra só o miolo. Para rodar, coloque-o no esqueleto MainWindow acima.

Trecho mínimo

// verificado na fonte: Main.java getScreenShot (533, 667) e getNextScreenShot (541)
import dev.crossfly.Main;
import dev.crossfly.ui.image.Image;

// Captura o quadro atual, opaco (sem alpha), e salva um PNG:
Image shot = Main.getScreenShot(true);   // true = remove alpha
String path = shot.toPng("screen_");     // ex.: .../screen_20260706153000.png

// Se você acabou de alterar a UI e quer o PRÓXIMO quadro renderizado:
Image next = Main.instance.getNextScreenShot(false);  // mantém alpha

Notas de implementação (fonte):

A imagem capturada tem alreadyScreenScaled = true e sofre flipY() (o backbuffer OpenGL vem invertido verticalmente).

Na plataforma WebGL, opaque=true não aplica setOpaque() (guarda explícita no código); o alpha é mantido mesmo pedindo opaco.

getScreenShot difere de Component.toImage(): aqui não há pintura/render — captura-se o backbuffer do quadro corrente.

Para comparações cross-platform (ex.: testes), fixe a fonte com Styles.setDefaultFont(Font.getFont(false, 20)), pois a renderização de fontes varia por dispositivo.

Aprofunde-se

Receita irmã: salvar-imagem.md — grave o screenshot em PNG/JPEG.
Desenho customizado — paint thread e runOnPaintThreadAndWait.