Статьи:

Профиль:

SDK VST — руководство пользователя, создание МИДИ плагинов


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

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

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

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

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

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

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

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

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

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

Введение

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

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

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

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

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]; // «http://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;

    }

    2 комментарияSDK VST — руководство пользователя, создание МИДИ плагинов

    • corp

      Интерфейс хост-программы

      IHostApplication

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

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

      Данный интерфейс — это тот минимум, который осуществляется всеми хост-программами. На него также ссылается указатель IPluginBase::initialize.

      Методы:

      • IHostApplication::getName
      • IHostApplication::getVersion
      • IHostApplication::getBuild
      • IHostApplication::getApplicationPath
      • IHostApplication::getMainWindow

      IHostApplication::getName

      const char* PLUGIN_API getName ()

      Возвращает строку с названием хост-программы (например «Кубейс»). Указатель действителен пока действителен ссылающийся интерфейс.

      IHostApplication::getVersion

      const char* PLUGIN_API getVersion ()

      Возвращает строку с указанием версии программы (например «2.0″). Указатель действителен пока действителен ссылающийся интерфейс.

      IHostApplication::getBuild

      const char* PLUGIN_API getBuild ()

      Возвращает строку с указанием построения программы (например «100″). Указатель действителен пока действителен ссылающийся интерфейс. Я так и не разобрался что же конкретно имеется ввиду пот «build string». Понятно то что это текстовая информация, может быть подверсия программы..

      IHostApplication::getApplicationPath

      tresult PLUGIN_API getApplicationPath (void** path)

      Копирует информацию о патче программы в соответствующий параметр.

      IHostApplication::getMainWindow

      tresult PLUGIN_API getMainWindow (void** window)

      Задаёт параметр окна плагина для использования в родительском окне хост-программы.

      Общие СДК классы

      CPluginFactory

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

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

      Данный интерфейс используется для добавления плагина. Методы:

      • CPluginFactory::registerClass

      CPluginFactory::registerClass

      bool registerClass ( PClassInfo* info, FUnknown* (*createFunc)(void*), void* context = 0)

      Регистрирует класс плагина, возвращает «правда» в случае успеха. Параметры:

      info Информация о классе (смотри PClassInfo, — название, идентификатор и т.д. )
      createFunc Функция в «С» стиле, которая может создать экземпляр данного класса.
      context Переменная используемая для создания функции

      CPlugParams

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

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

      Это вспомогательный класс, который задаёт параметры, например при работе с контроллером объекта.

      Конструкторы:

      • CPlugParams::CPlugParams

      Методы:

      • CPlugParams::add
      • CPlugParams::addParam
      • CPlugParams::addIntParam
      • CPlugParams::addStringParam
      • CPlugParams::addListParam
      • CPlugParams::total
      • CPlugParams::at
      • CPlugParams::getName
      • CPlugParams::getParameter

      Конструкторы:

      CPlugParams::CPlugParams (IPlugController* controller = 0)

      Если Вы направляете контроллер к конструктору, то все добавленные параметры будут автоматически подсоединены.

      Добавочные параметры:

      CParameter* add (CParameter* p, long tag, const char* name)
      CParameter* addParam (long tag, const char* name)
      CIntParameter* addIntParam (long tag, const char* name, long min = 0, long max = 1)
      CStringParameter* addStringParam (long tag, const char* name)
      CStringListParameter* addListParam (long tag, const char* name, const char** strings = 0)

      add Добавление параметра объекта, созданного «снаружи»
      addParam Добавление булевого параметра («вкл/выкл»)
      addIntParam Добавление целочисленного параметра
      addStringParam Добавление строкового параметра
      addListParam Добавление списочного параметра

      Контейнер не использует addRef при добавлении параметров, они реализованы в деструкторе.

      Получение параметров:

      long total const ();
      CParameter* at (long index) const;
      bool getName (long index, char str[128]) const;
      CParameter* getParameter (const char* name) const;
      CParameter* getParameter (long tag) const;

      total возвращает колличество параметров
      at Получает параметры исходя из заголовка (index)
      getName Копирует название параметров в заданный заголовок
      getParameter (const char*) Получает параметы исходя из имени
      getParameter (long) Получает параметры исходя из тэгов

      CParameter

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

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

      Библиотека СДК содержит базовые классы параметров:

      CParameter булевый параметр (вкл/выкл) базового класса
      CIntParameter целочисленный параметр
      CStringParameter строковой параметр
      CStringListParameter параметр списка строк

      Дополнительные методы:

      enableUpdates включено/выключено обновление параметров
      initValue
      initString
      Задаёт значение параметра, без последующего обновления. Рекурсия при обновлении значения параметра внутри IPlugController::parameterChanged
      setNormalized
      getNormalized
      Задаёт или получает параметр как нормализированое значение с плавающей точкой (диапазон от 0.0 до 1.0)

    Вы должны быть залогинены для комментирования.