Package io.github.ghosthack.imageio

Class ImageioNative

java.lang.Object

io.github.ghosthack.imageio.ImageioNative

public final class ImageioNative
extends Object

Unified cross-platform API for native image decoding.

Automatically delegates to the correct platform backend:

• macOS → Apple ImageIO (CGImageSource / Apple Media Engine)
• Windows → Windows Imaging Component (WIC / DXVA)

Use this when you want more control than javax.imageio.ImageIO.read() provides. The SPI-based auto-registration still works in parallel — this API is an alternative, not a replacement.

 if (ImageioNative.isAvailable()) {
     Dimension size = ImageioNative.getSize(bytes);
     BufferedImage img = ImageioNative.decode(bytes);
 }
 

For platform-specific features (e.g., Windows codec installation checks), use AppleImageio or WindowsImageio directly.

Method Summary

Modifier and Type	Method	Description
static Set<String>	activeFormats()	Returns the set of format names currently active on this platform, as controlled by the imageio.native.formats system property.
static Set<String>	activeSuffixes()	Returns the set of file suffixes currently active on this platform.
static boolean	canDecode(byte[] header, int length)	Probes whether the platform's native decoder can handle the given data.
static BufferedImage	decode(byte[] imageData)	Decodes raw image bytes through the platform's native decoder.
static Dimension	getSize(byte[] imageData)	Returns image dimensions without full pixel decode.
static boolean	isAvailable()	Returns true if a native image decoding backend is available on the current platform (macOS or Windows).

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

isAvailable

public static boolean isAvailable()

Returns true if a native image decoding backend is available on the current platform (macOS or Windows).

canDecode

public static boolean canDecode(byte[] header,
 int length)

Probes whether the platform's native decoder can handle the given data.

Parameters:

header - first bytes of the image (4 KB is sufficient)

length - number of valid bytes in header

Returns:

true if the format is recognised by the current platform

activeFormats

public static Set<String> activeFormats()

Returns the set of format names currently active on this platform, as controlled by the imageio.native.formats system property.

Returns:

unmodifiable set of format names (e.g. "HEIC", "AVIF", "WEBP")

activeSuffixes

public static Set<String> activeSuffixes()

Returns the set of file suffixes currently active on this platform.

Returns:

unmodifiable set of suffixes (e.g. "heic", "avif", "webp", "jp2")

getSize

public static Dimension getSize(byte[] imageData)
                         throws IIOException

Returns image dimensions without full pixel decode.

Queries the native decoder for image metadata only — no pixel buffer allocation, no colour-space conversion. Significantly cheaper than decode(byte[]) for cases where only dimensions are needed.

Parameters:

imageData - the raw image file bytes

Returns:

image dimensions

Throws:

IIOException - if the format is unsupported, file is corrupt, or no backend is available

decode

public static BufferedImage decode(byte[] imageData)
                            throws IIOException

Decodes raw image bytes through the platform's native decoder.

Unlike ImageIO.read() which silently returns null on failure, this method throws IIOException with a diagnostic message explaining what went wrong (unsupported format, missing codec, corrupt data, etc.).

Parameters:

imageData - the raw image file bytes

Returns:

decoded image (TYPE_INT_ARGB_PRE)

Throws:

IIOException - if the format is unsupported, decode fails, or no backend is available