/[svn]/linuxsampler/trunk/src/plugins/InstrumentEditor.h
ViewVC logotype

Contents of /linuxsampler/trunk/src/plugins/InstrumentEditor.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2687 - (show annotations) (download) (as text)
Sun Jan 4 17:16:05 2015 UTC (5 years, 6 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 15199 byte(s)
* Instrument editor interface: Changed instrument editor plugin interface,
providing additional informations like the EngineChannel for which the
instrument editor was spawned for. This allows the instrument editors to
interact more actively with the sampler.
* Bumped version (1.0.0.svn60).

1 /***************************************************************************
2 * *
3 * Copyright (C) 2007 - 2015 Christian Schoenebeck *
4 * *
5 * This program is free software; you can redistribute it and/or modify *
6 * it under the terms of the GNU General Public License as published by *
7 * the Free Software Foundation; either version 2 of the License, or *
8 * (at your option) any later version. *
9 * *
10 * This program is distributed in the hope that it will be useful, *
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of *
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
13 * GNU General Public License for more details. *
14 * *
15 * You should have received a copy of the GNU General Public License *
16 * along with this program; if not, write to the Free Software *
17 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, *
18 * MA 02111-1307 USA *
19 ***************************************************************************/
20
21 #ifndef LS_INSTRUMENT_EDITOR_H
22 #define LS_INSTRUMENT_EDITOR_H
23
24 #include "../common/global.h"
25 #include "../common/Thread.h"
26 #include "../drivers/midi/VirtualMidiDevice.h"
27
28 #include <set>
29
30 namespace LinuxSampler {
31
32 // just symbol prototyping
33 class InstrumentEditorListener;
34 class EngineChannel;
35
36 /** @brief Instrument Editor Interface (external plugin)
37 *
38 * LinuxSampler allows to spawn arbitrary instrument editor applications
39 * within the sampler's own process. That way instrument editors are
40 * able to modify already loaded instruments live or on-the-fly, that is
41 * without having to load it again neither on sampler nor on editor side,
42 * which is essential for editing large instruments.
43 *
44 * Instrument editors have to implement this abstract base class, embedded
45 * into a DLL and placed into the respective sampler's library path. The
46 * sampler will load these external DLLs as plugins on startup. Whenever
47 * there's a request for editing an instrument, the sampler will try to
48 * launch a matching registered editor, by calling the respective
49 * plugin's @c Main() method.
50 */
51 class InstrumentEditor : public VirtualMidiDevice, protected Thread {
52 public:
53
54 /////////////////////////////////////////////////////////////////
55 // abstract methods
56 // (these have to be implemented by the descendant)
57
58 /**
59 * Entry point for the instrument editor's thread. As the
60 * instrument data structure is passed as typeless (void*)
61 * pointer, this is not type safe! The implementing instrument
62 * editor has to interpret the @a sTypeName and @a sTypeVersion
63 * arguments to determine if it's able to cast the instrument
64 * pointer to a known type and actually be able to work with it.
65 *
66 * @param pInstrument - pointer to the respective instrument object
67 * @param sTypeName - format of the instrument data structure
68 * (i.e. @c "libgig" )
69 * @param sTypeVersion - version of the instrument data structure
70 * (i.e. @c "3.0.1" ).
71 * @param pUserData - (optional) arbitrary 3rd party data that might
72 * been passed by Launch()
73 */
74 virtual int Main(void* pInstrument, String sTypeName, String sTypeVersion, void* pUserData = NULL) = 0;
75
76 /**
77 * The instrument editor has to return @c true in case it supports
78 * the given instrument data structure type and version, it has to
79 * return @c false otherwise. This method will be called by the
80 * sampler to determine which editor is capable to work with a
81 * certain instrument.
82 *
83 * @param sTypeName - i.e. @c "libgig"
84 * @param sTypeVersion - i.e. @c "3.0.1"
85 */
86 virtual bool IsTypeSupported(String sTypeName, String sTypeVersion) = 0;
87
88 /**
89 * The instrument editor's name (i.e. @c "gigedit" ).
90 */
91 virtual String Name() = 0;
92
93 /**
94 * The instrument editor's version (i.e. @c "0.0.1" ).
95 */
96 virtual String Version() = 0;
97
98 /**
99 * Arbitrary textual description of the instrument editor
100 * (i.e. "Gigasampler and DLS format editor, GTK based").
101 */
102 virtual String Description() = 0;
103
104
105
106 /////////////////////////////////////////////////////////////////
107 // normal methods
108 // (usually not to be overriden by descendant)
109
110 /** @brief Dispatch pending sample removal event.
111 *
112 * @e SHOULD be called by the instrument editor @e before deleting
113 * samples, so the sampler can react by stopping usage of these
114 * samples to avoid a crash.
115 *
116 * After calling this method, the instrument editor @e MUST call
117 * @c NotifySamplesRemoved() after it actually deleted the samples, so
118 * the sampler can react by i.e. resuming playback of sampler engines.
119 *
120 * @param Samples - list of samples that will be deleted by the
121 * instrument editor
122 */
123 void NotifySamplesToBeRemoved(std::set<void*> Samples);
124
125 /** @brief Dispatch completed sample removal event.
126 *
127 * Inform the sampler that the by @c NotifySamplesToBeRemoved()
128 * previously announced samples have been deleted.
129 */
130 void NotifySamplesRemoved();
131
132 /** @brief Dispatch pending data structure modification event.
133 *
134 * @e SHOULD be called by the instrument editor @e before modifying
135 * data structures (except samples, which have their own dispatch
136 * methods) which could otherwise lead to undesired synchronisation
137 * issues and a crash. The respective data structure is passed as a
138 * typeless pointer @a pStruct , so the instrument editor additionally
139 * has to pass the name of the data structure (i.e. @c "gig::Region" ),
140 * so the sampler can cast the pointer to an appropriate type. The
141 * sampler will react by stopping usage of the respective data
142 * structure.
143 *
144 * After calling this method, the instrument editor @e MUST call
145 * @c NotifyDataStructureChanged() , so the sampler can react by
146 * resuming usage of the respective data structure for playback.
147 *
148 * @param pStruct - data structure going to be modified
149 * @param sStructType - name of the data structure (i.e. its C++
150 * struct or class name)
151 */
152 void NotifyDataStructureToBeChanged(void* pStruct, String sStructType);
153
154 /** @brief Dispatch completed data structure modification event.
155 *
156 * Inform the sampler that the by @c NotifyDataStructureToBeChanged()
157 * previously announced data structure has been completely modified.
158 *
159 * @param pStruct - data structure that has been modified
160 * @param sStructType - name of the data structure (i.e. its C++
161 * struct or class name)
162 */
163 void NotifyDataStructureChanged(void* pStruct, String sStructType);
164
165 /** @brief Dispatch sample reference changed event.
166 *
167 * @e SHOULD be called by the instrument editor @e after a certain data
168 * structure changed its reference / pointer to a sample, so the
169 * sampler can react by:
170 *
171 * - Caching the newly referenced sample if necessary.
172 * - Un-caching the old referenced sample if necessary.
173 *
174 * @e Note: the instrument editor additionally @e MUST embed this call
175 * into the respective @c NotifyDataStructureToBeChanged() and
176 * @c NotifyDataStructureChanged() calls for announcing the data
177 * structure whose sample reference is actually to be changed, so the
178 * sampler can react by suspending usage. For example:
179 * @code
180 * NotifyDataStructureToBeChanged(pDimReg, "gig::DimensionRegion");
181 * gig::Sample* pOldSample = pDimReg->pSample;
182 * pDimReg->pSample = pNewSample;
183 * NotifySampleReferenceChanged(pOldSample, pNewSample);
184 * NotifyDataStructureChanged(pDimReg, "gig::DimensionRegion");
185 * @endcode
186 * So calling this method alone is not safe!
187 *
188 * @param pOldSample - previous sample reference
189 * @param pNewSample - current sample reference
190 */
191 void NotifySampleReferenceChanged(void* pOldSample, void* pNewSample);
192
193 /**
194 * Launch the instrument editor for the given instrument. The
195 * editor will be spawned in its own thread and this method will
196 * return as soon as the editor's thread actually started.
197 *
198 * @param pEngineChannel - the engine channel on which @a pInstrument is
199 * currently used on and for which the instrument
200 * editor shall be spawned for editing
201 * @param pInstrument - pointer to the respective instrument object
202 * @param sTypeName - format of the instrument data structure
203 * (i.e. @c "libgig" )
204 * @param sTypeVersion - version of the instrument data structure
205 * (i.e. @c "3.0.1" ).
206 * @param pUserData - (optional) arbitrary 3rd party data that might
207 * e.g. been passed by
208 * InstrumentManager::LaunchInstrumentEditor()
209 */
210 void Launch(EngineChannel* pEngineChannel, void* pInstrument, String sTypeName, String sTypeVersion, void* pUserData = NULL);
211
212 /**
213 * Returns the EngineChannel for which this instrument editor was
214 * spawned for, for editing the respective instrument loaded on that
215 * EngineChannel.
216 */
217 EngineChannel* GetEngineChannel();
218
219 /**
220 * Registers object that wants to be notified on events.
221 */
222 void AddListener(InstrumentEditorListener* pListener);
223
224 /**
225 * Unregisters object that doesn't want to be notified anymore.
226 */
227 void RemoveListener(InstrumentEditorListener* pListener);
228
229 /**
230 * Constructor
231 */
232 InstrumentEditor();
233
234 /**
235 * Destructor
236 */
237 virtual ~InstrumentEditor();
238
239 protected:
240 std::set<InstrumentEditorListener*> listeners;
241
242 // derived abstract method from base class 'Thread'
243 virtual int Main();
244 private:
245 void* pInstrument;
246 String sTypeName;
247 String sTypeVersion;
248 void* pUserData;
249 EngineChannel* pEngineChannel;
250 };
251
252 /** @brief Instrument Editor Notifications
253 *
254 * This abstract interface class has to be implemented by classes that
255 * want to be notified on certain events of an instrument editor. This is
256 * typically used on sampler side, but might also be used by an instrument
257 * editor to get informed about modifications another instrument editor
258 * makes.
259 */
260 class InstrumentEditorListener {
261 public:
262 /** @brief Called after the instrument editor stopped running.
263 *
264 * Automatically called after the instrument editor application stopped
265 * running. This method has to be implemented by the descendant.
266 *
267 * @param pSender - instrument editor that died
268 */
269 virtual void OnInstrumentEditorQuit(InstrumentEditor* pSender) = 0;
270
271 /** @brief Called before samples are to be deleted.
272 *
273 * See the dispatcher method
274 * @c InstrumentEditor::NotifySamplesToBeRemoved() for details.
275 * This method has to be implemented by the descendant.
276 *
277 * @param Samples - list of samples that will be deleted by the
278 * instrument editor
279 * @param pSender - instrument editor that is going to do this
280 * modification
281 */
282 virtual void OnSamplesToBeRemoved(std::set<void*> Samples, InstrumentEditor* pSender) = 0;
283
284 /** @brief Called after samples have been deleted.
285 *
286 * See the dispatcher method
287 * @c InstrumentEditor::NotifySamplesRemoved() for details.
288 * This method has to be implemented by the descendant.
289 *
290 * @param pSender - instrument editor that did this modification
291 */
292 virtual void OnSamplesRemoved(InstrumentEditor* pSender) = 0;
293
294 /** @brief Called before data structure is to be modified.
295 *
296 * See the dispatcher method
297 * @c InstrumentEditor::NotifyDataStructureToBeChanged() for details.
298 * This method has to be implemented by the descendant.
299 *
300 * @param pStruct - data structure going to be modified
301 * @param sStructType - name of the data structure (i.e. its C++
302 * struct or class name)
303 * @param pSender - instrument editor that is going to do this
304 * modification
305 */
306 virtual void OnDataStructureToBeChanged(void* pStruct, String sStructType, InstrumentEditor* pSender) = 0;
307
308 /** @brief Called after data structure has been modified.
309 *
310 * See the dispatcher method
311 * @c InstrumentEditor::NotifyDataStructureChanged() for details.
312 * This method has to be implemented by the descendant.
313 *
314 * @param pStruct - data structure that has been modified
315 * @param sStructType - name of the data structure (i.e. its C++
316 * struct or class name)
317 * @param pSender - instrument editor that did this modification
318 */
319 virtual void OnDataStructureChanged(void* pStruct, String sStructType, InstrumentEditor* pSender) = 0;
320
321 /** @brief Called after some data structure changed its reference to a sample.
322 *
323 * @c InstrumentEditor::NotifySampleReferenceChanged() for details.
324 * This method has to be implemented by the descendant.
325 *
326 * @param pOldSample - previous sample reference
327 * @param pNewSample - current sample reference
328 * @param pSender - instrument editor that did this modification
329 */
330 virtual void OnSampleReferenceChanged(void* pOldSample, void* pNewSample, InstrumentEditor* pSender) = 0;
331 };
332
333 } // namespace LinuxSampler
334
335 #endif // LS_INSTRUMENT_EDITOR_H

  ViewVC Help
Powered by ViewVC