Carla Backend
Classes | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Friends | List of all members
CarlaEngine Class Referenceabstract

#include <CarlaEngine.hpp>

Classes

struct  PatchbayPosition
 

Public Member Functions

virtual ~CarlaEngine ()
 
virtual uint getMaxClientNameSize () const noexcept
 
virtual uint getMaxPortNameSize () const noexcept
 
uint getCurrentPluginCount () const noexcept
 
uint getMaxPluginNumber () const noexcept
 
virtual bool init (const char *clientName)=0
 
virtual bool close ()
 
virtual void idle () noexcept
 
virtual bool isRunning () const noexcept=0
 
virtual bool isOffline () const noexcept=0
 
virtual bool usesConstantBufferSize () const noexcept
 
virtual EngineType getType () const noexcept=0
 
virtual const char * getCurrentDriverName () const noexcept=0
 
virtual CarlaEngineClientaddClient (CarlaPluginPtr plugin)
 
virtual float getDSPLoad () const noexcept
 
virtual uint32_t getTotalXruns () const noexcept
 
virtual void clearXruns () const noexcept
 
virtual bool setBufferSizeAndSampleRate (uint bufferSize, double sampleRate)
 
virtual bool showDeviceControlPanel () const noexcept
 
bool addPlugin (BinaryType btype, PluginType ptype, const char *filename, const char *name, const char *label, int64_t uniqueId, const void *extra, uint options=PLUGIN_OPTIONS_NULL)
 
bool addPlugin (PluginType ptype, const char *filename, const char *name, const char *label, int64_t uniqueId, const void *extra)
 
virtual bool removePlugin (uint id)
 
bool removeAllPlugins ()
 
virtual bool renamePlugin (uint id, const char *newName)
 
bool clonePlugin (uint id)
 
bool replacePlugin (uint id) noexcept
 
virtual bool switchPlugins (uint idA, uint idB) noexcept
 
virtual void touchPluginParameter (uint id, uint32_t parameterId, bool touch) noexcept
 
CarlaPluginPtr getPlugin (uint id) const noexcept
 
CarlaPluginPtr getPluginUnchecked (uint id) const noexcept
 
const char * getUniquePluginName (const char *name) const
 
bool loadFile (const char *filename)
 
bool loadProject (const char *filename, bool setAsCurrentProject)
 
bool saveProject (const char *filename, bool setAsCurrentProject)
 
virtual const char * getCurrentProjectFolder () const noexcept
 
const char * getCurrentProjectFilename () const noexcept
 
void clearCurrentProjectFilename () noexcept
 
uint32_t getBufferSize () const noexcept
 
double getSampleRate () const noexcept
 
const char * getName () const noexcept
 
EngineProcessMode getProccessMode () const noexcept
 
const EngineOptionsgetOptions () const noexcept
 
virtual EngineTimeInfo getTimeInfo () const noexcept
 
const float * getPeaks (uint pluginId) const noexcept
 
float getInputPeak (uint pluginId, bool isLeft) const noexcept
 
float getOutputPeak (uint pluginId, bool isLeft) const noexcept
 
virtual void callback (bool sendHost, bool sendOSC, EngineCallbackOpcode action, uint pluginId, int value1, int value2, int value3, float valuef, const char *valueStr) noexcept
 
void setCallback (EngineCallbackFunc func, void *ptr) noexcept
 
virtual const char * runFileCallback (FileCallbackOpcode action, bool isDir, const char *title, const char *filter) noexcept
 
void setFileCallback (FileCallbackFunc func, void *ptr) noexcept
 
virtual bool patchbayConnect (bool external, uint groupA, uint portA, uint groupB, uint portB)
 
virtual bool patchbayDisconnect (bool external, uint connectionId)
 
virtual bool patchbaySetGroupPos (bool sendHost, bool sendOSC, bool external, uint groupId, int x1, int y1, int x2, int y2)
 
virtual bool patchbayRefresh (bool sendHost, bool sendOSC, bool external)
 
virtual void transportPlay () noexcept
 
virtual void transportPause () noexcept
 
virtual void transportBPM (double bpm) noexcept
 
virtual void transportRelocate (uint64_t frame) noexcept
 
const char * getLastError () const noexcept
 
void setLastError (const char *error) const noexcept
 
bool isAboutToClose () const noexcept
 
bool setAboutToClose () noexcept
 
bool isLoadingProject () const noexcept
 
void setActionCanceled (bool canceled) noexcept
 
bool wasActionCanceled () const noexcept
 
virtual void setOption (EngineOption option, int value, const char *valueStr) noexcept
 
bool isOscControlRegistered () const noexcept
 
const char * getOscServerPathTCP () const noexcept
 
const char * getOscServerPathUDP () const noexcept
 

Static Public Member Functions

static uint getDriverCount ()
 
static const char * getDriverName (uint index)
 
static const char *const * getDriverDeviceNames (uint index)
 
static const EngineDriverDeviceInfogetDriverDeviceInfo (uint index, const char *driverName)
 
static bool showDriverDeviceControlPanel (uint index, const char *deviceName)
 
static CarlaEnginenewDriverByName (const char *driverName)
 

Protected Member Functions

 CarlaEngine ()
 
void bufferSizeChanged (uint32_t newBufferSize)
 
void sampleRateChanged (double newSampleRate)
 
void offlineModeChanged (bool isOffline)
 
void setPluginPeaksRT (uint pluginId, float const inPeaks[2], float const outPeaks[2]) noexcept
 
void saveProjectInternal (water::MemoryOutputStream &outStrm) const
 
bool loadProjectInternal (water::XmlDocument &xmlDoc, bool alwaysLoadConnections)
 
EngineEventgetInternalEventBuffer (bool isInput) const noexcept
 
virtual const char *const * getPatchbayConnections (bool external) const
 
virtual const PatchbayPositiongetPatchbayPositions (bool external, uint &count) const
 
virtual void restorePatchbayConnection (bool external, const char *sourcePort, const char *targetPort)
 
virtual bool restorePatchbayGroupPosition (bool external, PatchbayPosition &ppos)
 
virtual bool connectExternalGraphPort (uint, uint, const char *)
 
virtual bool disconnectExternalGraphPort (uint, uint, const char *)
 

Protected Attributes

ProtectedData *const pData
 

Friends

class CarlaEngineEventPort
 
class CarlaEngineOsc
 
class CarlaEngineThread
 
class CarlaPluginInstance
 
class EngineInternalGraph
 
class PendingRtEventsRunner
 
class ScopedActionLock
 
class ScopedEngineEnvironmentLocker
 
class ScopedThreadStopper
 
class PatchbayGraph
 
struct ExternalGraph
 
struct RackGraph
 

Detailed Description

Carla Engine.

Note
This is a virtual class for all available engine types available in Carla.

Constructor & Destructor Documentation

◆ CarlaEngine()

CarlaEngine::CarlaEngine ( )
protected

The constructor, protected.

Note
This only initializes engine data, it doesn't actually start the engine.

◆ ~CarlaEngine()

virtual CarlaEngine::~CarlaEngine ( )
virtual

The destructor. The engine must have been closed before this happens.

Member Function Documentation

◆ getDriverCount()

static uint CarlaEngine::getDriverCount ( )
static

Get the number of available engine drivers.

◆ getDriverName()

static const char* CarlaEngine::getDriverName ( uint  index)
static

Get the name of the engine driver at index.

◆ getDriverDeviceNames()

static const char* const* CarlaEngine::getDriverDeviceNames ( uint  index)
static

Get the device names of the driver at index.

◆ getDriverDeviceInfo()

static const EngineDriverDeviceInfo* CarlaEngine::getDriverDeviceInfo ( uint  index,
const char *  driverName 
)
static

Get device information about the driver at index and name driverName.

◆ showDriverDeviceControlPanel()

static bool CarlaEngine::showDriverDeviceControlPanel ( uint  index,
const char *  deviceName 
)
static

Show a device custom control panel.

See also
ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL

◆ newDriverByName()

static CarlaEngine* CarlaEngine::newDriverByName ( const char *  driverName)
static

Create a new engine, using driver driverName. Returned value must be deleted when no longer needed.

Note
This only initializes engine data, it doesn't actually start the engine.

◆ getMaxClientNameSize()

virtual uint CarlaEngine::getMaxClientNameSize ( ) const
virtualnoexcept

Maximum client name size.

◆ getMaxPortNameSize()

virtual uint CarlaEngine::getMaxPortNameSize ( ) const
virtualnoexcept

Maximum port name size.

◆ getCurrentPluginCount()

uint CarlaEngine::getCurrentPluginCount ( ) const
noexcept

Current number of plugins loaded.

◆ getMaxPluginNumber()

uint CarlaEngine::getMaxPluginNumber ( ) const
noexcept

Maximum number of loadable plugins allowed. This function returns 0 if engine is not started.

◆ init()

virtual bool CarlaEngine::init ( const char *  clientName)
pure virtual

Initialize/start the engine, using clientName. When the engine is initialized, you need to call idle() at regular intervals.

◆ close()

virtual bool CarlaEngine::close ( )
virtual

Close engine. This function always closes the engine even if it returns false. In other words, even when something goes wrong when closing the engine it still be closed nonetheless.

◆ idle()

virtual void CarlaEngine::idle ( )
virtualnoexcept

Idle engine.

◆ isRunning()

virtual bool CarlaEngine::isRunning ( ) const
pure virtualnoexcept

Check if engine is running.

◆ isOffline()

virtual bool CarlaEngine::isOffline ( ) const
pure virtualnoexcept

Check if engine is running offline (aka freewheel mode).

◆ usesConstantBufferSize()

virtual bool CarlaEngine::usesConstantBufferSize ( ) const
virtualnoexcept

Check if engine runs on a constant buffer size value. Default implementation returns true.

◆ getType()

virtual EngineType CarlaEngine::getType ( ) const
pure virtualnoexcept

Get engine type.

◆ getCurrentDriverName()

virtual const char* CarlaEngine::getCurrentDriverName ( ) const
pure virtualnoexcept

Get the currently used driver name.

◆ addClient()

virtual CarlaEngineClient* CarlaEngine::addClient ( CarlaPluginPtr  plugin)
virtual

Add new engine client.

Note
This function must only be called within a plugin class.

◆ getDSPLoad()

virtual float CarlaEngine::getDSPLoad ( ) const
virtualnoexcept

Get the current CPU load estimated by the engine.

◆ getTotalXruns()

virtual uint32_t CarlaEngine::getTotalXruns ( ) const
virtualnoexcept

Get the total number of xruns so far.

◆ clearXruns()

virtual void CarlaEngine::clearXruns ( ) const
virtualnoexcept

Clear the xrun count.

◆ setBufferSizeAndSampleRate()

virtual bool CarlaEngine::setBufferSizeAndSampleRate ( uint  bufferSize,
double  sampleRate 
)
virtual

Dynamically change buffer size and/or sample rate while engine is running.

See also
ENGINE_DRIVER_DEVICE_VARIABLE_BUFFER_SIZE
ENGINE_DRIVER_DEVICE_VARIABLE_SAMPLE_RATE

◆ showDeviceControlPanel()

virtual bool CarlaEngine::showDeviceControlPanel ( ) const
virtualnoexcept

Show the custom control panel for the current engine device.

See also
ENGINE_DRIVER_DEVICE_HAS_CONTROL_PANEL

◆ addPlugin() [1/2]

bool CarlaEngine::addPlugin ( BinaryType  btype,
PluginType  ptype,
const char *  filename,
const char *  name,
const char *  label,
int64_t  uniqueId,
const void *  extra,
uint  options = PLUGIN_OPTIONS_NULL 
)

Add new plugin.

See also
ENGINE_CALLBACK_PLUGIN_ADDED

◆ addPlugin() [2/2]

bool CarlaEngine::addPlugin ( PluginType  ptype,
const char *  filename,
const char *  name,
const char *  label,
int64_t  uniqueId,
const void *  extra 
)

Add new plugin, using native binary type.

See also
ENGINE_CALLBACK_PLUGIN_ADDED

◆ removePlugin()

virtual bool CarlaEngine::removePlugin ( uint  id)
virtual

Remove plugin with id id.

See also
ENGINE_CALLBACK_PLUGIN_REMOVED

◆ removeAllPlugins()

bool CarlaEngine::removeAllPlugins ( )

Remove all plugins.

◆ renamePlugin()

virtual bool CarlaEngine::renamePlugin ( uint  id,
const char *  newName 
)
virtual

Rename plugin with id id to newName. Returns the new name, or null if the operation failed. Returned variable must be deleted if non-null.

See also
ENGINE_CALLBACK_PLUGIN_RENAMED

◆ clonePlugin()

bool CarlaEngine::clonePlugin ( uint  id)

Clone plugin with id id.

◆ replacePlugin()

bool CarlaEngine::replacePlugin ( uint  id)
noexcept

Prepare replace of plugin with id id. The next call to addPlugin() will use this id, replacing the selected plugin.

Note
This function requires addPlugin() to be called afterwards, as soon as possible.

◆ switchPlugins()

virtual bool CarlaEngine::switchPlugins ( uint  idA,
uint  idB 
)
virtualnoexcept

Switch plugins with id idA and idB.

◆ touchPluginParameter()

virtual void CarlaEngine::touchPluginParameter ( uint  id,
uint32_t  parameterId,
bool  touch 
)
virtualnoexcept

Set a plugin's parameter in drag/touch mode. Usually happens from a UI when the user is moving a parameter with a mouse or similar input.

Parameters
parameterIdThe parameter to update
touchThe new state for the parameter

◆ getPlugin()

CarlaPluginPtr CarlaEngine::getPlugin ( uint  id) const
noexcept

Get plugin with id id.

◆ getPluginUnchecked()

CarlaPluginPtr CarlaEngine::getPluginUnchecked ( uint  id) const
noexcept

Get plugin with id id, faster unchecked version.

◆ getUniquePluginName()

const char* CarlaEngine::getUniquePluginName ( const char *  name) const

Get a unique plugin name within the engine. Returned variable must be deleted if non-null.

◆ loadFile()

bool CarlaEngine::loadFile ( const char *  filename)

Load a file of any type. This will try to load a generic file as a plugin, either by direct handling (SF2 and SFZ) or by using an internal plugin (like Audio and MIDI).

◆ loadProject()

bool CarlaEngine::loadProject ( const char *  filename,
bool  setAsCurrentProject 
)

Load a project file.

Note
Already loaded plugins are not removed; call removeAllPlugins() first if needed.

◆ saveProject()

bool CarlaEngine::saveProject ( const char *  filename,
bool  setAsCurrentProject 
)

Save current project to a file.

◆ getCurrentProjectFolder()

virtual const char* CarlaEngine::getCurrentProjectFolder ( ) const
virtualnoexcept

Get the currently set project folder.

Note
Valid for both standalone and plugin versions.

◆ getCurrentProjectFilename()

const char* CarlaEngine::getCurrentProjectFilename ( ) const
noexcept

Get the currently set project filename.

Note
Valid only for both standalone version.

◆ clearCurrentProjectFilename()

void CarlaEngine::clearCurrentProjectFilename ( )
noexcept

Clear the currently set project filename.

◆ getBufferSize()

uint32_t CarlaEngine::getBufferSize ( ) const
noexcept

Get the current buffer size.

◆ getSampleRate()

double CarlaEngine::getSampleRate ( ) const
noexcept

Get the current sample rate.

◆ getName()

const char* CarlaEngine::getName ( ) const
noexcept

Get the current engine name.

◆ getProccessMode()

EngineProcessMode CarlaEngine::getProccessMode ( ) const
noexcept

Get the current engine process mode.

◆ getOptions()

const EngineOptions& CarlaEngine::getOptions ( ) const
noexcept

Get the current engine options (read-only).

◆ getTimeInfo()

virtual EngineTimeInfo CarlaEngine::getTimeInfo ( ) const
virtualnoexcept

Get the current Time information (read-only).

◆ getPeaks()

const float* CarlaEngine::getPeaks ( uint  pluginId) const
noexcept

Get a plugin's peak values.

Note
not thread-safe if pluginId == MAIN_CARLA_PLUGIN_ID

◆ getInputPeak()

float CarlaEngine::getInputPeak ( uint  pluginId,
bool  isLeft 
) const
noexcept

Get a plugin's input peak value.

◆ getOutputPeak()

float CarlaEngine::getOutputPeak ( uint  pluginId,
bool  isLeft 
) const
noexcept

Get a plugin's output peak value.

◆ callback()

virtual void CarlaEngine::callback ( bool  sendHost,
bool  sendOSC,
EngineCallbackOpcode  action,
uint  pluginId,
int  value1,
int  value2,
int  value3,
float  valuef,
const char *  valueStr 
)
virtualnoexcept

Call the main engine callback, if set. May be called by plugins.

◆ setCallback()

void CarlaEngine::setCallback ( EngineCallbackFunc  func,
void *  ptr 
)
noexcept

Set the main engine callback to func.

◆ runFileCallback()

virtual const char* CarlaEngine::runFileCallback ( FileCallbackOpcode  action,
bool  isDir,
const char *  title,
const char *  filter 
)
virtualnoexcept

Call the file callback, if set. May be called by plugins.

◆ setFileCallback()

void CarlaEngine::setFileCallback ( FileCallbackFunc  func,
void *  ptr 
)
noexcept

Set the file callback to func.

◆ patchbayConnect()

virtual bool CarlaEngine::patchbayConnect ( bool  external,
uint  groupA,
uint  portA,
uint  groupB,
uint  portB 
)
virtual

Connect two patchbay ports.

◆ patchbayDisconnect()

virtual bool CarlaEngine::patchbayDisconnect ( bool  external,
uint  connectionId 
)
virtual

Remove a patchbay connection.

◆ patchbaySetGroupPos()

virtual bool CarlaEngine::patchbaySetGroupPos ( bool  sendHost,
bool  sendOSC,
bool  external,
uint  groupId,
int  x1,
int  y1,
int  x2,
int  y2 
)
virtual

Set the position of a group.

◆ patchbayRefresh()

virtual bool CarlaEngine::patchbayRefresh ( bool  sendHost,
bool  sendOSC,
bool  external 
)
virtual

Force the engine to resend all patchbay clients, ports and connections again.

◆ transportPlay()

virtual void CarlaEngine::transportPlay ( )
virtualnoexcept

Start playback of the engine transport.

◆ transportPause()

virtual void CarlaEngine::transportPause ( )
virtualnoexcept

Pause the engine transport.

◆ transportBPM()

virtual void CarlaEngine::transportBPM ( double  bpm)
virtualnoexcept

Set the engine transport bpm to bpm.

◆ transportRelocate()

virtual void CarlaEngine::transportRelocate ( uint64_t  frame)
virtualnoexcept

Relocate the engine transport to frames.

◆ getLastError()

const char* CarlaEngine::getLastError ( ) const
noexcept

Get last error.

◆ setLastError()

void CarlaEngine::setLastError ( const char *  error) const
noexcept

Set last error.

◆ isAboutToClose()

bool CarlaEngine::isAboutToClose ( ) const
noexcept

Check if the engine is about to close.

◆ setAboutToClose()

bool CarlaEngine::setAboutToClose ( )
noexcept

Tell the engine it's about to close. This is used to prevent the engine thread(s) from reactivating. Returns true if there's no pending engine events.

◆ isLoadingProject()

bool CarlaEngine::isLoadingProject ( ) const
noexcept

TODO.

◆ setActionCanceled()

void CarlaEngine::setActionCanceled ( bool  canceled)
noexcept

Tell the engine to stop the current cancelable action.

See also
ENGINE_CALLBACK_CANCELABLE_ACTION

◆ wasActionCanceled()

bool CarlaEngine::wasActionCanceled ( ) const
noexcept

Check wherever the last cancelable action was indeed canceled or not.

◆ setOption()

virtual void CarlaEngine::setOption ( EngineOption  option,
int  value,
const char *  valueStr 
)
virtualnoexcept

Set the engine option option to value or valueStr.

◆ isOscControlRegistered()

bool CarlaEngine::isOscControlRegistered ( ) const
noexcept

Check if OSC controller is registered.

◆ getOscServerPathTCP()

const char* CarlaEngine::getOscServerPathTCP ( ) const
noexcept

Get OSC TCP server path.

◆ getOscServerPathUDP()

const char* CarlaEngine::getOscServerPathUDP ( ) const
noexcept

Get OSC UDP server path.

◆ bufferSizeChanged()

void CarlaEngine::bufferSizeChanged ( uint32_t  newBufferSize)
protected

Report to all plugins about buffer size change.

◆ sampleRateChanged()

void CarlaEngine::sampleRateChanged ( double  newSampleRate)
protected

Report to all plugins about sample rate change. This is not supported on all plugin types, in which case they will have to be re-initiated.

◆ offlineModeChanged()

void CarlaEngine::offlineModeChanged ( bool  isOffline)
protected

Report to all plugins about offline mode change.

◆ setPluginPeaksRT()

void CarlaEngine::setPluginPeaksRT ( uint  pluginId,
float const  inPeaks[2],
float const  outPeaks[2] 
)
protectednoexcept

Set a plugin (stereo) peak values.

Note
RT call

◆ saveProjectInternal()

void CarlaEngine::saveProjectInternal ( water::MemoryOutputStream &  outStrm) const
protected

Common save project function for main engine and plugin.

◆ loadProjectInternal()

bool CarlaEngine::loadProjectInternal ( water::XmlDocument &  xmlDoc,
bool  alwaysLoadConnections 
)
protected

Common load project function for main engine and plugin.

◆ getInternalEventBuffer()

EngineEvent* CarlaEngine::getInternalEventBuffer ( bool  isInput) const
protectednoexcept

Return internal data, needed for EventPorts when used in Rack, Patchbay and Bridge modes.

Note
RT call

◆ getPatchbayConnections()

virtual const char* const* CarlaEngine::getPatchbayConnections ( bool  external) const
protectedvirtual

◆ getPatchbayPositions()

virtual const PatchbayPosition* CarlaEngine::getPatchbayPositions ( bool  external,
uint &  count 
) const
protectedvirtual

◆ restorePatchbayConnection()

virtual void CarlaEngine::restorePatchbayConnection ( bool  external,
const char *  sourcePort,
const char *  targetPort 
)
protectedvirtual

◆ restorePatchbayGroupPosition()

virtual bool CarlaEngine::restorePatchbayGroupPosition ( bool  external,
PatchbayPosition ppos 
)
protectedvirtual

◆ connectExternalGraphPort()

virtual bool CarlaEngine::connectExternalGraphPort ( uint  ,
uint  ,
const char *   
)
protectedvirtual

Virtual functions for handling external graph ports.

◆ disconnectExternalGraphPort()

virtual bool CarlaEngine::disconnectExternalGraphPort ( uint  ,
uint  ,
const char *   
)
protectedvirtual

Friends And Related Function Documentation

◆ CarlaEngineEventPort

friend class CarlaEngineEventPort
friend

Some internal classes read directly from pData or call protected functions.

◆ CarlaEngineOsc

friend class CarlaEngineOsc
friend

◆ CarlaEngineThread

friend class CarlaEngineThread
friend

◆ CarlaPluginInstance

friend class CarlaPluginInstance
friend

◆ EngineInternalGraph

friend class EngineInternalGraph
friend

◆ PendingRtEventsRunner

friend class PendingRtEventsRunner
friend

◆ ScopedActionLock

friend class ScopedActionLock
friend

◆ ScopedEngineEnvironmentLocker

friend class ScopedEngineEnvironmentLocker
friend

◆ ScopedThreadStopper

friend class ScopedThreadStopper
friend

◆ PatchbayGraph

friend class PatchbayGraph
friend

◆ ExternalGraph

friend struct ExternalGraph
friend

◆ RackGraph

friend struct RackGraph
friend

Member Data Documentation

◆ pData

ProtectedData* const CarlaEngine::pData
protected

The documentation for this class was generated from the following file: