Como salvar uma imagem em PNG ou JPEG

Propósito. Persistir uma Image em disco. O CrossFly oferece dois níveis: conveniência (salva um arquivo com nome por timestamp e retorna o caminho) e controle total (você fornece o OutputStream).

Conveniência (salva arquivo automaticamente)

• String toPng(String... prefix) — salva um PNG com nome <prefix><timestamp>.png. No desktop grava em Device.homeFolder; em mobile grava em /sdcard/. Retorna o caminho salvo, ou null em caso de erro (o erro é tratado internamente via Debug.handle). O prefix é opcional.
• String toJpg(int... quality) — salva um JPEG com nome por timestamp. quality é opcional (default 90); 100 = sem compressão, 85 = boa compressão, 60 = grande compressão mas com ruído. Retorna o caminho, ou null em erro.

Controle total (você fornece o stream)

• void toPng(OutputStream s) throws ImageException, IOException — grava o PNG no stream. O PNG é 24 BPP, ou 32 BPP se a imagem tiver canal alpha.
• void toJpg(OutputStream s, int quality) throws ImageException, IOException — grava o JPEG no stream com a qualidade dada (0–100). O stream é fechado pela chamada.

Atenção às sobrecargas: toPng(String...)/toJpg(int...) salvam um arquivo e engolem exceções (retornam null). Já toPng(OutputStream)/toJpg(OutputStream,int) propagam ImageException/IOException. Escolha conforme quer ou não tratar o erro.

Exemplo completo (copiar, colar e rodar)

package com.exemplo;

import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;

import dev.crossfly.ui.*;                     // Window
import dev.crossfly.ui.layout.*;             // VerticalLayout
import dev.crossfly.ui.image.*;              // Image, ImageException
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());

      try {
         Image img = new Image("/sdcard/foto.jpg");   // sua imagem já carregada ou gerada

         // 1) Conveniência: arquivo com timestamp; retorna o caminho
         String pngPath = img.toPng("thumb_");   // ex.: .../thumb_20260706153000.png
         String jpgPath = img.toJpg(85);         // qualidade 85
         Debug.log("PNG: " + pngPath + " | JPG: " + jpgPath);

         // 2) Controle total: você decide o destino e trata erros
         try (OutputStream out = new FileOutputStream("/sdcard/saida.png")) {
            img.toPng(out);                      // stream é fechado pela chamada; propaga exceções
         } catch (ImageException | IOException e) {
            // trate falha de escrita/codificação
         }
      } catch (ImageException | IOException e) {
         // falha ao carregar a imagem de origem
      }
   }
}

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

Trecho mínimo

// verificado na fonte: Image.java toPng/toJpg — linhas 800, 811, 1454, 1479
import dev.crossfly.ui.image.*;   // Image, ImageException

Image img = /* sua imagem já carregada ou gerada */;

// 1) Conveniência: arquivo com timestamp; retorna o caminho
String pngPath = img.toPng("thumb_");   // ex.: .../thumb_20260706153000.png
String jpgPath = img.toJpg(85);         // qualidade 85

// 2) Controle total: você decide o destino e trata erros
try (java.io.OutputStream out = new java.io.FileOutputStream("/sdcard/saida.png")) {
   img.toPng(out);                      // stream é fechado pela chamada; propaga exceções
} catch (ImageException | java.io.IOException e) {
   // trate falha de escrita/codificação
}

Aprofunde-se

• Receita irmã: thumbnail.md — gere o thumbnail e depois salve com esta receita.
• Receita irmã: screenshot.md — capture a tela e salve com toPng().