Система плагинов RenderWare

From Multi Theft Auto: Wiki
Revision as of 19:10, 14 June 2021 by EOFIK (talk | contribs) (Перевод на русский язык)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

Справка

  • структура плагина - это структура данных которая должна быть зарегистрирована в типе RenderWare;
  • объект плагина - это тип RenderWare с поддержкой плагинов;
  • контейнер плагина - это глобальный дескриптор с расширительной информацией об объекте плагина (например, размер, конструкторы, деструкторы и обратные вызовы потока).

Известные типы RenderWare с поддержкой (встроенных) плагинов

  • RpAtomic - дескриптор рендеринга геометрии;
  • RpClump - контейнер с атомикой, лампами и камерами;
  • RpGeometry - 3D сетчатый держатель;
  • RpMaterial - рендеринговый материал для геометрии;
  • RpWorld - секторный менеджер для рендеринга сцен, который обрабатывает динамическое освещение;
  • RpLight - динамический световой дескриптор;
  • RwFrame - матрица в 3d пространстве, которая содержит объекты кадра (атомика, свет, камеры), создает иерархию для преобразования и смещения объектов;
  • RwCamera - вьюпорт в 3D пространство со свойствами рендеринга;
  • RwRaster - данные текстуры gfx;
  • RwTexture - дескриптор рендеринга растра;
  • RwTexDictionary - контейнер текстур для поиска по имени.

Регистрация расширений объектов плагинов

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

RwObjectRegisterPlugin

size_t RwObjectRegisterPlugin( size_t sPluginSize, unsigned int uiPluginID, RwPluginConstructor constructor,
RwPluginDestructor destructor, RwPluginCopyConstructor copyConstructor = NULL );
  • sPluginSize - размер структуры плагина, которая должна быть зарегистрирована в объекте плагина;
  • uiPluginID - уникальный идентификатор плагина, который может быть распознан системой (например, в потоках);
  • constructor - вызывается при построении объекта плагина, чтобы настроить структуру плагина на его смещение;
  • destructor - вызывается при уничтожении объекта плагина для освобождения связанных ресурсов;
  • copyConstructor (может быть НУЛЕВЫМ) - вызывается при клонировании плагина для воссоздания свойств исходного объекта плагина в новом с теми же свойствами.

Функция возвращает смещение зарегистрированной структуры плагина.

Типы обратного вызова (шаблоны)

RwPluginConstructor

template <class objectType>
objectType* RwPluginConstructor( objectType *obj, size_t sPluginOffset );

RwPluginDestructor

template <class objectType>
void RwPluginDestructor( objectType *obj, size_t sPluginOffset );
  • obj - рассматриваемый объект плагина;
  • sPluginOffset - смещение структуры плагина.

Если процедура конструктора возвращает NULL, плагин не смог построить. Делать это не рекомендуется, так как объект плагина все равно будет передан среде выполнения. С другой стороны, деструктор не должен давать сбоев.

RwPluginCopyConstructor

template <class objectType>
objectType* RwPluginCopyConstructor( objectType *objNew, objectType *source, size_t sPluginOffset );
  • objNew - вновь созданный объект плагина;
  • source - объект плагина для клонирования данных из него;
  • sPluginOffset - смещение структуры плагина;

Регистрация расширений потока объектов плагина

Структуры плагинов могут предлагать потоковое представление. Как только разделы, обозначенные идентификатором структуры, найдены в RwStream, выдается обратный вызов read. Если тип RenderWare записывается на диск, вызываются все обратные вызовы write. Плагины не должны записывать детали на диск. Процедура регистрации определяется следующим образом...

RwObjectRegisterPluginStream

size_t RwObjectRegisterPluginStream( unsigned int uiPluginID, RwPluginStreamRead readCallback, RwPluginStreamWrite writeCallback,
RwPluginStreamGetSize sizeCallback );
  • uiPluginID - идентификатор структуры плагина (чтобы найти его в реестре);
  • readCallback - выдается после того, как структура плагина найдена по идентификатору в RwStream;
  • writeCallback - вызывается после записи объекта плагина в RwStream;
  • sizeCallback - вызывается для возврата размера структуры плагина в потоке (для целей выделения).

Смещение структуры плагина возвращается в случае успешной регистрации. В противном случае функция возвращает 0 (что всегда является недопустимым смещением). Регистрация завершится неудачей, если структура плагина не была зарегистрирована ранее. Поэтому вызовите RwObjectRegisterPlugin перед RwObjectRegisterPluginStream!

Типы обратного вызова (шаблоны)

RwPluginStreamRead

template <class objectType>
RwStream* RwPluginStreamRead( RwStream *stream, size_t sPluginSize, objectType *obj );
  • stream - исходный поток объекта плагина;
  • sPluginSize - размер объекта плагина (возвращается из RwPluginStreamGetSize);
  • obj - объект плагина для записи данных.

Если эта функция успешно работает, она должна вернуть поток. В противном случае она может вернуть NULL. Это означает, что чтение типа RenderWare не удалось.

RwPluginStreamWrite

template <class objectType>
int RwPluginStreamWrite( RwStream *stream, size_t sPluginSize, objectType *obj );
  • stream - исходный поток объекта плагина;
  • sPluginSize - размер объекта плагина (возвращается из RwPluginStreamGetSize);
  • obj - объект плагина для записи данных.

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

RwPluginStreamGetSize

template <class objectType>
size_t RwPluginStreamGetSize( objectType *obj );
  • obj - объект плагина для записи на диск.

Этот обратный вызов должен возвращать необходимый размер для записи в RwStream. Если возвращается 0, данные не должны записываться на диск (следовательно, раздел не создается). Возвращаемое значение передается обратному вызову write.

Время жизни объекта плагина RenderWare

Как только объект плагина создан, сначала он заполняется данными RenderWare. Затем все конструкторы вызываются в порядке их назначения, чтобы заполнить все детали плагина. Чтобы получить доступ к деталям плагина, необходимо создать API, который обращается к структуре плагина (которая была зарегистрирована в указанном плагине) по смещению, которому она назначена. Обычно существует глобальная переменная, которая содержит смещение структуры плагина, которое используется во всех API. Поскольку структуры все время строятся одинаково, информация о смещении структуры плагина может быть опущена путем создания нового определения, которое статически отображает смещения во время компиляции. Оптимальные реализации используют смещение структуры плагина, возвращаемое функцией регистрации, так что каждая зарегистрированная структура в объекте плагина независима от других.

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

Retrieved from "https://wiki.multitheftauto.com/wiki/Система_плагинов_RenderWare?oldid=71204"