linuxsampler 2.3.1
|
Instrument Editor Interface (external plugin) More...
#include <InstrumentEditor.h>
Public Types | |
enum | event_type_t { EVENT_TYPE_NOTEON = 1 , EVENT_TYPE_NOTEOFF = 2 , EVENT_TYPE_CC = 3 , EVENT_TYPE_PITCHBEND , EVENT_TYPE_PROGRAM , EVENT_TYPE_CHPRESSURE } |
Public Member Functions | |
virtual int | Main (void *pInstrument, String sTypeName, String sTypeVersion, void *pUserData=NULL)=0 |
Entry point for the instrument editor's thread. | |
virtual bool | IsTypeSupported (String sTypeName, String sTypeVersion)=0 |
The instrument editor has to return true in case it supports the given instrument data structure type and version, it has to return false otherwise. | |
virtual String | Name ()=0 |
The instrument editor's name (i.e. | |
virtual String | Version ()=0 |
The instrument editor's version (i.e. | |
virtual String | Description ()=0 |
Arbitrary textual description of the instrument editor (i.e. | |
void | NotifySamplesToBeRemoved (std::set< void * > Samples) |
Dispatch pending sample removal event. | |
void | NotifySamplesRemoved () |
Dispatch completed sample removal event. | |
void | NotifyDataStructureToBeChanged (void *pStruct, String sStructType) |
Dispatch pending data structure modification event. | |
void | NotifyDataStructureChanged (void *pStruct, String sStructType) |
Dispatch completed data structure modification event. | |
void | NotifySampleReferenceChanged (void *pOldSample, void *pNewSample) |
Dispatch sample reference changed event. | |
void | Launch (EngineChannel *pEngineChannel, void *pInstrument, String sTypeName, String sTypeVersion, void *pUserData=NULL) |
Launch the instrument editor for the given instrument. | |
EngineChannel * | GetEngineChannel () |
Returns the EngineChannel for which this instrument editor was spawned for, for editing the respective instrument loaded on that EngineChannel. | |
void | AddListener (InstrumentEditorListener *pListener) |
Registers object that wants to be notified on events. | |
void | RemoveListener (InstrumentEditorListener *pListener) |
Unregisters object that doesn't want to be notified anymore. | |
InstrumentEditor () | |
Constructor. | |
virtual | ~InstrumentEditor () |
Destructor. | |
bool | SendNoteOnToSampler (uint8_t Key, uint8_t Velocity) |
Sends a MIDI note on event to the sampler. | |
bool | SendNoteOffToSampler (uint8_t Key, uint8_t Velocity) |
Sends a MIDI note off event to the sampler. | |
bool | SendCCToSampler (uint8_t Controller, uint8_t Value) |
Sends a MIDI Control Change event to the sampler. | |
bool | SendChannelPressureToSampler (uint8_t Pressure) |
Sends a MIDI Channel Pressure (aftertouch) event to the sampler. | |
bool | SendPitchBendToSampler (int Pitch) |
Sends a MIDI Pitch Bend event to the sampler. | |
bool | SendProgramChangeToSampler (uint8_t Program) |
Sends a MIDI Program Change event to the sampler. | |
bool | NotesChanged () |
Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler during the last call to this method. | |
bool | NoteChanged (uint8_t Key) |
Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler for Key during the last call to this method. | |
bool | NoteIsActive (uint8_t Key) |
Can be called by the virtual MIDI device to check which key / note is currently active by the sampler, e.g. | |
uint8_t | NoteOnVelocity (uint8_t Key) |
Returns the velocity of the last note on event. | |
uint8_t | NoteOffVelocity (uint8_t Key) |
Returns the velocity of the last note off event. | |
bool | ControllersChanged () |
Can be called by the virtual MIDI device to check whether a Control Change MIDI event arrived to the sampler during the last call to this method. | |
bool | ControllerChanged (uint8_t Controller) |
Can be called by the virtual MIDI device to check whether a Control Change MIDI event arrived to the sampler for Controller during the last call to this method. | |
uint8_t | ControllerValue (uint8_t Controller) |
Returns the value of the last Control Change event. | |
void | SendNoteOnToDevice (uint8_t Key, uint8_t Velocity) |
Informs the virtual MIDI device that a note on event occured (e.g. | |
void | SendNoteOffToDevice (uint8_t Key, uint8_t Velocity) |
Informs the virtual MIDI device that a note off event occured (e.g. | |
void | SendCCToDevice (uint8_t Controller, uint8_t Value) |
Informs the virtual MIDI device that a Control Change event occured (e.g. | |
bool | GetMidiEventFromDevice (event_t &Event) |
Gets the next pending MIDI event from the virtual MIDI device by using a lockfree FIFO. | |
void | SetMaxEvents (int n) |
Adjusts the internal event buffer to cover at least the given amount of MIDI events. | |
void | Reset () |
Intended to be called on "panic" / all notes off situations. | |
Protected Member Functions | |
virtual int | Main () |
This method needs to be implemented by the descending class and is the entry point for the new thread. | |
virtual int | StartThread () |
virtual int | StopThread () |
virtual int | SignalStopThread () |
virtual bool | IsRunning () |
std::string | name () |
void | TestCancel () |
Synchronization point for potentially terminating the thread. | |
virtual int | SignalStartThread () |
virtual int | SetSchedulingPriority () |
virtual int | LockMemory () |
virtual void | EnableDestructor () |
virtual int | onThreadEnd () |
Static Protected Member Functions | |
static void * | allocAlignedMem (size_t boundary, size_t size) |
Allocates an aligned block of memory. | |
static void | freeAlignedMem (void *ptr) |
Frees an aligned block of memory allocated with allocAlignedMem() | |
static bool | lockMemory (void *addr, size_t size) |
Locks a region of memory in physical RAM. | |
static bool | unlockMemory (void *addr, size_t size) |
Unlocks a region of memory in physical RAM. | |
static void | pushCancelable (bool cancel) |
static void | popCancelable () |
static std::string | nameOfCaller () |
static void | setNameOfCaller (std::string name) |
Protected Attributes | |
std::set< InstrumentEditorListener * > | listeners |
Instrument Editor Interface (external plugin)
LinuxSampler allows to spawn arbitrary instrument editor applications within the sampler's own process. That way instrument editors are able to modify already loaded instruments live or on-the-fly, that is without having to load it again neither on sampler nor on editor side, which is essential for editing large instruments.
Instrument editors have to implement this abstract base class, embedded into a DLL and placed into the respective sampler's library path. The sampler will load these external DLLs as plugins on startup. Whenever there's a request for editing an instrument, the sampler will try to launch a matching registered editor, by calling the respective plugin's Main()
method.
Definition at line 51 of file InstrumentEditor.h.
Enumerator | |
---|---|
EVENT_TYPE_NOTEON | |
EVENT_TYPE_NOTEOFF | |
EVENT_TYPE_CC | |
EVENT_TYPE_PITCHBEND | |
EVENT_TYPE_PROGRAM | |
EVENT_TYPE_CHPRESSURE |
Definition at line 22 of file VirtualMidiDevice.h.
LinuxSampler::InstrumentEditor::InstrumentEditor | ( | ) |
Constructor.
|
virtual |
Destructor.
void LinuxSampler::InstrumentEditor::AddListener | ( | InstrumentEditorListener * | pListener | ) |
Registers object that wants to be notified on events.
|
inlinestaticinherited |
Allocates an aligned block of memory.
Allocated memory blocks need to be freed using freeAlignedMem().
boundary | - the alignement boundary, usually a power of 2 e.g. 4 but it can be an arbitrary number between 1 and 128 |
size | - size in bytes to be allocated |
Definition at line 83 of file Thread.h.
Referenced by LinuxSampler::AudioChannel::AudioChannel().
Can be called by the virtual MIDI device to check whether a Control Change MIDI event arrived to the sampler for Controller during the last call to this method.
So this is a asynchronously, "polling" based communication mechanism, which works in conjunction with the ControllerValue() method call.
|
inherited |
Can be called by the virtual MIDI device to check whether a Control Change MIDI event arrived to the sampler during the last call to this method.
So this is a asynchronously, "polling" based communication mechanism, which works in conjunction with the ControllerValue() method call.
Returns the value of the last Control Change event.
No FIFO is used!
Arbitrary textual description of the instrument editor (i.e.
"Gigasampler and DLS format editor, GTK based").
Frees an aligned block of memory allocated with allocAlignedMem()
ptr | - pointer to the memory block |
Definition at line 95 of file Thread.h.
Referenced by LinuxSampler::AudioChannel::~AudioChannel().
EngineChannel * LinuxSampler::InstrumentEditor::GetEngineChannel | ( | ) |
Returns the EngineChannel for which this instrument editor was spawned for, for editing the respective instrument loaded on that EngineChannel.
Gets the next pending MIDI event from the virtual MIDI device by using a lockfree FIFO.
Note: this method is usually only called by the sampler.
Event | - destination for writing the next event to |
|
pure virtual |
The instrument editor has to return true
in case it supports the given instrument data structure type and version, it has to return false
otherwise.
This method will be called by the sampler to determine which editor is capable to work with a certain instrument.
sTypeName | - i.e. "libgig" |
sTypeVersion | - i.e. "3.0.1" |
void LinuxSampler::InstrumentEditor::Launch | ( | EngineChannel * | pEngineChannel, |
void * | pInstrument, | ||
String | sTypeName, | ||
String | sTypeVersion, | ||
void * | pUserData = NULL |
||
) |
Launch the instrument editor for the given instrument.
The editor will be spawned in its own thread and this method will return as soon as the editor's thread actually started.
pEngineChannel | - the engine channel on which pInstrument is currently used on and for which the instrument editor shall be spawned for editing |
pInstrument | - pointer to the respective instrument object |
sTypeName | - format of the instrument data structure (i.e. "libgig" ) |
sTypeVersion | - version of the instrument data structure (i.e. "3.0.1" ). |
pUserData | - (optional) arbitrary 3rd party data that might e.g. been passed by InstrumentManager::LaunchInstrumentEditor() |
This method needs to be implemented by the descending class and is the entry point for the new thread.
NOTE: If your thread runs for a longer time, i.e. if it is running a loop, then you should explicitly call TestCancel() once in a while in your Main() implementation, especially if your implementation does not use any system calls.
Implements LinuxSampler::Thread.
|
pure virtual |
Entry point for the instrument editor's thread.
As the instrument data structure is passed as typeless (void*) pointer, this is not type safe! The implementing instrument editor has to interpret the sTypeName and sTypeVersion arguments to determine if it's able to cast the instrument pointer to a known type and actually be able to work with it.
pInstrument | - pointer to the respective instrument object |
sTypeName | - format of the instrument data structure (i.e. "libgig" ) |
sTypeVersion | - version of the instrument data structure (i.e. "3.0.1" ). |
pUserData | - (optional) arbitrary 3rd party data that might been passed by Launch() |
|
inherited |
The instrument editor's name (i.e.
"gigedit"
).
|
staticinherited |
Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler for Key during the last call to this method.
So this is a asynchronously, "polling" based communication mechanism, which works in conjunction with the NoteIsActive() method call.
Can be called by the virtual MIDI device to check which key / note is currently active by the sampler, e.g.
to highlight the respective keys on a graphical virtual keyboard.
Returns the velocity of the last note off event.
No FIFO is used!
Returns the velocity of the last note on event.
No FIFO is used!
|
inherited |
Can be called by the virtual MIDI device to check whether a new note on or note off MIDI event arrived to the sampler during the last call to this method.
So this is a asynchronously, "polling" based communication mechanism, which works in conjunction with the NoteIsActive() method call.
void LinuxSampler::InstrumentEditor::NotifyDataStructureChanged | ( | void * | pStruct, |
String | sStructType | ||
) |
Dispatch completed data structure modification event.
Inform the sampler that the by NotifyDataStructureToBeChanged()
previously announced data structure has been completely modified.
pStruct | - data structure that has been modified |
sStructType | - name of the data structure (i.e. its C++ struct or class name) |
void LinuxSampler::InstrumentEditor::NotifyDataStructureToBeChanged | ( | void * | pStruct, |
String | sStructType | ||
) |
Dispatch pending data structure modification event.
SHOULD be called by the instrument editor before modifying data structures (except samples, which have their own dispatch methods) which could otherwise lead to undesired synchronisation issues and a crash. The respective data structure is passed as a typeless pointer pStruct , so the instrument editor additionally has to pass the name of the data structure (i.e. "gig::Region"
), so the sampler can cast the pointer to an appropriate type. The sampler will react by stopping usage of the respective data structure.
After calling this method, the instrument editor MUST call NotifyDataStructureChanged()
, so the sampler can react by resuming usage of the respective data structure for playback.
pStruct | - data structure going to be modified |
sStructType | - name of the data structure (i.e. its C++ struct or class name) |
void LinuxSampler::InstrumentEditor::NotifySampleReferenceChanged | ( | void * | pOldSample, |
void * | pNewSample | ||
) |
Dispatch sample reference changed event.
SHOULD be called by the instrument editor after a certain data structure changed its reference / pointer to a sample, so the sampler can react by:
Note: the instrument editor additionally MUST embed this call into the respective NotifyDataStructureToBeChanged()
and NotifyDataStructureChanged()
calls for announcing the data structure whose sample reference is actually to be changed, so the sampler can react by suspending usage. For example:
So calling this method alone is not safe!
pOldSample | - previous sample reference |
pNewSample | - current sample reference |
void LinuxSampler::InstrumentEditor::NotifySamplesRemoved | ( | ) |
Dispatch completed sample removal event.
Inform the sampler that the by NotifySamplesToBeRemoved()
previously announced samples have been deleted.
Dispatch pending sample removal event.
SHOULD be called by the instrument editor before deleting samples, so the sampler can react by stopping usage of these samples to avoid a crash.
After calling this method, the instrument editor MUST call NotifySamplesRemoved()
after it actually deleted the samples, so the sampler can react by i.e. resuming playback of sampler engines.
Samples | - list of samples that will be deleted by the instrument editor |
void LinuxSampler::InstrumentEditor::RemoveListener | ( | InstrumentEditorListener * | pListener | ) |
Unregisters object that doesn't want to be notified anymore.
|
inherited |
Intended to be called on "panic" / all notes off situations.
Calling this method will reset all internal atomic flags, such that the state reflects that no note is currently active (its key pressed down).
Only exception: this method currently does not reset the internal ring buffer which is used to transmit MIDI events to the sampler.
Also note that this method is not fully concurrency safe. That means since only flags are reset, calling this method means no harm, but it might conflict with MIDI events etc and thus still cause hanging notes durcing such a specific concurrency conflict. Or in other words: the user might need to trigger the "panic" button multiple times.
|
inherited |
Informs the virtual MIDI device that a Control Change event occured (e.g.
caused by a MIDI keyboard connected to the sampler). Communication acts asynchronously, that is this method call doesn't lock in any way and returns immediately. It is thus realtime safe.
Note: this method is usually only called by the sampler.
|
inherited |
Sends a MIDI Control Change event to the sampler.
Sends a MIDI Channel Pressure (aftertouch) event to the sampler.
|
inherited |
Informs the virtual MIDI device that a note off event occured (e.g.
caused by a MIDI keyboard connected to the sampler). Communication acts asynchronously, that is this method call doesn't lock in any way and returns immediately. It is thus realtime safe.
Note: this method is usually only called by the sampler.
|
inherited |
Sends a MIDI note off event to the sampler.
|
inherited |
Informs the virtual MIDI device that a note on event occured (e.g.
caused by a MIDI keyboard connected to the sampler). Communication acts asynchronously, that is this method call doesn't lock in any way and returns immediately. It is thus realtime safe.
Note: this method is usually only called by the sampler.
|
inherited |
Sends a MIDI note on event to the sampler.
Sends a MIDI Pitch Bend event to the sampler.
Pitch | - MIDI pitch value (-8192 ... +8191) |
Sends a MIDI Program Change event to the sampler.
If you want to change the sound bank, call SendCCToSampler() (with controller = 0 for bank select MSB and/or controller = 32 for bank select LSB) before calling this method.
Program | - MIDI program number |
Adjusts the internal event buffer to cover at least the given amount of MIDI events.
This might be useful, since the internal event buffer is by default quite small (i.e. just 12 events).
This method is not thread safe! Any operations upon this device have to be stopped before calling this method!
|
protectedinherited |
Synchronization point for potentially terminating the thread.
Like already described in Main() you should call TestCancel() in your Main() implementation once in a while to provide the system a chance to perform a clean termination of your thread. Depending on the underlying OS, and also depending on whether your are using any system call in your Main() implementation, it might otherwise be possible that the thread cannot be terminated at all! And even if the underlying OS supports terminating busy threads which do not call TestCancel(), this might still cause undefined behavior on such OSes!
The instrument editor's version (i.e.
"0.0.1"
).
|
protected |
Definition at line 240 of file InstrumentEditor.h.