/[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 1876 - (show annotations) (download) (as text)
Fri Mar 27 12:16:12 2009 UTC (10 years, 2 months ago) by schoenebeck
File MIME type: text/x-c++hdr
File size: 14302 byte(s)
* added optional 3rd party user data parameter for following
  liblinuxsampler C++ API methods: InstrumentEditor::Main(),
  InstrumentEditor::Launch(), InstrumentManager::LaunchInstrumentEditor()
* minor cosmetics regarding configure script summary
* debian packaging: include DSSI and LV2 plugin binaries of the sampler
  into the liblinuxsampler package
* RPM packaging: include DSSI and LV2 plugin binaries of the sampler
  into the liblinuxsampler package
* bumped version to 0.5.1.12cvs

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

  ViewVC Help
Powered by ViewVC