falkTX
/
Carla
mirror of https://github.com/falkTX/Carla
1
0
Fork 0
Code Releases 42 Activity
Browse Source

Update some comments

tags/1.9.4
falkTX 10 years ago
parent
4ec007ee1d
commit
cffc662a10
2 changed files with 95 additions and 88 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +90
    -84
      source/backend/CarlaEngine.hpp
  2. +5
    -4
      source/backend/plugin/CarlaPluginInternal.hpp

+ 90
- 84
source/backend/CarlaEngine.hpp View File

@@ -51,7 +51,7 @@ enum EngineType {
kEngineTypeNull = 0,

/*!
* JACK engine type.\n
* JACK engine type.
* Provides all processing modes.
*/
kEngineTypeJack = 1,
@@ -88,19 +88,19 @@ enum EnginePortType {

/*!
* Audio port type.
* \see CarlaEngineAudioPort
* @see CarlaEngineAudioPort
*/
kEnginePortTypeAudio = 1,

/*!
* CV port type.
* \see CarlaEngineCVPort
* @see CarlaEngineCVPort
*/
kEnginePortTypeCV = 2,

/*!
* Event port type (Control or MIDI).
* \see CarlaEngineEventPort
* @see CarlaEngineEventPort
*/
kEnginePortTypeEvent = 3
};
@@ -116,13 +116,13 @@ enum EngineEventType {

/*!
* Control event type.
* \see EngineControlEvent
* @see EngineControlEvent
*/
kEngineEventTypeControl = 1,

/*!
* MIDI event type.
* \see EngineMidiEvent
* @see EngineMidiEvent
*/
kEngineEventTypeMidi = 2
};
@@ -137,8 +137,8 @@ enum EngineControlEventType {
kEngineControlEventTypeNull = 0,

/*!
* Parameter event type.\n
* \note Value uses a normalized range of 0.0f<->1.0f.
* Parameter event type.
* @note Value uses a normalized range of 0.0f<->1.0f.
*/
kEngineControlEventTypeParameter = 1,

@@ -174,7 +174,7 @@ struct EngineControlEvent {
float value; //!< Parameter value, normalized to 0.0f<->1.0f.

/*!
* Convert this control event to MIDI data.
* Convert this control event into MIDI data.
*/
void convertToMidiData(const uint8_t channel, uint8_t& size, uint8_t data[3]) const noexcept;
};
@@ -299,16 +299,15 @@ struct EngineTimeInfo {
// -----------------------------------------------------------------------

/*!
* Carla Engine port (Abstract).\n
* Carla Engine port (Abstract).
* This is the base class for all Carla Engine ports.
*/
class CarlaEnginePort
{
protected:
/*!
* The constructor.\n
* Param \a isInputPort defines wherever this is an input port or not (output otherwise).\n
* Input/output and process mode are constant for the lifetime of the port.
* The constructor.
* All constructor parameters are constant and will never change in the lifetime of the port.
*/
CarlaEnginePort(const CarlaEngineClient& client, const bool isInputPort) noexcept;

@@ -360,7 +359,7 @@ class CarlaEngineAudioPort : public CarlaEnginePort
{
public:
/*!
* The constructor.\n
* The constructor.
* All constructor parameters are constant and will never change in the lifetime of the port.
*/
CarlaEngineAudioPort(const CarlaEngineClient& client, const bool isInputPort) noexcept;
@@ -373,7 +372,7 @@ public:
/*!
* Get the type of the port, in this case kEnginePortTypeAudio.
*/
EnginePortType getType() const noexcept override
EnginePortType getType() const noexcept final
{
return kEnginePortTypeAudio;
}
@@ -385,7 +384,7 @@ public:

/*!
* Direct access to the port's audio buffer.
* May return null.
* May be null.
*/
float* getBuffer() const noexcept
{
@@ -407,7 +406,7 @@ class CarlaEngineCVPort : public CarlaEnginePort
{
public:
/*!
* The constructor.\n
* The constructor.
* All constructor parameters are constant and will never change in the lifetime of the port.
*/
CarlaEngineCVPort(const CarlaEngineClient& client, const bool isInputPort) noexcept;
@@ -420,7 +419,7 @@ public:
/*!
* Get the type of the port, in this case kEnginePortTypeCV.
*/
EnginePortType getType() const noexcept override
EnginePortType getType() const noexcept final
{
return kEnginePortTypeCV;
}
@@ -432,7 +431,7 @@ public:

/*!
* Direct access to the port's CV buffer.
* May return null.
* May be null.
*/
float* getBuffer() const noexcept
{
@@ -454,7 +453,7 @@ class CarlaEngineEventPort : public CarlaEnginePort
{
public:
/*!
* The constructor.\n
* The constructor.
* All constructor parameters are constant and will never change in the lifetime of the port.
*/
CarlaEngineEventPort(const CarlaEngineClient& client, const bool isInputPort) noexcept;
@@ -467,62 +466,62 @@ public:
/*!
* Get the type of the port, in this case kEnginePortTypeEvent.
*/
EnginePortType getType() const noexcept override
EnginePortType getType() const noexcept final
{
return kEnginePortTypeEvent;
}

/*!
* Initialize the port's internal buffer for \a engine.
* Initialize the port's internal buffer for @a engine.
*/
void initBuffer() noexcept override;

/*!
* Get the number of events present in the buffer.
* \note You must only call this for input ports.
* @note You must only call this for input ports.
*/
virtual uint32_t getEventCount() const noexcept;

/*!
* Get the event at \a index.
* \note You must only call this for input ports.
* Get the event at @a index.
* @note You must only call this for input ports.
*/
virtual const EngineEvent& getEvent(const uint32_t index) const noexcept;

/*!
* Get the event at \a index, faster unchecked version.
* Get the event at @a index, faster unchecked version.
*/
virtual const EngineEvent& getEventUnchecked(const uint32_t index) const noexcept;

/*!
* Write a control event into the buffer.
* \note You must only call this for output ports.
* @note You must only call this for output ports.
*/
bool writeControlEvent(const uint32_t time, const uint8_t channel, const EngineControlEvent& ctrl) noexcept;

/*!
* Write a control event into the buffer.\n
* Write a control event into the buffer.
* Arguments are the same as in the EngineControlEvent struct.
* \note You must only call this for output ports.
* @note You must only call this for output ports.
*/
virtual bool writeControlEvent(const uint32_t time, const uint8_t channel, const EngineControlEventType type, const uint16_t param, const float value = 0.0f) noexcept;

/*!
* Write a MIDI event into the buffer.
* \note You must only call this for output ports.
* @note You must only call this for output ports.
*/
bool writeMidiEvent(const uint32_t time, const uint8_t size, const uint8_t* const data) noexcept;

/*!
* Write a MIDI event into the buffer.
* \note You must only call this for output ports.
* @note You must only call this for output ports.
*/
bool writeMidiEvent(const uint32_t time, const uint8_t channel, const EngineMidiEvent& midi) noexcept;

/*!
* Write a MIDI event into the buffer.\n
* Write a MIDI event into the buffer.
* Arguments are the same as in the EngineMidiEvent struct.
* \note You must only call this for output ports.
* @note You must only call this for output ports.
*/
virtual bool writeMidiEvent(const uint32_t time, const uint8_t channel, const uint8_t port, const uint8_t size, const uint8_t* const data) noexcept;

@@ -538,16 +537,16 @@ protected:
// -----------------------------------------------------------------------

/*!
* Carla Engine client.\n
* Each plugin requires one client from the engine (created via CarlaEngine::addClient()).\n
* \note This is a virtual class, some engine types provide custom funtionality.
* Carla Engine client.
* Each plugin requires one client from the engine (created via CarlaEngine::addClient()).
* @note This is a virtual class, some engine types provide custom funtionality.
*/
class CarlaEngineClient
{
public:
/*!
* The constructor, protected.\n
* All constructor parameters are constant and will never change in the lifetime of the client.\n
* The constructor, protected.
* All constructor parameters are constant and will never change in the lifetime of the client.
* Client starts in deactivated state.
*/
CarlaEngineClient(const CarlaEngine& engine) noexcept;
@@ -558,13 +557,13 @@ public:
virtual ~CarlaEngineClient() noexcept;

/*!
* Activate this client.\n
* Activate this client.
* Client must be deactivated before calling this function.
*/
virtual void activate() noexcept;

/*!
* Deactivate this client.\n
* Deactivate this client.
* Client must be activated before calling this function.
*/
virtual void deactivate() noexcept;
@@ -575,9 +574,9 @@ public:
virtual bool isActive() const noexcept;

/*!
* Check if the client is ok.\n
* Check if the client is ok.
* Plugins will refuse to instantiate if this returns false.
* \note This is always true in rack and patchbay processing modes.
* @note This is always true in rack and patchbay processing modes.
*/
virtual bool isOk() const noexcept;

@@ -592,8 +591,8 @@ public:
virtual void setLatency(const uint32_t samples) noexcept;

/*!
* Add a new port of type \a portType.
* \note This function does nothing in rack processing mode since ports are static there (2 audio + 1 event for both input and output).
* Add a new port of type @a portType.
* @note This function does nothing in rack processing mode since ports are static there.
*/
virtual CarlaEnginePort* addPort(const EnginePortType portType, const char* const name, const bool isInput);

@@ -620,20 +619,20 @@ protected:

/*!
* Carla Engine.
* \note This is a virtual class for all available engine types available in Carla.
* @note This is a virtual class for all available engine types available in Carla.
*/
class CarlaEngine
{
protected:
/*!
* The constructor, protected.\n
* \note This only initializes engine data, it doesn't start the engine (audio).
* The constructor, protected.
* @note This only initializes engine data, it doesn't actually start the engine.
*/
CarlaEngine();

public:
/*!
* The decontructor.
* The destructor.
* The engine must have been closed before this happens.
*/
virtual ~CarlaEngine();
@@ -647,24 +646,24 @@ public:
static uint getDriverCount();

/*!
* Get the name of the engine driver at \a index.
* Get the name of the engine driver at @a index.
*/
static const char* getDriverName(const uint index);

/*!
* Get the device names of driver at \a index.
* Get the device names of the driver at @a index.
*/
static const char* const* getDriverDeviceNames(const uint index);

/*!
* Get the device names of driver at \a index.
* Get device information about the driver at @a index and name @a driverName.
*/
static const EngineDriverDeviceInfo* getDriverDeviceInfo(const uint index, const char* const driverName);

/*!
* Create a new engine, using driver \a driverName. \n
* Returned variable must be deleted when no longer needed.
* \note This only initializes engine data, it doesn't initialize the engine itself.
* Create a new engine, using driver @a driverName.
* Returned value must be deleted when no longer needed.
* @note This only initializes engine data, it doesn't actually start the engine.
*/
static CarlaEngine* newDriverByName(const char* const driverName);

@@ -688,7 +687,7 @@ public:

/*!
* Maximum number of loadable plugins allowed.
* \note This function returns 0 if engine is not started.
* This function returns 0 if engine is not started.
*/
uint getMaxPluginNumber() const noexcept;

@@ -696,7 +695,8 @@ public:
// Virtual, per-engine type calls

/*!
* Initialize engine, using \a clientName.
* Initialize/start the engine, using @a clientName.
* When the engine is intialized, you need to call idle() at regular intervals.
*/
virtual bool init(const char* const clientName);

@@ -732,7 +732,7 @@ public:

/*!
* Add new engine client.
* \note This function must only be called within a plugin class.
* @note This function must only be called within a plugin class.
*/
virtual CarlaEngineClient* addClient(CarlaPlugin* const plugin);

@@ -741,16 +741,19 @@ public:

/*!
* Add new plugin.
* @see ENGINE_CALLBACK_PLUGIN_ADDED
*/
bool addPlugin(const BinaryType btype, const PluginType ptype, const char* const filename, const char* const name, const char* const label, const int64_t uniqueId, const void* const extra);

/*!
* Add new plugin, using native binary type.
* @see ENGINE_CALLBACK_PLUGIN_ADDED
*/
bool addPlugin(const PluginType ptype, const char* const filename, const char* const name, const char* const label, const int64_t uniqueId, const void* const extra);

/*!
* Remove plugin with id \a id.
* Remove plugin with id @a id.
* @see ENGINE_CALLBACK_PLUGIN_REMOVED
*/
bool removePlugin(const uint id);

@@ -760,41 +763,43 @@ public:
bool removeAllPlugins();

/*!
* Rename plugin with id \a id to \a newName.\n
* Returns the new name, or nullptr if the operation failed.
* Rename plugin with id @a id to @a newName.
* Returns the new name, or null if the operation failed.
* Returned variable must be deleted if non-null.
* @see ENGINE_CALLBACK_PLUGIN_RENAMED
*/
virtual const char* renamePlugin(const uint id, const char* const newName);

/*!
* Clone plugin with id \a id.
* Clone plugin with id @a id.
*/
bool clonePlugin(const uint id);

/*!
* Prepare replace of plugin with id \a id.\n
* Prepare replace of plugin with id @a 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.
* @note This function requires addPlugin() to be called afterwards, as soon as possible.
*/
bool replacePlugin(const uint id);

/*!
* Switch plugins with id \a idA and \a idB.
* Switch plugins with id @a idA and @a idB.
*/
bool switchPlugins(const uint idA, const uint idB);

/*!
* Get plugin with id \a id.
* Get plugin with id @a id.
*/
CarlaPlugin* getPlugin(const uint id) const;

/*!
* Get plugin with id \a id, faster unchecked version.
* Get plugin with id @a id, faster unchecked version.
*/
CarlaPlugin* getPluginUnchecked(const uint id) const noexcept;

/*!
* Get a unique plugin name within the engine.\n
* Returned variable must be deleted if non-NULL.
* Get a unique plugin name within the engine.
* Returned variable must be deleted if non-null.
*/
const char* getUniquePluginName(const char* const name) const;

@@ -802,7 +807,7 @@ public:
// Project management

/*!
* Load a file of any type.\n
* Load a file of any type.
* This will try to load a generic file as a plugin,
* either by direct handling (GIG, SF2 and SFZ) or by using an internal plugin (like Audio and MIDI).
*/
@@ -824,6 +829,7 @@ public:

/*!
* Get the current engine driver hints.
* @see EngineDriverHints
*/
uint getHints() const noexcept;

@@ -874,13 +880,13 @@ public:
// Callback

/*!
* Run the main engine callback, if set.
* Call the main engine callback, if set.
* May be called by plugins.
*/
void callback(const EngineCallbackOpcode action, const uint pluginId, const int value1, const int value2, const float value3, const char* const valueStr) noexcept;

/*!
* Set the main engine callback.
* Set the main engine callback to @a func.
*/
void setCallback(const EngineCallbackFunc func, void* const ptr) noexcept;

@@ -888,13 +894,13 @@ public:
// Callback

/*!
* Run the file callback, if set.
* Call the file callback, if set.
* May be called by plugins.
*/
const char* runFileCallback(const FileCallbackOpcode action, const bool isDir, const char* const title, const char* const filter) noexcept;

/*!
* Set the file callback.
* Set the file callback to @a func.
*/
void setFileCallback(const FileCallbackFunc func, void* const ptr) noexcept;

@@ -903,12 +909,12 @@ public:
// Patchbay

/*!
* Connect patchbay ports \a portA and \a portB.
* Connect two patchbay ports.
*/
virtual bool patchbayConnect(const uint groupA, const uint portA, const uint groupB, const uint portB);

/*!
* Disconnect patchbay connection \a connectionId.
* Remove a patchbay connection.
*/
virtual bool patchbayDisconnect(const uint connectionId);

@@ -932,7 +938,7 @@ public:
virtual void transportPause() noexcept;

/*!
* Relocate the engine transport to \a frames.
* Relocate the engine transport to @a frames.
*/
virtual void transportRelocate(const uint64_t frame) noexcept;

@@ -953,7 +959,7 @@ public:
// Misc

/*!
* Tell the engine it's about to close.\n
* Tell the engine it's about to close.
* This is used to prevent the engine thread(s) from reactivating.
*/
void setAboutToClose() noexcept;
@@ -962,7 +968,7 @@ public:
// Options

/*!
* Set the engine option \a option.
* Set the engine option @a option to @a value or @a valueStr.
*/
void setOption(const EngineOption option, const int value, const char* const valueStr);

@@ -1008,12 +1014,12 @@ public:

/*!
* Return internal data, needed for EventPorts when used in Rack and Bridge modes.
* \note RT call
* @note RT call
*/
EngineEvent* getInternalEventBuffer(const bool isInput) const noexcept;

/*!
* Force register a plugin into slot \a id. \n
* Force register a plugin into slot @a id.
* This is needed so we can receive OSC events for a plugin while it initializes.
*/
void registerEnginePlugin(const uint id, CarlaPlugin* const plugin) noexcept;
@@ -1047,7 +1053,7 @@ protected:
void bufferSizeChanged(const uint32_t newBufferSize);

/*!
* Report to all plugins about sample rate change.\n
* 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.
*/
void sampleRateChanged(const double newSampleRate);
@@ -1058,15 +1064,15 @@ protected:
void offlineModeChanged(const bool isOffline);

/*!
* Run any pending RT events.\n
* Run any pending RT events.
* Must always be called at the end of audio processing.
* \note RT call
* @note RT call
*/
void runPendingRtEvents() noexcept;

/*!
* Set a plugin (stereo) peak values.
* \note RT call
* @note RT call
*/
void setPluginPeaks(const uint pluginId, float const inPeaks[2], float const outPeaks[2]) noexcept;



+ 5
- 4
source/backend/plugin/CarlaPluginInternal.hpp View File

@@ -64,11 +64,12 @@ const uint PLUGIN_EXTRA_HINT_USES_MULTI_PROGS = 0x08;
// -----------------------------------------------------------------------

/*!
* Post-RT event type.\n
* Post-RT event type.
* These are events postponned from within the process function,
*
* During process, we cannot lock, allocate memory or do UI stuff,\n
* During process, we cannot lock, allocate memory or do UI stuff,
* so events have to be postponned to be executed later, on a separate thread.
* @see PluginPostRtEvent
*/
enum PluginPostRtEventType {
kPluginPostRtEventNull = 0,
@@ -82,7 +83,7 @@ enum PluginPostRtEventType {

/*!
* A Post-RT event.
* \see PluginPostRtEventType
* @see PluginPostRtEventType
*/
struct PluginPostRtEvent {
PluginPostRtEventType type;
@@ -96,7 +97,7 @@ struct PluginPostRtEvent {
struct ExternalMidiNote {
int8_t channel; // invalid if -1
uint8_t note; // 0 to 127
uint8_t velo; // note-off if 0
uint8_t velo; // 1 to 127, 0 for note-off
};

// -----------------------------------------------------------------------


Write Preview
Loading…
Cancel
Save