Задайте интерфейс MATLAB для библиотеки C++

Как завершить определения в файле определения библиотеки

MATLAB^® интерфейс преобразует подписи функции C++ в подписи функции MATLAB. Некоторые построения языка C++ не имеют уникальных соответствий на языке MATLAB. MATLAB использует library definition file (с MLX расширение файла), который издатель создает и изменяет, чтобы предоставить недостающую информацию. У издателя должно быть достаточно навыков языка C++, чтобы интерпретировать функциональную подпись и предоставить недостающую информацию.

MATLAB сообщает вам об этих неполных определениях через это clibgen.generateLibraryDefinition предупреждающее сообщение:

Warning: Some C++ language constructs in the files for generating interface file 
are not supported and not imported.

Пример информации, которую должен задать издатель, относится к использованию pointers, чтобы передать данные функциям. Указатель является местоположением в памяти, которая указывает на запуск блока данных. Чтобы передать эти данные MATLAB безопасно, издатель должен задать размер данных. Поиск по функциям указывает на размер данных, возможно, как дополнительный входной параметр. Используя файл определения MATLAB, издатель задает значение, и затем MATLAB создает эквивалентную подпись функции MATLAB. Чтобы отобразить функциональные подписи, смотрите Справку Отображения для Интерфейса MATLAB к Библиотеке C++.

После создания файла определения библиотеки definelibName.mlx использование clibgen.generateLibraryDefinition, вам придется изменить содержимое, чтобы включать функциональность в интерфейс. Используйте Live Editor, чтобы изменить MLX файл определения. Замените <DIRECTION>, <SHAPE>, и <MLTYPE> параметры с недостающей информацией. Эти параметры используются для этих случаев.

Чтобы задать, является ли аргумент указателя входом только для чтения, выход только или модифицируемый входной параметр, использует параметр НАПРАВЛЕНИЯ.
Если аргумент указателя используется для данных массива, то информация о размерности требуется, чтобы преобразовывать массив между C++ и MATLAB. Используйте параметр SHAPE, чтобы указать эту информацию.
C++ имеет много типов, представляющих аргументы строки. Вы можете должны быть задать MLTYPE и значения SHAPE так, чтобы MATLAB мог правильно преобразовать тип C++ в string MATLAB ввод.

MATLAB предлагает предложения кода для значений этих параметров. Активировать предложения для определенного параметра:

Не прокомментируйте код, задающий функцию.
Удалите название параметра, включая <> 'characters'.
Сделайте паузу, чтобы позволить предложениям кода быть отображенными.
Если предложения не появляются, убедитесь что definelibName.mlx файл находится на вашем пути MATLAB.

Автозадайте аргументы

Можно направить MATLAB, чтобы автозадать тип и форму определенных типов аргумента при помощи clibgen.generateLibraryDefinition и clibgen.buildInterface аргументы name-value. Опции:

Обрабатывать весь const символьные указатели в библиотеке как отключенные пустым указателем струны до, набор аргумент TreatConstCharPointerAsCString к true.
Чтобы обработать все объектные указатели в библиотеке как скаляры, установите аргумент TreatObjectPointerAsScalar на true.

Когда вы подтверждаете определение библиотеки, вы можете получить ошибки о дублирующихся подписях MATLAB. Чтобы разрешить эти ошибки, смотрите, Согласовывают Конфликты Подписи MATLAB.

Согласуйте конфликты подписи MATLAB

После генерации и редактирования файла определения библиотеки, может быть две или больше функции или другие построения с идентичными подписями MATLAB. Чтобы проверять на этот конфликт, подтвердите файл определения. Например, для файла определения definelibnameВвод:

definelibname

Если существует конфликт, MATLAB отображает ошибку со ссылкой на код в файле определения. Чтобы разрешить конфликт, выберите одно из следующего:

Пересмотрите defineArgument или defineOutput аргументы, чтобы создать уникальную подпись MATLAB. Конфликт происходит, когда существует несколько перегруженных функций, и вы задаете те же параметры аргумента. Смотрите, Как Завершить Определения в Файле Определения Библиотеки.
Удалите одну из функций путем комментирования определения построения. Конфликт может произойти, когда вы используете один из clibgen.generateLibraryDefinition аргументы name-value, чтобы преобразовать все случаи конкретного типа. Также можно удалить перегруженную функцию.

После изменения файла определения, повторно выполненного файл, чтобы подтвердить ваши редактирования.

Настройте содержимое

Рассмотрите схему переименования, используемую MATLAB, чтобы заменить недопустимые имена. Для получения дополнительной информации смотрите Имена C++, Которые Недопустимы в MATLAB.

Рассмотрите автоматически сгенерированную справку. MATLAB копирует некоторые комментарии C++ в Description и DetailedDescription аргументы. Можно изменить или заменить это содержимое, которое является базисом doc команда для конечных пользователей.

Настройте имена шаблона функции

Рассмотрите уникальные имена функций, сгенерированные из шаблонов функций в файле определения библиотеки. Например, класс A в этом заголовочном файле задает шаблон функции show и обеспечивает инстанцирования для типов int'double', и const A.

class A{}; // User type
template<typename T> void show(T a) {}
template void show<int>(int);
template void show<double>(double);
template<> void show<const A &>(const A& a){}

Если вы создаете интерфейс A к этой библиотеке MATLAB создает перегруженные функции, которые имеют подписи для этих инстанцирований.

summary(defineA)

MATLAB Interface to libname Library

Class clib.libname.A

  Constructors:
    clib.libname.A(clib.libname.A)
    clib.libname.A()

  No Methods defined

  No Properties defined

Functions
clib.libname.show(int32)
clib.libname.show(double)
clib.libname.show(clib.libname.A)

Интерфейс C++ также генерирует уникальные имена функций на основе типов подписи. Чтобы просмотреть уникальные имена, используйте свойство TemplateUniqueName.

d = defineA;
d.Functions(1:3).TemplateUniqueName

ans = "clib.libname.show_int_"
ans = "clib.libname.show_double_"
ans = "clib.libname.show_AConst__"

Можно настроить эти имена в файле определения библиотеки. Например, измените имя функции для объекта класса clib.libname.show_AConst__. Перезапустите MATLAB и отредактируйте defineA.mlx. Найдите addFunction оператор для show_AConst__ функционируйте и измените "TemplateUniqueName" аргумент значения имени. Замените show_AConst__ с новым именем, например, showObjectA. Обновите "Description" аргумент значения имени, заменяя clib.libname.show с новым именем clib.libname.showObjectA и изменение текста справки, чтобы считать Representation of C++ function show for class A.

"Description", "clib.libname.showObjectA    Representation of C++ function show for class A.");

help clib.libname.showObjectA

 clib.libname.showObjectA    Representation of C++ function show for class A.

    Inputs
      a              read-only clib.libname.A  

    No outputs

Для получения дополнительной информации смотрите Шаблоны Функции и Функции членства Использования.

Соответствие размерности

Если количество размерностей аргумента MATLAB больше, чем соответствующий параметр C++, то MATLAB удаляет одноэлементные размерности слева, пока количество размерностей не совпадает друг с другом. Если все одноэлементные размерности удалены, и аргумент MATLAB больше, чем параметр C++, то MATLAB производит исключение.

Если количество размерностей аргумента MATLAB меньше, чем параметр C++, MATLAB добавляет одноэлементные размерности. По умолчанию MATLAB вставляет одноэлементные размерности в начале аргумента. Чтобы вставить одноэлементные размерности в конце аргумента, установите 'AddTrailingSingletons' к true в defineArgument функции - defineArgument (ConstructorDefinition), defineArgument (FunctionDefinition), и defineArgument (MethodDefinition).

Например, библиотека C++ содержит две функции, которые имеют входные параметры в интерфейсе libname заданный можно следующим образом:

void setImages(const uint8_t * images, int numOfImages, int height, int width);

% By default 'AddTrailingSingletons' is false
defineArgument(setImagesFunctionDefinition, "images", "uint8", "input", ...
    ["numOfImages", "height", "width"])

void setColorImage(const uint8_t * image, int height, int width, int colorDepth);

defineArgument(setColorImageFunctionDefinition, "image", "uint8", "input", ...
    ["height", "width", "colorDepth"], "AddTrailingSingletons", true)

В MATLAB создайте матрицу изображений, таким образом что:

size(myImage)

ans =
     768   1024

Когда вы вызываете setImages, MATLAB настраивает размер myImage к [1, 768, 1024].

setImages(myImage)

Когда вы вызываете setColorImage MATLAB настраивает размер myImage к [768, 1024, 1].

setColorImage(myImage)

Документация