Основы C++ для JUCE: сборка, типы, функции и указатели

Код учебного плагина (plug-in)?плагин (plug-in) — Программный модуль эффекта или инструмента, который загружается в DAW или другую программу-хост и обрабатывает переданные ему аудиоблоки. тремоло (tremolo)?тремоло (tremolo) — Эффект периодического изменения амплитуды аудиосигнала. Скорость пульсации задаёт частота управляющего генератора, а диапазон усиления зависит от глубины и способа её преобразования. из официального курса JUCE написан на C++23 и местами выглядит непривычно: макросы вместо констант, пустые функции для «использования» параметра, static_cast на каждом шагу. Эта статья разбирает язык ровно в том объёме, который нужен, чтобы читать этот код и дописывать его. Каждое понятие показано на строке из этого плагина, а за подробностями ведут заметки на полях со ссылками на учебник Learn C++ и справочник cppreference.

Фрагменты взяты из готовой версии плагина в папке complete репозитория tremolo-juce-course (JUCE 8.0.12). Они приведены в оформлении репозитория, а собственные примеры сайта — в стиле JUCE. Короткие учебные примеры без JUCE проверены компиляцией: Apple clang 17, режим C++23.

C++ развивается стандартами: C++98, C++11, C++14, C++17, C++20, C++23. Рядом с возможностями, которые появились после 1998 года, в скобках указан стандарт. Плагин собирается в режиме C++23, поэтому доступно всё перечисленное.

Классы, конструкторы, наследование и время жизни объектов (object lifetime)?время жизни объекта (object lifetime) — Промежуток от окончания конструктора до начала деструктора, в который к объекту можно обращаться. Зависит от того, где объект создан: в блоке, внутри другого объекта или в куче. разобраны во второй части, «C++ в плагине: классы, конструкторы и время жизни», шаблоны — в «C++ в плагине: шаблоны и сериализация параметров». Владение объектами (ownership)?владение объектом (ownership) — Ответственность за удаление объекта. Владелец удаляет объект, наблюдатели только пользуются им через указатель или ссылку и должны перестать обращаться к нему до удаления. в куче (heap)?куча (heap) — Динамическая память для объектов, созданных выражением new. Такой объект живёт до явного delete или до удаления его владельцем, например умным указателем. — в отдельной статье «Кто владеет объектом», а правила для аудиопотока (audio thread)?аудиопоток (audio thread) — Поток с повышенным приоритетом, который вызывает обработку звука для каждого блока. Каждый вызов должен закончиться до срока блока, поэтому в нём не выделяют память, не берут блокировки и не обращаются к диску. — в «C++ в аудиопотоке».

Как код попадает в компилятор

#include <juce_core/juce_core.h>   // угловые скобки: системные пути и пути библиотек
#include "tremolo_plugin.h"        // кавычки: сначала рядом с текущим файлом

Файлы стандартной библиотеки подключаются без расширения: <vector>, <memory>, <ranges>, <cmath>. Заголовок, который может попасть в одну единицу компиляции дважды, начинается с #pragma once. Строка гарантирует, что файл будет вставлен один раз. Раньше для этого писали «стражи включения» #ifndef, #define, #endif; #pragma once в стандарт не входит, но поддерживается всеми основными компиляторами.

Модуль JUCE и «unity build»

Заголовки из include/Tremolo/ не подключают JUCE, а файлы из source/ не подключают свои заголовки. Это работает благодаря формату модуля JUCE. Заголовок tremolo_plugin.h подключает JUCE, стандартную библиотеку и все заголовки проекта в нужном порядке:

// tremolo_plugin.h
#include <juce_dsp/juce_dsp.h>
#include <vector>
#include <memory>
// ...
#include "include/Tremolo/Parameters.h"
#include "include/Tremolo/Tremolo.h"
#include "include/Tremolo/PluginProcessor.h"

А tremolo_plugin.cpp подключает этот заголовок и затем вставляет через #include все файлы реализации:

// tremolo_plugin.cpp
#include "tremolo_plugin.h"
#include <TremoloPluginAssets.h>
#include "source/LfoVisualizer.cpp"
#include "source/Parameters.cpp"
#include "source/PluginProcessor.cpp"

В итоге весь плагин компилируется как одна единица трансляции. Такой приём называют unity build. Для него важен порядок #include в tremolo_plugin.h: класс должен быть объявлен выше места, где его используют. Например, Tremolo.h стоит раньше PluginProcessor.h, который хранит поле типа Tremolo. А новый заголовок или .cpp нужно добавить в tremolo_plugin.h или tremolo_plugin.cpp, иначе компилятор его не увидит.

Обычная схема — раздельная компиляция: каждый .cpp сам подключает нужные заголовки, и правка одного файла пересобирает только его. Повторный разбор общих заголовков в такой схеме сокращают предкомпилированные заголовки (precompiled headers), в CMake их задаёт команда target_precompile_headers (CMake 3.16). Склеивать исходники CMake тоже умеет сам: свойство цели UNITY_BUILD (CMake 3.16) объединяет файлы в пакеты во время сборки, а исходный код остаётся пригодным для раздельной компиляции. Модули C++20 (import вместо #include) решают ту же задачу средствами языка: интерфейс модуля компилируется один раз, а макросы импортирующего файла на него не влияют.

Макросы из CMake

const juce::String PluginProcessor::getName() const {
  return TREMOLO_PLUGIN_NAME;
}

TREMOLO_PLUGIN_NAME нигде в C++ не определён. Его передаёт компилятору CMake: в CMakeLists.txt проекта стоит TREMOLO_PLUGIN_NAME="${TREMOLO_PLUGIN_NAME}" в target_compile_definitions, что равносильно флагу -DTREMOLO_PLUGIN_NAME="Tremolo". Препроцессор заменит имя строкой "Tremolo".

Комментарии

// однострочный комментарий

/* многострочный
   комментарий */

/** Комментарий документации (Doxygen).
 *  @code ... @endcode — пример кода внутри документации
 */

Стандарт языка знает только // и /* */. Форма /** */ обычный комментарий для компилятора, но генератор документации Doxygen и среды разработки считают её описанием следующего объявления. Команды @param, @return, @code относятся к разметке Doxygen. В этой форме написано описание класса BypassTransitionSmoother. Комментарий после закрывающей скобки, например } // namespace tremolo, подсказывает, какой блок закрыт; это соглашение стиля, и clang-format умеет его проверять.

Типы и литералы

std::size_t

size_t не встроенный тип и не ключевое слово. Это имя беззнакового целого типа, выбранного реализацией. Полное имя std::size_t объявлено в заголовке <cstddef>. Тип предназначен для размеров объектов и индексов контейнеров стандартной библиотеки. В плагине он нужен на границе с JUCE: библиотека возвращает количество отсчётов как int, а std::vector и std::span ждут size_t.

lfoSamples.resize(4u * static_cast<size_t>(expectedMaxFramesPerBlock));

Преобразование само знак не проверяет: отрицательное число, превращённое в size_t, станет огромным положительным. Поэтому оно записано явно, о чём подробнее в разделе про static_cast.

Литералы

Строка в кавычках, например "Tremolo", не объект-строка, как в Python, а массив char с нулевым байтом на конце. Объекты строк — это классы std::string и juce::String; из литерала они создаются неявно. Сырой литерал R"(...)" (C++11) отключает экранирование и сохраняет переносы строк, с префиксом u8 — в кодировке UTF-8. Так в тестах плагина записан ожидаемый JSON:

const juce::String expectedOutput =
    u8R"({
  "__version__": 1,
  "pluginName": "Tremolo",
  "modulationRateHz": 10.0,
  "bypassed": true,
  "modulationWaveform": "Triangle"
})";

Нулевой указатель обозначает nullptr (C++11). Раньше писали NULL или 0, но это целое число, и оно путалось с перегрузками функций. У nullptr собственный тип, и приводится он только к указателям: setLookAndFeel(nullptr) в деструкторе редактора.

auto, const и constexpr

for (auto& lfo : lfos) {   // ссылка на каждый осциллятор в массиве
  lfo.reset();
}

Если в этом цикле написать auto lfo, reset() сработает на копии осциллятора (oscillator)?осциллятор (oscillator) — Генератор повторяющегося колебания. Частота задаёт число повторений за секунду, а форма волны — изменение значения внутри одного периода., а исходный не изменится.

const запрещает менять объект после инициализации. В коде плагина почти всё неизменяемое помечено const:

const auto inputSample = buffer.getSample(channelIndex, frameIndex);
const auto outputSample = modulationValue * inputSample;

Операторы и приведение типов

Условный оператор условие ? значение_если_да : значение_если_нет — выражение, а не инструкция. Через него выбирают целевое значение и подпись кнопки:

const auto target = bypass ? 1.0f : 0.0f;
bypassButton.setButtonText(bypassButton.getToggleState() ? "Bypassed" : "Bypass");

static_cast

dryBuffer.setSize(static_cast<int>(spec.numChannels),
                  static_cast<int>(spec.maximumBlockSize));

В коде плагина static_cast встречается часто, потому что строгие предупреждения (см. раздел о предупреждениях) запрещают молча смешивать знаковые и беззнаковые числа. JUCE хранит размеры как int, а стандартная библиотека ждёт size_t. Приведение в стиле C, (int)x, допускает более широкий набор преобразований и хуже показывает намерение, поэтому в современном коде его избегают. Другие виды приведений в плагине не используются: const_cast снимает const, reinterpret_cast переинтерпретирует биты, dynamic_cast проверяет тип в иерархии классов во время выполнения.

Пространства имён

juce::AudioBuffer<float>          // класс AudioBuffer из пространства juce
juce::dsp::AudioBlock<float>      // вложенное пространство juce::dsp
std::views::iota (0, n)           // функция из std::views
Tremolo::LfoWaveform::sine        // значение перечисления внутри класса
PluginProcessor::getName()        // метод класса в определении вне класса

Пространство имён можно вложить в другое: juce::dsp — часть juce. Запись namespace tremolo::assets { ... } (C++17) равна двум вложенным блокам. Поиск имени идёт изнутри наружу: в PluginEditor.cpp написано assets::Background_png, хотя сгенерированные данные лежат в tremolo::assets. Код редактора находится внутри namespace tremolo, поэтому assets находится относительно него.

Анонимное пространство имён

В этом проекте нужна оговорка. Из-за unity build все файлы source/*.cpp составляют одну единицу трансляции, поэтому анонимные пространства из разных файлов объединяются. Две вспомогательные функции с одинаковым именем в разных файлах всё равно будут конфликтовать. В заголовке такое пространство создаёт отдельные копии в каждой единице, поэтому для общего интерфейса оно не подходит.

Функции

Тип результата пишется перед именем. В определении вне класса имя метода уточняют именем класса. Компилятор должен увидеть объявление функции до её вызова, поэтому и нужны заголовки:

// PluginProcessor.h — объявление (сигнатура)
bool acceptsMidi() const override;

// PluginProcessor.cpp — определение (тело)
bool PluginProcessor::acceptsMidi() const {
  return false;
}

В объявлении имена параметров можно опустить, важны только типы: void processBlock(juce::AudioBuffer<float>&, juce::MidiBuffer&);. Если параметр в теле не нужен, имя можно опустить и в определении. Если тело функции ещё не написано, JUCE предлагает вызвать juce::ignoreUnused(index);: пустая функция «использует» аргумент, и компилятор не предупреждает о неиспользуемой переменной. Стандартная альтернатива (C++17) — атрибут [[maybe_unused]] int index.

Перегрузка

int twice (int value) { return value * 2; }
double twice (double value) { return value * 2.0; }

// twice (3) вызовет первое тело, twice (3.5) — второе.

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

inline и цепочки вызовов

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

return juce::File::getSpecialLocation(
           juce::File::SpecialLocationType::currentExecutableFile)
    .getParentDirectory()
    .getChildFile(fileName)
    .getFullPathName()
    .toStdString();

Так же построены BusesProperties().withInput(...).withOutput(...) в конструкторе процессора. Шаблон называют «строитель» (builder).

Значение, ссылка и указатель

Это главное отличие C++ от Python, Go и TypeScript: автор кода выбирает, как передаётся объект. В Python и TypeScript объект всегда передаётся по ссылке на него. В Go структура по умолчанию копируется целиком. В C++ копируется любой объект, даже большой класс, если не сказано иное.

Ссылка T&

Ссылку можно и вернуть из функции. Например, процессор плагина хранит параметры в поле parameters, а редактору отдаёт их методом getParameterRefs(). Рядом объявлен метод getBypassParameter(), который возвращает указатель:

// PluginProcessor.h
[[nodiscard]] Parameters& getParameterRefs() noexcept;
juce::AudioProcessorParameter* getBypassParameter() const noexcept override;
// ...
Parameters parameters{*this};  // поле: сам объект, не ссылка и не указатель

// PluginProcessor.cpp
Parameters& PluginProcessor::getParameterRefs() noexcept {
  return parameters;
}

juce::AudioProcessorParameter* PluginProcessor::getBypassParameter() const noexcept {
  return &parameters.bypassed;
}

Копию Parameters вернуть и не удалось бы: структура запрещает копирование и перемещение макросами JUCE_DECLARE_NON_COPYABLE и JUCE_DECLARE_NON_MOVEABLE (см. запрет копирования). По той же причине вызывающий код сохраняет результат в ссылку: auto& params = p.getParameterRefs();. Запись auto params = ... отбрасывает ссылку и пытается скопировать объект, и компилятор сообщит о вызове удалённого конструктора копирования. Редактор обходится без переменной: p.getParameterRefs().rate сразу обращается к полю rate объекта процессора.

void PluginProcessor::getStateInformation(juce::MemoryBlock& destData) {
  juce::MemoryOutputStream outputStream{destData, true};
  JsonSerializer::serialize(parameters, outputStream);
}

Аргумент parameters — существующее поле процессора. При вызове ссылка из объявления связывается с этим объектом, и внутри serialize имя параметра обозначает само поле, без копии. Поэтому в месте вызова передают объект: serialize(&parameters, outputStream) не скомпилируется, потому что &parameters — указатель Parameters*. Второй аргумент передаётся так же: outputStream имеет тип juce::MemoryOutputStream, и ссылка на базовый класс juce::OutputStream& привязывается к нему (см. наследование).

Амперсанд ссылки пишут там, где объявляется тип: у параметра, возвращаемого значения, поля или переменной. В вызове функции и после return стоят выражения, и & в них берёт адрес. Подробнее о двух значениях символа — во врезке ниже.

Указатель T*

Кто отвечает за удаление объекта, на который указывает указатель, — отдельный вопрос. Он разобран в статье «Кто владеет объектом».

const в типе указателя

Две звёздочки появляются, когда каналов несколько. juce::AudioBuffer хранит таблицу указателей на каналы, а getArrayOfReadPointers() возвращает адрес этой таблицы с типом const float* const*. const перед первой звёздочкой защищает отсчёты, const между звёздочками — указатели каналов в таблице. Сам возвращённый указатель обычный: его можно перенаправить, таблицу и отсчёты это не затронет. getArrayOfWritePointers() возвращает float* const*: отсчёты менять можно, подменить канал нельзя. Те же типы получает колбэк аудиоустройства JUCE audioDeviceIOCallbackWithContext: входные каналы — const float* const*, выходные — float* const*.

const float* const* inputs = buffer.getArrayOfReadPointers();
float* const* outputs = buffer.getArrayOfWritePointers();

const auto x = inputs[1][10];  // канал 1, отсчёт 10: читать можно
outputs[1][10] = 0.5f * x;     // писать отсчёт через float* const* можно
// inputs[1][10] = 0.0f;       // ошибка: отсчёты константны
// outputs[1] = nullptr;       // ошибка: указатели каналов константны

У среднего const есть и второе назначение: float** неявно превращается в const float* const*, но не в const float**. Иначе через const float** можно было бы записать в таблицу адрес константного числа, а потом изменить это число через исходный float*.

Массивы и std::span

void applyGain (std::span<float> samples, float gain) noexcept
{
    for (auto& sample : samples)
        sample *= gain;
}

std::array<float, 4> window { 0.0f, 0.5f, 1.0f, 0.5f }; // длина известна при компиляции
std::vector<float> block (512);                         // длина задаётся при выполнении

applyGain (window, 0.5f);
applyGain (block, 0.5f);
applyGain ({ buffer.getWritePointer (0),                 // указатель и длина из AudioBuffer
             static_cast<std::size_t> (buffer.getNumSamples()) }, 0.5f);
applyGain (std::span { block }.first (64), 0.0f);        // первые 64 отсчёта

Цикл по диапазону

Вместо классического for (int i = 0; i < n; ++i) код плагина использует std::views::iota (C++20, заголовок <ranges>): ленивую последовательность целых чисел в полуоткрытом интервале [начало, конец), как range(a, b) в Python. Массив в памяти не создаётся, а индекс можно объявить const.

for (const auto frameIndex : std::views::iota(0, buffer.getNumSamples())) {
  for (const auto channelIndex : std::views::iota(0, buffer.getNumChannels())) {
    const auto inputSample = buffer.getSample(channelIndex, frameIndex);
    buffer.setSample(channelIndex, frameIndex, modulationValue * inputSample);
  }
}

Оба аргумента iota должны быть одного типа. getNumSamples() возвращает int, поэтому начало записано как 0, а не 0u.

noexcept и [[nodiscard]]

void setBypass(bool bypass) noexcept { /* ... */ }
[[nodiscard]] bool isTransitioning() const noexcept { /* ... */ }

Атрибут [[nodiscard]] (C++17) просит компилятор предупредить, если результат функции проигнорирован: вызывать isTransitioning(); и не использовать ответ бессмысленно. Двойные квадратные скобки — стандартный синтаксис атрибутов (C++11), отличный от [] индексирования и от захвата лямбды. Атрибут nodiscard — не ключевое слово вроде const, а имя атрибута. Другие атрибуты: [[maybe_unused]], [[fallthrough]], [[likely]]. Правила описаны в стандарте.

Точка входа плагина

У плагина нет функции main(). Вместо неё JUCE ищет функцию с фиксированным именем, которая создаёт процессор:

}  // namespace tremolo

// This creates new instances of the plugin.
// This function definition must be in the global namespace.
juce::AudioProcessor* JUCE_CALLTYPE createPluginFilter() {
  return new tremolo::PluginProcessor();
}

Функция определена вне namespace tremolo, в глобальном пространстве: внутри пространства её полное имя стало бы tremolo::createPluginFilter, и JUCE её бы не нашёл. Макрос JUCE_CALLTYPE задаёт соглашение о вызове, то есть порядок передачи аргументов. Оно нужно, чтобы плагин и хост одинаково понимали вызов; на Windows это __stdcall, на других платформах макрос пуст.

Выражение new T(...) создаёт объект в куче и возвращает указатель на него. Владение переходит обёртке плагина JUCE, и она позже вызовет delete. Возвращается указатель на базовый класс juce::AudioProcessor*, хотя создан tremolo::PluginProcessor: объект наследника можно использовать везде, где ждут базовый класс (см. наследование). В собственном коде голые new и delete обычно не пишут: для этого есть std::make_unique, подробнее — в «Кто владеет объектом».

Стиль кода в примерах

Собственные примеры сайта следуют JUCE Coding Standards — правилам оформления самого фреймворка. В них отступ занимает 4 пробела, фигурные скобки стоят на отдельной строке, перед открывающей скобкой вызова с аргументами ставится пробел, литерал пишется как 0.0f, а параметр шаблона называется словом, а не T. Одна и та же функция в двух стилях:

// Оформление учебного плагина (Chromium)
void applyGain(std::span<float> samples, float gain) noexcept {
  for (auto& sample : samples)
    sample *= gain;
}

// Оформление примеров сайта (JUCE)
void applyGain (std::span<float> samples, float gain) noexcept
{
    for (auto& sample : samples)
        sample *= gain;
}

Примеры собираются в режиме C++23. У величины с единицей измерения единица видна в имени или в комментарии: delaySeconds, latencySamples, double cutoff = 1000.0; // Гц. Объектами владеют поля и std::unique_ptr; голые new и delete встречаются только там, где статья разбирает ручное владение или API JUCE принимает сырой указатель. Вместо массивов C — std::array, std::vector и std::span, вместо приведения (int) x — static_cast<int> (x). Возможности новее C++11 при первом упоминании помечены стандартом в скобках, как std::span (C++20) в этой статье.

Предупреждения компилятора

Файл cmake/CompilerWarnings.cmake включает строгий набор предупреждений, и он объясняет несколько особенностей стиля кода. Таблица 4 связывает флаги с тем, как они видны в коде.

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

Источники

• Alex. Learn C++. Главы 2 «C++ Basics: Functions and Files» (уроки 2.7, 2.8, 2.10, 2.11, 2.12), 4, 5, 7, 10, 11, 12, 16 и 17. в списке литературы → — препроцессор, заголовки, типы, литералы, пространства имён, приведение типов, перегрузка, ссылки, возврат ссылки, указатели и const, std::vector, std::array и циклы.
• Wilczek J. C++ Pointers Explained For Audio Programming. Разделы о массивах, двойных указателях, const и std::span. в списке литературы → — указатель как адрес блока отсчётов, std::array и std::vector вместо массивов C, таблица каналов float** в колбэке аудиоустройства, чтение const справа налево, std::span вместо пары «указатель и длина».
• cppreference. Pointer declaration — раздел Constness: const до и после *, равенство const T* и T const*; std::span — невладеющий вид на непрерывную память.
• cppreference. static_cast — допустимые преобразования; std::size_t — определение и заголовок <cstddef>; noexcept specifier и nodiscard — семантика и стандарт появления.
• Проект стандарта C++ (eel.is/c++draft): support.types.layout — size_t, namespace.unnamed — анонимное пространство имён, dcl.attr.grammar — синтаксис атрибутов.
• JUCE. JUCE Module Format — модуль из одного .cpp, который вставляет остальные исходники, и блок BEGIN_JUCE_MODULE_DECLARATION.
• CMake. UNITY_BUILD и target_precompile_headers — автоматический unity build и предкомпилированные заголовки (CMake 3.16).
• cppreference. Modules — модули C++20 и отличие import от #include.
• Doxygen. Documenting the code — формы комментариев документации.
• JUCE. Coding Standards — оформление и соглашения исходников JUCE, на которых основан стиль примеров сайта.
• Clang. ClangFormatStyleOptions — параметр BasedOnStyle и встроенные стили, в том числе Chromium.
• JUCE. tremolo-juce-course — фрагменты кода из папки complete: tremolo_plugin.h, tremolo_plugin.cpp, PluginProcessor.h, PluginProcessor.cpp, Parameters.cpp, Tremolo.h, BypassTransitionSmoother.h, cmake/CompilerWarnings.cmake, CMakeLists.txt, test/source/TestUtils.h, Parameters.h, JsonSerializer.h и JsonSerializer.cpp.
• JUCE 8.0.12: juce_AudioSampleBuffer.h — типы getReadPointer, getWritePointer, getArrayOfReadPointers и getArrayOfWritePointers; juce_AudioIODevice.h — параметры audioDeviceIOCallbackWithContext.