← Руководство

Скриптовые процессоры

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

Тип скриптового процессора	Точка интеграции	Функция	Типичное использование
Генератор	Источники звука	Производит аудио-семплы	Настраиваемые генераторы звука, которые выделяют звук в сцену, обычно через `AudioSource`.
Выход корня	Основной выход аудиодвигателя	Производит аудио-семплы	Пользовательские аудиосистемы с доступом к системе заданий, интеграцией межпроцессорных программ или генераторов звука, которые выделяют аудио непосредственно в основной выходной микш.

Общая архитектура

Все скриптовые процессоры имеют одну и ту же структуру высокого уровня. Каждый процессор разделен на следующие две части:

Контрольная часть: Создает, настраивает и управляет процессором из игровой логики и, как правило, работает на главном потоке.
Часть реального времени: Генерирует и обрабатывает звуковые семплы. Обычно запускается в потоке аудио или в Job System.

Каждая часть представляет отдельный интерфейс: Processor.IControl для логики управления и Processor.IRealtime для обработки в реальном времени. Для создания работающего процессора необходимо реализовать оба интерфейса. Обратите внимание, что каждый тип процессора предоставляет определенные интерфейсы (производные от Processor.IControl/Processor.IRealtimeНапример, при реализации генератора, используйте GeneratorInstance.IControl и GeneratorInstance.IRealtime.

Контексты управления и реального времени

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

Контекст управления: позволяет выделять и уничтожать экземпляры процессора, а также взаимодействовать с ними из логики игры. Сам экземпляр выступает в роли манипулятора, и вы получаете доступ к его возможностям через контекст управления. Как правило, вы используете встроенный контекст управления, который подключается и рендируется непосредственно к аудиосистеме Unity. Вы также можете создать контекст ручного управления для автономного рендеринга. Контексты ручного управления дают вам полный контроль над выделением, рендерингом и уничтожением, что эффективно для автономного рендеринга, анализа звука, визуализации и автоматических тестов.
Контекст реального времени : Эквивалент контекста управления в реальном времени. Используйте его для выполнения операций в реальном времени на экземпляре процессора, таких как генерация или обработка аудиосемплов во время цикла микширования. При использовании встроенного контекста управления Unity автоматически создает и уничтожает контексты реального времени. Если вы используете ручной контекст управления, вы сами отвечаете за управление жизненным циклом контекстов реального времени.

Смешанные циклы

Контекст реального времени всегда принадлежит конкретному циклу микширования. Когда вы используете встроенный контекст управления, аудиосистема Unity управляет циклами микширования за вас. Однако, если вы используете контекст ручного управления, вы отвечаете за начало и окончание каждого цикла. Чтобы управлять циклом микширования, выполните следующие действия:

Запустите новый цикл смешивания, вызвав ControlContext.Manual.BeginMix(), который возвращает временный RealtimeContext.
Используйте RealtimeContext для выполнения функций реального времени на экземплярах процессора.
Завершите цикл смешивания, вызвав ControlContext.Manual.EndMix().

Ниже приведен пример кода:

var realtimeContext = ControlContext.Manual.BeginMix();

foreach (var processor in processors)
{
    // Use realtimeContext to drive real-time functionality on the processor.
}

ControlContext.Manual.EndMix();

Механизмы связи

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

Трубы

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

Обе части (контроль/реальное время) имеют общий канал для обмена данными, доступный из обратных вызовов IRealtime/IControl. Данные могут течь в обоих направлениях. Все данные, отправляемые из контрольной части в одном и том же кадре, поступают через общий канал в часть реального времени в одном и том же цикле смешивания. Аналогичным образом, все данные, отправляемые из части реального времени в одном и том же цикле смешивания, видны для контрольной части в том же кадре. Данные, отправляемые в часть реального времени, доступны только для одного цикла смешивания, а данные, отправляемые обратно из части реального времени, доступны на контрольной части только для одного обновляемого кадра.

Сообщения

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

Обновленные данные

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

Контрольная сторона — обычно вызывается один раз на каждый рендируемый кадр видео. Используйте для:
- Продвинутая логика игры, связанная с процессором.
- Чтение параметров редактора/UI.
- Отправка/получение данных в/из части реального времени (через трубопровод).
- Опрос внешних источников (например, состояния таймлайнов или игровых триггеров).
- Расписание одноразовых событий (например, повторное запуск конверта или переключение клипов).
Сторона реального времени - вызывает один раз в цикле смешивания. Используйте его для:
- Обновление аудиологики и зависимости от состояния реального времени.
- Отправка/прием данных в/из контрольной части (через трубу).
- Подготовьте состояние, необходимое для предстоящего Process call(s).

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

Default — эквивалент UpdateIfDataIsAvailable.
NeverUpdate — Привязка обновления отключена; она никогда не запускается.
UpdateIfDataIsAvailable — Hook запускается только тогда, когда в трубке появляется новая информация.
UpdateAlways — Hook запускает каждый кадр (контроль) или каждый цикл смешивания (реальное время), независимо от наличия данных.

Канальные буферы и аудиоформаты

Буфер канала (ChannelBuffer) содержит данные аудио-семплирования, когда они перемещаются через конвейер обработки аудио. Он обеспечивает двухмерное представление, каналы × кадры, над базовым блоком семплов и не зависит от расположения семплов (планарный или переплетенный). Это позволяет процессорам эффективно работать с аудио-данными, независимо от того, как семплы организованы в памяти. Поддерживающий буфер является переходным и может быть основан на собственной/неуправляемой памяти, либо постоянным, либо временно выделенным с помощью конструкции stackalloc в C# — или через управляемое выделение.

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