CarlaEngine Class Reference

#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 CarlaEngineClient *	addClient (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 EngineOptions &	getOptions () 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
void	saveProjectInternal (water::MemoryOutputStream &outStrm) const
bool	loadProjectInternal (water::XmlDocument &xmlDoc, bool alwaysLoadConnections)

Static Public Member Functions
static uint	getDriverCount ()
static const char *	getDriverName (uint index)
static const char *const *	getDriverDeviceNames (uint index)
static const EngineDriverDeviceInfo *	getDriverDeviceInfo (uint index, const char *driverName)
static bool	showDriverDeviceControlPanel (uint index, const char *deviceName)
static CarlaEngine *	newDriverByName (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
EngineEvent *	getInternalEventBuffer (bool isInput) const noexcept
virtual const char *const *	getPatchbayConnections (bool external) const
virtual const PatchbayPosition *	getPatchbayPositions (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	CarlaEngineRunner
class	CarlaPluginInstance
class	EngineInternalGraph
class	PendingRtEventsRunner
class	ScopedActionLock
class	ScopedEngineEnvironmentLocker
class	ScopedRunnerStopper
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

parameterId	The parameter to update
touch	The 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

Common save project function for main engine and plugin.

loadProjectInternal()

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

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 Symbol Documentation

CarlaEngineEventPort

friend class CarlaEngineEventPort

friend

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

CarlaEngineOsc

friend class CarlaEngineOsc

friend

CarlaEngineRunner

friend class CarlaEngineRunner

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

ScopedRunnerStopper

friend class ScopedRunnerStopper

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:

• CarlaEngine.hpp