linuxsampler 1.0.0
|
Instrument Editor Interface (external plugin) More...
#include <InstrumentEditor.h>
Public Types | |
enum | event_type_t { EVENT_TYPE_NOTEON = 1, EVENT_TYPE_NOTEOFF = 2 } |
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 (void *pInstrument, String sTypeName, String sTypeVersion, void *pUserData=NULL) |
Launch the instrument editor for the given instrument. | |
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 | 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. | |
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. | |
bool | GetMidiEventFromDevice (event_t &Event) |
Gets the next pending MIDI event from the virtual MIDI device by using a lockfree FIFO. | |
Protected Member Functions | |
virtual int | Main () |
This method needs to be implemented by the descendant and is the entry point for the new thread. FIXME: should be protected. | |
virtual int | StartThread () |
virtual int | StopThread () |
virtual int | SignalStartThread () |
virtual int | SignalStopThread () |
void | TestCancel () |
virtual bool | IsRunning () |
virtual int | SetSchedulingPriority () |
virtual int | LockMemory () |
virtual void | EnableDestructor () |
virtual int | Destructor () |
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. | |
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 50 of file InstrumentEditor.h.
enum LinuxSampler::VirtualMidiDevice::event_type_t [inherited] |
Definition at line 22 of file VirtualMidiDevice.h.
LinuxSampler::InstrumentEditor::InstrumentEditor | ( | ) |
Constructor.
virtual LinuxSampler::InstrumentEditor::~InstrumentEditor | ( | ) | [virtual] |
Destructor.
void LinuxSampler::InstrumentEditor::AddListener | ( | InstrumentEditorListener * | pListener | ) |
Registers object that wants to be notified on events.
static void* LinuxSampler::Thread::allocAlignedMem | ( | size_t | boundary, |
size_t | size | ||
) | [inline, static, inherited] |
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 |
virtual String LinuxSampler::InstrumentEditor::Description | ( | ) | [pure virtual] |
Arbitrary textual description of the instrument editor (i.e.
"Gigasampler and DLS format editor, GTK based").
virtual int LinuxSampler::Thread::Destructor | ( | ) | [virtual, inherited] |
virtual void LinuxSampler::Thread::EnableDestructor | ( | ) | [virtual, inherited] |
static void LinuxSampler::Thread::freeAlignedMem | ( | void * | ptr | ) | [inline, static, inherited] |
Frees an aligned block of memory allocated with allocAlignedMem()
ptr | - pointer to the memory block |
bool LinuxSampler::VirtualMidiDevice::GetMidiEventFromDevice | ( | event_t & | Event | ) | [inherited] |
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 |
virtual bool LinuxSampler::Thread::IsRunning | ( | ) | [virtual, inherited] |
virtual bool LinuxSampler::InstrumentEditor::IsTypeSupported | ( | String | sTypeName, |
String | sTypeVersion | ||
) | [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 | ( | 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.
pUserData | - (optional) arbitrary 3rd party data that might e.g. been passed by InstrumentManager::LaunchInstrumentEditor() |
virtual int LinuxSampler::Thread::LockMemory | ( | ) | [virtual, inherited] |
static bool LinuxSampler::Thread::lockMemory | ( | void * | addr, |
size_t | size | ||
) | [inline, static, inherited] |
virtual int LinuxSampler::InstrumentEditor::Main | ( | void * | pInstrument, |
String | sTypeName, | ||
String | sTypeVersion, | ||
void * | pUserData = NULL |
||
) | [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() |
virtual int LinuxSampler::InstrumentEditor::Main | ( | ) | [protected, virtual] |
This method needs to be implemented by the descendant and is the entry point for the new thread. FIXME: should be protected.
Implements LinuxSampler::Thread.
virtual String LinuxSampler::InstrumentEditor::Name | ( | ) | [pure virtual] |
The instrument editor's name (i.e.
"gigedit"
).
Referenced by LinuxSampler::InstrumentEditorFactory::InnerFactoryRegistrator< PluginClass_T >::~InnerFactoryRegistrator().
bool LinuxSampler::VirtualMidiDevice::NoteChanged | ( | uint8_t | Key | ) | [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 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.
bool LinuxSampler::VirtualMidiDevice::NoteIsActive | ( | uint8_t | Key | ) | [inherited] |
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.
uint8_t LinuxSampler::VirtualMidiDevice::NoteOffVelocity | ( | uint8_t | Key | ) | [inherited] |
Returns the velocity of the last note off event.
No FIFO is used!
uint8_t LinuxSampler::VirtualMidiDevice::NoteOnVelocity | ( | uint8_t | Key | ) | [inherited] |
Returns the velocity of the last note on event.
No FIFO is used!
bool LinuxSampler::VirtualMidiDevice::NotesChanged | ( | ) | [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:
NotifyDataStructureToBeChanged(pDimReg, "gig::DimensionRegion"); gig::Sample* pOldSample = pDimReg->pSample; pDimReg->pSample = pNewSample; NotifySampleReferenceChanged(pOldSample, pNewSample); NotifyDataStructureChanged(pDimReg, "gig::DimensionRegion");
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.
void LinuxSampler::InstrumentEditor::NotifySamplesToBeRemoved | ( | std::set< void * > | Samples | ) |
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.
void LinuxSampler::VirtualMidiDevice::SendNoteOffToDevice | ( | uint8_t | Key, |
uint8_t | Velocity | ||
) | [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.
bool LinuxSampler::VirtualMidiDevice::SendNoteOffToSampler | ( | uint8_t | Key, |
uint8_t | Velocity | ||
) | [inherited] |
Sends a MIDI note off event to the sampler.
void LinuxSampler::VirtualMidiDevice::SendNoteOnToDevice | ( | uint8_t | Key, |
uint8_t | Velocity | ||
) | [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.
bool LinuxSampler::VirtualMidiDevice::SendNoteOnToSampler | ( | uint8_t | Key, |
uint8_t | Velocity | ||
) | [inherited] |
Sends a MIDI note on event to the sampler.
virtual int LinuxSampler::Thread::SetSchedulingPriority | ( | ) | [virtual, inherited] |
virtual int LinuxSampler::Thread::SignalStartThread | ( | ) | [virtual, inherited] |
virtual int LinuxSampler::Thread::SignalStopThread | ( | ) | [virtual, inherited] |
virtual int LinuxSampler::Thread::StartThread | ( | ) | [virtual, inherited] |
virtual int LinuxSampler::Thread::StopThread | ( | ) | [virtual, inherited] |
void LinuxSampler::Thread::TestCancel | ( | ) | [inline, inherited] |
static bool LinuxSampler::Thread::unlockMemory | ( | void * | addr, |
size_t | size | ||
) | [inline, static, inherited] |
virtual String LinuxSampler::InstrumentEditor::Version | ( | ) | [pure virtual] |
The instrument editor's version (i.e.
"0.0.1"
).
std::set<InstrumentEditorListener*> LinuxSampler::InstrumentEditor::listeners [protected] |
Definition at line 224 of file InstrumentEditor.h.