How to save an image as PNG or JPEG

Purpose. Persist an Image to disk. CrossFly offers two levels: convenience (saves a file named by timestamp and returns the path) and full control (you provide the OutputStream).

Convenience (saves the file automatically)

• String toPng(String... prefix) — saves a PNG named <prefix><timestamp>.png. On desktop it writes to Device.homeFolder; on mobile it writes to /sdcard/. Returns the saved path, or null on error (the error is handled internally via Debug.handle). The prefix is optional.
• String toJpg(int... quality) — saves a JPEG named by timestamp. quality is optional (default 90); 100 = no compression, 85 = good compression, 60 = heavy compression but with noise. Returns the path, or null on error.

Full control (you provide the stream)

• void toPng(OutputStream s) throws ImageException, IOException — writes the PNG to the stream. The PNG is 24 BPP, or 32 BPP if the image has an alpha channel.
• void toJpg(OutputStream s, int quality) throws ImageException, IOException — writes the JPEG to the stream with the given quality (0–100). The stream is closed by the call.

Watch out for the overloads: toPng(String...)/toJpg(int...) save a file and swallow exceptions (return null). Whereas toPng(OutputStream)/toJpg(OutputStream,int) propagate ImageException/IOException. Choose according to whether or not you want to handle the error.

Complete example (copy, paste and run)

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

/** Runnable main screen. Point the launcher (classname) and run: 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");   // your already-loaded or generated image

         // 1) Convenience: file with timestamp; returns the path
         String pngPath = img.toPng("thumb_");   // e.g.: .../thumb_20260706153000.png
         String jpgPath = img.toJpg(85);         // quality 85
         Debug.log("PNG: " + pngPath + " | JPG: " + jpgPath);

         // 2) Full control: you decide the destination and handle errors
         try (OutputStream out = new FileOutputStream("/sdcard/saida.png")) {
            img.toPng(out);                      // stream is closed by the call; propagates exceptions
         } catch (ImageException | IOException e) {
            // handle write/encoding failure
         }
      } catch (ImageException | IOException e) {
         // failed to load the source image
      }
   }
}

The snippet below shows only the core. To run it, place it inside the MainWindow skeleton above.

Minimal snippet

// verified in source: Image.java toPng/toJpg — lines 800, 811, 1454, 1479
import dev.crossfly.ui.image.*;   // Image, ImageException

Image img = /* your already-loaded or generated image */;

// 1) Convenience: file with timestamp; returns the path
String pngPath = img.toPng("thumb_");   // e.g.: .../thumb_20260706153000.png
String jpgPath = img.toJpg(85);         // quality 85

// 2) Full control: you decide the destination and handle errors
try (java.io.OutputStream out = new java.io.FileOutputStream("/sdcard/saida.png")) {
   img.toPng(out);                      // stream is closed by the call; propagates exceptions
} catch (ImageException | java.io.IOException e) {
   // handle write/encoding failure
}

Dive deeper

• Sibling recipe: thumbnail.md — generate the thumbnail and then save it with this recipe.
• Sibling recipe: screenshot.md — capture the screen and save it with toPng().