Русские мануалы по vst

Вашему вниманию предоставляется перевод руководства пользователя по СДК ВСТ — библиотеки, которая необходима для создания Вашего собственного ВСТ МИДИ плагина на языке объектно-ориентированого программирования С++. Скачать саму СДК библиотеку можно с официального сайта. Для скачивания Вам необходимо зарегестрироваться как разработчику ВСТ плагинов. На данный момент на официальном сайте есть две СДК библиотеки — стандартная, 3.1 версии и «модульная архитектура». Документацию стандартной СДК библиотеки я переведу чуть позже. Сейчас же я перевожу документацию модульной архитектуры ВСТ, ориентированной для создания ВСТ плагинов, работающих с МИДИ данными.

Первый логичный вопрос, который пришёл лично мне в голову : «Какую из этих двух СДК библиотек осваивать ?». Стандартная библиотека предназначена для разработки ВСТ плагинов работающих с аудио данными. Данная же СДК библиотека используется для разработки  МИДИ плагинов, работающих с миди сообщениями, её плюсом является кроссплатформеность.

Пара слов о устройстве библиотеки: Это первая часть руководства, в которой даётся справочная теоретическая часть. Во второй части даются непосредственные указания по созданию ВСТ МИДИ плагина, перечисляются классы С++ для работы с МИДИ данными. Вся СДК библиотека (первая и вторая часть) представляет собой сборку так называемых ИНТЕРФЕЙСОВ. Интерфейс — это в свою очередь сборка МЕТОДОВ. Методы и предназначены для работы с МИДИ данными. Методы объединены в интерфейсы по типу своего действия. Называются методы так: «Название интерфейса:название метода«.

В целом не пугайтесь первой части, просмотрите её, после чего просмотрите вторую часть, должно стать более понятно, обратите внимание на наличие примера в данной СДК библиотеке.

Итак скачиваем архив с СДК библиотекой «VST Module Architecture SDK». Распаковываем с помощью архиватора вроде WinRar. На изображении ниже дана краткая информация о содержимом архива:

Рекомендации по работе с руководством:

Зелёным цветом — выделены заголовки интерфейсов библиотеки.

Оранжевым цветом — выделены методы интерфейсов библиотеки.

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

Хочу заметить то что всё руководство собрано в одном файле. Благодаря чему Вы можете задать поиск на странице того что Вас интересует, например  метода «IViewFactory»  и сразу же найти где он используется. В опере работать особенно удобно так как искомые слова подсвечиваются. 🙂

Введение

Модульная ВСТ архитектура, описанная в данном документе, является объектно-ориентированой кросс-платформенной и независимо компилируемой моделью. Она описывает как должны выглядеть компоненты и как они взаимодействуют с хост-программой (в которую загружается плагин). Мы можем разделить специфику на три группы:

1. Связь интерфейсов

Всё с чем может работать как плагин, так и хост-программа. Данный интерфейс в С++ реализован в качестве класса, использующего только визуальные методы. Базовым интерфейсом является FUnknown. Все остальные интерфейсы являются прямыми или косвенными производными от него.

2. Интерфейс экспорта модулей

Модуль  — в операционной системе Виндоус под модулем понимается  динамическая библиотека, хранящаяся в .dll файлах (формат ВСТ плагинов). В операционной системе  Макинтош — это «.o, .dylib» файлы. Модули содержат в себе один или несколько классов плагина, например описывающих различные миди эффекты (содержащиеся в плагине). Работает с GetPluginFactory, С-подобная функция, используемая для создания заводских объектов, рассмотрена позже.

3. Специфические интерфейсы

Каждая разновидность плагинов (миди эффекты и т.д.) описывает свои собственные интерфейсы. Также как некоторые базовые интерфейсы описаны во всех категориях плагинов.

COM совместимость

Рыба СОМ расшифровывается на английский язык как «Component Object Model» (Объектная Модель Компонентов). Данный стандарт используется при создании новых программ под ОС Виндоус. Наша СДК библиотека бинарно совместима с этим стандартом, благодаря интерфейсу FUnknown. Библиотека не нуждается в каких-то СОМ исходниках.

Базовый интерфейс

FUnknown

Наследование: нет

Подключаемый файл: funknown.h

Метод FUnknown::queryInterface используется для связи указателей (pointer, в программировании — ссылка на опр. объект/код) с объектами других интерфейсов. Методы  FUnknown::addRef и FUnknown::release используются для обозначения времени жизни (активности) объекта. Если связей больше не существует — объект уничтожается и больше не использует ресурсы памяти.

Интерфейсы идентифицируются 16-ти байтными глобальными уникальными идентификаторами. Библиотека СДК содержит класс, называемый  FUID, и используемый для этих целей.

Методы:

FUnknown::release

FUnknown::queryInterface

FUnknown::addRef

FUnknown::queryInterface

tresult PLUGIN_API queryInterface (const char* iid, void** obj)

Запрос к указателю, находящегося в определённом интерфейсе. Возващает kResultOk в случае успеха, или же kNoInterface в случае отсутствия указанного объекта в данном интерфейсе. Объект использует addRef во время ответа на запрос.

Параметры:

iid	16-ти байтный идентификато интерфейса (FUID)
obj	Во время возврата, obj должен ссылаться на запрошенный интерфейс

FUnknown::addRef

unsigned long PLUGIN_API addRef ()

Добавляет ссылку (референт, в данном случае в смысле указания) и возвращает обновлённую ссылку. Считается при наличии более одного объекта.

FUnknown::release

unsigned long PLUGIN_API release ()

Отправляет ссылку и возвращает новое значение. Если колличество референтов превышает ноль, то объект удаляется из памяти.

Как описать класс из интерфейса

В первом примере мы опишем класс прямо из FUnknown, используя некоторые вспомогательные макросы из СДК:

class CMyClass: public FUnknown
{
public:
	CMyClass ();
	virtual ~CMyClass ();

	DECLARE_FUNKNOWN_METHODS  // декларирует ранее описанные queryInterface, addRef и release
};

CMyClass::CMyClass ()
{
	FUNKNOWN_CTOR // счётчик референтов (ссылок)
}

CMyClass::~CMyClass ()
{
	FUNKNOWN_DTOR // уменьшение (декремент) глобального счётчика объектов
}

IMPLEMENT_REFCOUNT (CMyClass) // реализует подсчёт ссылок (реферов)

tresult CMyClass::queryInterface (const char* iid, void** obj)
{
	QUERY_INTERFACE (iid, obj, ::FUnknown::iid, CMyClass)
	return kNoInterface;
}

Ниже приведён пример класса с более чем одним интерфейсом, реализованный с использованием множественного наследования. Также нужно учитывать то что Вы должны дать необходимые описания интерфейсов в queryInterface методе.

class CMyMultiClass:	public IPluginBase,
			public IPlugController,
			public IEditorFactory
{
public:
	DECLARE_FUNKNOWN_METHODS

	// декларирование методов всех наследующих интерфейсов производится здесь.
};

tresult CMyMultiClass::queryInterface (const char* iid, void** obj)
{
	QUERY_INTERFACE (iid, obj, ::FUnknown::iid, IPluginBase)
	QUERY_INTERFACE (iid, obj, IPluginBase::iid, IPluginBase)
	QUERY_INTERFACE (iid, obj, IPlugController::iid, IPlugController)
	QUERY_INTERFACE (iid, obj, IEditorFactory::iid, IEditorFactory)
	*obj = 0;
	return kNoInterface;
}

Типы данных

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

Ответ:	Описание
kNoInterface	Запрашиваемый интерфейс не существует (не выполняется), используется только в FUnknown::queryInterface
kResultTrue	То же что и kResultOk, всё хорошо.
kResultFalse	Ложь, без детальной информации об ошибке.
kInvalidArgument	Запрощику предоставляется неверный аргумент в качестве ответа
kNotImplemented	Функция не существует (не выполняется)
kInternalError	Произошла внутренняя ошибка
kNotInitialized	Объект инициализирован не корректно (IPluginBase::initialize)
kOutOfMemory	Не хватает памяти

FUID

Подключаемый файл: funknown.h

Библиотека СДК содержит С++ класс FUID для хранения 16-ти байтных глобальных уникальных идентификаторов. Каждый интерфейс декларирует свои идентификаторы в качестве статического (постоянного, константного, не изменяемого) участника внутри интерфейса (FUnknown::iid)

Методы:

FUID::print

FUID::generate

FUID::isValid

FUID::toString

FUID::fromString

FUID::toRegistryString

FUID::fromRegistryString

FUID::generate

bool generate ()

Генерирует новый уникальный идентификатор (UID), который будет возвращать правду в случае успеха или ложь в случае провала. В случае возвращения лжи — идентификатор не сгенерирован или же не является глобальным.

FUID::isValid

bool isValid ()

Проверяет — действительными являются ли данные идентификатора.

FUID::toString

void toString (char* string)

Конвертирует тип идентификатора в строку. Строки имеют длинну в 32 символа, используется ASCII кодирование.

FUID::toRegistryString

void toRegistryString (char* string)

Конвертирует тип идентификатора в строку формата OLE.

FUID::fromRegistryString

bool fromRegistryString (char* string)

Заберает данные идентификатора из строки в формате OLE.

FUID::print

void print (char* string = 0, long style = kINLINE_UID)

Печатает идентификатор в строку. Формат может быть одним из следующих: FUID::kINLINE_UID, FUID::kDECLARE_UID или FUID::kFUID.

ViewRect

Подключаемый файл: iplugui.h

struct ViewRect
{
long left;
long top;
long right;
long bottom;
};

описания на дано.

Основы плагина

GetPluginFactory

extern «C» PLUGIN_API IPluginFactory* GetPluginFactory ();

С точки зрения хост-программы, модуль плагина — это динамическая библиотека которая может создавать определённые типы объектов. Интерфейс IPluginFactory содержит методы предназначенные для получения информации о классах, экспортируемых плагином и механизм создания экземпляров этих классов. Хост-программа запрашивает GetPluginFactory на получение указателя к объекту IPluginFactory. На данный момент библиотека СДК уже использует динамическую .dll библиотеку плагина (смотри CPluginFactory в файле pluginfactory.h), которая должна отвечать на ваши запросы.  Всё что нужно сделать — это единожды зарегестрировать информацию о Вашем классе с помощью  CPluginFactory::registerClass.

PLUGIN_API IPluginFactory* GetPluginFactory ()
{
	if(!gPluginFactory)
	{
		gPluginFactory = new CPluginFactory (factoryInfo);

		//классы регистрируются тут...
		gPluginFactory->registerClass (pluginClass, myCreateFunc, 0);
	}
	else
		gPluginFactory->addRef ();

	return gPluginFactory;
}

Для компилирования данного кода Вы нуждаетесь в PFactoryInfo информации о .dll модуле, которая декларирована в файле  ipluginbase.h.

struct PFactoryInfo
{

char vendor[64]; // «Васькины плагины»
char url[256]; // «https://corpuscul.net»
char email[128]; //  «Vasia@mail.ru»
long flags; // смотри IPluginFactory::getFactoryInfo

}

struct PClassInfo
{

char cid[16];
long cardinality;
char category[kCategorySize];
char name[kNameSize];

};

Идентификаторы	Описания
PClassInfo::cid	Идентификатор класса используемый в IPluginFactory::createInstance. Каждый выполняющийся класс должен иметь свой собственный идентификатор. В ОС Видоус Вы можете использовать инструмент программы Visual Studio — Guidgen.exe для его генерирования.
PClassInfo::cardinality	В настоящее время игнорируется, следует установить параметр PClassInfo::kManyInstances.
PClassInfo::category	Категория строки класса, например kMidiModuleClass для миди эффектов. Взаимодействие хост программы с плагином определяется типом последнего, так например при использовании строки kMidiModuleClass — работа производится с интерфейсом IMidiEffect.
PClassInfo::name	Имя класса видимое пользователю, вроде «мой первый плагин».

При этом функция должна выглядеть как-то так:

FUnknown* myCreateFunc (void* context)
{

return (IPluginBase*)new CMyPlugin ();

}

Функция не нуждается в предописании, Вы можете использовать её где угодно.

Экспортирование GetPluginFactory

Для того чтобы функция GetPluginFactory была «видимой» для хост-программы её нужно экспортировать. При работе на языке С++ Вам необходимо добавить def файл в Ваш проект, который выглядит примерно так:

LIBRARY MyPluginName
EXPORTS

GetPluginFactory

Пример работы хоста

Хост-программа будет работать с Вашим плагином примерно так (пример вод ОС Виндоус):

HMODULE hModule = LoadLibrary ("SomePlugin.dll");
if(hModule)
{
	GetFactoryProc proc = (GetFactoryProc)GetProcAddress (hModule, "GetPluginFactory");

	IPluginFactory* factory = proc ? proc () : 0;
	if(factory)
	{
		for(long i = 0; i < factory->countClasses (); i++)
		{
			PClassInfo ci;
			factory->getClassInfo (i, &ci);

			FUnknown* obj;
			factory->createInstance (ci.cid, FUnknown::iid, (void**)&obj);
			...
			obj->release ();
		}

		factory->release ();
	}

	FreeLibrary (hModule);
}

IPluginFactory

Наследование: FUnknown <- IPluginFactory

Подключаемый файл: ipluginbase.h

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

Методы:

• IPluginFactory::getFactoryInfo
• IPluginFactory::countClasses
• IPluginFactory::getClassInfo
• IPluginFactory::createInstance

Давайте рассмотрим каждый из них подробнее

IPluginFactory::getFactoryInfo

tresult PLUGIN_API getFactoryInfo (PFactoryInfo* info);

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

Флаг PFactoryInfo:

kPluginClassesDiscardable

Колличество экспортируемых классов может изменяться каждый раз, когда .dll модуль загружается. Если данный флаг задан, хост-программа не кеширует информацию о классе. Это влияет на продолжительность загрузки плагина.

IPluginFactory::countClasses

long PLUGIN_API countClasses ();

Возвращает колличество экспортированных классов, или же классов зарегестрированных с помощью CPluginFactory::registerClass.

IPluginFactory::getClassInfo

tresult PLUGIN_API getClassInfo (long index, PClassInfo* info)

Заполняет структуру PClassInfo информацией об указанном в заголовке классе.

IPluginFactory::createInstance

tresult PLUGIN_API createInstance (const char* cid, const char* iid, void** obj);

Создаёт новый экземпляр класса. Параметры:

cid	Идентификатор создаваемого экземпляра класса (смотри PClassInfo::cid)
iid	Уникальный иденификатор запрашиваемого интерфейса
obj	Переменная, на которую ссылаются указатели при создании новых объектов.

IPluginBase

Наследование: FUnknown <- IPluginBase

Подключаемый файл: ipluginbase.h

Все экспортируемые плагином классы в некотором роде описываются в IPluginBase. Данный интерфейс содержит два метода:

• IPluginBase::initialize
• IPluginBase::terminate

IPluginBase::initialize

tresult PLUGIN_API initialize (FUnknown* context);

Плагин распознаёт в каком контексте он будет работать, используется следующим интерфейсом:

• IHostApplication

IPluginBase::terminate

tresult PLUGIN_API terminate ()

Данный метод запрашивается сразу же после удаления плагина для уничтожения всех связей с интерфейсами хост-программы.

Визуальный интерфейс GUI  плагина

Gui — это внешний вид плагина, каким видит его пользователь.

Gui использующий XML

Все хост-программы компании Стеинберг поддерживают описание визуального интерфейса плагина с помощью языка XML. Т.е. плагин содержит XML код а хост-программа воссоздаёт его внешний вид из соответствующих контроллеров (кнопок, регуляторов, меню и т.д.). Контроллер должен быть связан с определённым параметром (объектом), значение которого изменяется. Он получает сообщения когда пользователь изменят положение контроллера. В тоже время при изменении значения каким-либо объектом — изменяется и положение соответствующего контроллера. Все принимающие уастие в этом процессе интерфейсы  можно найти в файле iplugui.h:

IUIFactory	Обеспечивает XML описание и создаёт контроллер объекта (объектов)
IPlugController IGenericPlugController	Задаёт IParameter для каждого значения, активируется во время изменения значения (с которым связан контроллер)
IViewFactory	Создаёт заданный внешний вид плагина (смотри  IPlugView ). Используется для комбинирования XML технологии с другими GUI инструментами (VSTGUI,MFC,…)

Описание используемых XML тэгов будет дано позже.

Плагин GUI использующий VSTGUI

Компания Стеинберг представляет бесплатный кросс-платформенный набор инструментов для ВСТ плагинов, называемый VSTGUI. Также существует специальная версия библиотеки для работы с описываемой тут СДК библиотекой «VST Module Architecture«. Если Вы хотите использовать Ваши собственные настройки GUI (напримерMFC или Wim32) Вы должны добавить/выполнить  IViewFactory или IEditorFactory интерфейсы и Вашу собственную IPlugView.

Скачать VSTGUI. Я опишу работу с VSTGui позже.

IUIFactory

Наследование: FUnknown <- IUIFactory

Подключаемый файл: iplugui.h

Данный интерфейс сообщает о поддержке плагина работы с XML кодом. Методы:

• IUIFactory::createController
• IUIFactory::getViewDescription

IUIFactory::createController

tresult PLUGIN_API createController (char* name, IPlugController** c)

Создаёт контроллер объекта, имя описывает контекст в котором контроллер будет использован. «С» указывает на новый, только что созданный контроллер объекта. Используется хост-программой когда интерфейс более не нужен.

IUIFactory::getViewDescription

tresult PLUGIN_API getViewDescription (

char* name,
char* templateName,
char* xml,
long* bufferSize)

Данный метод предоставляет XML код, с помощью которого описывается плагин. Параметры:

Название	Контекстная строка для запрашиваесого XML кода
templateName	Если указатель действительный, плагин копирует имя создаваемого xml. Максимальная длинна — 128 байт.
xml	Если указатель действительный — плагин копирует XML код в буфер. Хост-программа просчитывает необходимое колличество памяти, ниже предоставлена заметка.
bufferSize	Если указатель действительный, устанавливает необходимое колличество памяти для хранения XML информации.

Заметка: IUIFactory::getViewDescription может быть вызвана несколько раз, с некоторыми указателями выставленными/заданными на ноль, для просчёта необходимого колличества памяти для XML кода. Ниже предоставлен пример кода хост-программы:

IUIFactory* factory; // действительная ссылка на модуль ( factory )
char templateName[128];
long xmlSize;

if(factory->getViewDescription ("editor", templateName, 0, &xmlSize) == kResultOk)
{
	char* xml = new char[xmlSize];
	if(factory->getViewDescription ("editor", 0, xml, 0) == kResultOk)
	{
		// создание редактора...
	}
	delete [] xml;
}

IUIFactory2

Наследование: FUnknown <- IUIFactory <- IUIFactory2

Подключаемый файл: iplugui.h

Интерфейс IUIFactory2 обеспечивает доступ к внутренним ресурсам плагина, которые могут быть использованы внутри XML описания пользовательского интерфейса (положения кнопок и т.д.). Методы:

• IUIFactory2::getResource

IUIFactory2::getResource

tresult PLUGIN_API getResource ( const char* path, char* buffer, long* bufferSize)

Копирует в буфер запрашиваемые ресурсы. Параметры:

path	Патч с ресурсами, описывается в XML коде, например «<bitmap name=»bitmap1″ path=»path_for_getResource«/>»
buffer	Если указатель действительный, то плагин копирует ресурсы в буфер. Хост-программа расчитывает необходимое колличество памяти (см. заметку).
bufferSize	Если указатель действительный, задаёт необходимое ресурсу колличество памяти.

Заметка: IUIFactory2::getResource может быть вызван несколько раз с некоторыми указателями назначенными на ноль, например для расчёта необходимого колличества памяти для хранения ресурса. Типичным ресурсом является изображение в следующих форматах: BMP, PNG, JPEG, PSD… Если ресурс загружен прямо в динамическую библиотеку .dll , убедитесь в добавлении изображений как raw ресурсов (RCDATA а не как BITMAP).

IViewFactory

Наследование:FUnknown <- IViewFactory

Подключаемый файл: iplugui.h

Данный интерфейс позволяет плагину смешивать собственные контроллеры с контроллерами хост программы. Интерфейс должен быть описан в IPlugController а не в объекте IUI factory. Методы:

• IViewFactory::createView
• IViewFactory::testCondition

IViewFactory::createView

tresult PLUGIN_API createView (
const char* name,
ViewRect* rect,
IPlugView** view)

Задаёт специфику отображения плагина. Параметры:

name	Отображение названия плагина как XML кода
rect	Отображение прямоугольника как XML кода
view	Ссылается на  новый, только что созданный объект. Используется хост программой когда в нём больше нет нужды.

Ниже приведён пример XML кода и соответствующий запрос функции IViewFactory::createView:

XML код:

	<view name="MyCustomView" size="0,0,500,300"/>

Запрос функции:

	IViewFactory* viewFactory; // ссылаемся на действительный модуль
	ViewRect rect (0, 0, 500, 300);

	IPlugView* view;
	if(viewFactory->createView ("MyCustomView", &rect, &view) == kResultOk)
	{
		...
		view->release ();
	}

IViewFactory::testCondition

tresult PLUGIN_API testCondition (const char* condition)

Тестирование условия, описанного в XML коде. Ниже приведён пример с запросом IViewFactory::testCondition:

XML код:

	<variant condition="mono AND NOT stereo"/>
	...
	</variant>

Запрос Функции:

	IViewFactory* viewFactory; // действительный указатель

	if(viewFactory->testCondition ("mono") && !viewFactory->testCondition ("stereo"))
	{
		// Условие выполнено (правда).
	}

IPlugView

Наследование: FUnknown <- IPlugView

Подключаемый файл: iplugui.h

Интерфейс IPlugView представляет определённую специфику отображения плагина. Создан с помощью IViewFactory::createView или IEditorFactory::createEditor.  Методы:

• IPlugView::attached
• IPlugView::removed
• IPlugView::idle
• IPlugView::onWheel
• IPlugView::onKey
• IPlugView::onSize

IPlugView::attached

tresult PLUGIN_API attached (void* parent)

Работа с приклиплением окна плагина к родительскому окну. Тип данных зависит от платформы, на ОС Виндоус — HWND, на Макинтош — WindowRef.

IPlugView::removed

tresult PLUGIN_API removed ()

Закрытие окна из родительского окна.

IPlugView::idle

tresult PLUGIN_API idle ()

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

IPlugView::onWheel

tresult PLUGIN_API onWheel (float distance)

Работает с колёсиком мышки, дистанция может быть положительная и отрицательная, в зависимости от движения колёсика.

IPlugView::onKey

tresult PLUGIN_API onKey (char asciiKey, long keyMsg, long modifiers)

Анализирует — нажатие пользователя на определённую клавишу, keyMsg описан в файле plugkeycodes.h.

IPlugView::onSize

tresult PLUGIN_API onSize (ViewRect* newSize)

Изменение положения или размера объекта. Происходит при изменении положения или размера родительского окна. При изменении размера используются стили описанные в XML.

IEditorFactory

Наследование: FUnknown <- IEditorFactory

Подключаемый файл: iplugui.h

Данный интерфейс используется при работе с плагином, внешний интерфейс GUI которого построен в других инструментах (VSTGUI,MFC,Win32) без использования кода XML. Методы:

• IEditorFactory::getEditorSize
• IEditorFactory::createEditor

IEditorFactory::getEditorSize

tresult PLUGIN_API getEditorSize (const char* name, ViewRect* rect)

Хост-программа запрашивает размер редактора, «name» задаёт контекст, в котором редактор будет использоваться (обычно «editor»).

IEditorFactory::createEditor

tresult PLUGIN_API createEditor (const char* name, ViewRect* rect, IPlugView** editor)

Создаёт редактор плагина. Параметры:

rect	Размер создаваемого редактора. Хост-программа передаёт размер методу через IEditorFactory::getEditorSize.
editor	Указатель на только что созданный объект редактора, используется когда в интерфейсе больше нет нужды.

Параметры плагинов

IPlugController

Наследование: FUnknown <- IPlugController

Подключаемый файл: iplugparams.h

Плагин передаёт свои параметры хост-программе с помощью интерфейса IPlugController. Хост-программа запрашивает параметры объектов, которые будут использоваться в дальнейшем, например для автоматизации. На практике, плагины должны использовать IGenericPlugController, который описан в IPlugController и осуществляет дополнительную функциональность. Методы:

• IPlugController::getParameter
• IPlugController::parameterChanged

IPlugController::getParameter

tresult PLUGIN_API getParameter (const char* name, IParameter** pp)

Получает параметр по имени, на возврате «рр» должен быть ассоциирован с указателем IParameter, или нулём в случае недействительности имени. Параметры должны существовать столько же, сколько существуют их контроллеры и должны быть уничтожены/удалены/дезактивированы после них.

IPlugController::parameterChanged

tresult PLUGIN_API parameterChanged (IParameter* p, long tag)

Значение параметра «р» было изменено. Вероятно причиной является автоматизация или изменение пользователем положения контроллера. «tag» — это идентификатор данного параметра, ассоциированый с IParameter::connect.

IGenericPlugController

Наследование: FUnknown <- IPlugController <- IGenericPlugController

Подключаемый файл: iplugparams.h

С помощью данного интерфейса хост программа производит нумерацию существующих параметров плагина. Методы:

• IGenericPlugController::countParameters
• IGenericPlugController::getParameterName
• IGenericPlugController::getParameterIndexed

IGenericPlugController::countParameters

long PLUGIN_API countParameters ()

Возвращает колличество действительных параметров.

IGenericPlugController::getParameterName

tresult PLUGIN_API getParameterName (long index, char str[128])

Копирует название параметра, находящего назагаловочной (индексной) позиции в буфер str.

IGenericPlugController::getParameterIndexed

tresult PLUGIN_API getParameterIndexed (long index, IParameter** pp)

Задаёт параметру объекта определённый заголовок. По возвращению, рр должен быть ассоциирован с указателем IParameter, или нулём в случае недействительного заголовка (index). Смотрите также описание метода IPlugController::getParameter.

IParameter

Наследственность: FUnknown <- IParameter

Подключаемый файл: iplugparams.h

Данный интерфейс представляет параметр объекта. Он включает в себя методы, используемые для  изменения текущих значений. Бибилиотека СДК поддерживает работу с параметрами базовых типов : integer, string, list. Методы:

• IParameter::toString
• IParameter::fromString
• IParameter::getValue
• IParameter::setValue
• IParameter::getMinValue
• IParameter::getMaxValue
• IParameter::connect

IParameter::toString

void PLUGIN_API toString (char str[128])

Конвертиует текущее значение в тип «строка». Значение «0» может быть представлено как «0», «ноль», «выключен»…

IParameter::fromString

void PLUGIN_API fromString (const char* str)

Задаёт значение исходя из строки, например «0» может быть получен из строки «выключен».

IParameter::getValue

long PLUGIN_API getValue ()

Возвращает текущее целое (int) значение параметра.

IParameter::setValue

void PLUGIN_API setValue (long value)

Задаёт текущее целое (int) значение параметра.

IParameter::getMinValue

long PLUGIN_API getMinValue ()

Возвращает минимальное целое значение параметра.

IParameter::getMaxValue

long PLUGIN_API getMaxValue ()

Возвращает максимальное целое значение параметра.

IParameter::connect

void PLUGIN_API connect (IPlugController* c, long tag)

Подсоединяет параметр к контроллеру объекта используя заданный идентификатор tag. Заданный контроллер «с» будет оповещён об изменении значения с использованием метода IPlugController::parameterChanged. Заметка: хост-программа не может изменять подсоединение/маршрутизацию параметров.

Хранение плагина

Всего есть два способа хранения текущего состояния плагина: с помощью интерфейса параметров плагина (рассмотренного только что) или же с помощью блоковой памяти (chunk). Хост-программа в начале запрашивает интерфейс плагина IPersistentChunk. Если таковой не найден — то сохраняются значения параметров. Блоковая память позволяет сохранить дополнительные данные (состояние определённого параметра). При использовании блоковой памяти — Вы должны позаботиться о сохранении и загрузке состояния параметров сами!

IPersistentChunk

Наследственность: FUnknown <- IPersistentChunk

Подключаемый файл: iplugstorage.h

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

• IPersistentChunk::getUID
• IPersistentChunk::setChunk
• IPersistentChunk::getChunk

IPersistentChunk::getUID

tresult PLUGIN_API getUID (char* uid)

Копирует 16 байт глобального уникального идентификатора в uid. Идентификатор используется для ассоциации блоковой памяти с плагином.

IPersistentChunk::setChunk

tresult PLUGIN_API setChunk (char* chunk, long size)

Запрашивается хост-программой для создания установки (пресета). Метод запрашисается дважды, в начале параметр блоковой памяти = 0, потом возвращается информация о необходимом объёме памяти для хранения установки, после чего хост-программы опять запрашивает IPersistentChunk::getChunk для сохранения значений параметров в блоковую память. Ниже предоставлен пример кода:

IPersistentChunk* plug; // действительный указатель

long size;
if(plug->getChunk (0, &size) == kResultOk && size > 0)
{

char* chunk = new char[size];
plug->getChunk (chunk, &size);
…
delete [] chunk;

}