Audio plugin host https://kx.studio/carla
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

CarlaEngine.hpp 33KB

11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
10 years ago
10 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
10 years ago
11 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
11 years ago
10 years ago
10 years ago
11 years ago
10 years ago
11 years ago
10 years ago
11 years ago
10 years ago
10 years ago
11 years ago
10 years ago
11 years ago
10 years ago
10 years ago
10 years ago
11 years ago
11 years ago
11 years ago
10 years ago
10 years ago
10 years ago
11 years ago
10 years ago
10 years ago
10 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
11 years ago
10 years ago
11 years ago
11 years ago
11 years ago
10 years ago
10 years ago
10 years ago
10 years ago
11 years ago
10 years ago
11 years ago
10 years ago
10 years ago
11 years ago
10 years ago
10 years ago
10 years ago
11 years ago
11 years ago
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215
  1. /*
  2. * Carla Plugin Host
  3. * Copyright (C) 2011-2014 Filipe Coelho <falktx@falktx.com>
  4. *
  5. * This program is free software; you can redistribute it and/or
  6. * modify it under the terms of the GNU General Public License as
  7. * published by the Free Software Foundation; either version 2 of
  8. * the License, or any later version.
  9. *
  10. * This program is distributed in the hope that it will be useful,
  11. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13. * GNU General Public License for more details.
  14. *
  15. * For a full copy of the GNU General Public License see the doc/GPL.txt file.
  16. */
  17. #ifndef CARLA_ENGINE_HPP_INCLUDED
  18. #define CARLA_ENGINE_HPP_INCLUDED
  19. #include "CarlaBackend.h"
  20. #ifdef BUILD_BRIDGE
  21. struct CarlaOscData;
  22. #endif
  23. namespace juce {
  24. class MemoryOutputStream;
  25. class XmlDocument;
  26. }
  27. CARLA_BACKEND_START_NAMESPACE
  28. // -----------------------------------------------------------------------
  29. /*!
  30. * @defgroup CarlaEngineAPI Carla Engine API
  31. *
  32. * The Carla Engine API.
  33. * @{
  34. */
  35. /*!
  36. * The type of an engine.
  37. */
  38. enum EngineType {
  39. /*!
  40. * Null engine type.
  41. */
  42. kEngineTypeNull = 0,
  43. /*!
  44. * JACK engine type.
  45. * Provides all processing modes.
  46. */
  47. kEngineTypeJack = 1,
  48. /*!
  49. * Juce engine type, used to provide Native Audio and MIDI support.
  50. */
  51. kEngineTypeJuce = 2,
  52. /*!
  53. * RtAudio engine type, used to provide Native Audio and MIDI support.
  54. */
  55. kEngineTypeRtAudio = 3,
  56. /*!
  57. * Plugin engine type, used to export the engine as a plugin.
  58. */
  59. kEngineTypePlugin = 4,
  60. /*!
  61. * Bridge engine type, used in BridgePlugin class.
  62. */
  63. kEngineTypeBridge = 5
  64. };
  65. /*!
  66. * The type of an engine port.
  67. */
  68. enum EnginePortType {
  69. /*!
  70. * Null port type.
  71. */
  72. kEnginePortTypeNull = 0,
  73. /*!
  74. * Audio port type.
  75. * @see CarlaEngineAudioPort
  76. */
  77. kEnginePortTypeAudio = 1,
  78. /*!
  79. * CV port type.
  80. * @see CarlaEngineCVPort
  81. */
  82. kEnginePortTypeCV = 2,
  83. /*!
  84. * Event port type (Control or MIDI).
  85. * @see CarlaEngineEventPort
  86. */
  87. kEnginePortTypeEvent = 3
  88. };
  89. /*!
  90. * The type of an engine event.
  91. */
  92. enum EngineEventType {
  93. /*!
  94. * Null port type.
  95. */
  96. kEngineEventTypeNull = 0,
  97. /*!
  98. * Control event type.
  99. * @see EngineControlEvent
  100. */
  101. kEngineEventTypeControl = 1,
  102. /*!
  103. * MIDI event type.
  104. * @see EngineMidiEvent
  105. */
  106. kEngineEventTypeMidi = 2
  107. };
  108. /*!
  109. * The type of an engine control event.
  110. */
  111. enum EngineControlEventType {
  112. /*!
  113. * Null event type.
  114. */
  115. kEngineControlEventTypeNull = 0,
  116. /*!
  117. * Parameter event type.
  118. * @note Value uses a normalized range of 0.0f<->1.0f.
  119. */
  120. kEngineControlEventTypeParameter = 1,
  121. /*!
  122. * MIDI Bank event type.
  123. */
  124. kEngineControlEventTypeMidiBank = 2,
  125. /*!
  126. * MIDI Program change event type.
  127. */
  128. kEngineControlEventTypeMidiProgram = 3,
  129. /*!
  130. * All sound off event type.
  131. */
  132. kEngineControlEventTypeAllSoundOff = 4,
  133. /*!
  134. * All notes off event type.
  135. */
  136. kEngineControlEventTypeAllNotesOff = 5
  137. };
  138. // -----------------------------------------------------------------------
  139. /*!
  140. * Engine control event.
  141. */
  142. struct CARLA_API EngineControlEvent {
  143. EngineControlEventType type; //!< Control-Event type.
  144. uint16_t param; //!< Parameter Id, midi bank or midi program.
  145. float value; //!< Parameter value, normalized to 0.0f<->1.0f.
  146. /*!
  147. * Convert this control event into MIDI data.
  148. */
  149. void convertToMidiData(const uint8_t channel, uint8_t& size, uint8_t data[3]) const noexcept;
  150. };
  151. /*!
  152. * Engine MIDI event.
  153. */
  154. struct CARLA_API EngineMidiEvent {
  155. static const uint8_t kDataSize = 4; //!< Size of internal data
  156. uint8_t port; //!< Port offset (usually 0)
  157. uint8_t size; //!< Number of bytes used
  158. /*!
  159. * MIDI data, without channel bit.
  160. * If size > kDataSize, dataExt is used (otherwise NULL).
  161. */
  162. uint8_t data[kDataSize];
  163. const uint8_t* dataExt;
  164. };
  165. /*!
  166. * Engine event.
  167. */
  168. struct CARLA_API EngineEvent {
  169. EngineEventType type; //!< Event Type; either Control or MIDI
  170. uint32_t time; //!< Time offset in frames
  171. uint8_t channel; //!< Channel, used for MIDI-related events
  172. /*!
  173. * Event specific data.
  174. */
  175. union {
  176. EngineControlEvent ctrl;
  177. EngineMidiEvent midi;
  178. };
  179. /*!
  180. * Fill this event from MIDI data.
  181. */
  182. void fillFromMidiData(const uint8_t size, const uint8_t* const data, const uint8_t midiPortOffset) noexcept;
  183. };
  184. // -----------------------------------------------------------------------
  185. /*!
  186. * Engine options.
  187. */
  188. struct CARLA_API EngineOptions {
  189. EngineProcessMode processMode;
  190. EngineTransportMode transportMode;
  191. bool forceStereo;
  192. bool preferPluginBridges;
  193. bool preferUiBridges;
  194. bool uisAlwaysOnTop;
  195. uint maxParameters;
  196. uint uiBridgesTimeout;
  197. uint audioNumPeriods;
  198. uint audioBufferSize;
  199. uint audioSampleRate;
  200. const char* audioDevice;
  201. const char* pathLADSPA;
  202. const char* pathDSSI;
  203. const char* pathLV2;
  204. const char* pathVST2;
  205. const char* pathVST3;
  206. const char* pathGIG;
  207. const char* pathSF2;
  208. const char* pathSFZ;
  209. const char* binaryDir;
  210. const char* resourceDir;
  211. bool preventBadBehaviour;
  212. uintptr_t frontendWinId;
  213. #ifndef DOXYGEN
  214. EngineOptions() noexcept;
  215. ~EngineOptions() noexcept;
  216. CARLA_DECLARE_NON_COPY_STRUCT(EngineOptions)
  217. #endif
  218. };
  219. /*!
  220. * Engine BBT Time information.
  221. */
  222. struct CARLA_API EngineTimeInfoBBT {
  223. int32_t bar; //!< current bar
  224. int32_t beat; //!< current beat-within-bar
  225. int32_t tick; //!< current tick-within-beat
  226. double barStartTick;
  227. float beatsPerBar; //!< time signature "numerator"
  228. float beatType; //!< time signature "denominator"
  229. double ticksPerBeat;
  230. double beatsPerMinute;
  231. #ifndef DOXYGEN
  232. EngineTimeInfoBBT() noexcept;
  233. #endif
  234. };
  235. /*!
  236. * Engine Time information.
  237. */
  238. struct CARLA_API EngineTimeInfo {
  239. static const uint kValidBBT = 0x1;
  240. bool playing;
  241. uint64_t frame;
  242. uint64_t usecs;
  243. uint valid;
  244. EngineTimeInfoBBT bbt;
  245. /*!
  246. * Clear.
  247. */
  248. void clear() noexcept;
  249. #ifndef DOXYGEN
  250. EngineTimeInfo() noexcept;
  251. // quick operator, doesn't check all values
  252. bool operator==(const EngineTimeInfo& timeInfo) const noexcept;
  253. bool operator!=(const EngineTimeInfo& timeInfo) const noexcept;
  254. #endif
  255. };
  256. // -----------------------------------------------------------------------
  257. /*!
  258. * Carla Engine port (Abstract).
  259. * This is the base class for all Carla Engine ports.
  260. */
  261. class CARLA_API CarlaEnginePort
  262. {
  263. protected:
  264. /*!
  265. * The constructor.
  266. * All constructor parameters are constant and will never change in the lifetime of the port.
  267. */
  268. CarlaEnginePort(const CarlaEngineClient& client, const bool isInputPort, const uint32_t indexOffset) noexcept;
  269. public:
  270. /*!
  271. * The destructor.
  272. */
  273. virtual ~CarlaEnginePort() noexcept;
  274. /*!
  275. * Get the type of the port, as provided by the respective subclasses.
  276. */
  277. virtual EnginePortType getType() const noexcept = 0;
  278. /*!
  279. * Initialize the port's internal buffer.
  280. */
  281. virtual void initBuffer() noexcept = 0;
  282. /*!
  283. * Check if this port is an input.
  284. */
  285. bool isInput() const noexcept
  286. {
  287. return kIsInput;
  288. }
  289. /*!
  290. * Get this ports' engine client.
  291. */
  292. const CarlaEngineClient& getEngineClient() const noexcept
  293. {
  294. return kClient;
  295. }
  296. #ifndef DOXYGEN
  297. protected:
  298. const CarlaEngineClient& kClient;
  299. const bool kIsInput;
  300. const uint32_t kIndexOffset;
  301. CARLA_DECLARE_NON_COPY_CLASS(CarlaEnginePort)
  302. #endif
  303. };
  304. /*!
  305. * Carla Engine Audio port.
  306. */
  307. class CARLA_API CarlaEngineAudioPort : public CarlaEnginePort
  308. {
  309. public:
  310. /*!
  311. * The constructor.
  312. * All constructor parameters are constant and will never change in the lifetime of the port.
  313. */
  314. CarlaEngineAudioPort(const CarlaEngineClient& client, const bool isInputPort, const uint32_t indexOffset) noexcept;
  315. /*!
  316. * The destructor.
  317. */
  318. ~CarlaEngineAudioPort() noexcept override;
  319. /*!
  320. * Get the type of the port, in this case kEnginePortTypeAudio.
  321. */
  322. EnginePortType getType() const noexcept final
  323. {
  324. return kEnginePortTypeAudio;
  325. }
  326. /*!
  327. * Initialize the port's internal buffer.
  328. */
  329. void initBuffer() noexcept override;
  330. /*!
  331. * Direct access to the port's audio buffer.
  332. * May be null.
  333. */
  334. float* getBuffer() const noexcept
  335. {
  336. return fBuffer;
  337. }
  338. #ifndef DOXYGEN
  339. protected:
  340. float* fBuffer;
  341. CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineAudioPort)
  342. #endif
  343. };
  344. /*!
  345. * Carla Engine CV port.
  346. */
  347. class CARLA_API CarlaEngineCVPort : public CarlaEnginePort
  348. {
  349. public:
  350. /*!
  351. * The constructor.
  352. * All constructor parameters are constant and will never change in the lifetime of the port.
  353. */
  354. CarlaEngineCVPort(const CarlaEngineClient& client, const bool isInputPort, const uint32_t indexOffset) noexcept;
  355. /*!
  356. * The destructor.
  357. */
  358. ~CarlaEngineCVPort() noexcept override;
  359. /*!
  360. * Get the type of the port, in this case kEnginePortTypeCV.
  361. */
  362. EnginePortType getType() const noexcept final
  363. {
  364. return kEnginePortTypeCV;
  365. }
  366. /*!
  367. * Initialize the port's internal buffer.
  368. */
  369. void initBuffer() noexcept override;
  370. /*!
  371. * Direct access to the port's CV buffer.
  372. * May be null.
  373. */
  374. float* getBuffer() const noexcept
  375. {
  376. return fBuffer;
  377. }
  378. #ifndef DOXYGEN
  379. protected:
  380. float* fBuffer;
  381. CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineCVPort)
  382. #endif
  383. };
  384. /*!
  385. * Carla Engine Event port.
  386. */
  387. class CARLA_API CarlaEngineEventPort : public CarlaEnginePort
  388. {
  389. public:
  390. /*!
  391. * The constructor.
  392. * All constructor parameters are constant and will never change in the lifetime of the port.
  393. */
  394. CarlaEngineEventPort(const CarlaEngineClient& client, const bool isInputPort, const uint32_t indexOffset) noexcept;
  395. /*!
  396. * The destructor.
  397. */
  398. ~CarlaEngineEventPort() noexcept override;
  399. /*!
  400. * Get the type of the port, in this case kEnginePortTypeEvent.
  401. */
  402. EnginePortType getType() const noexcept final
  403. {
  404. return kEnginePortTypeEvent;
  405. }
  406. /*!
  407. * Initialize the port's internal buffer for @a engine.
  408. */
  409. void initBuffer() noexcept override;
  410. /*!
  411. * Get the number of events present in the buffer.
  412. * @note You must only call this for input ports.
  413. */
  414. virtual uint32_t getEventCount() const noexcept;
  415. /*!
  416. * Get the event at @a index.
  417. * @note You must only call this for input ports.
  418. */
  419. virtual const EngineEvent& getEvent(const uint32_t index) const noexcept;
  420. /*!
  421. * Get the event at @a index, faster unchecked version.
  422. */
  423. virtual const EngineEvent& getEventUnchecked(const uint32_t index) const noexcept;
  424. /*!
  425. * Write a control event into the buffer.
  426. * @note You must only call this for output ports.
  427. */
  428. bool writeControlEvent(const uint32_t time, const uint8_t channel, const EngineControlEvent& ctrl) noexcept;
  429. /*!
  430. * Write a control event into the buffer.
  431. * Arguments are the same as in the EngineControlEvent struct.
  432. * @note You must only call this for output ports.
  433. */
  434. virtual bool writeControlEvent(const uint32_t time, const uint8_t channel, const EngineControlEventType type, const uint16_t param, const float value = 0.0f) noexcept;
  435. /*!
  436. * Write a MIDI event into the buffer.
  437. * @note You must only call this for output ports.
  438. */
  439. bool writeMidiEvent(const uint32_t time, const uint8_t size, const uint8_t* const data) noexcept;
  440. /*!
  441. * Write a MIDI event into the buffer.
  442. * @note You must only call this for output ports.
  443. */
  444. bool writeMidiEvent(const uint32_t time, const uint8_t channel, const EngineMidiEvent& midi) noexcept;
  445. /*!
  446. * Write a MIDI event into the buffer.
  447. * Arguments are the same as in the EngineMidiEvent struct.
  448. * @note You must only call this for output ports.
  449. */
  450. virtual bool writeMidiEvent(const uint32_t time, const uint8_t channel, const uint8_t size, const uint8_t* const data) noexcept;
  451. #ifndef DOXYGEN
  452. protected:
  453. EngineEvent* fBuffer;
  454. const EngineProcessMode kProcessMode;
  455. friend class CarlaPluginInstance;
  456. CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineEventPort)
  457. #endif
  458. };
  459. // -----------------------------------------------------------------------
  460. /*!
  461. * Carla Engine client.
  462. * Each plugin requires one client from the engine (created via CarlaEngine::addClient()).
  463. * @note This is a virtual class, some engine types provide custom funtionality.
  464. */
  465. class CARLA_API CarlaEngineClient
  466. {
  467. public:
  468. /*!
  469. * The constructor, protected.
  470. * All constructor parameters are constant and will never change in the lifetime of the client.
  471. * Client starts in deactivated state.
  472. */
  473. CarlaEngineClient(const CarlaEngine& engine);
  474. /*!
  475. * The destructor.
  476. */
  477. virtual ~CarlaEngineClient() noexcept;
  478. /*!
  479. * Activate this client.
  480. * Client must be deactivated before calling this function.
  481. */
  482. virtual void activate() noexcept;
  483. /*!
  484. * Deactivate this client.
  485. * Client must be activated before calling this function.
  486. */
  487. virtual void deactivate() noexcept;
  488. /*!
  489. * Check if the client is activated.
  490. */
  491. virtual bool isActive() const noexcept;
  492. /*!
  493. * Check if the client is ok.
  494. * Plugins will refuse to instantiate if this returns false.
  495. * @note This is always true in rack and patchbay processing modes.
  496. */
  497. virtual bool isOk() const noexcept;
  498. /*!
  499. * Get the current latency, in samples.
  500. */
  501. virtual uint32_t getLatency() const noexcept;
  502. /*!
  503. * Change the client's latency.
  504. */
  505. virtual void setLatency(const uint32_t samples) noexcept;
  506. /*!
  507. * Add a new port of type @a portType.
  508. * @note This function does nothing in rack processing mode since ports are static there.
  509. */
  510. virtual CarlaEnginePort* addPort(const EnginePortType portType, const char* const name, const bool isInput, const uint32_t indexOffset);
  511. /*!
  512. * Get this client's engine.
  513. */
  514. const CarlaEngine& getEngine() const noexcept;
  515. /*!
  516. * Get the engine's process mode.
  517. */
  518. EngineProcessMode getProcessMode() const noexcept;
  519. /*!
  520. * Get an audio port name.
  521. */
  522. const char* getAudioPortName(const bool isInput, const uint index) const noexcept;
  523. /*!
  524. * Get a CV port name.
  525. */
  526. const char* getCVPortName(const bool isInput, const uint index) const noexcept;
  527. /*!
  528. * Get an event port name.
  529. */
  530. const char* getEventPortName(const bool isInput, const uint index) const noexcept;
  531. #ifndef DOXYGEN
  532. protected:
  533. /*!
  534. * Internal data, for CarlaEngineClient subclasses only.
  535. */
  536. struct ProtectedData;
  537. ProtectedData* const pData;
  538. void _addAudioPortName(const bool, const char* const);
  539. void _addCVPortName(const bool, const char* const);
  540. void _addEventPortName(const bool, const char* const);
  541. const char* _getUniquePortName(const char* const);
  542. CARLA_DECLARE_NON_COPY_CLASS(CarlaEngineClient)
  543. #endif
  544. };
  545. // -----------------------------------------------------------------------
  546. /*!
  547. * Carla Engine.
  548. * @note This is a virtual class for all available engine types available in Carla.
  549. */
  550. class CARLA_API CarlaEngine
  551. {
  552. protected:
  553. /*!
  554. * The constructor, protected.
  555. * @note This only initializes engine data, it doesn't actually start the engine.
  556. */
  557. CarlaEngine();
  558. public:
  559. /*!
  560. * The destructor.
  561. * The engine must have been closed before this happens.
  562. */
  563. virtual ~CarlaEngine();
  564. // -------------------------------------------------------------------
  565. // Static calls
  566. /*!
  567. * Get the number of available engine drivers.
  568. */
  569. static uint getDriverCount();
  570. /*!
  571. * Get the name of the engine driver at @a index.
  572. */
  573. static const char* getDriverName(const uint index);
  574. /*!
  575. * Get the device names of the driver at @a index.
  576. */
  577. static const char* const* getDriverDeviceNames(const uint index);
  578. /*!
  579. * Get device information about the driver at @a index and name @a driverName.
  580. */
  581. static const EngineDriverDeviceInfo* getDriverDeviceInfo(const uint index, const char* const driverName);
  582. /*!
  583. * Create a new engine, using driver @a driverName.
  584. * Returned value must be deleted when no longer needed.
  585. * @note This only initializes engine data, it doesn't actually start the engine.
  586. */
  587. static CarlaEngine* newDriverByName(const char* const driverName);
  588. // -------------------------------------------------------------------
  589. // Constant values
  590. /*!
  591. * Maximum client name size.
  592. */
  593. virtual uint getMaxClientNameSize() const noexcept;
  594. /*!
  595. * Maximum port name size.
  596. */
  597. virtual uint getMaxPortNameSize() const noexcept;
  598. /*!
  599. * Current number of plugins loaded.
  600. */
  601. uint getCurrentPluginCount() const noexcept;
  602. /*!
  603. * Maximum number of loadable plugins allowed.
  604. * This function returns 0 if engine is not started.
  605. */
  606. uint getMaxPluginNumber() const noexcept;
  607. // -------------------------------------------------------------------
  608. // Virtual, per-engine type calls
  609. /*!
  610. * Initialize/start the engine, using @a clientName.
  611. * When the engine is intialized, you need to call idle() at regular intervals.
  612. */
  613. virtual bool init(const char* const clientName) = 0;
  614. /*!
  615. * Close engine.
  616. * This function always closes the engine even if it returns false.
  617. * In other words, even when something goes wrong when closing the engine it still be closed nonetheless.
  618. */
  619. virtual bool close();
  620. /*!
  621. * Idle engine.
  622. */
  623. virtual void idle() noexcept;
  624. /*!
  625. * Check if engine is running.
  626. */
  627. virtual bool isRunning() const noexcept = 0;
  628. /*!
  629. * Check if engine is running offline (aka freewheel mode).
  630. */
  631. virtual bool isOffline() const noexcept = 0;
  632. /*!
  633. * Get engine type.
  634. */
  635. virtual EngineType getType() const noexcept = 0;
  636. /*!
  637. * Get the currently used driver name.
  638. */
  639. virtual const char* getCurrentDriverName() const noexcept = 0;
  640. /*!
  641. * Add new engine client.
  642. * @note This function must only be called within a plugin class.
  643. */
  644. virtual CarlaEngineClient* addClient(CarlaPlugin* const plugin);
  645. // -------------------------------------------------------------------
  646. // Plugin management
  647. /*!
  648. * Add new plugin.
  649. * @see ENGINE_CALLBACK_PLUGIN_ADDED
  650. */
  651. bool addPlugin(const BinaryType btype, const PluginType ptype,
  652. const char* const filename, const char* const name, const char* const label, const int64_t uniqueId,
  653. const void* const extra, const uint options);
  654. /*!
  655. * Add new plugin, using native binary type and default options.
  656. * @see ENGINE_CALLBACK_PLUGIN_ADDED
  657. */
  658. bool addPlugin(const PluginType ptype,
  659. const char* const filename, const char* const name, const char* const label, const int64_t uniqueId,
  660. const void* const extra);
  661. /*!
  662. * Remove plugin with id @a id.
  663. * @see ENGINE_CALLBACK_PLUGIN_REMOVED
  664. */
  665. bool removePlugin(const uint id);
  666. /*!
  667. * Remove all plugins.
  668. */
  669. bool removeAllPlugins();
  670. #ifndef BUILD_BRIDGE
  671. /*!
  672. * Rename plugin with id @a id to @a newName.
  673. * Returns the new name, or null if the operation failed.
  674. * Returned variable must be deleted if non-null.
  675. * @see ENGINE_CALLBACK_PLUGIN_RENAMED
  676. */
  677. virtual const char* renamePlugin(const uint id, const char* const newName);
  678. /*!
  679. * Clone plugin with id @a id.
  680. */
  681. bool clonePlugin(const uint id);
  682. /*!
  683. * Prepare replace of plugin with id @a id.
  684. * The next call to addPlugin() will use this id, replacing the selected plugin.
  685. * @note This function requires addPlugin() to be called afterwards, as soon as possible.
  686. */
  687. bool replacePlugin(const uint id) noexcept;
  688. /*!
  689. * Switch plugins with id @a idA and @a idB.
  690. */
  691. bool switchPlugins(const uint idA, const uint idB) noexcept;
  692. #endif
  693. /*!
  694. * Get plugin with id @a id.
  695. */
  696. CarlaPlugin* getPlugin(const uint id) const noexcept;
  697. /*!
  698. * Get plugin with id @a id, faster unchecked version.
  699. */
  700. CarlaPlugin* getPluginUnchecked(const uint id) const noexcept;
  701. /*!
  702. * Get a unique plugin name within the engine.
  703. * Returned variable must be deleted if non-null.
  704. */
  705. const char* getUniquePluginName(const char* const name) const;
  706. // -------------------------------------------------------------------
  707. // Project management
  708. /*!
  709. * Load a file of any type.
  710. * This will try to load a generic file as a plugin,
  711. * either by direct handling (GIG, SF2 and SFZ) or by using an internal plugin (like Audio and MIDI).
  712. */
  713. bool loadFile(const char* const filename);
  714. /*!
  715. * Load a project file.
  716. * @note Already loaded plugins are not removed; call removeAllPlugins() first if needed.
  717. */
  718. bool loadProject(const char* const filename);
  719. /*!
  720. * Save current project to a file.
  721. */
  722. bool saveProject(const char* const filename);
  723. // -------------------------------------------------------------------
  724. // Information (base)
  725. /*!
  726. * Get the current engine driver hints.
  727. * @see EngineDriverHints
  728. */
  729. uint getHints() const noexcept;
  730. /*!
  731. * Get the current buffer size.
  732. */
  733. uint32_t getBufferSize() const noexcept;
  734. /*!
  735. * Get the current sample rate.
  736. */
  737. double getSampleRate() const noexcept;
  738. /*!
  739. * Get the current engine name.
  740. */
  741. const char* getName() const noexcept;
  742. /*!
  743. * Get the current engine proccess mode.
  744. */
  745. EngineProcessMode getProccessMode() const noexcept;
  746. /*!
  747. * Get the current engine options (read-only).
  748. */
  749. const EngineOptions& getOptions() const noexcept;
  750. /*!
  751. * Get the current Time information (read-only).
  752. */
  753. const EngineTimeInfo& getTimeInfo() const noexcept;
  754. // -------------------------------------------------------------------
  755. // Information (peaks)
  756. /*!
  757. * TODO.
  758. */
  759. float getInputPeak(const uint pluginId, const bool isLeft) const noexcept;
  760. /*!
  761. * TODO.
  762. */
  763. float getOutputPeak(const uint pluginId, const bool isLeft) const noexcept;
  764. // -------------------------------------------------------------------
  765. // Callback
  766. /*!
  767. * Call the main engine callback, if set.
  768. * May be called by plugins.
  769. */
  770. virtual void callback(const EngineCallbackOpcode action, const uint pluginId, const int value1, const int value2, const float value3, const char* const valueStr) noexcept;
  771. /*!
  772. * Set the main engine callback to @a func.
  773. */
  774. void setCallback(const EngineCallbackFunc func, void* const ptr) noexcept;
  775. // -------------------------------------------------------------------
  776. // Callback
  777. /*!
  778. * Call the file callback, if set.
  779. * May be called by plugins.
  780. */
  781. const char* runFileCallback(const FileCallbackOpcode action, const bool isDir, const char* const title, const char* const filter) noexcept;
  782. /*!
  783. * Set the file callback to @a func.
  784. */
  785. void setFileCallback(const FileCallbackFunc func, void* const ptr) noexcept;
  786. #ifndef BUILD_BRIDGE
  787. // -------------------------------------------------------------------
  788. // Patchbay
  789. /*!
  790. * Connect two patchbay ports.
  791. */
  792. virtual bool patchbayConnect(const uint groupA, const uint portA, const uint groupB, const uint portB);
  793. /*!
  794. * Remove a patchbay connection.
  795. */
  796. virtual bool patchbayDisconnect(const uint connectionId);
  797. /*!
  798. * Force the engine to resend all patchbay clients, ports and connections again.
  799. */
  800. virtual bool patchbayRefresh(const bool external);
  801. #endif
  802. // -------------------------------------------------------------------
  803. // Transport
  804. /*!
  805. * Start playback of the engine transport.
  806. */
  807. virtual void transportPlay() noexcept;
  808. /*!
  809. * Pause the engine transport.
  810. */
  811. virtual void transportPause() noexcept;
  812. /*!
  813. * Relocate the engine transport to @a frames.
  814. */
  815. virtual void transportRelocate(const uint64_t frame) noexcept;
  816. // -------------------------------------------------------------------
  817. // Error handling
  818. /*!
  819. * Get last error.
  820. */
  821. const char* getLastError() const noexcept;
  822. /*!
  823. * Set last error.
  824. */
  825. void setLastError(const char* const error) const noexcept;
  826. // -------------------------------------------------------------------
  827. // Misc
  828. /*!
  829. * Tell the engine it's about to close.
  830. * This is used to prevent the engine thread(s) from reactivating.
  831. */
  832. void setAboutToClose() noexcept;
  833. // -------------------------------------------------------------------
  834. // Options
  835. /*!
  836. * Set the engine option @a option to @a value or @a valueStr.
  837. */
  838. void setOption(const EngineOption option, const int value, const char* const valueStr) noexcept;
  839. // -------------------------------------------------------------------
  840. // OSC Stuff
  841. #ifndef BUILD_BRIDGE
  842. /*!
  843. * Check if OSC controller is registered.
  844. */
  845. bool isOscControlRegistered() const noexcept;
  846. #endif
  847. /*!
  848. * Idle OSC.
  849. */
  850. void idleOsc() const noexcept;
  851. /*!
  852. * Get OSC TCP server path.
  853. */
  854. const char* getOscServerPathTCP() const noexcept;
  855. /*!
  856. * Get OSC UDP server path.
  857. */
  858. const char* getOscServerPathUDP() const noexcept;
  859. // -------------------------------------------------------------------
  860. // Helper functions
  861. /*!
  862. * Return internal data, needed for EventPorts when used in Rack, Patchbay and Bridge modes.
  863. * @note RT call
  864. */
  865. EngineEvent* getInternalEventBuffer(const bool isInput) const noexcept;
  866. #ifndef BUILD_BRIDGE
  867. /*!
  868. * Virtual functions for handling external graph ports.
  869. */
  870. virtual bool connectExternalGraphPort(const uint, const uint, const char* const);
  871. virtual bool disconnectExternalGraphPort(const uint, const uint, const char* const);
  872. #endif
  873. // -------------------------------------------------------------------
  874. protected:
  875. /*!
  876. * Internal data, for CarlaEngine subclasses only.
  877. */
  878. struct ProtectedData;
  879. ProtectedData* const pData;
  880. /*!
  881. * Some internal classes read directly from pData or call protected functions.
  882. */
  883. friend class CarlaPluginInstance;
  884. friend class EngineInternalGraph;
  885. friend class PendingRtEventsRunner;
  886. friend class ScopedActionLock;
  887. friend class ScopedEngineEnvironmentLocker;
  888. friend struct PatchbayGraph;
  889. friend struct RackGraph;
  890. // -------------------------------------------------------------------
  891. // Internal stuff
  892. /*!
  893. * Report to all plugins about buffer size change.
  894. */
  895. void bufferSizeChanged(const uint32_t newBufferSize);
  896. /*!
  897. * Report to all plugins about sample rate change.
  898. * This is not supported on all plugin types, in which case they will have to be re-initiated.
  899. */
  900. void sampleRateChanged(const double newSampleRate);
  901. /*!
  902. * Report to all plugins about offline mode change.
  903. */
  904. void offlineModeChanged(const bool isOffline);
  905. /*!
  906. * Set a plugin (stereo) peak values.
  907. * @note RT call
  908. */
  909. void setPluginPeaks(const uint pluginId, float const inPeaks[2], float const outPeaks[2]) noexcept;
  910. /*!
  911. * Common save project function for main engine and plugin.
  912. */
  913. void saveProjectInternal(juce::MemoryOutputStream& outStrm) const;
  914. /*!
  915. * Common load project function for main engine and plugin.
  916. */
  917. bool loadProjectInternal(juce::XmlDocument& xmlDoc);
  918. #ifndef BUILD_BRIDGE
  919. // -------------------------------------------------------------------
  920. // Patchbay stuff
  921. /*!
  922. * Virtual functions for handling patchbay state.
  923. * Do not free returned data.
  924. */
  925. virtual const char* const* getPatchbayConnections(const bool external) const;
  926. virtual void restorePatchbayConnection(const bool external, const char* const sourcePort, const char* const targetPort, const bool sendCallback);
  927. #endif
  928. // -------------------------------------------------------------------
  929. public:
  930. /*!
  931. * Native audio APIs.
  932. */
  933. enum AudioApi {
  934. AUDIO_API_NULL = 0,
  935. // common
  936. AUDIO_API_JACK = 1,
  937. // linux
  938. AUDIO_API_ALSA = 2,
  939. AUDIO_API_OSS = 3,
  940. AUDIO_API_PULSE = 4,
  941. // macos
  942. AUDIO_API_CORE = 5,
  943. // windows
  944. AUDIO_API_ASIO = 6,
  945. AUDIO_API_DS = 7
  946. };
  947. // -------------------------------------------------------------------
  948. // Engine initializers
  949. // JACK
  950. static CarlaEngine* newJack();
  951. #ifdef BUILD_BRIDGE
  952. // Bridge
  953. static CarlaEngine* newBridge(const char* const audioPoolBaseName, const char* const rtClientBaseName, const char* const nonRtClientBaseName, const char* const nonRtServerBaseName);
  954. #else
  955. # if defined(CARLA_OS_MAC) || defined(CARLA_OS_WIN)
  956. // Juce
  957. static CarlaEngine* newJuce(const AudioApi api);
  958. static uint getJuceApiCount();
  959. static const char* getJuceApiName(const uint index);
  960. static const char* const* getJuceApiDeviceNames(const uint index);
  961. static const EngineDriverDeviceInfo* getJuceDeviceInfo(const uint index, const char* const deviceName);
  962. # else
  963. // RtAudio
  964. static CarlaEngine* newRtAudio(const AudioApi api);
  965. static uint getRtAudioApiCount();
  966. static const char* getRtAudioApiName(const uint index);
  967. static const char* const* getRtAudioApiDeviceNames(const uint index);
  968. static const EngineDriverDeviceInfo* getRtAudioDeviceInfo(const uint index, const char* const deviceName);
  969. # endif
  970. #endif
  971. #ifndef BUILD_BRIDGE
  972. // -------------------------------------------------------------------
  973. // OSC Controller stuff
  974. void oscSend_control_add_plugin_start(const uint pluginId, const char* const pluginName) const noexcept;
  975. void oscSend_control_add_plugin_end(const uint pluginId) const noexcept;
  976. void oscSend_control_remove_plugin(const uint pluginId) const noexcept;
  977. void oscSend_control_set_plugin_info1(const uint pluginId, const PluginType type, const PluginCategory category, const uint hints, const int64_t uniqueId) const noexcept;
  978. void oscSend_control_set_plugin_info2(const uint pluginId, const char* const realName, const char* const label, const char* const maker, const char* const copyright) const noexcept;
  979. void oscSend_control_set_audio_count(const uint pluginId, const uint32_t ins, const uint32_t outs) const noexcept;
  980. void oscSend_control_set_midi_count(const uint pluginId, const uint32_t ins, const uint32_t outs) const noexcept;
  981. void oscSend_control_set_parameter_count(const uint pluginId, const uint32_t ins, const uint32_t outs) const noexcept;
  982. void oscSend_control_set_program_count(const uint pluginId, const uint32_t count) const noexcept;
  983. void oscSend_control_set_midi_program_count(const uint pluginId, const uint32_t count) const noexcept;
  984. void oscSend_control_set_parameter_data(const uint pluginId, const uint32_t index, const ParameterType type, const uint hints, const char* const name, const char* const unit) const noexcept;
  985. void oscSend_control_set_parameter_ranges1(const uint pluginId, const uint32_t index, const float def, const float min, const float max) const noexcept;
  986. void oscSend_control_set_parameter_ranges2(const uint pluginId, const uint32_t index, const float step, const float stepSmall, const float stepLarge) const noexcept;
  987. void oscSend_control_set_parameter_midi_cc(const uint pluginId, const uint32_t index, const int16_t cc) const noexcept;
  988. void oscSend_control_set_parameter_midi_channel(const uint pluginId, const uint32_t index, const uint8_t channel) const noexcept;
  989. void oscSend_control_set_parameter_value(const uint pluginId, const int32_t index, const float value) const noexcept; // may be used for internal params (< 0)
  990. void oscSend_control_set_default_value(const uint pluginId, const uint32_t index, const float value) const noexcept;
  991. void oscSend_control_set_current_program(const uint pluginId, const int32_t index) const noexcept;
  992. void oscSend_control_set_current_midi_program(const uint pluginId, const int32_t index) const noexcept;
  993. void oscSend_control_set_program_name(const uint pluginId, const uint32_t index, const char* const name) const noexcept;
  994. void oscSend_control_set_midi_program_data(const uint pluginId, const uint32_t index, const uint32_t bank, const uint32_t program, const char* const name) const noexcept;
  995. void oscSend_control_note_on(const uint pluginId, const uint8_t channel, const uint8_t note, const uint8_t velo) const noexcept;
  996. void oscSend_control_note_off(const uint pluginId, const uint8_t channel, const uint8_t note) const noexcept;
  997. void oscSend_control_set_peaks(const uint pluginId) const noexcept;
  998. void oscSend_control_exit() const noexcept;
  999. #endif
  1000. CARLA_DECLARE_NON_COPY_CLASS(CarlaEngine)
  1001. };
  1002. /**@}*/
  1003. // -----------------------------------------------------------------------
  1004. CARLA_BACKEND_END_NAMESPACE
  1005. #endif // CARLA_ENGINE_HPP_INCLUDED