/[svn]/linuxsampler/trunk/src/drivers/DeviceParameter.h
ViewVC logotype

Diff of /linuxsampler/trunk/src/drivers/DeviceParameter.h

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

revision 2413 by persson, Fri Jun 22 10:10:06 2007 UTC revision 2414 by schoenebeck, Wed Feb 13 13:38:00 2013 UTC
# Line 3  Line 3 
3   *   LinuxSampler - modular, streaming capable sampler                     *   *   LinuxSampler - modular, streaming capable sampler                     *
4   *                                                                         *   *                                                                         *
5   *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *   *   Copyright (C) 2003, 2004 by Benno Senoner and Christian Schoenebeck   *
6   *   Copyright (C) 2005, 2006 Christian Schoenebeck                        *   *   Copyright (C) 2005 - 2013 Christian Schoenebeck                       *
7   *                                                                         *   *                                                                         *
8   *   This program is free software; you can redistribute it and/or modify  *   *   This program is free software; you can redistribute it and/or modify  *
9   *   it under the terms of the GNU General Public License as published by  *   *   it under the terms of the GNU General Public License as published by  *
# Line 33  Line 33 
33  #include "Device.h"  #include "Device.h"
34    
35  namespace LinuxSampler {  namespace LinuxSampler {
36        
37        /////////////////////////////////////////////////////////////////
38        // "Runtime" parameters
39    
40      // TODO: All plurar parameter classes (except for String) have to be added (namely DeviceRuntimeParameterBools, DeviceRuntimeParameterInts, DeviceRuntimeParameterFloats, DeviceCreationParameterBools, DeviceCreationParameterInts, DeviceCreationParameterFloats), I ignored them for the moment, because they were not that necessary.      // TODO: All plurar parameter classes (except for String) have to be added (namely DeviceRuntimeParameterBools, DeviceRuntimeParameterInts, DeviceRuntimeParameterFloats, DeviceCreationParameterBools, DeviceCreationParameterInts, DeviceCreationParameterFloats), I ignored them for the moment, because they were not that necessary.
41    
42        /** @brief Abstracet base class for all driver parameters of the sampler.
43         *
44         * All audio / MIDI drivers for the sampler are using dynamic driver
45         * parameters based on this base class. The main purpose behind this
46         * concept is to be able to write GUI frontends for the sampler, which
47         * don't need to know about specific drivers the sampler provides, nor the
48         * exact list of parameters those drivers offer. Instead a frontend can
49         * use this API to retrieve what kind of parameters the respective
50         * available drivers offer at runtime. This way new drivers can be added
51         * or existing ones being changed arbitrarily to the sampler at any time,
52         * without a GUI frontend to be changed or recompiled.
53         *
54         * There are various parameter classes deriving from this base class, which
55         * implement convenient handling for the various common value types like
56         * bool, int, float, String. A driver would rather use one of those
57         * type specialized classes, instead of this abstract base class. Because
58         * the methods of this very base parameter class here are generalized being
59         * encoded in String type for all parameter types.
60         *
61         * Besides that, there are 2 distinct sets of parameter types:
62         * - "Runtime" parameters which can be set and changed by the user (i.e.
63         *    with a GUI frontend) at any time.
64         * - "Creation" parameters which can only be set by the user before a
65         *   driver is instantiated (a driver instance is called a "device" in
66         *   the sampler's terms). After the driver is instantiated, "creation"
67         *   parameters are read only for the life time of a driver (device)
68         *   instance. Typical example for a "creation" parameter would be an
69         *   audio driver that allows to select a specific sound card.
70         *
71         * @see DeviceCreationParameter
72         */
73      class DeviceRuntimeParameter {      class DeviceRuntimeParameter {
74          public:          public:
75              virtual String           Type()          = 0;              /**
76              virtual String           Description()   = 0;               * Some name reflecting the parameter's value type, like "BOOL,
77              virtual bool             Fix()           = 0;               * "INT", "FLOAT", "STRING", "STRINGS". Upon the value returned
78              virtual bool             Multiplicity()  = 0;               * here, the object can be casted to the respective implementing
79              virtual optional<String> RangeMin()      = 0;               * parameter class.
80              virtual optional<String> RangeMax()      = 0;               */
81                virtual String Type() = 0;
82                
83                /**
84                 * A human readable description, explaining the exact purpose of
85                 * the driver parameter. The text returned here can be used to
86                 * display the user in a GUI frontend some helping text, that
87                 * explains what the parameter actually does.
88                 */
89                virtual String Description() = 0;
90                
91                /**
92                 * Whether the parameter is read only. Not to be confused with
93                 * "creation" parameters! A driver parameter which returns true
94                 * here can never be set or altered at any time. Not even at
95                 * instanciation time of the driver! A typical example would be
96                 * a parameter "SAMPLERATE" for a specific sound card, where the
97                 * specific sound card does not allow to switch the sound card's
98                 * sample rate in any way. Yet the value returned by the parameter
99                 * (read only) might be different, depending on the actual sound
100                 * card the user selected with the audio driver.
101                 */
102                virtual bool Fix() = 0;
103                
104                /**
105                 * Whether the parameter only allows to set one scalar value, or
106                 * if @c true is returned here, the parameter allows to manage a
107                 * list of values instead. A typical example of multiplicity
108                 * parameter is i.e. a "ROUTING" parameter, that would allow a
109                 * user to interconnect the sampler with other apps and devices
110                 * with drivers that support such concepts (like JACK and ALSA MIDI
111                 * do).
112                 */
113                virtual bool Multiplicity() = 0;
114                
115                /**
116                 * The driver parameter might (optionally) return a minimum value
117                 * for the parameter. If some actual value is returned here, the
118                 * sampler automatically performs bounds checking of parameter
119                 * values to be set for such a parameter and a GUI frontend might
120                 * display a spin box in such a case to the user, honoring the
121                 * returned minimum value.
122                 *
123                 * You probably don't want to call this method directly, but instead
124                 * cast this object to the respective deriving parameter class like
125                 * DeviceRuntimeParameterInt, and use its RangeMinAsInt() method
126                 * instead, which conveniently returns a value in its value type.
127                 * So you don't need to parse this return value here.
128                 */
129                virtual optional<String> RangeMin() = 0;
130                
131                /**
132                 * The driver parameter might (optionally) return a maximum value
133                 * for the parameter. If some actual value is returned here, the
134                 * sampler automatically performs bounds checking of parameter
135                 * values to be set for such a parameter and a GUI frontend might
136                 * display a spin box in such a case to the user, honoring the
137                 * returned maximum value.
138                 *
139                 * You probably don't want to call this method directly, but instead
140                 * cast this object to the respective deriving parameter class like
141                 * DeviceRuntimeParameterInt, and use its RangeMaxAsInt() method
142                 * instead, which conveniently returns a value in its value type.
143                 * So you don't need to parse this return value here.
144                 */
145                virtual optional<String> RangeMax() = 0;
146                
147                /**
148                 * The driver parameter might (optionally) return a list of
149                 * possible values for this parameter, encoded as comma separated
150                 * list. For example an audio driver might return "44100,96000" for
151                 * a "SAMPLERATE" parameter for a specific sound card.
152                 *
153                 * You probably don't want to call this method directly, but instead
154                 * cast this object to the respective deriving parameter class like
155                 * DeviceRuntimeParameterInt, and use its PossibilitiesAsInt() method
156                 * instead, which conveniently returns a vector in its value type.
157                 * So you don't need to parse this return value here.
158                 */
159              virtual optional<String> Possibilities() = 0;              virtual optional<String> Possibilities() = 0;
160              virtual String           Value()         = 0;              
161              virtual void             SetValue(String val) throw (Exception) = 0;              /**
162                 * The current value of this parameter (encoded as String).
163                 * You might want to cast to the respective deriving parameter
164                 * class like DeviceRuntimeParameterInt and use its method
165                 * ValueAsInt() for not being forced to parse the String here.
166                 */
167                virtual String Value() = 0;
168                
169                /**
170                 * Alter the parameter with the value given by @a val. The
171                 * respective deriving parameter class automatically parses the
172                 * String value supplied here, and converts it into its native
173                 * value type like int, float or String vector ("Strings").
174                 *
175                 * @param - new parameter value encoded as string
176                 * @throws Exception - if @a val is out of bounds, not encoded
177                 *                     correctly in its string representation or
178                 *                     any other reason the driver might not want
179                 *                     to accept the given value.
180                 */
181                virtual void SetValue(String val) throw (Exception) = 0;
182                
183                /** @brief Destructor.
184                 *
185                 * Virtual base destructor which enforces that all destructors of
186                 * all deriving classes are called automatically upon object
187                 * destruction.
188                 */
189              virtual ~DeviceRuntimeParameter(){};              virtual ~DeviceRuntimeParameter(){};
190      };      };
191    
192        /** @brief Abstract base class for driver parameters of type @c bool.
193         *
194         * Implements a "runtime" driver parameter for value type @c bool.
195         * A driver offering a parameter of type @c bool would derive its
196         * parameter class from this class and implement the abstract method
197         * OnSetValue() to react on a parameter value being set.
198         *
199         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
200         * about "runtime" parameters vs. "creation" parameters.
201         *
202         * @see DeviceCreationParameterBool
203         */
204      class DeviceRuntimeParameterBool : public DeviceRuntimeParameter {      class DeviceRuntimeParameterBool : public DeviceRuntimeParameter {
205          public:          public:
206                /** @brief Constructor for value type @c bool.
207                 *
208                 * Sets an initial value for the parameter.
209                 *
210                 * @param bVal - initial boolean value
211                 */
212              DeviceRuntimeParameterBool(bool bVal);              DeviceRuntimeParameterBool(bool bVal);
213                
214                /////////////////////////////////////////////////////////////////
215                // derived methods, implementing type "BOOL"
216                //     (usually not to be overriden by descendant)
217                
218              virtual String           Type();              virtual String           Type();
219              virtual bool             Multiplicity();              virtual bool             Multiplicity();
220              virtual optional<String> RangeMin();              virtual optional<String> RangeMin();
# Line 60  namespace LinuxSampler { Line 222  namespace LinuxSampler {
222              virtual optional<String> Possibilities();              virtual optional<String> Possibilities();
223              virtual String           Value();              virtual String           Value();
224              virtual void             SetValue(String val) throw (Exception);              virtual void             SetValue(String val) throw (Exception);
225                
226                /////////////////////////////////////////////////////////////////
227                // convenience methods for type "BOOL"
228                //     (usually not to be overriden by descendant)
229    
230              virtual bool ValueAsBool();              virtual bool ValueAsBool();
231              virtual void SetValue(bool b) throw (Exception);              virtual void SetValue(bool b) throw (Exception);
232    
233                /////////////////////////////////////////////////////////////////
234                // abstract methods
235                //     (these have to be implemented by the descendant)
236                
237                /**
238                 * Must be implemented be a driver's parameter class to react on
239                 * the parameter value being set / altered.
240                 *
241                 * @param b - new parameter value set by the user
242                 * @throws Exception - might be thrown by the driver in case it
243                 *                     cannot handle the supplied parameter value
244                 *                     for whatever reason
245                 */
246              virtual void OnSetValue(bool b) throw (Exception) = 0;              virtual void OnSetValue(bool b) throw (Exception) = 0;
247          protected:          protected:
248              bool bVal;              bool bVal;
249      };      };
250    
251        /** @brief Abstract base class for driver parameters of type @c int.
252         *
253         * Implements a "runtime" driver parameter for value type @c int.
254         * A driver offering a parameter of type @c int would derive its
255         * parameter class from this class and implement the abstract methods
256         * OnSetValue(), RangeMinAsInt(), RangeMaxAsInt(), PossibilitiesAsInt().
257         *
258         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
259         * about "runtime" parameters vs. "creation" parameters.
260         *
261         * @see DeviceCreationParameterInt
262         */
263      class DeviceRuntimeParameterInt : public DeviceRuntimeParameter {      class DeviceRuntimeParameterInt : public DeviceRuntimeParameter {
264          public:          public:
265                /** @brief Constructor for value type @c int.
266                 *
267                 * Sets an initial value for the parameter.
268                 *
269                 * @param iVal - initial integer value
270                 */
271              DeviceRuntimeParameterInt(int iVal);              DeviceRuntimeParameterInt(int iVal);
272                
273                /////////////////////////////////////////////////////////////////
274                // derived methods, implementing type "INT"
275                //     (usually not to be overriden by descendant)
276                
277              virtual String           Type();              virtual String           Type();
278              virtual bool             Multiplicity();              virtual bool             Multiplicity();
279              virtual optional<String> RangeMin();              virtual optional<String> RangeMin();
# Line 79  namespace LinuxSampler { Line 281  namespace LinuxSampler {
281              virtual optional<String> Possibilities();              virtual optional<String> Possibilities();
282              virtual String           Value();              virtual String           Value();
283              virtual void             SetValue(String val) throw (Exception);              virtual void             SetValue(String val) throw (Exception);
284                
285                /////////////////////////////////////////////////////////////////
286                // convenience methods for type "INT"
287                //     (usually not to be overriden by descendant)
288    
289              virtual int  ValueAsInt();              virtual int  ValueAsInt();
290              virtual void SetValue(int i) throw (Exception);              virtual void SetValue(int i) throw (Exception);
291                
292              virtual optional<int>    RangeMinAsInt()      = 0;              /////////////////////////////////////////////////////////////////
293              virtual optional<int>    RangeMaxAsInt()      = 0;              // abstract methods
294                //     (these have to be implemented by the descendant)
295    
296                /**
297                 * Must be implemented by descendant, returning a minimum int value
298                 * for the parameter. If a minimum value does not make sense for
299                 * the specific driver parameter, then the implementation should
300                 * return @c optional<int>::nothing.
301                 */
302                virtual optional<int> RangeMinAsInt() = 0;
303                
304                /**
305                 * Must be implemented by descendant, returning a maximum int value
306                 * for the parameter. If a maximum value does not make sense for
307                 * the specific driver parameter, then the implementation should
308                 * return @c optional<int>::nothing.
309                 */
310                virtual optional<int> RangeMaxAsInt() = 0;
311                
312                /**
313                 * Must be implemented by descendant, returning a list of possible
314                 * int values for the parameter. If a list of possible values does
315                 * not make sense, the implementation should return an empty
316                 * vector.
317                 */
318              virtual std::vector<int> PossibilitiesAsInt() = 0;              virtual std::vector<int> PossibilitiesAsInt() = 0;
319              virtual void             OnSetValue(int i) throw (Exception) = 0;              
320                /**
321                 * Must be implemented be a driver's parameter class to react on
322                 * the parameter value being set / altered.
323                 *
324                 * @param i - new parameter value set by the user
325                 * @throws Exception - might be thrown by the driver in case it
326                 *                     cannot handle the supplied parameter value
327                 *                     for whatever reason
328                 */
329                virtual void OnSetValue(int i) throw (Exception) = 0;
330          protected:          protected:
331              int iVal;              int iVal;
332      };      };
333    
334        /** @brief Abstract base class for driver parameters of type @c float.
335         *
336         * Implements a "runtime" driver parameter for value type @c float.
337         * A driver offering a parameter of type @c float would derive its
338         * parameter class from this class and implement the abstract methods
339         * OnSetValue(), RangeMinAsFloat(), RangeMaxAsFloat() and
340         * PossibilitiesAsFloat().
341         *
342         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
343         * about "runtime" parameters vs. "creation" parameters.
344         *
345         * @see DeviceCreationParameterFloat
346         */
347      class DeviceRuntimeParameterFloat : public DeviceRuntimeParameter {      class DeviceRuntimeParameterFloat : public DeviceRuntimeParameter {
348          public:          public:
349                /** @brief Constructor for value type @c float.
350                 *
351                 * Sets an initial value for the parameter.
352                 *
353                 * @param fVal - initial float value
354                 */
355              DeviceRuntimeParameterFloat(float fVal);              DeviceRuntimeParameterFloat(float fVal);
356                
357                /////////////////////////////////////////////////////////////////
358                // derived methods, implementing type "FLOAT"
359                //     (usually not to be overriden by descendant)
360                
361              virtual String           Type();              virtual String           Type();
362              virtual bool             Multiplicity();              virtual bool             Multiplicity();
363              virtual optional<String> RangeMin();              virtual optional<String> RangeMin();
# Line 102  namespace LinuxSampler { Line 366  namespace LinuxSampler {
366              virtual String           Value();              virtual String           Value();
367              virtual void             SetValue(String val) throw (Exception);              virtual void             SetValue(String val) throw (Exception);
368    
369                /////////////////////////////////////////////////////////////////
370                // convenience methods for type "FLOAT"
371                //     (usually not to be overriden by descendant)
372                
373              virtual float ValueAsFloat();              virtual float ValueAsFloat();
374              virtual void  SetValue(float f) throw (Exception);              virtual void  SetValue(float f) throw (Exception);
375                
376              virtual optional<float>     RangeMinAsFloat()      = 0;              /////////////////////////////////////////////////////////////////
377              virtual optional<float>     RangeMaxAsFloat()      = 0;              // abstract methods
378              virtual std::vector<float>  PossibilitiesAsFloat() = 0;              //     (these have to be implemented by the descendant)
379              virtual void                OnSetValue(float f) = 0;  
380                /**
381                 * Must be implemented by descendant, returning a minimum float
382                 * value for the parameter. If a minimum value does not make sense
383                 * for the specific driver parameter, then the implementation
384                 * should return @c optional<float>::nothing.
385                 */
386                virtual optional<float> RangeMinAsFloat() = 0;
387                
388                /**
389                 * Must be implemented by descendant, returning a maximum float
390                 * value for the parameter. If a maximum value does not make sense
391                 * for the specific driver parameter, then the implementation
392                 * should return @c optional<float>::nothing.
393                 */
394                virtual optional<float> RangeMaxAsFloat() = 0;
395                
396                /**
397                 * Must be implemented by descendant, returning a list of possible
398                 * float values for the parameter. If a list of possible values
399                 * does not make sense, the implementation should return an empty
400                 * vector.
401                 */
402                virtual std::vector<float> PossibilitiesAsFloat() = 0;
403                
404                /**
405                 * Must be implemented be a driver's parameter class to react on
406                 * the parameter value being set / altered.
407                 *
408                 * @param f - new parameter value set by the user
409                 * @throws Exception - might be thrown by the driver in case it
410                 *                     cannot handle the supplied parameter value
411                 *                     for whatever reason
412                 */
413                virtual void OnSetValue(float f) = 0;
414          protected:          protected:
415              float fVal;              float fVal;
416      };      };
417    
418        /** @brief Abstract base class for driver parameters of type @c String.
419         *
420         * Implements a "runtime" driver parameter for value type @c String.
421         * A driver offering a parameter of type @c String would derive its
422         * parameter class from this class and implement the abstract methods
423         * OnSetValue() and PossibilitiesAsString().
424         *
425         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
426         * about "runtime" parameters vs. "creation" parameters.
427         *
428         * @see DeviceCreationParameterString
429         */
430      class DeviceRuntimeParameterString : public DeviceRuntimeParameter {      class DeviceRuntimeParameterString : public DeviceRuntimeParameter {
431          public:          public:
432                /** @brief Constructor for value type @c String.
433                 *
434                 * Sets an initial value for the parameter.
435                 *
436                 * @param sVal - initial String value
437                 */
438              DeviceRuntimeParameterString(String sVal);              DeviceRuntimeParameterString(String sVal);
439                
440                /// @brief Destructor.
441              virtual ~DeviceRuntimeParameterString(){}              virtual ~DeviceRuntimeParameterString(){}
442                
443                /////////////////////////////////////////////////////////////////
444                // derived methods, implementing type "STRING"
445                //     (usually not to be overriden by descendant)
446                
447              virtual String           Type();              virtual String           Type();
448              virtual bool             Multiplicity();              virtual bool             Multiplicity();
449              virtual optional<String> RangeMin();              virtual optional<String> RangeMin();
# Line 124  namespace LinuxSampler { Line 451  namespace LinuxSampler {
451              virtual optional<String> Possibilities();              virtual optional<String> Possibilities();
452              virtual String           Value();              virtual String           Value();
453              virtual void             SetValue(String val) throw (Exception);              virtual void             SetValue(String val) throw (Exception);
454                
455                /////////////////////////////////////////////////////////////////
456                // convenience methods for type "STRING"
457                //     (usually not to be overriden by descendant)
458    
459              virtual String ValueAsString();              virtual String ValueAsString();
460              virtual void   SetValueAsString(String s) throw (Exception);              virtual void   SetValueAsString(String s) throw (Exception);
461                
462                /////////////////////////////////////////////////////////////////
463                // abstract methods
464                //     (these have to be implemented by the descendant)
465    
466                /**
467                 * Must be implemented by descendant, returning a list of possible
468                 * String values for the parameter. If a list of possible values
469                 * does not make sense, the implementation should return an empty
470                 * vector.
471                 */
472              virtual std::vector<String> PossibilitiesAsString() = 0;              virtual std::vector<String> PossibilitiesAsString() = 0;
473              virtual void                OnSetValue(String s)    = 0;              
474                /**
475                 * Must be implemented be a driver's parameter class to react on
476                 * the parameter value being set / altered.
477                 *
478                 * @param s - new parameter value set by the user
479                 * @throws Exception - might be thrown by the driver in case it
480                 *                     cannot handle the supplied parameter value
481                 *                     for whatever reason
482                 */
483                virtual void OnSetValue(String s) = 0;
484          protected:          protected:
485              String sVal;              String sVal;
486      };      };
487    
488        /** @brief Abstract base class for driver parameters of a @c String list type.
489         *
490         * Implements a "runtime" driver parameter for multiple values of type
491         * @c String. A driver offering a parameter of a @c String list type would
492         * derive its parameter class from this class and implement the abstract
493         * methods OnSetValue() and PossibilitiesAsString().
494         *
495         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
496         * about "runtime" parameters vs. "creation" parameters.
497         *
498         * @see DeviceCreationParameterStrings
499         */
500      class DeviceRuntimeParameterStrings : public DeviceRuntimeParameter {      class DeviceRuntimeParameterStrings : public DeviceRuntimeParameter {
501          public:          public:
502                /** @brief Constructor for value type @c String.
503                 *
504                 * Sets an initial list of values for the parameter.
505                 *
506                 * @param sVal - initial String value
507                 */
508              DeviceRuntimeParameterStrings(std::vector<String> vS);              DeviceRuntimeParameterStrings(std::vector<String> vS);
509                
510                /// @brief Destructor.
511              virtual ~DeviceRuntimeParameterStrings(){}              virtual ~DeviceRuntimeParameterStrings(){}
512                
513                /////////////////////////////////////////////////////////////////
514                // derived methods, implementing type "STRINGS"
515                //     (usually not to be overriden by descendant)
516                
517              virtual String           Type();              virtual String           Type();
518              virtual bool             Multiplicity();              virtual bool             Multiplicity();
519              virtual optional<String> RangeMin();              virtual optional<String> RangeMin();
# Line 145  namespace LinuxSampler { Line 521  namespace LinuxSampler {
521              virtual optional<String> Possibilities();              virtual optional<String> Possibilities();
522              virtual String           Value();              virtual String           Value();
523              virtual void             SetValue(String val) throw (Exception);              virtual void             SetValue(String val) throw (Exception);
524                
525                /////////////////////////////////////////////////////////////////
526                // convenience methods for type "STRINGS"
527                //     (usually not to be overriden by descendant)
528    
529              virtual std::vector<String> ValueAsStrings();              virtual std::vector<String> ValueAsStrings();
530              virtual void                SetValue(std::vector<String> vS) throw (Exception);              virtual void                SetValue(std::vector<String> vS) throw (Exception);
531                
532              virtual std::vector<String> PossibilitiesAsString()            = 0;              /////////////////////////////////////////////////////////////////
533              virtual void                OnSetValue(std::vector<String> vS) = 0;              // abstract methods
534                //     (these have to be implemented by the descendant)
535    
536                /**
537                 * Must be implemented by descendant, returning a list of possible
538                 * String values for the parameter. If a list of possible values
539                 * does not make sense, the implementation should return an empty
540                 * vector.
541                 */
542                virtual std::vector<String> PossibilitiesAsString() = 0;
543                
544                /**
545                 * Must be implemented be a driver's parameter class to react on
546                 * the parameter value being set / altered.
547                 *
548                 * @param vS - new parameter values set by the user
549                 * @throws Exception - might be thrown by the driver in case it
550                 *                     cannot handle the supplied parameter values
551                 *                     for whatever reason
552                 */
553                virtual void OnSetValue(std::vector<String> vS) = 0;
554          protected:          protected:
555              std::vector<String> sVals;              std::vector<String> sVals;
556      };      };
557    
558        
559        /////////////////////////////////////////////////////////////////
560        // "Creation" parameters
561    
562        /** @brief Abstract base class for parameters at driver instanciation time.
563         *
564         * Device "creation" parameters are special parameters, that are meant to be only
565         * set when a device (driver instance) is created. After device creation those
566         * parameters act as read only parameters. See DeviceRuntimeParameter for a
567         * discussion about this topic.
568         *
569         * In addition to "runtime" parameters, "creation" parameters also handle
570         * additional meta informations required in the specific situations of
571         * creating a device (driver instance). For example "creation" parameters
572         * might indicate whether they MUST be provided explicitly
573         * ( @c Mandatory() ) by the user (i.e. a parameter "CARD" selecting a
574         * specific sound card) for being able to create an instance of the driver.
575         * And "creation" parameters might indicate being dependent to other
576         * parameters, i.e. a parameter "SAMPLERATE" might depend on a parameter
577         * "CARD", to be able to actually provide a list of meaningful
578         * possibilities for sample rates the respective sound card supports.
579         */
580      class DeviceCreationParameter : public DeviceRuntimeParameter {      class DeviceCreationParameter : public DeviceRuntimeParameter {
581          public:          public:
582              DeviceCreationParameter ( void )                  { pDevice = NULL; }              /// @brief Constructor.
583              virtual bool                                      Mandatory() = 0;              DeviceCreationParameter ( void ) { pDevice = NULL; }
584              virtual optional<String>                          Depends();              
585                /**
586                 * Whether the parameter must be supplied by the user at device
587                 * creation time. If this method return @c false, then the
588                 * parameter is optional
589                 */
590                virtual bool Mandatory() = 0;
591                
592                /**
593                 * Might return a comma separated list of parameter names this
594                 * parameter depends on. See this class's introduction about a
595                 * discussion of parameters with dependencies. If this method
596                 * returns @c optional<String>::nothing, then it does not have any
597                 * dependencies to other parameters.
598                 *
599                 * This method already provides an implementation, which usually is
600                 * not overridden by descendants. A descendant would rather
601                 * implement DependsAsParameters() instead.
602                 *
603                 * @see DependsAsParameters()
604                 */
605                virtual optional<String> Depends();
606                
607                /**
608                 * Might return a unique key-value pair list (map) reflecting the
609                 * dependencies of this parameter to other parameters. Each entry
610                 * in the map consists of a key-value pair, the key being the
611                 * parameter name of the respective dependent parameter, and the
612                 * value being an instance of the dependency parameter of that name.
613                 *
614                 * A descendant MUST implement this method, informing about its
615                 * dependencies. If the parameter does not have any dependencies it
616                 * should return an empty map.
617                 *
618                 * See this class's introduction about a discussion of parameters
619                 * with dependencies.
620                 */
621              virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() = 0;              virtual std::map<String,DeviceCreationParameter*> DependsAsParameters() = 0;
622              virtual optional<String>                          Default();              
623              virtual optional<String>                          Default(std::map<String,String> Parameters) = 0;              /**
624              virtual optional<String>                          RangeMin();               * Might return a default value for this parameter. The default
625              virtual optional<String>                          RangeMin(std::map<String,String> Parameters) = 0;               * value will be used if the user does not provide a specific value
626              virtual optional<String>                          RangeMax();               * for this parameter at device creation time. If the parameter
627              virtual optional<String>                          RangeMax(std::map<String,String> Parameters) = 0;               * does not have a reasonable default value, it will return
628              virtual optional<String>                          Possibilities();               * @c optional<String>::nothing.
629              virtual optional<String>                          Possibilities(std::map<String,String> Parameters) = 0;               *
630              void                                              Attach(Device* pDevice) { this->pDevice = pDevice; }               * This method already provides an implementation, which usually is
631                 * not overridden by descendants. A descendant would rather
632                 * implement the other Default() method taking arguments.
633                 */
634                virtual optional<String> Default();
635                
636                /**
637                 * Might return a default value for this parameter. The default
638                 * value will be used if the user does not provide a specific value
639                 * for this parameter at device creation time.
640                 *
641                 * This method must be implemented by descendants. If the parameter
642                 * does not have a reasonable default value, it should return
643                 * @c optional<String>::nothing.
644                 *
645                 * As arguments, the parameters are passed to this method
646                 * automatically, which the user already provided. For example a
647                 * parameter "CARD" the user already did set for selecting a
648                 * specific sound card. So such arguments resolve dependencies
649                 * of this parameter.
650                 *
651                 * @param Parameters - other parameters which the user already
652                 *                     supplied
653                 */
654                virtual optional<String> Default(std::map<String,String> Parameters) = 0;
655                
656                /**
657                 * Might return a minimum value for this parameter. If the
658                 * parameter does not have a reasonable minimum value, it will
659                 * return @c optional<String>::nothing.
660                 *
661                 * This method already provides an implementation, which usually is
662                 * not overridden by descendants. A descendant would rather
663                 * implement the other RangeMin() method taking arguments.
664                 */
665                virtual optional<String> RangeMin();
666                
667                /**
668                 * Might return a minimum value for this parameter.
669                 *
670                 * This method must be implemented by descendants. If the parameter
671                 * does not have a reasonable minimum value, it should return
672                 * @c optional<String>::nothing.
673                 *
674                 * As arguments, the parameters are passed to this method
675                 * automatically, which the user already provided. For example a
676                 * parameter "CARD" the user already did set for selecting a
677                 * specific sound card. So such arguments resolve dependencies
678                 * of this parameter.
679                 *
680                 * @param Parameters - other parameters which the user already
681                 *                     supplied
682                 */
683                virtual optional<String> RangeMin(std::map<String,String> Parameters) = 0;
684                
685                /**
686                 * Might return a maximum value for this parameter. If the
687                 * parameter does not have a reasonable maximum value, it will
688                 * return @c optional<String>::nothing.
689                 *
690                 * This method already provides an implementation, which usually is
691                 * not overridden by descendants. A descendant would rather
692                 * implement the other RangeMax() method taking arguments.
693                 */
694                virtual optional<String> RangeMax();
695                
696                /**
697                 * Might return a maximum value for this parameter.
698                 *
699                 * This method must be implemented by descendants. If the parameter
700                 * does not have a reasonable maximum value, it should return
701                 * @c optional<String>::nothing.
702                 *
703                 * As arguments, the parameters are passed to this method
704                 * automatically, which the user already provided. For example a
705                 * parameter "CARD" the user already did set for selecting a
706                 * specific sound card. So such arguments resolve dependencies
707                 * of this parameter.
708                 *
709                 * @param Parameters - other parameters which the user already
710                 *                     supplied
711                 */
712                virtual optional<String> RangeMax(std::map<String,String> Parameters) = 0;
713                
714                /**
715                 * Might return a comma separated list as String with possible
716                 * values for this parameter. If the parameter does not have
717                 * reasonable, specific possible values, it will return
718                 * @c optional<String>::nothing.
719                 *
720                 * This method already provides an implementation, which usually is
721                 * not overridden by descendants. A descendant would rather
722                 * implement the other Possibilities() method taking arguments.
723                 */
724                virtual optional<String> Possibilities();
725                
726                /**
727                 * Might return a comma separated list as String with possible
728                 * values for this parameter.
729                 *
730                 * This method must be implemented by descendants. If the parameter
731                 * does not have reasonable, specific possible values, it should
732                 * return @c optional<String>::nothing.
733                 *
734                 * As arguments, the parameters are passed to this method
735                 * automatically, which the user already provided. For example a
736                 * parameter "CARD" the user already did set for selecting a
737                 * specific sound card. So such arguments resolve dependencies
738                 * of this parameter.
739                 *
740                 * @param Parameters - other parameters which the user already
741                 *                     supplied
742                 */
743                virtual optional<String> Possibilities(std::map<String,String> Parameters) = 0;
744                
745                /**
746                 * Sets the internal device pointer to a specific device (driver
747                 * instance) for this parameter object. Descendants usually use
748                 * that internal pointer to interact with their specific driver
749                 * implementation class.
750                 */
751                void Attach(Device* pDevice) { this->pDevice = pDevice; }
752          protected:          protected:
753              Device* pDevice;              Device* pDevice;
754      };      };
755    
756        /** @brief Abstract base class for driver parameters of type @c Bool.
757         *
758         * Implements a "creation" driver parameter for value type @c bool.
759         * A driver offering a parameter of type @c bool would derive its
760         * parameter class from this class and implement the abstract methods
761         * OnSetValue() and DefaultAsBool().
762         *
763         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
764         * about "runtime" parameters vs. "creation" parameters.
765         *
766         * @see DeviceRuntimeParameterBool
767         */
768      class DeviceCreationParameterBool : public DeviceCreationParameter {      class DeviceCreationParameterBool : public DeviceCreationParameter {
769          public:          public:
770              DeviceCreationParameterBool(bool bVal = false);              DeviceCreationParameterBool(bool bVal = false);
# Line 200  namespace LinuxSampler { Line 789  namespace LinuxSampler {
789          private:          private:
790      };      };
791    
792        /** @brief Abstract base class for driver parameters of type @c int.
793         *
794         * Implements a "creation" driver parameter for value type @c int.
795         * A driver offering a parameter of type @c int would derive its
796         * parameter class from this class and implement the abstract methods
797         * OnSetValue(), PossibilitiesAsInt(), RangeMinAsInt(), RangeMaxAsInt()
798         * and DefaultAsInt().
799         *
800         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
801         * about "runtime" parameters vs. "creation" parameters.
802         *
803         * @see DeviceRuntimeParameterInt
804         */
805      class DeviceCreationParameterInt : public DeviceCreationParameter {      class DeviceCreationParameterInt : public DeviceCreationParameter {
806          public:          public:
807              DeviceCreationParameterInt(int iVal = 0);              DeviceCreationParameterInt(int iVal = 0);
# Line 227  namespace LinuxSampler { Line 829  namespace LinuxSampler {
829          private:          private:
830      };      };
831    
832        /** @brief Abstract base class for driver parameters of type @c float.
833         *
834         * Implements a "creation" driver parameter for value type @c float.
835         * A driver offering a parameter of type @c float would derive its
836         * parameter class from this class and implement the abstract methods
837         * OnSetValue(), PossibilitiesAsFloat(), RangeMinAsFloat(),
838         * RangeMaxAsFloat() and DefaultAsFloat().
839         *
840         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
841         * about "runtime" parameters vs. "creation" parameters.
842         *
843         * @see DeviceRuntimeParameterFloat
844         */
845      class DeviceCreationParameterFloat : public DeviceCreationParameter {      class DeviceCreationParameterFloat : public DeviceCreationParameter {
846          public:          public:
847              DeviceCreationParameterFloat(float fVal = 0.0);              DeviceCreationParameterFloat(float fVal = 0.0);
# Line 254  namespace LinuxSampler { Line 869  namespace LinuxSampler {
869          private:          private:
870      };      };
871    
872        /** @brief Abstract base class for driver parameters of type @c String.
873         *
874         * Implements a "creation" driver parameter for value type @c String.
875         * A driver offering a parameter of type @c String would derive its
876         * parameter class from this class and implement the abstract methods
877         * OnSetValue(), PossibilitiesAsString() and DefaultAsString().
878         *
879         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
880         * about "runtime" parameters vs. "creation" parameters.
881         *
882         * @see DeviceRuntimeParameterString
883         */
884      class DeviceCreationParameterString : public DeviceCreationParameter {      class DeviceCreationParameterString : public DeviceCreationParameter {
885          public:          public:
886              DeviceCreationParameterString(String sVal = String());              DeviceCreationParameterString(String sVal = String());
# Line 279  namespace LinuxSampler { Line 906  namespace LinuxSampler {
906          private:          private:
907      };      };
908    
909        /** @brief Abstract base class for driver parameters of a @c String list type.
910         *
911         * Implements a "creation" driver parameter for @c String value types.
912         * A driver offering a parameter allowing to set multiple values of type
913         * @c String would derive its parameter class from this class and implement
914         * the abstract methods OnSetValue(), PossibilitiesAsString() and
915         * DefaultAsStrings().
916         *
917         * See DeviceCreationParameter and DeviceRuntimeParameter for a discussion
918         * about "runtime" parameters vs. "creation" parameters.
919         *
920         * @see DeviceRuntimeParameterStrings
921         */
922      class DeviceCreationParameterStrings : public DeviceCreationParameter {      class DeviceCreationParameterStrings : public DeviceCreationParameter {
923          public:          public:
924              DeviceCreationParameterStrings();              DeviceCreationParameterStrings();
Legend:
Removed from v.2413  
changed lines
  Added in v.2414
  ViewVC Help
Powered by ViewVC