image_ffi

A high-performance Flutter plugin for cross-platform image format conversion using native APIs.

Features

• 🖼️ Versatile Format Conversion: Supports conversion between JPEG, PNG, and WebP. It also handles HEIC/HEIF, allowing conversion from HEIC on all supported platforms and to HEIC on iOS/macOS.
• ⚡ Native Performance: Achieves high speed by using platform-native APIs directly: ImageIO on iOS/macOS and BitmapFactory on Android.
• 🔒 Efficient Native Interop: Employs FFI and JNI to create a fast, type-safe bridge between Dart and native code, ensuring robust and reliable communication.

Platform Support

Platform	Minimum Version	API Used
iOS	14.0	ImageIO (CoreFoundation, CoreGraphics)
macOS	10.15	ImageIO (CoreFoundation, CoreGraphics)
Android	7	BitmapFactory, Bitmap compression
Web	N/A	Not supported

on Android, HEIC input is supported on Android 9+ but HEIC output is not supported.

Getting Started

Installation

Add image_ffi to your pubspec.yaml:

dependencies:
  image_ffi: ^0.0.1

Basic Usage

import 'package:image_ffi/image_ffi.dart';
import 'dart:typed_data';

// Convert HEIC image to JPEG
final jpegData = await ImageConverter.convert(
  inputData: heicImageData,
  format: OutputFormat.jpeg,
  quality: 90,
);

// Convert any format to PNG
final pngData = await ImageConverter.convert(
  inputData: imageData,
  format: OutputFormat.png,
);

Supported Formats

Input Formats

• iOS/macOS: JPEG, PNG, HEIC, WebP, BMP, GIF, TIFF, and more
• Android: JPEG, PNG, WebP, GIF, BMP, HEIC (via BitmapFactory)

Output Formats

The supported output formats are defined by the OutputFormat enum, with platform-specific limitations:

• JPEG: Supported on all platforms.
• PNG: Supported on all platforms.
• WebP: Supported on Android only.
• HEIC: Supported on iOS/macOS only.

API Reference

ImageConverter.convert()

static Future<Uint8List> convert({
  required Uint8List inputData,
  OutputFormat format = OutputFormat.jpeg,
  int quality = 100,
}) async

Parameters:

• inputData (Uint8List): Raw image data to convert
• format (OutputFormat): Target image format (default: JPEG)
• quality (int): Compression quality 1-100 (default: 100, only for lossy formats)

Returns: Future<Uint8List> containing the converted image data

Throws:

• UnsupportedError: If the platform or format is not supported
• Exception: If conversion fails

OutputFormat Enum

enum OutputFormat {
  /// JPEG format (.jpg, .jpeg)
  /// Lossy compression, suitable for photos
  jpeg,

  /// PNG format (.png)
  /// Lossless compression, supports transparency
  png,

  /// WebP format (.webp)
  /// Modern format with superior compression (not supported on Darwin)
  webp,

  /// HEIC format (.heic)
  /// High Efficiency Image Format (not supported on Android)
  heic,
}

Implementation Details

iOS/macOS Implementation

The iOS/macOS implementation uses the ImageIO framework via FFI bindings:

1. Decoding: CGImageSourceCreateWithData reads input data
2. Rendering: CGImageSourceCreateImageAtIndex decodes to CGImage
3. Encoding: CGImageDestinationCreateWithData encodes to target format
4. Quality: Uses kCGImageDestinationLossyCompressionQuality for JPEG/WebP

Key Functions:

• CFDataCreate: Create immutable data from input bytes
• CGImageSourceCreateWithData: Create image source from data
• CGImageDestinationCreateWithData: Create image destination
• CGImageDestinationAddImage: Add image to destination
• CGImageDestinationFinalize: Complete encoding

Android Implementation

The Android implementation uses BitmapFactory and Bitmap.compress:

1. Decoding: BitmapFactory.decodeByteArray handles all supported formats
2. Compression: Bitmap.compress encodes to target format
3. Buffer Management: ByteArrayOutputStream manages output data

Key Limitations:

• HEIC can be read (input only) but cannot be written (output format not supported)
• Requires Android 9+ for full HEIC support