如何把图像保存为 PNG 或 JPEG

目的。 把一张 Image 持久化到磁盘。CrossFly 提供两个层次：便捷（保存一个以时间戳命名的文件并返回路径）和完全控制（由你提供 OutputStream）。

便捷（自动保存文件）

String toPng(String... prefix) — 保存一个名为 <prefix><timestamp>.png 的 PNG。在桌面端写入 Device.homeFolder；在移动端写入 /sdcard/。返回保存的路径，或在出错时返回 null（错误在内部通过 Debug.handle 处理）。prefix 是可选的。
String toJpg(int... quality) — 保存一个以时间戳命名的 JPEG。quality 是可选的（默认 90）；100 = 无压缩，85 = 良好压缩，60 = 大幅压缩但有噪点。返回路径，或在出错时返回 null。

完全控制（由你提供流）

void toPng(OutputStream s) throws ImageException, IOException — 把 PNG 写入流。PNG 为 24 BPP，若图像带 alpha 通道则为 32 BPP。
void toJpg(OutputStream s, int quality) throws ImageException, IOException — 以给定质量（0–100）把 JPEG 写入流。该流会被调用关闭。

注意重载：toPng(String...)/toJpg(int...) 会保存一个文件并吞掉异常（返回 null）。而 toPng(OutputStream)/toJpg(OutputStream,int) 会传播 ImageException/IOException。根据你是否想处理错误来选择。

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

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

/** 可执行的主界面。将 launcher 指向此类（classname）并运行：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");   // 你已加载或生成的图像

         // 1) 便捷方式：带时间戳的文件；返回路径
         String pngPath = img.toPng("thumb_");   // 例如：.../thumb_20260706153000.png
         String jpgPath = img.toJpg(85);         // 质量 85
         Debug.log("PNG: " + pngPath + " | JPG: " + jpgPath);

         // 2) 完全控制：由你决定目标并处理错误
         try (OutputStream out = new FileOutputStream("/sdcard/saida.png")) {
            img.toPng(out);                      // stream 由该调用关闭；异常会向上传播
         } catch (ImageException | IOException e) {
            // 处理写入/编码失败
         }
      } catch (ImageException | IOException e) {
         // 加载源图像失败
      }
   }
}

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

最小片段

// 已在源码核实：Image.java toPng/toJpg — 800、811、1454、1479 行
import dev.crossfly.ui.image.*;   // Image, ImageException

Image img = /* 你已加载或生成的图像 */;

// 1) 便捷方式：带时间戳的文件；返回路径
String pngPath = img.toPng("thumb_");   // 例如：.../thumb_20260706153000.png
String jpgPath = img.toJpg(85);         // 质量 85

// 2) 完全控制：由你决定目标并处理错误
try (java.io.OutputStream out = new java.io.FileOutputStream("/sdcard/saida.png")) {
   img.toPng(out);                      // stream 由该调用关闭；异常会向上传播
} catch (ImageException | java.io.IOException e) {
   // 处理写入/编码失败
}

深入了解

姊妹配方：thumbnail.md — 生成缩略图后用本配方保存它。
姊妹配方：screenshot.md — 捕获屏幕并用 toPng() 保存。