AI Lab

Open Artificial Intelligence Laboratory

RDK: Применение библиотеки в проекте

Скачать: RDK.UsingToProject.Ru.doc

Введение

         В этом документе будет рассмотрены основные понятия и функционал, необходимый для использования библиотеки RDK конечным пользователем. Документ не описывает процесса развития библиотеки для добавления нового функционала, например новых алгоритмов. Ознакомление с информацией по развитию библиотеки следует начать с документа: RDK.QuickStart.ComponentDevelopment.Ru.doc

1 Варианты использования

Интерфейс взаимодействия с пользовательским приложением может быть следующих трех типов:

-       В виде статической или динамической библиотеки – управление ядром обеспечивается через интерфейс на чистом C. Ядро собирается статической или динамической библиотекой и подключается соответственно либо на этапе сборки проекта, либо во время выполнения. Этот тип взаимодействия является основным.

-       С прямым доступом к классам управляющего ядра – управление ядром обеспечивается через полноценный C++ интерфейс, для всех функций, которые доступны в интерфейсе на чистом C, существуют, вызываемые ими аналоги в классах ядра. Позволяет, в частности, обеспечить альтернативный доступ к компонентам и их содержимому, эффективный по быстродействию.

-       Использование компонент в явном виде в коде – путем непосредственного использования классов и функций библиотеки. Обычно нежелателен для конечного использования. Область применения – реализация своих библиотек на основе RDK, либо использование отдельных элементов в конечных проектах, где структура моделей расчетов жестко определена и накладных расходы на интерфейс неприемлемо велики.

2 Использование в виде статической или динамической библиотеки

2.1 Требуемые файлы

Для подключения RDKв виде библиотеки необходимо в исходных кодах использовать файлы: Deploy/Include/rdk_initlib.hили Deploy/Include/rdk_initdll.h в зависимости от того, в каком варианте собрана библиотека. Одновременно в проект должен быть добавлен соотвествующий файл Deploy/Dll/rdk.xxx.libили Deploy/Lib/rdk.xxx.lib, где xxx– имя используемого окружения. Например для C++ Builderфайлы имеют вид rdk.bcb.lib. Также в проект должен быть добавлен путь поиска исходных файлов Deploy/Include.

В некоторых случаях может быть необходим прямой доступ к классам управляющего ядра библиотеки. В этом случае необходимо для подключения библиотеки использовать файл Deploy/Include/rdk_cpp_initlib.hили Deploy/Include/rdk_cpp_initdll.h. Обязательным требованием при этом является, то, чтобы библиотека и пользовательское приложение были собраны одним компилятором. При таком способе подключения доступен как весь стандартный C-интерфейс, так и прямой доступ к указателям на экземпляры классов управляющего ядра.

Альтернативным способом подключения как статической библиотеки является ее сборка из исходных кодов непосредственно в конечном программном продукте. В этом случае, в проект вместо .lib файлов добавляются следующие файлы из папки Deploy/Include:

-       rdk.xxx.cpp (xxx – имя используемого окружения, например bcb, win, gcc, ansi)

-       rdk_cpp_initlib.cpp

-       rdk_new.cpp

2.2 Основные понятия

RDKпредоставляет, в частности, средства для построения приложений, структура алгоритмов которых может быть заранее неизвестна, или модифицируется во время выполнения. Для этого в RDKреализовано расширение Engine (управляющее ядро) и его развитие для решения задач видеообработки – GraphicsEngine (управляющее ядро библиотеки видеообработки).

На рисунке 1 представлена схема взаимодействия основных модулей RDK.

 RDK.UsingToProject.Ru pic1

 Рисунок. 1 – Схема взаимодействия основных модулей RDK

Управляющее ядро (Engine) обеспечивает функционал по инициализации и деинициализации основных модулей библиотеки: среды выполнения и хранилища объектов. Также управляющее ядро предоставляет пользовательской программе унифицированный интерфейс взаимодействия с модулями библиотеки.

Хранилище классов и компонент (Storage) предоставляет средства по управлению доступным набором компонент (решающих модулей) во время выполнения программы. Таким образом, обеспечивается возможность динамической замены компонент, или модификации структурной схемы модели (под моделью будем понимать алгоритм верхнего уровня, решающий поставленную пользователем задачу).

Среда выполнения (Environment), используя хранилище объектов, обеспечивает функционал по формированию структурной схемы модели, управлению отдельными компонентами модели, заданию входных данных модели для расчета и выдачу выходных данных.

Модель (Model) – часть среды, содержащая в себе собственно структуру алгоритма и все функции по управлению им.

Компонент (Component) – самодостаточная в рамках модели сущность. Имеет методы для связи с другими контейнерами, может содержать в себе другие компоненты. В рамках своего владельца определяется уникальным идентификатором id (целое число) и строковым именем. Для прямого доступа к вложенному компоненту можно использовать составное строковое описание вида “id1.id2.id3”, например “13.7.1”, или “ComponentName1.SubComponentName2.SubComponentName3”.

. 35

Содержание

 Введение  2.5.1 Параметрами компонент
 1 Варианты использования  2.5.2 Переменными состояния компонент
 2 Использование в виде статической или динамической библиотеки  2.5.4 Управлением хранилищем объектов
 2.1 Требуемые файлы  2.5.3 Счетом
2.2 Основные понятия 2.5.5 Созданием и удалением модели
2.3 Жизненный цикл 2.5.6 Добавлением и удалением компонент из модели
2.4 Базовые функции управления 2.5.7 Отношениями между именем компонента и его идентификатором
2.4.1 Инициализация и деинициализация 2.5.8 Связями компонент
2.4.2 Задание входных данных 2.5.9 Входами и выходами компонент
2.4.3 Доступ к компонентам 2.5.10 Загрузкой и сохранением модели
2.4.4 Ввод-вывод данных параметров компонент 2.5.11 Доступом ко времени и статистике производительности компонент
2.4.5 Ввод-вывод переменных состояния компонент 2.6 Упрощенный способ доступа к значениям параметров и переменных состояния для C++ разработчика
2.4.6 Расчет и время 3 Использование с прямым доступом к классам управляющего ядра

2.4.7 Получение выходных данных

4 Использование компонент в явном виде в коде
2.4.8 Доступ к системному журналу и обработка исключительных ситуаций Заключение
2.5 Дополнительные функции управления  

 

2.3 Жизненный цикл

На рисунке 2 представлена типичная последовательность действий при использовании Engine. Пунктиром показаны необязательные действия.

RDK.UsingToProject.Ru pic2

Рисунок 2 – Последовательность действий при использовании Engine

 

Эта последовательность действий всегда одинакова. Однако в общем случае в эту последовательность могут добавляться дополнительные действия, связанные, например, с загрузкой и сохранением модели, созданием модели, ее наполнением компонентами и установкой связей между ними, получением статистической информации, например о быстродействии расчетов отдельных компонент, и т.п.

         Таким образом, можно кратко описать жизненный цикл:

1.Инициализация среды: EngineInit/ GraphicalEngineInit .

2.Просмотр/Задание параметров компонент: Model_GetComponentState/ Model_SetComponentState.

3.Задание входных изображений: Env_SetInputImage.

4.Расчет: Env_Calculate.

5.Просмотр выходных изображений: Env_GetOutputImage; Model_GetComponentOutput .

6.Просмотр переменных состояния компонент: Model_GetComponentState.

7.Повтор цикла 2–6.

8.Деинициализация среды: EngineUnInit(может быть опущена).

 

2.4 Базовые функции управления

Список всех функций приведен в документе RDK.UsersGuide.doc

2.4.1 Инициализация и деинициализация

2.4.1.1.     Инициализация управляющего ядра

Для инициализации управляющего ядра необходимо вызвать функцию int EngineInit(int predefined_structure, void* exception_handler =0) с параметрами:

-       predefined_structure – индекс модели аналитики. Для инициализации без предустановленной модели необходимо установить параметр равным 0.

-       exception_handler – функция обратного вызова, вызываемая при генерации исключений в RDK.

2.4.1.2.     Инициализиция управляющего ядра библиотеки видеообработки

Альтернативный способ, используемый, для инициализации управляющего ядра видеообработки используется функция int GraphicalEngineInit(int predefined_structure, int num_inputs, int num_outputs, int input_width, int input_height, bool reflectionx=false,         void* exception_handler =0).

Параметры:

-       int predefined_structure – индекс модели аналитики. Для инициализации без предустановленной модели необходимо установить параметр равным 0.

-       num_inputs – число входов.

-       num_outputs – число выходов.

-       input_width – ширина изображения (определяется камерой).

-       input_height – высота изображения (определяется камерой).

-       reflectionx – флаг необходимости переворота входного изображения вокруг горизонтальной оси.

-       exception_handler – функция обратного вызова, вызываемая при генерации исключений в RDK.

2.4.1.3.     Деинициализация

Для деинициализации управляющего ядра необходимо вызвать функцию int EngineUnInit(void). Вызов функции необязателен в конце выполнения программы, т.к. она будет вызвана автоматически при завершении приложения.

2.4.1.4.     Пример кода инициализации/деиницализации

#include “rdk_dllinit.h”

 

int main()

{

GraphicalEngineInit(3,1,1,640,480,true);

//Цикл расчетов...

EngineUnInit(); // можно опустить, вызовется автоматически при

//завершении программы

}

2.4.2 Задание входных данных

Возможно несколько способов задания входных данных.

  1. 1.Установка значений параметров и переменных состояния компонент (см. п.п. 2.3.4 и 2.3.5).
  2. 2.Задание входных изображений графического движка.

Для задания входного изображения используется функция void Env_SetInputImage(int number, unsigned char* image, int width, int height, int cmodel) с параметрами:

-       int number – индекс входа (в соответствии с числом входов заданных при инициализации).

-       unsigned char* image – указатель на область памяти со значениями яркостей пикселей изображения.

-       int width – ширина передаваемого изображения.

-       int height – высота передаваемого изображения.

-       int cmodel – цветовая модель передаваемого изображения (обычно допустимые значения 400 (8бит на пиксель, черно-белое), и 3 (24 бита на пиксель, цветное BGR)).

Пример кода задания входного изображения:

#include “rdk_dllinit.h”

int main()

{

GraphicalEngineInit(3,1,1,640,480,true);

 

unsigned char* buffer=0; // Буфер пикселей изображения

int width=0, height=0;

 

//Цикл расчетов...

for(int i=0;i<100;i++)

{

// здесь откуда-то получаем данные изображения и заполняем buffer,

// width и height...

Env_SetInputImage(0, buffer, width, height, 3); // Предполагаем,

// что изображение в буфере цветное BGR

 

// ...здесь выполнение расчетов

}

EngineUnInit(); // можно опустить, вызовется автоматически при

//завершении программы

}

 

Для принудительного задания выходных изображений отдельных компонент используется функция const void* const Model_ SetComponentBitmapOutput ( const char * stringid, int index, void * bmp ), с параметрами:

-       stringid – строковой Id компонента .

-       index – индекс выхода .

-       bmp – указатель на структуру вида:

struct UBitmap

{

unsigned char *Data; // Значения пикселей изображения

int ColorModel; // Формат изображения

int Width, Height; // размеры изображения по осям

int Length; // Число пикселей изображения

int ByteLength; // Число элементов UBColor изображения

int MemoryLength; // Число байт выделенной памяти

int ChannelOffset[4]; // Смещения цветовых каналов

int LineByteLength; // Длина строки изображения в байтах

int PixelByteLength; // Длина пикселя изображения в байтах

unsigned char* PData; // Указатель на текущий элемент изображения

};

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

 

Пример кода задания выходного изображения:

#include “rdk_dllinit.h”

int main()

{

GraphicalEngineInit(3,1,1,640,480,true);

 

unsigned char* buffer=0; // Буфер пикселей изображения

int width=0, height=0;

UBitmap input_image;

 

//Цикл расчетов...

for(int i=0;i<100;i++)

{

// здесь откуда-то получаем данные изображения и заполняем buffer,

// width и height...

Env_SetInputImage(0, buffer, width, height, 3); // Предполагаем,

// что изображение в буфере цветное BGR

Env_Calculate();

 

// Принудительное задание выходного изображения

input_image.SetRes(640,480,400); // Предполагаем, что изображение в

//буфере черно-белое (400)

Model_SetComponentBitmapOutput(“Pipeline1.BinarizationInPixel”, 0, &input_image);

 

}

EngineUnInit(); // можно опустить, вызовется автоматически

Для принудительного задания входных изображений отдельных компонент используется функция const void* const Model_SetComponentBitmapInput(const char *stringid, int index, void *bmp).

Использование аналогично функции Model_ GetComponentBitmapOutput.

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

 

2.4.3 Доступ к компонентам

Возможно два способа доступа к компонентам:

-       по идентификатору,

-       по имени.

Идентификатор компонента (Id) представляет собой число, которое однозначно определяет компонент в составе родительского компонента. Последовательность таких идентификаторов, однозначно определяет глобальное размещение компонента в составе модели. Во всех функциях RDK, где используется идентификатор компонента, он записывается в виде строковой последовательности чисел, разделяемых знаком точки. Например “1” – определяет компонент, располагающийся непосредственно в модели,“1.4” – означает компонент с Id=4, располагающийся в компоненте модели с Id=1. Идентификатор состоящий из одного числа – называют коротким Id. Составной идентификатор называют длинным Id. Составной идентификатор, записанный в форме строки, называют строковым Id.

Каждому идентификатору однозначно соответствует строковое имя. Правила формирования длинных имен аналогичны соответствующим правилам для идентификаторов. Так например имя объекта, лежащего непосредственно в модели может быть записано например так: “Pipeline1”. Длинное имя дочернего компонента, вложенного в Pipeline1, может быть записано как “Pipeline1.Contrasting”.

Во всех функциях RDK, где используется идентификатор компонента, можно произвольно использовать как длинный Id, так и длинное имя.

2.4.4 Ввод-вывод данных параметров компонент

Для доступа к параметрам компонент используются следующие функции:

-       Model_GetComponentParameters – чтение параметров компонента.

-       Model_SetComponentParameters – запись параметров компонента.

Для чтения параметров компонент, необходимо вызвать функцию const char * Model_GetComponentParameters(const char *stringid), с параметром –строковой Id компонента. Функция возвращает XML описание следующего вида, показанного в исходном коде ниже. Корневой тег описания представляет собой длинное имя компонента, и содержит тег Parameters, в котором уже перечислены имена, типы данных и значения параметров компонента.

<Pipeline1.FileIO>

      <Parameters>

            <Activity Type="bool">1</Activity>

            <AutoNumInputs Type="bool">1</AutoNumInputs>

            <BinFlag Type="int">0</BinFlag>

            <ClearFlag Type="int">0</ClearFlag>

            <Coord Type="MVector">

                  <x Type="double">0</x>

                  <y Type="double">0</y>

                  <z Type="double">0</z>

            </Coord>

            <Direction Type="int">1</Direction>

            <FileName Type="std::string" Size="6">in.txt</FileName>

            <Id Type="int" Header="">21</Id>

            <Name Type="std::string" Size="6">FileIO</Name>

            <NumInputs Type="int">1</NumInputs>

            <NumOutputs Type="int">1</NumOutputs>

            <ReadPartSize Type="int">2048</ReadPartSize>

            <TimeStep Type="int">2000</TimeStep>

      </Parameters>

</Pipeline1.FileIO>

         Важно помнить, что возвращаемые функциями RDK указатели указывают на временную область памяти, которая должна быть скопирована для дальнейшего использования, до вызова другой функции RDK.

         Для записи параметров компонент следует пользоваться функцией bool Model_SetComponentParameters(const char *stringid, const char* buffer), с параметрами:

-       stringidстроковой Id компонента.

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

2.4.5 Ввод-вывод переменных состояния компонент

Ввод-вывод значений переменных состояния компонент полностью аналогичен вводу-выводу значений параметров, за исключением того, что для переменных состояния используются функции:

-       Model_GetComponentState – чтение состояния компонента.

-       Model_SetComponentState – запись состояния компонента.

2.4.6 Расчет и время

Для расчета используется вызов функции int Env_Calculate(const char* stringid), с параметром – строковой Id компонента, подлежащего расчету. Если stringid=0 (значение по умолчанию), то осуществляется расчет всех компонент модели.

Пример использования:

#include “rdk_dllinit.h”

int main()

{

GraphicalEngineInit(3,1,1,640,480,true);

 

unsigned char* buffer=0; // Буфер пикселей изображения

int width=0, height=0;

 

//Цикл расчетов...

for(int i=0;i<100;i++)

{

// здесь откуда-то получаем данные изображения и заполняем buffer,

// width и height...

Env_SetInputImage(0, buffer, width, height, 3); // Предполагаем,

// что изображение в буфере цветное BGR

Env_Calculate();

 

// ...здесь получение результатов расчетов

}

EngineUnInit(); // можно опустить, вызовется автоматически при

//завершении программы

}

 

         Между вызовом функции Env_Calculate с нулевым аргументом, и с указанием конкретного компонента, подлежащего расчету, имеется фундаментальное различие. Его объяснение требует введения понятия времени в RDK.

Существует 2 времени:

-       Реальное время, протекающее вне зависимости от процесса счета, информация о котором получается от системного таймера.

-       Модельное время, характеризующее время, прошедшее в модели, за одну итерацию счета, вне зависимости от фактически затраченного на расчет этой итерации времени.

Функция Env_Calculate с нулевым аргументом, осуществляет проведение одной итерации расчета, и затем соответствующее увеличение модельного времени на требуемую величину. При указании для расчета конкретного компонента, увеличения модельного времени не происходит, т.к. система не может знать, завершен ли индивидуальный расчет всех требуемых компонент. Поэтому по завершении такого индивидуального расчета всех компоннет необходимо однократно вызвать функцию void Env_IncreaseModelTimeByStep(void).

Подробнее об управлении времени см. п.2.4.6.

2.4.7 Получение выходных данных

Возможно несколько способов получения выходных данных.

  1. 1.Получение значений переменных состояния компонент (см. п. 2.3.5).
  2. 2.Получение выходных изображений ядра видеообработки (не рекомендуется).
  3. 3.Получение выходных изображений отдельных компонент.

Для получения выходного изображения ядра видеообработки используется функция unsigned char* Env_GetOutputImage(int index) с параметром – индексом выхода (в соответствии с числом выходов заданных при инициализации). Функция возвращает указатель на область памяти, содержащую значения пикселей изображения, или 0, если по какой-то причине данные отсутствуют.

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

-       Env_GetOutputImageWidth – возвращает ширину изображения.

-       Env_GetOutputImageHeight – возвращает высоту изображения

-       Env_GetOutputImageColorModelвозвращает цветовую модель.

 

Для получения выходных изображений отдельных компонент используется функция const void* const Model_GetComponentBitmapOutput(const char *stringid, int index), с параметрами :

-       stringid – строковой Id компонента .

-       index – индекс выхода .

Функция возвращает указатель на структуру вида:

struct UBitmap

{

unsigned char *Data; // Значения пикселей изображения

int ColorModel; // Формат изображения

int Width, Height; // размеры изображения по осям

int Length; // Число пикселей изображения

int ByteLength; // Число элементов UBColor изображения

int MemoryLength; // Число байт выделенной памяти

int ChannelOffset[4]; // Смещения цветовых каналов

int LineByteLength; // Длина строки изображения в байтах

int PixelByteLength; // Длина пикселя изображения в байтах

unsigned char* PData; // Указатель на текущий элемент изображения

};

Пример кода получения выходного изображения:

#include “rdk_dllinit.h”

 

int main()

{

GraphicalEngineInit(3,1,1,640,480,true);

 

unsigned char* buffer=0; // Буфер пикселей изображения

int width=0, height=0;

UBitmap *output_image=0;

 

//Цикл расчетов...

for(int i=0;i<100;i++)

{

// здесь откуда-то получаем данные изображения и заполняем buffer,

// width и height...

Env_SetInputImage(0, buffer, width, height, 3); // Предполагаем,

// что изображение в буфере цветное BGR

Env_Calculate();

 

// Получение результирующих изображений

output_image=(UBitmap*)Model_GetComponentBitmapOutput(“Pipeline1.BinarizationInPixel”, 0);

 

}

EngineUnInit(); // можно опустить, вызовется автоматически при

//завершении программы

}

 

Для получения входных изображений отдельных компонент используется функция const void* const Model_GetComponentBitmapInput(const char *stringid, int index).

Использование аналогично функции Model_ GetComponentBitmapOutput.

 

2.4.8 Доступ к системному журналу и обработка исключительных ситуаций

Библиотека генерирует и самостоятельно обрабатывает определенный набор исключений, и также, в определенных случаях (при выполнении операций с деревом компонент, например при итерации счета), может перехватывать и обрабатывать все системные исключения.

Пользовательское приложение информируется об наступлении исключительной ситуации при помощи обратного вызова функции, указатель на которую передается функции инициализации ядра (см. п.2.4.1.1).

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

-       Engine_GetExceptionHandler – возвращает текущий указатель на функцию обратного вызова.

-       Engine_SetExceptionHandler – устанавливает новый указатель на функцию обратного вызова. Принимает аргумент void* value – адрес функции.

-       Engine_GetLog – возвращает массив строк лога.

2.5 Дополнительные функции управления

2.5.1 Параметрами компонент

Для доступа к параметрам компонент также существуют следующие функции:

-       Model_GetComponentParametersEx – возвращает параметры компонента с описаниями. Функция работает аналогично Model_GetComponentParameters (см п.2.3.4), но каждый параметр в получаемом XML-описании, имеет дополнительный атрибут Header, содержащий описание параметра. Описание параметров содержится в файле ClassesDescription.xml, загружаемом при инициализации ядра.

-       Model_GetComponentSelectedParameters – возвращает выборочные параметры компонента. Не реализована.

-       Model_GetComponentParameterValue – возвращает значение параметра компонента по идентификатору компонента и имени параметра. Принимает два аргумента const char *stringid – строковой Id компонента, const char *paramname – имя параметра, значение которого необходимо прочитать. Возвращает содержимое соответствующего тега в XML описании.

-       Model_SetComponentParameterValue – Устанавливает значение параметра компонента по идентификатору компонента и имени параметра. Принимает три аргумента const char *stringid – строковой Id компонента, const char *paramname – имя параметра, значение которого необходимо записать, const char *buffer – содержимое соответствующего тега в XML-описании.

2.5.2 Переменными состояния компонент

Для доступа к переменным состояния компонент также существуют следующие функции:

-       Model_GetComponentSelectedState – возвращает выборочные переменные состояния компонента. Не реализована.

-       Model_GetComponentStateValue – возвращает значение переменной состояния компонента по идентификатору компонента и имени параметра. Принимает два аргумента const char *stringid – строковой Id компонента, const char *statename – имя переменной состояния, значение которой необходимо прочитать. Возвращает содержимое соответствующего тега в XML описании.

-       Model_SetComponentStateValue – Устанавливает значение переменных состояния компонента по идентификатору компонента и имени параметра. Принимает три аргумента const char *stringid – строковой Id компонента, const char *statename – имя переменной состояния, значение которой необходимо записать, const char *buffer – содержимое соответствующего тега в XML-описании.

2.5.3 Счетом

2.5.3.1.     Сброс процесса счета

Для сброса счета и приведения модели в исхоное состояния используется функция int Env_Reset(const char* stringid). Если stringid=0, то осуществляется сброс всей модели.

2.5.3.2.     Расчет в режиме эмуляции реального времени

Если необходимо, чтобы внутреннее время модели автоматически поддерживалось равным прошедшему от последнего сброса счета реальному времени, то необходимо использовать функцию void Env_RTCalculate(void), вместо Env_Calculate. При вызове этой функции ядро автоматически определяет, сколько реального времени прошло с момента последнего расчета, сколько реального времени необходимо на одну итерацию, и выполняет столько итераций счета, сколько необходимо, чтобы модельное время совпало с реальным.

Этот режим обычно не используется, если модель зависит от предоставляемых извне данных (например, модель видеоаналитики, получающая входные кадры через вызов функции Env_SetInputImage). Обычное применение режима, когда входные и выходные данные получаются через интерфейсные компоненты внутри модели, а сама модель представляет собой решение системы дифференциальных уравнений.

2.5.4 Управлением хранилищем объектов

Хранилище объектов с точки зрения пользователя предоставляет информацию об идентификаторах классов компонент, доступных для использования при построении модели алгоритма. Для этой цели существуют следующие функции:

-       int Storage_GetNumClasses(void) – возвращает число классов в хранилище

-       void Storage_GetClassesList(int *buffer) – возвращает id классов в хранилище. Память должна быть выделена

-       const char * Storage_GetClassName(int id) – возвращает имя класса по его id.

-       int Storage_GetClassId(const char *name) – возвращает Id класса по его имени.

 

2.5.5 Созданием и удалением модели

Для управлением моделью существуют следующие функции:

-       int Model_Destroy(void) – удаляет существующую модель. Если модель не существует, то не делает ничего.

-       int Model_Create (int classid) – создает новую модель. Модельь может быть создана на основе любого класса компонента, определяемого идентификатором ‘classid’.

-       int Model_Clear(void) – удаляет из модели все компоненты.

-       bool Model_Check(void) – проверяет, существует ли модель. Возвращает true если модель существует, и false если нет.

2.5.6 Добавлением и удалением компонент из модели

Для управления структурой компонент в составе модели существуют следующие основные функции:

-       int Model_AddComponent(const char* stringid, int classid) – добавляет в выбранный компонент модели с идентификатором 'stringid' экземпляр компонента с заданным 'classid'.

-       int Model_DelComponent(const char* stringid, int id) – удаляет из выбранного компонента модели с идентификатором 'stringid' экземпляр компонента с заданным 'id'.

-       int Model_GetNumComponents(const char* stringid) ­– возвращает число всех компонент в заданном компоненте 'stringid'.

-       int Model_GetComponentsList(const char* stringid, int *buffer) – возвращает массив id всех компонент заданного компонента 'stringid'.

2.5.7 Отношениями между именем компонента и его идентификатором

Существует набор функций для определения имени компонента по его идентификатору:

-       const char* Model_GetComponentName(const char* stringid) – возвращает короткое имя компонента по заданному строковому Id 'stringid'.

-       const char* Model_GetComponentLongName(const char* stringid, const char* owner_level_stringid=0) – возвращает длинное имя компонента по заданному 'stringid'. Имя формируется до уровня компонента owner_level_stringid. Если owner_level_stringid=0, то имя формируется до уровня текущего компонента (обычно уровень модели).

-       const char* Model_GetComponentLongId(const char* stringid, const char* owner_level_stringid=0) – возвращает длинный id компонента по заданному 'stringid'. Имя формируется до уровня компонента owner_level_stringid. Если owner_level_stringid=0, то имя формируется до уровня текущего компонента (обычно уровень модели). Эта функция обычно используется для получения по известному строковому Id компонента, его строкового Id до другого уровня иерархии в модели.

2.5.8 Связями компонент

Каждый компонент может иметь N входов и M выходов. Каждый выход может быть связан с произвольным числом входов других компонент, а также своих входов. При этом к каждому входу может быть подключен только один выход. Связь между входом и выходом полностью определяется строковым Id и индексом выхода компонента-источника сигнала, строковым Id и индексом входа компонента-приемника сигнала. При этом, индекс входа может быть опущен (=-1), в этом случае при установлении связи, компонент-приемник сигнала будет пытаться создать новый вход для подключения, если это разрешено соответствующим параметром AutoNumInputs этого компонента.

Для управления связями используются следующие функции:

-       int Model_CreateLink(const char* stringid1, int output_number, const char* stringid2, int input_number) – связывает выбранные компоненты друг с другом

-       int Model_BreakLink(const char* stringid1, int output_number, const char* stringid2, int input_number) ­– разрывает выбранную связь.

-       int Model_BreakAllLinks(void) – разрывает все связи.

-       int Model_BreakAllComponentLinks(const char* stringid) – разрывает все входные и выходные связи выбранного контейнера.

-       int Model_BreakAllComponentInputLinks(const char* stringid) – разрывает все входные связи выбранного контейнера

-       int Model_BreakAllComponentOutputLinks(const char* stringid) – разрывает все выходные связи выбранного контейнера

-       const char * Model_GetComponentInternalLinks(const char* stringid) – возвращает все связи внутри компонента stringid в виде xml в буфер buffer.

-       int Model_SetComponentInternalLinks(const char* stringid, const char* buffer) – устанавливает все связи внутри компонента stringid из строки xml в буфере buffer.

-       const char * Model_GetComponentInputLinks(const char* stringid) – Возвращает все входные связи к компоненту stringid в виде xml в буфер buffer.

-       const char * Model_GetComponentOutputLinks(const char* stringid) – Возвращает все выходные связи из компонента stringid в виде xml в буфер buffer.

Также существует ряд функций для формирования цепочек связей:

-       int Model_ChainLinking(const char* stringid) – связывает все компоненты выбранного компонента по возрастанию id в формате: 0 выход к 0 входу. Компонент с минимальным id привязывается к необходимому числу выходов модели. Обычно используется для построения простых цепочек обработки.

-       int Model_ParallelLinking(const char* stringid) – Связывает все компоненты выбранного компонента параллельно, подключая их к необходимому числу выходов модели. Обычно используется для тестирования производительности различных компонент.

2.5.9 Входами и выходами компонент

У каждого компонента существует N входов и M выходов. Каждый вход и выход представляют собой в общем случае массив байт, разбитый по элементам, где каждый элемент имеет длину K байт. Одновременно с этим каждый вход и выход может иметь соответствующее ему изображение, однако этот аспект в данном пункте не рассматривается.

Для управления данными входов и выходов существуют следующие функции:

-       int Model_GetComponentNumInputs(const char *stringid) – возвращает число входов у компонента.

-       int Model_GetComponentInputDataSize(const char *stringid, int index) –возвращает размер входа компонента в числе элементов.

-       int Model_GetComponentInputElementSize(const char *stringid, int index) –возвращает размер элемента входа в байтах.

-       int Model_GetComponentInputByteSize(const char *stringid, int index) – возвращает размер входа компонента в байтах.

-       unsigned char* Model_GetComponentInputData(const char *stringid, int index) – возвращает указатель на данные входа как на массив байт. Только для чтения!

-       int Model_GetComponentNumOutputs(const char *stringid) – возвращает число выходов у компонента.

-       int Model_GetComponentOutputDataSize(const char *stringid, int index) – возвращает размер выхода компонента в числе элементов.

-       int Model_GetComponentOutputElementSize(const char *stringid, int index) – возвращает размер элемента выхода в байтах.

-       int Model_GetComponentOutputByteSize(const char *stringid, int index) – возвращает размер выхода компонента в байтах.

-       unsigned char* Model_GetComponentOutputData(const char *stringid, int index) – возвращает указатель на данные выхода как на массив байт. Только для чтения!

2.5.10 Загрузкой и сохранением модели

Существует три способа загрузки и сохранения модели:

-       Полная, включая структуру модели, связи между компонентами и значения параметров всех компонент (но исключая значения переменных состояния).

-       Только значения параметров всех компонент модели без изменения текущей структуры модели и связей.

-       Только значения переменных состояния всех компонент модели без изменения текущей структуры модели, связей и параметров.

Ниже представлены функции, реализующие все три способа.

Полная загрузка и сохранение реализуется вызовом следующих функций:

-       const char * Model_SaveComponent(const char *stringid) – сохраняет все внутренние данные компонента со строковым Id stringid, и всех его дочерних компонент, исключая переменные состояния в XML-описание и возвращает указатель на него.

-       int Model_LoadComponent(const char *stringid, char* buffer) – загружает все внутренние данные компонента со строковым Id stringid, и всех его дочерних компонент, исключая переменные состояния из xml, расположенном в строке buffer.

Загрузка и сохранение параметров реализуется вызовом следующих функций:

-       const char * Model_SaveComponentParameters (const char *stringid) – сохраняет все параметры компонента со строковым Id stringid, и всех его дочерних компонент в XML-описание и возвращает указатель на него.

-       int Model_LoadComponentParameters (const char *stringid, char* buffer) – загружает все параметры компонента со строковым Id stringid, и всех его дочерних компонент из xml, расположенном в строке buffer.

Загрузка и сохранение переменных состояния реализуется вызовом следующих функций:

-       const char * Model_SaveComponentState (const char *stringid) – сохраняет все переменные состояния компонента со строковым Id stringid, и всех его дочерних компонент в XML-описание и возвращает указатель на него.

-       int Model_LoadComponentState (const char *stringid, char* buffer) – загружает все переменные состояния компонента со строковым Id stringid, и всех его дочерних компонент из xml, расположенном в строке buffer.

2.5.11 Доступом ко времени и статистике производительности компонент

2.5.11.1. Шаг счета

Для управления счетом компонент существует возможность задать шаг счета для каждого компонента, определяющего какое время модели протекает за одну итерацию счета для этого компонента. Шаг задается как цело число и исчисляется тысячными долями секунды. Например значение шага 1000 означает изменение времени модели на 0.001 с за итерацию расчета.

Следующие функции позволяют управлять шагом счета:

-       int Model_GetTimeStep(const char *stringid) – возвращает шаг счета компонента с заданным stringid.

-       void Model_SetTimeStep(const char *stringid, int value) – устанавливает шаг счета компонента с заданным stringid в значение value.

-       void Model_SetGlobalTimeStep(const char *stringid, int value) – устанавливает шаг счета компонента с заданным stringid и всех его дочерних компонент.

2.5.11.2. Время модели

Для доступа и управления временем модели используются следующие функции:

-       long long Model_GetTime(void) – возвращает текущее время модели в микросекундах от начала расчета (с последнего сброса процесса счета).

-       double Model_GetDoubleTime(void) – возвращает текущее время модели в секундах и дробных долях секунды от начала расчета (с последнего сброса процесса счета).

-       bool Model_SetTime(long long value) – задает текущее время модели в микросекундах от начала расчета. Обычно не требуется.

2.5.11.3. Реальное время

Для доступа и управления реальным временем существуют следующие функции:

-       long long Model_GetRealTime(void) – возвращает текущее реальное время в микросекундах от начала расчета (с последнего сброса процесса счета).

-       double Model_GetDoubleRealTime(void) – возвращает текущее реальное время в секундах и дробных долях секунды от начала расчета (с последнего сброса процесса счета).

-       bool Model_SetRealTime(long long value) – задает текущее реальное время для ядра в микросекундах от начала расчета. Обычно не требуется.

-       bool Model_IncreaseRealTime(long long value) – увеличивает реальное время на заданную величину. Обычно не требуется.

2.5.11.4. Анализ быстродействия

Для анализа производительности расчета ядра существуют следующие функции:

-       long long Model_GetStepDuration(const char *stringid) – возвращает время расчета компонента без времени расчета дочерних компонент в миллисекундах.

-       long long Model_GetFullStepDuration(const char *stringid) – возвращает время расчета компонента (вместе со времени расчета дочерних компонент) в миллисекундах.

-       double Model_GetInstantPerformance(const char *stringid) – возвращает мгновенное быстродействие, равное отношению полного затраченного времени к ожидаемому времени шага счета.

2.6 Упрощенный способ доступа к значениям параметров и переменных состояния для C++ разработчика

Разработчики приложений на C++ могут включить в проект файлы myrdk.h, myrdk.xxx.cpp (xxx – имя используемого окружения, например bcb, win, gcc, ansi). Это позволяет напрямую использовать множество вспомогательных классов и функций, применяемых в ядре (подробнее см. документ RDK.DevelopersGuide.doc), и в частности таким образом организовать более удобное взаимодействие приложения с ядром RDK.

Для упрощенного доступа к параметрам используются следующие шаблонные функции:

template<typename T>

T& ReadParameterValue(const std::string &comp_name, const std::string &param_name, T &res);

 

template<typename T>

T ReadParameterValue(const std::string &comp_name, const std::string &param_name);

Здесь comp_name – строковой Id компонента;

         param_name – имя параметра;

         res – опциональный буфер для возвращаемого результата.

Аналогичные функции существуют для упрощенного доступа к переменным состояния:

template<typename T>

T& ReadStateValue(const std::string &comp_name, const std::string &state_name, T &res);

 

template<typename T>

T ReadStateValue(const std::string &comp_name, const std::string &state_name);

Здесь comp_name – строковой Id компонента;

         state_name – имя переменной состояния;

         res – опциональный буфер для возвращаемого результата.

3 Использование с прямым доступом к классам управляющего ядра

Для прямого доступа к экземплярам классов управляющего ядра необходимо подключить в конечное ПО файл rdk_cpp_initxxx.h (см. п. 2.1) и использовать следующие функции для доступа к ядру:

-       RDK::UEPtr<RDK::UEngine>& GetEngine(void) – возвращает ссылку на указатель собственно экземпляра класса ядра;

-       RDK::UEPtr<RDK::UAEnvironment>& GetEnvironment(void) – ссылку на указатель среды выполнения;

-       RDK::UEPtr<RDK::UAStorage>& GetStorage(void) – возвращает ссылку на указатель хранилища;

-       RDK::UEPtr<RDK::UAContainer> GetModel(void) – возвращает указатель на текущую модель обработки;

Для работы с этими указателями необходимо ознакомится с документом RDK.DevelopersGuide.doc.

4 Использование компонент в явном виде в коде

Необходимо ознакомится с документом RDK.DevelopersGuide.doc.

Заключение

         Рассмотрен основной функционал ядра RDK, в объеме, достаточном для использования как готовой библиотеки.

         Следующим этапом необходимо ознакомление с документом RDK.StandardComponentDescription.UsersGuide.doc, содержащим описание существующих компонент с точки зрения пользователя.

Разработки RDK RDK: Применение библиотеки в проекте