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

Diff of /linuxsampler/trunk/src/engines/InstrumentEditor.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1212 by schoenebeck, Tue May 29 23:59:36 2007 UTC revision 1321 by schoenebeck, Tue Sep 4 01:12:49 2007 UTC
# Line 44  namespace LinuxSampler { Line 44  namespace LinuxSampler {
44       * sampler will load these external DLLs as plugins on startup. Whenever       * sampler will load these external DLLs as plugins on startup. Whenever
45       * there's a request for editing an instrument, the sampler will try to       * there's a request for editing an instrument, the sampler will try to
46       * launch a matching registered editor, by calling the respective       * launch a matching registered editor, by calling the respective
47       * plugin's Main() method.       * plugin's @c Main() method.
48       */       */
49      class InstrumentEditor : protected Thread {      class InstrumentEditor : protected Thread {
50      public:      public:
# Line 63  namespace LinuxSampler { Line 63  namespace LinuxSampler {
63           *           *
64           * @param pInstrument - pointer to the respective instrument object           * @param pInstrument - pointer to the respective instrument object
65           * @param sTypeName - format of the instrument data structure           * @param sTypeName - format of the instrument data structure
66           *                    (i.e. "libgig")           *                    (i.e. @c "libgig" )
67           * @param sTypeVersion - version of the instrument data structure           * @param sTypeVersion - version of the instrument data structure
68           *                       (i.e. "3.0.1").           *                       (i.e. @c "3.0.1" ).
69           */           */
70          virtual int Main(void* pInstrument, String sTypeName, String sTypeVersion) = 0;          virtual int Main(void* pInstrument, String sTypeName, String sTypeVersion) = 0;
71    
# Line 76  namespace LinuxSampler { Line 76  namespace LinuxSampler {
76           * sampler to determine which editor is capable to work with a           * sampler to determine which editor is capable to work with a
77           * certain instrument.           * certain instrument.
78           *           *
79           * @param sTypeName - i.e. "libgig"           * @param sTypeName - i.e. @c "libgig"
80           * @param STypeVersion - i.e. "3.0.1"           * @param STypeVersion - i.e. @c "3.0.1"
81           */           */
82          virtual bool IsTypeSupported(String sTypeName, String sTypeVersion) = 0;          virtual bool IsTypeSupported(String sTypeName, String sTypeVersion) = 0;
83    
84          /**          /**
85           * The instrument editor's name (i.e. "gigedit").           * The instrument editor's name (i.e. @c "gigedit" ).
86           */           */
87          virtual String Name() = 0;          virtual String Name() = 0;
88    
89          /**          /**
90           * The instrument editor's version (i.e. "0.0.1").           * The instrument editor's version (i.e. @c "0.0.1" ).
91           */           */
92          virtual String Version() = 0;          virtual String Version() = 0;
93    
# Line 103  namespace LinuxSampler { Line 103  namespace LinuxSampler {
103          // normal methods          // normal methods
104          //     (usually not to be overriden by descendant)          //     (usually not to be overriden by descendant)
105    
106            /** @brief Dispatch pending sample removal event.
107             *
108             * @e SHOULD be called by the instrument editor @e before deleting
109             * samples, so the sampler can react by stopping usage of these
110             * samples to avoid a crash.
111             *
112             * After calling this method, the instrument editor @e MUST call
113             * @c NotifySamplesRemoved() after it actually deleted the samples, so
114             * the sampler can react by i.e. resuming playback of sampler engines.
115             *
116             * @param Samples - list of samples that will be deleted by the
117             *                  instrument editor
118             */
119            void NotifySamplesToBeRemoved(std::set<void*> Samples);
120    
121            /** @brief Dispatch completed sample removal event.
122             *
123             * Inform the sampler that the by @c NotifySamplesToBeRemoved()
124             * previously announced samples have been deleted.
125             */
126            void NotifySamplesRemoved();
127    
128            /** @brief Dispatch pending data structure modification event.
129             *
130             * @e SHOULD be called by the instrument editor @e before modifying
131             * data structures (except samples, which have their own dispatch
132             * methods) which could otherwise lead to undesired synchronisation
133             * issues and a crash. The respective data structure is passed as a
134             * typeless pointer @a pStruct , so the instrument editor additionally
135             * has to pass the name of the data structure (i.e. @c "gig::Region" ),
136             * so the sampler can cast the pointer to an appropriate type. The
137             * sampler will react by stopping usage of the respective data
138             * structure.
139             *
140             * After calling this method, the instrument editor @e MUST call
141             * @c NotifyDataStructureChanged() , so the sampler can react by
142             * resuming usage of the respective data structure for playback.
143             *
144             * @param pStruct     - data structure going to be modified
145             * @param sStructType - name of the data structure (i.e. its C++
146             *                      struct or class name)
147             */
148            void NotifyDataStructureToBeChanged(void* pStruct, String sStructType);
149    
150            /** @brief Dispatch completed data structure modification event.
151             *
152             * Inform the sampler that the by @c NotifyDataStructureToBeChanged()
153             * previously announced data structure has been completely modified.
154             *
155             * @param pStruct     - data structure that has been modified
156             * @param sStructType - name of the data structure (i.e. its C++
157             *                      struct or class name)
158             */
159            void NotifyDataStructureChanged(void* pStruct, String sStructType);
160    
161            /** @brief Dispatch sample reference changed event.
162             *
163             * @e SHOULD be called by the instrument editor @e after a certain data
164             * structure changed its reference / pointer to a sample, so the
165             * sampler can react by:
166             *
167             * - Caching the newly referenced sample if necessary.
168             * - Un-caching the old referenced sample if necessary.
169             *
170             * @e Note: the instrument editor additionally @e MUST embed this call
171             * into the respective @c NotifyDataStructureToBeChanged() and
172             * @c NotifyDataStructureChanged() calls for announcing the data
173             * structure whose sample reference is actually to be changed, so the
174             * sampler can react by suspending usage. For example:
175             * @code
176             *  NotifyDataStructureToBeChanged(pDimReg, "gig::DimensionRegion");
177             *  gig::Sample* pOldSample = pDimReg->pSample;
178             *  pDimReg->pSample = pNewSample;
179             *  NotifySampleReferenceChanged(pOldSample, pNewSample);
180             *  NotifyDataStructureChanged(pDimReg, "gig::DimensionRegion");
181             * @endcode
182             * So calling this method alone is not safe!
183             *
184             * @param pOldSample - previous sample reference
185             * @param pNewSample - current sample reference
186             */
187            void NotifySampleReferenceChanged(void* pOldSample, void* pNewSample);
188    
189          /**          /**
190           * Launch the instrument editor for the given instrument. The           * Launch the instrument editor for the given instrument. The
191           * editor will be spawned in its own thread and this method will           * editor will be spawned in its own thread and this method will
# Line 139  namespace LinuxSampler { Line 222  namespace LinuxSampler {
222      /** @brief Instrument Editor Notifications      /** @brief Instrument Editor Notifications
223       *       *
224       * This abstract interface class has to be implemented by classes that       * This abstract interface class has to be implemented by classes that
225       * want to be notified on certain events of an instrument editor.       * want to be notified on certain events of an instrument editor. This is
226         * typically used on sampler side, but might also be used by an instrument
227         * editor to get informed about modifications another instrument editor
228         * makes.
229       */       */
230      class InstrumentEditorListener {      class InstrumentEditorListener {
231      public:      public:
232          /// Called after the instrument editor stopped running.          /** @brief Called after the instrument editor stopped running.
233             *
234             * Automatically called after the instrument editor application stopped
235             * running. This method has to be implemented by the descendant.
236             *
237             * @param pSender - instrument editor that died
238             */
239          virtual void OnInstrumentEditorQuit(InstrumentEditor* pSender) = 0;          virtual void OnInstrumentEditorQuit(InstrumentEditor* pSender) = 0;
240    
241            /** @brief Called before samples are to be deleted.
242             *
243             * See the dispatcher method
244             * @c InstrumentEditor::NotifySamplesToBeRemoved() for details.
245             * This method has to be implemented by the descendant.
246             *
247             * @param Samples - list of samples that will be deleted by the
248             *                  instrument editor
249             * @param pSender - instrument editor that is going to do this
250             *                  modification
251             */
252            virtual void OnSamplesToBeRemoved(std::set<void*> Samples, InstrumentEditor* pSender) = 0;
253    
254            /** @brief  Called after samples have been deleted.
255             *
256             * See the dispatcher method
257             * @c InstrumentEditor::NotifySamplesRemoved() for details.
258             * This method has to be implemented by the descendant.
259             *
260             * @param pSender - instrument editor that did this modification
261             */
262            virtual void OnSamplesRemoved(InstrumentEditor* pSender) = 0;
263    
264            /** @brief Called before data structure is to be modified.
265             *
266             * See the dispatcher method
267             * @c InstrumentEditor::NotifyDataStructureToBeChanged() for details.
268             * This method has to be implemented by the descendant.
269             *
270             * @param pStruct     - data structure going to be modified
271             * @param sStructType - name of the data structure (i.e. its C++
272             *                      struct or class name)
273             * @param pSender     - instrument editor that is going to do this
274             *                      modification
275             */
276            virtual void OnDataStructureToBeChanged(void* pStruct, String sStructType, InstrumentEditor* pSender) = 0;
277    
278            /** @brief Called after data structure has been modified.
279             *
280             * See the dispatcher method
281             * @c InstrumentEditor::NotifyDataStructureChanged() for details.
282             * This method has to be implemented by the descendant.
283             *
284             * @param pStruct     - data structure that has been modified
285             * @param sStructType - name of the data structure (i.e. its C++
286             *                      struct or class name)
287             * @param pSender     - instrument editor that did this modification
288             */
289            virtual void OnDataStructureChanged(void* pStruct, String sStructType, InstrumentEditor* pSender) = 0;
290    
291            /** @brief Called after some data structure changed its reference to a sample.
292             *
293             * @c InstrumentEditor::NotifySampleReferenceChanged() for details.
294             * This method has to be implemented by the descendant.
295             *
296             * @param pOldSample - previous sample reference
297             * @param pNewSample - current sample reference
298             * @param pSender    - instrument editor that did this modification
299             */
300            virtual void OnSampleReferenceChanged(void* pOldSample, void* pNewSample, InstrumentEditor* pSender) = 0;
301      };      };
302    
303  } // namespace LinuxSampler  } // namespace LinuxSampler

Legend:
Removed from v.1212  
changed lines
  Added in v.1321

  ViewVC Help
Powered by ViewVC