Все вы знаете, что Flutter реализует несколько абстракций для передачи данных между Dart-кодом и кодом, связанным с оболочкой Flutter Engine на языке платформы (например, Kotlin для Android). Но в действительности у Dart есть еще один инструмент для взаимодействия с внешним миром и он может использоваться для добавления C/C++ библиотек и вызова функций из Dart-кода. Основную сложность представляет разные соглашения по кодированию типизованных числовых значений, строк и структур, но часть задач по преобразованию и работе с памятью выполняют библиотека dart:ffi и пакет package:ffi/ffi.dart, а некоторые из них могут быть выполнены самостоятельно. В статье мы рассмотрим общие принципы подключения внешних библиотек и кодогенерации для создания связываний dart-функции и классов и структур данных C.

Начнем с более простого примера и создадим небольшую библиотеку на C и рассмотрим последовательность действий для ее интеграции во Flutter-приложение.

Создадим новый проект и в нем новый каталог в android/app/src/main/cpp, добавим исходный текст, файл с заголовками и CMakeLists.txt для сборки библиотеки:

#include "string.h"
#include "stdlib.h"

int sum(int a, int b) {
  return a+b;
}

int len(char* str) {
  return strlen(str);
}

char* reversed(char* str) {
  char* newstr = malloc(strlen(str)+1);
  str += strlen(str)-1;
  while (*str) {
    *newstr = *str;
    str--;
    newstr++;
  }
  *newstr = 0;
  return newstr;
}
#ifndef FFI1_SAMPLE_H
#define FFI1_SAMPLE_H

int sum(int a, int b);

int len(char* str);

char* reversed(char* str);
#endif //FFI1_SAMPLE_H

И создадим CMakeLists.txt:

cmake_minimum_required(VERSION 3.4.1)
project(sample)
add_library(sample SHARED sample.c)
find_library(log-lib log)
target_link_libraries(sample)

И также добавим конфигурацию внешней сборки в app/build.gradle:

...
android {
  ...
    externalNativeBuild {
        cmake {
            path "src/main/сpp/CMakeLists.txt"
        }
    }
}

После этого при выполнении сборки проекта через flutter build apk в финальный архив будет добавляться so-файл библиотеки, собранный для соответствующих платформ (lib/). Для подключения к библиотеке мы будем использовать возможности dart:ffi (Foreign Function Interface).

dart:ffi определяет внешние (нативные) типы данных и позволяет связать определение dart-функции и внешней функции из импортированной библиотеки. Типы данных включают в себя:

  • Void - пустой тип (может использоваться как результат функции, которая ничего не возвращает);

  • Bool - логическое значение (в C будет представлен целым числом);

  • Int8, Int16, Int32, Int64 - целое число со знаком с соответствующей разрядностью;

  • Uint8 (Char), Uint16, Uint32, Uint64 - целое число без знака с соответствующей разрядностью;

  • Float, Double - 32-х и 64-х разрядное число с плавающей точкой;

  • Pointer - указатель на область памяти в C;

  • Array, Struct, Union - составные типы данных (соответственно массив однотипных элементов, структура разнотипных элементов, объединение элементов, занимающих одну область памяти).

Для привязки внешних функций необходимо загрузить библиотеку (DynamicLibrary.open) и выполнить обнаружение функции по сигнатуре и названию. Например, для поиска функции sum можно использовать следующий вызов (при условии, что в переменной library размещен результат вызова DynamicLibrary.open):

typedef DartSumFunction = int sum(int,int); 
typedef CSumFunction = ffi.Int64 ffi.Function(ffi.Int64,ffi.Int64)> 
DartSumFunction sum = library.lookup('sum').asFunction();

Для определения структур и объединений необходимо создать класс-расширение от ffi.Struct или ffi.Union и пометить все его свойства ключевым словом external (внешние типы данных задаются через ffi-типы, которые используются как аннотации), например для описания комплексного числа можно создать такую структуру:

class ComplexNumber extends ffi.Struct {
  @ffi.Double()   
  external double x; 

  @ffi.Double() 
  external double y; 
}

Объединения создаются аналогично (наследованием от ffi.Union). Для управления памятью и определения указателей нужно использовать тип Pointer с уточнением типа значения под указателем (например, Pointer, Pointer или Uint8Pointer может быть использован как указатель на строку, поскольку аналогом в C является тип char*, указатель на целое 8-битное число без знака).

Для получения указателя из typed_data (бывает часто нужно для передачи двоичных данных, например изображения), можно использовать следующий фрагмент кода:

Uint8Pointer getBlob(Uint8List data) { 
  final blob = calloc(data.length); 
  final blobBytes = blob.asTypedList(data.length); 
  blobBytes.setAll(0, data); 
  return blob; 
}

Для определения массива (Array) также нужно использовать уточнение типа или одно из расширений (например, Int64Array).

Для выделения памяти можно использовать функцию calloc(N), которая возвращает указатель на тип T с выделением N элементов (суммарно N*sizeof(T) байт). Также для создания указателя на один элемент (например структуру) можно использовать malloc(). Важно не забывать освобождать выделенную память через malloc.free(ptr).

Для преобразования строк доступны расширения в String toNativeUtf8 (возвращает Pointer) и toDartString() для обратного преобразования. Для извлечения значения под указателем используется метод .value(). Указатели могут быть преобразованы к другому типу методом .cast. Все функции по управлению памятью и работе с указателями доступны в пакете package:ffi/ffi.dart.

Всегда необходимо помнить, что если внешняя функция возвращает указатель, нужно скопировать данные в другой объект, поскольку указатель будет нужно освободить. Поэтому предпочтительно для структур и объединений создавать отдельный Dart-класс и именованный конструктор, который будет заполнять данные Dart-объекта на основе значений, полученных из указателя на структуру.

Процесс создания интерфейса для вызова внешних функций может быть автоматизировать с помощью кодогенерации пакетом ffigen. Установим его как зависимость для разработки:

flutter pub add --dev ffigen

И добавим конфигурацию в pubspec.yaml:

ffigen:   
  output: 'lib/generated_bindings.dart'   
  name: SampleNative   
  headers:     
    entry-points:       
    - 'android/app/src/main/сpp/sample.h'

После запуска flutter pub run ffigen в сгенерированном файле будет доступен класс SampleNative, который при создании получает объект загруженной динамической библиотеки и представляет интерфейс с методами, совпадающими с заголовочным файлом sample.h:

import 'package:path/path.dart' as path; 

String libraryFilename(String library) { 
  if (Platform.isMacOs) return "lib${library}.dylib";
  if (Platform.isWindows) return "${library}.dll"; 
  return "lib${library}.so"; 
}

void example() { 
  ffi.DynamicLibrary library; 
  if (Platform.isAndroid) { 
    library = ffi.DynamicLibrary.open(libraryFilename('sample')); 
  } else if (Platform.isIos) { 
    library = ffi.DynamicLibrary.process(); 
  } else { 
    library = ffi.DynamicLibrary.open(path.join(Directory.current.path, libraryFilename('sample'))); 
  } 
  
  final nativeLibrary = NativeSample(library); 
  print(nativeLibrary.sum(2,2));
}

Теперь, когда мы умеет подключать простые библиотеки, обсудим способы интеграции OpenCV.

Начнем с установки исходных текстов и настройки сборки для получения so-библиотек и необходимых заголовочных файлов:

git clone https://github.com/opencv/opencv.git 
git clone https://github.com/opencv/opencv_contrib.git 
python3 opencv/platforms/android/build_sdk.py --sdk_path $ANDROID_HOME --ndk_path $ANDROID_NDK_HOME --extra_modules_path opencv_contrib/modules/

Для импорта сгенерированных библиотек и header-файлов можно использовать готовый CMakeLists.txt отсюда. Для правильной сборки нужно указать диалект языка C++ в build.gradle:

externalNativeBuild { 
  cmake { 
    cppFlags "-frtti -fexceptions -std=c++17" 
    abiFilters "armeabi-v7a", "arm64-v8a" 
  }
}

Обертки над функциями могут быть написаны самостоятельно или с использованием ffigen, например для функции cvMaxRect, которая принимает два указателя на прямоугольники и возвращает новый прямоугольник, определение может выглядеть следующим образом:

class CvRect extends Struct { 
  @Int64() external int x;

  @Int64() external int y;

  @Int64(); external int width;

  @Int64(); external int height; 
}

typedef CvRectPtr = Pointer<CvRect>

typedef cv_max_rect_function = NativeFunction<CvRect Function(CvRectPtr, CvRectPtr)> 
typedef CvMaxRectFunction = CvRect Function<CvRectPtr, CvRectPtr>
final cvMaxRect = library.lookup<cv_max_rect_function>('cvMaxRect').asFunction<CvMaxRectFunction>();

При вызовах ffi необходимо помнить, что обращение к функциям происходит синхронно и блокирует основной изолят, поэтому для длительных операций (преобразования изображение, детектирование объектов и др.) предпочтительно использовать изоляты (в простейшем варианте можно применить compute с передачей внешней функции).

Важно помнить, что dart FFI поддерживает только С API, поэтому для библиотек, которые созданы только для C++ потребуется создавать дополнительные функции-обертки для создания и удаления объектов (результатом может быть структура с указателем на объект или иным handle, который можно использовать для обнаружения созданного объекта в C-коде), а также функции-адаптеры для вызова соответствующих методов объекта (указатель или handle-объекта передается параметром функции). Для корректной компиляции обертки (при смешивании C и C++ исходных текстов) перед функциями необходимо добавить extern "C". Примеры создания таких связываний можно посмотреть в этом репозитории.

Во второй части статьи мы рассмотрим более подробно интеграцию нативных Android-библиотек на примере библиотеки обработки и синтеза звука AAudio.

И в заключение приглашаю всех желающих на бесплатный урок по теме: "Сферический Flutter в вакууме. Создаем свою систему координат для RenderObject".