/[svn]/linuxsampler/trunk/src/scriptvm/common.h
ViewVC logotype

Diff of /linuxsampler/trunk/src/scriptvm/common.h

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

revision 3277 by schoenebeck, Mon Jun 5 18:40:18 2017 UTC revision 3690 by schoenebeck, Fri Jan 3 10:18:21 2020 UTC
# Line 1  Line 1 
1  /*  /*
2   * Copyright (c) 2014-2017 Christian Schoenebeck   * Copyright (c) 2014-2020 Christian Schoenebeck
3   *   *
4   * http://www.linuxsampler.org   * http://www.linuxsampler.org
5   *   *
# Line 9  Line 9 
9    
10  // This header defines data types shared between the VM core implementation  // This header defines data types shared between the VM core implementation
11  // (inside the current source directory) and other parts of the sampler  // (inside the current source directory) and other parts of the sampler
12  // (located at other source directories).  // (located at other source directories). It also acts as public API of the
13    // Real-Time script engine for other applications.
14    
15  #ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H  #ifndef LS_INSTR_SCRIPT_PARSER_COMMON_H
16  #define LS_INSTR_SCRIPT_PARSER_COMMON_H  #define LS_INSTR_SCRIPT_PARSER_COMMON_H
# Line 18  Line 19 
19  #include <vector>  #include <vector>
20  #include <map>  #include <map>
21  #include <stddef.h> // offsetof()  #include <stddef.h> // offsetof()
22    #include <functional> // std::function<>
23    
24  namespace LinuxSampler {  namespace LinuxSampler {
25    
26      /**      /**
27         * Native data type used by the script engine both internally, as well as
28         * for all integer data types used by scripts (i.e. for all $foo variables
29         * in NKSP scripts). Note that this is different from the original KSP which
30         * is limited to 32 bit for integer variables in KSP scripts.
31         */
32        typedef int64_t vmint;
33    
34        /**
35         * Native data type used internally by the script engine for all unsigned
36         * integer types. This type is currently not exposed to scripts.
37         */
38        typedef uint64_t vmuint;
39    
40        /**
41         * Native data type used by the script engine both internally for floating
42         * point data, as well as for all @c real data types used by scripts (i.e.
43         * for all ~foo variables in NKSP scripts).
44         */
45        typedef float vmfloat;
46    
47        /**
48       * Identifies the type of a noteworthy issue identified by the script       * Identifies the type of a noteworthy issue identified by the script
49       * parser. That's either a parser error or parser warning.       * parser. That's either a parser error or parser warning.
50       */       */
# Line 43  namespace LinuxSampler { Line 66  namespace LinuxSampler {
66          INT_ARR_EXPR, ///< integer array expression          INT_ARR_EXPR, ///< integer array expression
67          STRING_EXPR, ///< string expression          STRING_EXPR, ///< string expression
68          STRING_ARR_EXPR, ///< string array expression          STRING_ARR_EXPR, ///< string array expression
69            REAL_EXPR, ///< floating point (scalar) expression
70            REAL_ARR_EXPR, ///< floating point array expression
71      };      };
72    
73      /** @brief Result flags of a script statement or script function call.      /** @brief Result flags of a script statement or script function call.
# Line 80  namespace LinuxSampler { Line 105  namespace LinuxSampler {
105       *       *
106       * Identifies one of the possible event handler callback types defined by       * Identifies one of the possible event handler callback types defined by
107       * the NKSP script language.       * the NKSP script language.
108         *
109         * IMPORTANT: this type is forced to be emitted as int32_t type ATM, because
110         * that's the native size expected by the built-in instrument script
111         * variable bindings (see occurrences of VMInt32RelPtr and DECLARE_VMINT
112         * respectively. A native type mismatch between the two could lead to
113         * undefined behavior! Background: By definition the C/C++ compiler is free
114         * to choose a bit size for individual enums which it might find
115         * appropriate, which is usually decided by the compiler according to the
116         * biggest enum constant value defined (in practice it is usually 32 bit).
117       */       */
118      enum VMEventHandlerType_t {      enum VMEventHandlerType_t : int32_t {
119          VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block.          VM_EVENT_HANDLER_INIT, ///< Initilization event handler, that is script's "on init ... end on" code block.
120          VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block.          VM_EVENT_HANDLER_NOTE, ///< Note event handler, that is script's "on note ... end on" code block.
121          VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block.          VM_EVENT_HANDLER_RELEASE, ///< Release event handler, that is script's "on release ... end on" code block.
122          VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block.          VM_EVENT_HANDLER_CONTROLLER, ///< Controller event handler, that is script's "on controller ... end on" code block.
123            VM_EVENT_HANDLER_RPN, ///< RPN event handler, that is script's "on rpn ... end on" code block.
124            VM_EVENT_HANDLER_NRPN, ///< NRPN event handler, that is script's "on nrpn ... end on" code block.
125        };
126    
127        /**
128         * All metric unit prefixes (actually just scale factors) supported by this
129         * script engine.
130         */
131        enum MetricPrefix_t {
132            VM_NO_PREFIX = 0, ///< = 1
133            VM_KILO,          ///< = 10^3, short 'k'
134            VM_HECTO,         ///< = 10^2, short 'h'
135            VM_DECA,          ///< = 10, short 'da'
136            VM_DECI,          ///< = 10^-1, short 'd'
137            VM_CENTI,         ///< = 10^-2, short 'c' (this is also used for tuning "cents")
138            VM_MILLI,         ///< = 10^-3, short 'm'
139            VM_MICRO,         ///< = 10^-6, short 'u'
140        };
141    
142        /**
143         * This constant is used for comparison with Unit::unitFactor() to check
144         * whether a number does have any metric unit prefix at all.
145         *
146         * @see Unit::unitFactor()
147         */
148        static const vmfloat VM_NO_FACTOR = vmfloat(1);
149    
150        /**
151         * All measurement unit types supported by this script engine.
152         *
153         * @e Note: there is no standard unit "cents" here (for pitch/tuning), use
154         * @c VM_CENTI for the latter instad. That's because the commonly cited
155         * "cents" unit is actually no measurement unit type but rather a metric
156         * unit prefix.
157         *
158         * @see MetricPrefix_t
159         */
160        enum StdUnit_t {
161            VM_NO_UNIT = 0, ///< No unit used, the number is just an abstract number.
162            VM_SECOND,      ///< Measuring time.
163            VM_HERTZ,       ///< Measuring frequency.
164            VM_BEL,         ///< Measuring relation between two energy levels (in logarithmic scale). Since we are using it for accoustics, we are always referring to A-weighted Bels (i.e. dBA).
165        };
166    
167        //TODO: see Unit::hasUnitFactorEver()
168        enum EverTriState_t {
169            VM_NEVER = 0,
170            VM_MAYBE,
171            VM_ALWAYS,
172      };      };
173    
174      // just symbol prototyping      // just symbol prototyping
175      class VMIntExpr;      class VMIntExpr;
176        class VMRealExpr;
177      class VMStringExpr;      class VMStringExpr;
178        class VMNumberExpr;
179        class VMArrayExpr;
180      class VMIntArrayExpr;      class VMIntArrayExpr;
181        class VMRealArrayExpr;
182      class VMStringArrayExpr;      class VMStringArrayExpr;
183        class VMParserContext;
184    
185        /** @brief Virtual machine standard measuring unit.
186         *
187         * Abstract base class representing standard measurement units throughout
188         * the script engine. These might be e.g. "dB" (deci Bel) for loudness,
189         * "Hz" (Hertz) for frequencies or "s" for "seconds". These unit types can
190         * combined with metric prefixes, for instance "kHz" (kilo Hertz),
191         * "us" (micro second), etc.
192         *
193         * Originally the script engine only supported abstract integer values for
194         * controlling any synthesis parameter or built-in function argument or
195         * variable. Under certain situations it makes sense though for an
196         * instrument script author to provide values in real, standard measurement
197         * units to provide a more natural and intuitive approach for writing
198         * instrument scripts, for example by setting the frequency of some LFO
199         * directly to "20Hz" or reducing loudness by "-4.2dB". Hence support for
200         * standard units in scripts was added as an extension to the NKSP script
201         * engine.
202         *
203         * So a unit consists of 1) a sequence of metric prefixes as scale factor
204         * (e.g. "k" for kilo) and 2) the actual unit type (e.g. "Hz" for Hertz).
205         * The unit type is a constant feature of number literals and variables, so
206         * once a variable was declared with a unit type (or no unit type at all)
207         * then that unit type of that variable cannot be changed for the entire
208         * life time of the script. This is different from the unit's metric
209         * prefix(es) of variables which may freely be changed at runtime.
210         */
211        class VMUnit {
212        public:
213            /**
214             * Returns the metric prefix(es) of this unit as unit factor. A metric
215             * prefix essentially is just a mathematical scale factor that should be
216             * applied to the number associated with the measurement unit. Consider
217             * a string literal in an NKSP script like '3kHz' where 'k' (kilo) is
218             * the metric prefix, which essentically is a scale factor of 1000.
219             *
220             * Usually a unit either has exactly none or one metric prefix, but note
221             * that there might also be units with more than one prefix, for example
222             * @c mdB (milli deci Bel) is used sometimes which has two prefixes. The
223             * latter is an exception though and more than two prefixes is currently
224             * not supported by the script engine.
225             *
226             * The factor returned by this method is the final mathematical factor
227             * that should be multiplied against the number associated with this
228             * unit. This factor results from the sequence of metric prefixes of
229             * this unit.
230             *
231             * @see MetricPrefix_t, hasUnitFactorNow(), hasUnitFactorEver(),
232             *      VM_NO_FACTOR
233             * @returns current metric unit factor
234             */
235            virtual vmfloat unitFactor() const = 0;
236    
237            //TODO: this still needs to be implemented in tree.h/.pp, built-in functions and as 2nd pass of parser appropriately
238            /*virtual*/ EverTriState_t hasUnitFactorEver() const { return VM_NEVER; }
239    
240            /**
241             * Whether this unit currently does have any metric unit prefix.
242             *
243             * This is actually just a convenience method which returns @c true if
244             * unitFactor() is not @c 1.0.
245             *
246             * @see MetricPrefix_t, unitFactor(), hasUnitFactorEver(), VM_NO_FACTOR
247             * @returns @c true if this unit currently has any metric prefix
248             */
249            bool hasUnitFactorNow() const;
250    
251            /**
252             * This is the actual fundamental measuring unit base type of this unit,
253             * which might be either Hertz, second or Bel.
254             *
255             * Note that a number without a unit type may still have metric
256             * prefixes.
257             *
258             * @returns standard unit type identifier or VM_NO_UNIT if no unit type
259             *          is used for this object
260             */
261            virtual StdUnit_t unitType() const = 0;
262    
263            /**
264             * Returns the actual mathematical factor represented by the passed
265             * @a prefix argument.
266             */
267            static vmfloat unitFactor(MetricPrefix_t prefix);
268    
269            /**
270             * Returns the actual mathematical factor represented by the passed
271             * two @a prefix1 and @a prefix2 arguments.
272             *
273             * @returns scale factor of given metric unit prefixes
274             */
275            static vmfloat unitFactor(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
276    
277            /**
278             * Returns the actual mathematical factor represented by the passed
279             * @a prefixes array. The passed array should always be terminated by a
280             * VM_NO_PREFIX value as last element.
281             *
282             * @param prefixes - sequence of metric prefixes
283             * @param size - max. amount of elements of array @a prefixes
284             * @returns scale factor of given metric unit prefixes
285             */
286            static vmfloat unitFactor(const MetricPrefix_t* prefixes, vmuint size = 2);
287        };
288    
289      /** @brief Virtual machine expression      /** @brief Virtual machine expression
290       *       *
# Line 125  namespace LinuxSampler { Line 317  namespace LinuxSampler {
317           * if this expression is i.e. actually a string expression like "12",           * if this expression is i.e. actually a string expression like "12",
318           * calling asInt() will @b not cast that numerical string expression to           * calling asInt() will @b not cast that numerical string expression to
319           * an integer expression 12 for you, instead this method will simply           * an integer expression 12 for you, instead this method will simply
320           * return NULL!           * return NULL! Same applies if this expression is actually a real
321             * number expression: asInt() would return NULL in that case as well.
322           *           *
323           * @see exprType()           * @see exprType(), asReal(), asNumber()
324           */           */
325          VMIntExpr* asInt() const;          VMIntExpr* asInt() const;
326    
327          /**          /**
328             * In case this expression is a real number (floating point) expression,
329             * then this method returns a casted pointer to that VMRealExpr object.
330             * It returns NULL if this expression is not a real number expression.
331             *
332             * @b Note: type casting performed by this method is strict! That means
333             * if this expression is i.e. actually a string expression like "12",
334             * calling asReal() will @b not cast that numerical string expression to
335             * a real number expression 12.0 for you, instead this method will
336             * simply return NULL! Same applies if this expression is actually an
337             * integer expression: asReal() would return NULL in that case as well.
338             *
339             * @see exprType(), asInt(), asNumber()
340             */
341            VMRealExpr* asReal() const;
342    
343            /**
344             * In case this expression is a scalar number expression, that is either
345             * an integer (scalar) expression or a real number (floating point
346             * scalar) expression, then this method returns a casted pointer to that
347             * VMNumberExpr base class object. It returns NULL if this
348             * expression is neither an integer (scalar), nor a real number (scalar)
349             * expression.
350             *
351             * Since the methods asInt() and asReal() are very strict, this method
352             * is provided as convenience access in case only very general
353             * information (e.g. which standard measurement unit is being used or
354             * whether final operator being effective to this expression) is
355             * intended to be retrieved of this scalar number expression independent
356             * from whether this expression is actually an integer or a real number
357             * expression.
358             *
359             * @see exprType(), asInt(), asReal()
360             */
361            VMNumberExpr* asNumber() const;
362    
363            /**
364           * In case this expression is a string expression, then this method           * In case this expression is a string expression, then this method
365           * returns a casted pointer to that VMStringExpr object. It returns NULL           * returns a casted pointer to that VMStringExpr object. It returns NULL
366           * if this expression is not a string expression.           * if this expression is not a string expression.
# Line 152  namespace LinuxSampler { Line 381  namespace LinuxSampler {
381           * returns NULL if this expression is not an integer array expression.           * returns NULL if this expression is not an integer array expression.
382           *           *
383           * @b Note: type casting performed by this method is strict! That means           * @b Note: type casting performed by this method is strict! That means
384           * if this expression is i.e. an integer expression or a string           * if this expression is i.e. an integer scalar expression, a real
385           * expression, calling asIntArray() will @b not cast those scalar           * number expression or a string expression, calling asIntArray() will
386           * expressions to an array expression for you, instead this method will           * @b not cast those expressions to an integer array expression for you,
387           * simply return NULL!           * instead this method will simply return NULL!
388           *           *
389           * @b Note: this method is currently, and in contrast to its other           * @b Note: this method is currently, and in contrast to its other
390           * counter parts, declared as virtual method. Some deriving classes are           * counter parts, declared as virtual method. Some deriving classes are
# Line 170  namespace LinuxSampler { Line 399  namespace LinuxSampler {
399          virtual VMIntArrayExpr* asIntArray() const;          virtual VMIntArrayExpr* asIntArray() const;
400    
401          /**          /**
402             * In case this expression is a real number (floating point) array
403             * expression, then this method returns a casted pointer to that
404             * VMRealArrayExpr object. It returns NULL if this expression is not a
405             * real number array expression.
406             *
407             * @b Note: type casting performed by this method is strict! That means
408             * if this expression is i.e. a real number scalar expression, an
409             * integer expression or a string expression, calling asRealArray() will
410             * @b not cast those scalar expressions to a real number array
411             * expression for you, instead this method will simply return NULL!
412             *
413             * @b Note: this method is currently, and in contrast to its other
414             * counter parts, declared as virtual method. Some deriving classes are
415             * currently using this to override this default implementation in order
416             * to implement an "evaluate now as real number array" behavior. This
417             * has efficiency reasons, however this also currently makes this part
418             * of the API less clean and should thus be addressed in future with
419             * appropriate changes to the API.
420             *
421             * @see exprType()
422             */
423            virtual VMRealArrayExpr* asRealArray() const;
424    
425            /**
426             * This is an alternative to calling either asIntArray() or
427             * asRealArray(). This method here might be used if the fundamental
428             * scalar data type (real or integer) of the array is not relevant,
429             * i.e. for just getting the size of the array. Since all as*() methods
430             * here are very strict regarding type casting, this asArray() method
431             * sometimes can reduce code complexity.
432             *
433             * Likewise calling this method only returns a valid pointer if the
434             * expression is some array type (currently either integer array or real
435             * number array). For any other expression type this method will return
436             * NULL instead.
437             *
438             * @see exprType()
439             */
440            VMArrayExpr* asArray() const;
441    
442            /**
443           * Returns true in case this expression can be considered to be a           * Returns true in case this expression can be considered to be a
444           * constant expression. A constant expression will retain the same           * constant expression. A constant expression will retain the same
445           * value throughout the entire life time of a script and the           * value throughout the entire life time of a script and the
# Line 200  namespace LinuxSampler { Line 470  namespace LinuxSampler {
470          bool isModifyable() const;          bool isModifyable() const;
471      };      };
472    
473        /** @brief Virtual machine scalar number expression
474         *
475         * This is the abstract base class for integer (scalar) expressions and
476         * real number (floating point scalar) expressions of scripts.
477         */
478        class VMNumberExpr : virtual public VMExpr, virtual public VMUnit {
479        public:
480            /**
481             * Returns @c true if the value of this expression should be applied
482             * as final value to the respective destination synthesis chain
483             * parameter.
484             *
485             * This property is somewhat special and dedicated for the purpose of
486             * this expression's (integer or real number) value to be applied as
487             * parameter to the synthesis chain of the sampler (i.e. for altering a
488             * filter cutoff frequency). Now historically and by default all values
489             * of scripts are applied relatively to the sampler's synthesis chain,
490             * that is the synthesis parameter value of a script is multiplied
491             * against other sources for the same synthesis parameter (i.e. an LFO
492             * or a dedicated MIDI controller either hard wired in the engine or
493             * defined by the instrument patch). So by default the resulting actual
494             * final synthesis parameter is a combination of all these sources. This
495             * has the advantage that it creates a very living and dynamic overall
496             * sound.
497             *
498             * However sometimes there are requirements by script authors where this
499             * is not what you want. Therefore the NKSP script engine added a
500             * language extension by prefixing a value in scripts with a @c !
501             * character the value will be defined as being the "final" value of the
502             * destination synthesis parameter, so that causes this value to be
503             * applied exclusively, and the values of all other sources are thus
504             * entirely ignored by the sampler's synthesis core as long as this
505             * value is assigned by the script engine as "final" value for the
506             * requested synthesis parameter.
507             */
508            virtual bool isFinal() const = 0;
509    
510            /**
511             * Calling this method evaluates the expression and returns the value
512             * of the expression as integer. If this scalar number expression is a
513             * real number expression then this method automatically casts the value
514             * from real number to integer.
515             */
516            vmint evalCastInt();
517    
518            /**
519             * Calling this method evaluates the expression and returns the value
520             * of the expression as integer and thus behaves similar to the previous
521             * method, however this overridden method automatically takes unit
522             * prefixes into account and returns a converted value corresponding to
523             * the given unit @a prefix expected by the caller.
524             *
525             * Example: Assume this expression was an integer expression '12kHz'
526             * then calling this method as @c evalCastInt(VM_MILLI) would return
527             * the value @c 12000000.
528             *
529             * @param prefix - measuring unit prefix expected for result by caller
530             */
531            vmint evalCastInt(MetricPrefix_t prefix);
532    
533            /**
534             * This method behaves like the previous method, just that it takes a
535             * measuring unit prefix with two elements (e.g. "milli cents" for
536             * tuning).
537             *
538             * @param prefix1 - 1st measuring unit prefix element expected by caller
539             * @param prefix2 - 2nd measuring unit prefix element expected by caller
540             */
541            vmint evalCastInt(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
542    
543            /**
544             * Calling this method evaluates the expression and returns the value
545             * of the expression as real number. If this scalar number expression is
546             * an integer expression then this method automatically casts the value
547             * from integer to real number.
548             */
549            vmfloat evalCastReal();
550    
551            /**
552             * Calling this method evaluates the expression and returns the value
553             * of the expression as real number and thus behaves similar to the
554             * previous method, however this overridden method automatically takes
555             * unit prefixes into account and returns a converted value
556             * corresponding to the given unit @a prefix expected by the caller.
557             *
558             * Example: Assume this expression was an integer expression '8ms' then
559             * calling this method as @c evalCastReal(VM_NO_PREFIX) would return the
560             * value @c 0.008.
561             *
562             * @param prefix - measuring unit prefix expected for result by caller
563             */
564            vmfloat evalCastReal(MetricPrefix_t prefix);
565    
566            /**
567             * This method behaves like the previous method, just that it takes a
568             * measuring unit prefix with two elements (e.g. "milli cents" for
569             * tuning).
570             *
571             * @param prefix1 - 1st measuring unit prefix element expected by caller
572             * @param prefix2 - 2nd measuring unit prefix element expected by caller
573             */
574            vmfloat evalCastReal(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
575        };
576    
577      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
578       *       *
579       * This is the abstract base class for all expressions inside scripts which       * This is the abstract base class for all expressions inside scripts which
# Line 207  namespace LinuxSampler { Line 581  namespace LinuxSampler {
581       * abstract method evalInt() to return the actual integer result value of       * abstract method evalInt() to return the actual integer result value of
582       * the expression.       * the expression.
583       */       */
584      class VMIntExpr : virtual public VMExpr {      class VMIntExpr : virtual public VMNumberExpr {
585      public:      public:
586          /**          /**
587           * Returns the result of this expression as integer (scalar) value.           * Returns the result of this expression as integer (scalar) value.
588           * This abstract method must be implemented by deriving classes.           * This abstract method must be implemented by deriving classes.
589           */           */
590          virtual int evalInt() = 0;          virtual vmint evalInt() = 0;
591    
592            /**
593             * Returns the result of this expression as integer (scalar) value and
594             * thus behaves similar to the previous method, however this overridden
595             * method automatically takes unit prefixes into account and returns a
596             * value corresponding to the expected given unit @a prefix.
597             *
598             * @param prefix - default measurement unit prefix expected by caller
599             */
600            vmint evalInt(MetricPrefix_t prefix);
601    
602            /**
603             * This method behaves like the previous method, just that it takes
604             * a default measurement prefix with two elements (i.e. "milli cents"
605             * for tuning).
606             */
607            vmint evalInt(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
608    
609          /**          /**
610           * Returns always INT_EXPR for instances of this class.           * Returns always INT_EXPR for instances of this class.
# Line 221  namespace LinuxSampler { Line 612  namespace LinuxSampler {
612          ExprType_t exprType() const OVERRIDE { return INT_EXPR; }          ExprType_t exprType() const OVERRIDE { return INT_EXPR; }
613      };      };
614    
615        /** @brief Virtual machine real number (floating point scalar) expression
616         *
617         * This is the abstract base class for all expressions inside scripts which
618         * evaluate to a real number (floating point scalar) value. Deriving classes
619         * implement the abstract method evalReal() to return the actual floating
620         * point result value of the expression.
621         */
622        class VMRealExpr : virtual public VMNumberExpr {
623        public:
624            /**
625             * Returns the result of this expression as real number (floating point
626             * scalar) value. This abstract method must be implemented by deriving
627             * classes.
628             */
629            virtual vmfloat evalReal() = 0;
630    
631            /**
632             * Returns the result of this expression as real number (floating point
633             * scalar) value and thus behaves similar to the previous method,
634             * however this overridden method automatically takes unit prefixes into
635             * account and returns a value corresponding to the expected given unit
636             * @a prefix.
637             *
638             * @param prefix - default measurement unit prefix expected by caller
639             */
640            vmfloat evalReal(MetricPrefix_t prefix);
641    
642            /**
643             * This method behaves like the previous method, just that it takes
644             * a default measurement prefix with two elements (i.e. "milli cents"
645             * for tuning).
646             */
647            vmfloat evalReal(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
648    
649            /**
650             * Returns always REAL_EXPR for instances of this class.
651             */
652            ExprType_t exprType() const OVERRIDE { return REAL_EXPR; }
653        };
654    
655      /** @brief Virtual machine string expression      /** @brief Virtual machine string expression
656       *       *
657       * This is the abstract base class for all expressions inside scripts which       * This is the abstract base class for all expressions inside scripts which
# Line 255  namespace LinuxSampler { Line 686  namespace LinuxSampler {
686           * Returns amount of elements in this array. This abstract method must           * Returns amount of elements in this array. This abstract method must
687           * be implemented by deriving classes.           * be implemented by deriving classes.
688           */           */
689          virtual int arraySize() const = 0;          virtual vmint arraySize() const = 0;
690        };
691    
692        /** @brief Virtual Machine Number Array Expression
693         *
694         * This is the abstract base class for all expressions which either evaluate
695         * to an integer array or real number array.
696         */
697        class VMNumberArrayExpr : virtual public VMArrayExpr {
698        public:
699            /**
700             * Returns the metric unit factor of the requested array element.
701             *
702             * @param i - array element index (must be between 0 .. arraySize() - 1)
703             * @see VMUnit::unitFactor() for details about metric unit factors
704             */
705            virtual vmfloat unitFactorOfElement(vmuint i) const = 0;
706    
707            /**
708             * Changes the current unit factor of the array element given by element
709             * index @a i.
710             *
711             * @param i - array element index (must be between 0 .. arraySize() - 1)
712             * @param factor - new unit factor to be assigned
713             * @see VMUnit::unitFactor() for details about metric unit factors
714             */
715            virtual void assignElementUnitFactor(vmuint i, vmfloat factor) = 0;
716      };      };
717    
718      /** @brief Virtual Machine Integer Array Expression      /** @brief Virtual Machine Integer Array Expression
# Line 265  namespace LinuxSampler { Line 722  namespace LinuxSampler {
722       * abstract methods arraySize(), evalIntElement() and assignIntElement() to       * abstract methods arraySize(), evalIntElement() and assignIntElement() to
723       * access the individual integer array values.       * access the individual integer array values.
724       */       */
725      class VMIntArrayExpr : virtual public VMArrayExpr {      class VMIntArrayExpr : virtual public VMNumberArrayExpr {
726      public:      public:
727          /**          /**
728           * Returns the (scalar) integer value of the array element given by           * Returns the (scalar) integer value of the array element given by
# Line 273  namespace LinuxSampler { Line 730  namespace LinuxSampler {
730           *           *
731           * @param i - array element index (must be between 0 .. arraySize() - 1)           * @param i - array element index (must be between 0 .. arraySize() - 1)
732           */           */
733          virtual int evalIntElement(uint i) = 0;          virtual vmint evalIntElement(vmuint i) = 0;
734    
735          /**          /**
736           * Changes the current value of an element (given by array element           * Changes the current value of an element (given by array element
# Line 282  namespace LinuxSampler { Line 739  namespace LinuxSampler {
739           * @param i - array element index (must be between 0 .. arraySize() - 1)           * @param i - array element index (must be between 0 .. arraySize() - 1)
740           * @param value - new integer scalar value to be assigned to that array element           * @param value - new integer scalar value to be assigned to that array element
741           */           */
742          virtual void assignIntElement(uint i, int value) = 0;          virtual void assignIntElement(vmuint i, vmint value) = 0;
743    
744          /**          /**
745           * Returns always INT_ARR_EXPR for instances of this class.           * Returns always INT_ARR_EXPR for instances of this class.
# Line 290  namespace LinuxSampler { Line 747  namespace LinuxSampler {
747          ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; }          ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; }
748      };      };
749    
750        /** @brief Virtual Machine Real Number Array Expression
751         *
752         * This is the abstract base class for all expressions inside scripts which
753         * evaluate to an array of real numbers (floating point values). Deriving
754         * classes implement the abstract methods arraySize(), evalRealElement() and
755         * assignRealElement() to access the array's individual real numbers.
756         */
757        class VMRealArrayExpr : virtual public VMNumberArrayExpr {
758        public:
759            /**
760             * Returns the (scalar) real mumber (floating point value) of the array
761             * element given by element index @a i.
762             *
763             * @param i - array element index (must be between 0 .. arraySize() - 1)
764             */
765            virtual vmfloat evalRealElement(vmuint i) = 0;
766    
767            /**
768             * Changes the current value of an element (given by array element
769             * index @a i) of this real number array.
770             *
771             * @param i - array element index (must be between 0 .. arraySize() - 1)
772             * @param value - new real number value to be assigned to that array element
773             */
774            virtual void assignRealElement(vmuint i, vmfloat value) = 0;
775    
776            /**
777             * Returns always REAL_ARR_EXPR for instances of this class.
778             */
779            ExprType_t exprType() const OVERRIDE { return REAL_ARR_EXPR; }
780        };
781    
782      /** @brief Arguments (parameters) for being passed to a built-in script function.      /** @brief Arguments (parameters) for being passed to a built-in script function.
783       *       *
784       * An argument or a set of arguments passed to a script function are       * An argument or a set of arguments passed to a script function are
# Line 304  namespace LinuxSampler { Line 793  namespace LinuxSampler {
793           * Returns the amount of arguments going to be passed to the script           * Returns the amount of arguments going to be passed to the script
794           * function.           * function.
795           */           */
796          virtual int argsCount() const = 0;          virtual vmint argsCount() const = 0;
797    
798          /**          /**
799           * Returns the respective argument (requested by argument index @a i) of           * Returns the respective argument (requested by argument index @a i) of
# Line 313  namespace LinuxSampler { Line 802  namespace LinuxSampler {
802           * argument passed to the function at runtime.           * argument passed to the function at runtime.
803           *           *
804           * @param i - function argument index (indexed from left to right)           * @param i - function argument index (indexed from left to right)
805             * @return requested function argument or NULL if @a i out of bounds
806           */           */
807          virtual VMExpr* arg(int i) = 0;          virtual VMExpr* arg(vmint i) = 0;
808      };      };
809    
810      /** @brief Result value returned from a call to a built-in script function.      /** @brief Result value returned from a call to a built-in script function.
# Line 370  namespace LinuxSampler { Line 860  namespace LinuxSampler {
860          /**          /**
861           * Script data type of the function's return value. If the function does           * Script data type of the function's return value. If the function does
862           * not return any value (void), then it returns EMPTY_EXPR here.           * not return any value (void), then it returns EMPTY_EXPR here.
863             *
864             * Some functions may have a different return type depending on the
865             * arguments to be passed to this function. That's what the @a args
866             * parameter is for, so that the method implementation can look ahead
867             * of what kind of parameters are going to be passed to the built-in
868             * function later on in order to decide which return value type would
869             * be used and returned by the function accordingly in that case.
870             *
871             * @param args - function arguments going to be passed for executing
872             *               this built-in function later on
873             */
874            virtual ExprType_t returnType(VMFnArgs* args) = 0;
875    
876            /**
877             * Standard measuring unit type of the function's result value
878             * (e.g. second, Hertz).
879             *
880             * Some functions may have a different standard measuring unit type for
881             * their return value depending on the arguments to be passed to this
882             * function. That's what the @a args parameter is for, so that the
883             * method implementation can look ahead of what kind of parameters are
884             * going to be passed to the built-in function later on in order to
885             * decide which return value type would be used and returned by the
886             * function accordingly in that case.
887             *
888             * @param args - function arguments going to be passed for executing
889             *               this built-in function later on
890             * @see Unit for details about standard measuring units
891           */           */
892          virtual ExprType_t returnType() = 0;          virtual StdUnit_t returnUnitType(VMFnArgs* args) = 0;
893    
894            /**
895             * Whether the result value returned by this built-in function is
896             * considered to be a 'final' value.
897             *
898             * Some functions may have a different 'final' feature for their return
899             * value depending on the arguments to be passed to this function.
900             * That's what the @a args parameter is for, so that the method
901             * implementation can look ahead of what kind of parameters are going to
902             * be passed to the built-in function later on in order to decide which
903             * return value type would be used and returned by the function
904             * accordingly in that case.
905             *
906             * @param args - function arguments going to be passed for executing
907             *               this built-in function later on
908             * @see VMNumberExpr::isFinal() for details about 'final' values
909             */
910            virtual bool returnsFinal(VMFnArgs* args) = 0;
911    
912          /**          /**
913           * Minimum amount of function arguments this function accepts. If a           * Minimum amount of function arguments this function accepts. If a
914           * script is calling this function with less arguments, the script           * script is calling this function with less arguments, the script
915           * parser will throw a parser error.           * parser will throw a parser error.
916           */           */
917          virtual int minRequiredArgs() const = 0;          virtual vmint minRequiredArgs() const = 0;
918    
919          /**          /**
920           * Maximum amount of function arguments this functions accepts. If a           * Maximum amount of function arguments this functions accepts. If a
921           * script is calling this function with more arguments, the script           * script is calling this function with more arguments, the script
922           * parser will throw a parser error.           * parser will throw a parser error.
923           */           */
924          virtual int maxAllowedArgs() const = 0;          virtual vmint maxAllowedArgs() const = 0;
925    
926          /**          /**
927           * Script data type of the function's @c iArg 'th function argument.           * This method is called by the parser to check whether arguments
928           * The information provided here is less strong than acceptsArgType().           * passed in scripts to this function are accepted by this function. If
929           * The parser will compare argument data types provided in scripts by           * a script calls this function with an argument's data type not
930           * calling acceptsArgType(). The return value of argType() is used by the           * accepted by this function, the parser will throw a parser error.
931           * parser instead to show an appropriate parser error which data type           *
932           * this function usually expects as "default" data type. Reason: a           * The parser will also use this method to assemble a list of actually
933           * function may accept multiple data types for a certain function           * supported data types accepted by this built-in function for the
934           * argument and would automatically cast the passed argument value in           * function argument in question, that is to provide an appropriate and
935           * that case to the type it actually needs.           * precise parser error message in such cases.
936           *           *
937           * @param iArg - index of the function argument in question           * @param iArg - index of the function argument in question
938           *               (must be between 0 .. maxAllowedArgs() - 1)           *               (must be between 0 .. maxAllowedArgs() - 1)
939             * @param type - script data type used for this function argument by
940             *               currently parsed script
941             * @return true if the given data type would be accepted for the
942             *         respective function argument by the function
943           */           */
944          virtual ExprType_t argType(int iArg) const = 0;          virtual bool acceptsArgType(vmint iArg, ExprType_t type) const = 0;
945    
946          /**          /**
947           * This method is called by the parser to check whether arguments           * This method is called by the parser to check whether arguments
948           * passed in scripts to this function are accepted by this function. If           * passed in scripts to this function are accepted by this function. If
949           * a script calls this function with an argument's data type not           * a script calls this function with an argument's measuremnt unit type
950           * accepted by this function, the parser will throw a parser error. On           * not accepted by this function, the parser will throw a parser error.
951           * such errors the data type returned by argType() will be used to           *
952           * assemble an appropriate error message regarding the precise misusage           * This default implementation of this method does not accept any
953           * of the built-in function.           * measurement unit. Deriving subclasses would override this method
954             * implementation in case they do accept any measurement unit for its
955             * function arguments.
956           *           *
957           * @param iArg - index of the function argument in question           * @param iArg - index of the function argument in question
958           *               (must be between 0 .. maxAllowedArgs() - 1)           *               (must be between 0 .. maxAllowedArgs() - 1)
959           * @param type - script data type used for this function argument by           * @param type - standard measurement unit data type used for this
960           *               currently parsed script           *               function argument by currently parsed script
961           * @return true if the given data type would be accepted for the           * @return true if the given standard measurement unit type would be
962           *         respective function argument by the function           *         accepted for the respective function argument by the function
963           */           */
964          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgUnitType(vmint iArg, StdUnit_t type) const;
965    
966            /**
967             * This method is called by the parser to check whether arguments
968             * passed in scripts to this function are accepted by this function. If
969             * a script calls this function with a metric unit prefix and metric
970             * prefixes are not accepted for that argument by this function, then
971             * the parser will throw a parser error.
972             *
973             * This default implementation of this method does not accept any
974             * metric prefix. Deriving subclasses would override this method
975             * implementation in case they do accept any metric prefix for its
976             * function arguments.
977             *
978             * @param iArg - index of the function argument in question
979             *               (must be between 0 .. maxAllowedArgs() - 1)
980             * @param type - standard measurement unit data type used for that
981             *               function argument by currently parsed script
982             *
983             * @return true if a metric prefix would be accepted for the respective
984             *         function argument by this function
985             *
986             * @see MetricPrefix_t
987             */
988            virtual bool acceptsArgUnitPrefix(vmint iArg, StdUnit_t type) const;
989    
990            /**
991             * This method is called by the parser to check whether arguments
992             * passed in scripts to this function are accepted by this function. If
993             * a script calls this function with an argument that is declared to be
994             * a "final" value and this is not accepted by this function, the parser
995             * will throw a parser error.
996             *
997             * This default implementation of this method does not accept a "final"
998             * value. Deriving subclasses would override this method implementation
999             * in case they do accept a "final" value for its function arguments.
1000             *
1001             * @param iArg - index of the function argument in question
1002             *               (must be between 0 .. maxAllowedArgs() - 1)
1003             * @return true if a "final" value would be accepted for the respective
1004             *         function argument by the function
1005             *
1006             * @see VMNumberExpr::isFinal(), returnsFinal()
1007             */
1008            virtual bool acceptsArgFinal(vmint iArg) const;
1009    
1010          /**          /**
1011           * This method is called by the parser to check whether some arguments           * This method is called by the parser to check whether some arguments
# Line 434  namespace LinuxSampler { Line 1020  namespace LinuxSampler {
1020           * @param iArg - index of the function argument in question           * @param iArg - index of the function argument in question
1021           *               (must be between 0 .. maxAllowedArgs() - 1)           *               (must be between 0 .. maxAllowedArgs() - 1)
1022           */           */
1023          virtual bool modifiesArg(int iArg) const = 0;          virtual bool modifiesArg(vmint iArg) const = 0;
1024    
1025            /** @brief Parse-time check of function arguments.
1026             *
1027             * This method is called by the parser to let the built-in function
1028             * perform its own, individual parse time checks on the arguments to be
1029             * passed to the built-in function. So this method is the place for
1030             * implementing custom checks which are very specific to the individual
1031             * built-in function's purpose and its individual requirements.
1032             *
1033             * For instance the built-in 'in_range()' function uses this method to
1034             * check whether the last 2 of their 3 arguments are of same data type
1035             * and if not it triggers a parser error. 'in_range()' also checks
1036             * whether all of its 3 arguments do have the same standard measuring
1037             * unit type and likewise raises a parser error if not.
1038             *
1039             * For less critical issues built-in functions may also raise parser
1040             * warnings instead.
1041             *
1042             * It is recommended that classes implementing (that is overriding) this
1043             * method should always call their super class's implementation of this
1044             * method to ensure their potential parse time checks are always
1045             * performed as well.
1046             *
1047             * @param args - function arguments going to be passed for executing
1048             *               this built-in function later on
1049             * @param err - the parser's error handler to be called by this method
1050             *              implementation to trigger a parser error with the
1051             *              respective error message text
1052             * @param wrn - the parser's warning handler to be called by this method
1053             *              implementation to trigger a parser warning with the
1054             *              respective warning message text
1055             */
1056            virtual void checkArgs(VMFnArgs* args,
1057                                   std::function<void(String)> err,
1058                                   std::function<void(String)> wrn);
1059    
1060          /**          /**
1061           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
# Line 468  namespace LinuxSampler { Line 1089  namespace LinuxSampler {
1089    
1090      /** @brief Virtual machine relative pointer.      /** @brief Virtual machine relative pointer.
1091       *       *
1092       * POD base of VMIntRelPtr and VMInt8RelPtr structures. Not intended to be       * POD base of VMInt64RelPtr, VMInt32RelPtr and VMInt8RelPtr structures. Not
1093       * used directly. Use VMIntRelPtr or VMInt8RelPtr instead.       * intended to be used directly. Use VMInt64RelPtr, VMInt32RelPtr,
1094         * VMInt8RelPtr instead.
1095       *       *
1096       * @see VMIntRelPtr, VMInt8RelPtr       * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr
1097       */       */
1098      struct VMRelPtr {      struct VMRelPtr {
1099          void** base; ///< Base pointer.          void** base; ///< Base pointer.
1100          int offset;  ///< Offset (in bytes) relative to base pointer.          vmint offset;  ///< Offset (in bytes) relative to base pointer.
1101          bool readonly; ///< Whether the pointed data may be modified or just be read.          bool readonly; ///< Whether the pointed data may be modified or just be read.
1102      };      };
1103    
1104      /** @brief Pointer to built-in VM integer variable (of C/C++ type int).      /** @brief Pointer to built-in VM integer variable (interface class).
1105         *
1106         * This class acts as an abstract interface to all built-in integer script
1107         * variables, independent of their actual native size (i.e. some built-in
1108         * script variables are internally using a native int size of 64 bit or 32
1109         * bit or 8 bit). The virtual machine is using this interface class instead
1110         * of its implementing descendants (VMInt64RelPtr, VMInt32RelPtr,
1111         * VMInt8RelPtr) in order for the virtual machine for not being required to
1112         * handle each of them differently.
1113         */
1114        struct VMIntPtr {
1115            virtual vmint evalInt() = 0;
1116            virtual void assign(vmint i) = 0;
1117            virtual bool isAssignable() const = 0;
1118        };
1119    
1120        /** @brief Pointer to built-in VM integer variable (of C/C++ type int64_t).
1121         *
1122         * Used for defining built-in 64 bit integer script variables.
1123         *
1124         * @b CAUTION: You may only use this class for pointing to C/C++ variables
1125         * of type "int64_t" (thus being exactly 64 bit in size). If the C/C++ int
1126         * variable you want to reference is only 32 bit in size then you @b must
1127         * use VMInt32RelPtr instead! Respectively for a referenced native variable
1128         * with only 8 bit in size you @b must use VMInt8RelPtr instead!
1129         *
1130         * For efficiency reasons the actual native C/C++ int variable is referenced
1131         * by two components here. The actual native int C/C++ variable in memory
1132         * is dereferenced at VM run-time by taking the @c base pointer dereference
1133         * and adding @c offset bytes. This has the advantage that for a large
1134         * number of built-in int variables, only one (or few) base pointer need
1135         * to be re-assigned before running a script, instead of updating each
1136         * built-in variable each time before a script is executed.
1137         *
1138         * Refer to DECLARE_VMINT() for example code.
1139         *
1140         * @see VMInt32RelPtr, VMInt16RelPtr, VMInt8RelPtr, DECLARE_VMINT()
1141         */
1142        struct VMInt64RelPtr : VMRelPtr, VMIntPtr {
1143            VMInt64RelPtr() {
1144                base   = NULL;
1145                offset = 0;
1146                readonly = false;
1147            }
1148            VMInt64RelPtr(const VMRelPtr& data) {
1149                base   = data.base;
1150                offset = data.offset;
1151                readonly = false;
1152            }
1153            vmint evalInt() OVERRIDE {
1154                return (vmint)*(int64_t*)&(*(uint8_t**)base)[offset];
1155            }
1156            void assign(vmint i) OVERRIDE {
1157                *(int64_t*)&(*(uint8_t**)base)[offset] = (int64_t)i;
1158            }
1159            bool isAssignable() const OVERRIDE { return !readonly; }
1160        };
1161    
1162        /** @brief Pointer to built-in VM integer variable (of C/C++ type int32_t).
1163       *       *
1164       * Used for defining built-in 32 bit integer script variables.       * Used for defining built-in 32 bit integer script variables.
1165       *       *
1166       * @b CAUTION: You may only use this class for pointing to C/C++ variables       * @b CAUTION: You may only use this class for pointing to C/C++ variables
1167       * of type "int" (which on most systems is 32 bit in size). If the C/C++ int       * of type "int32_t" (thus being exactly 32 bit in size). If the C/C++ int
1168       * variable you want to reference is only 8 bit in size, then you @b must       * variable you want to reference is 64 bit in size then you @b must use
1169       * use VMInt8RelPtr instead!       * VMInt64RelPtr instead! Respectively for a referenced native variable with
1170         * only 8 bit in size you @b must use VMInt8RelPtr instead!
1171       *       *
1172       * For efficiency reasons the actual native C/C++ int variable is referenced       * For efficiency reasons the actual native C/C++ int variable is referenced
1173       * by two components here. The actual native int C/C++ variable in memory       * by two components here. The actual native int C/C++ variable in memory
# Line 498  namespace LinuxSampler { Line 1179  namespace LinuxSampler {
1179       *       *
1180       * Refer to DECLARE_VMINT() for example code.       * Refer to DECLARE_VMINT() for example code.
1181       *       *
1182       * @see VMInt8RelPtr, DECLARE_VMINT()       * @see VMInt64RelPtr, VMInt16RelPtr, VMInt8RelPtr, DECLARE_VMINT()
1183       */       */
1184      struct VMIntRelPtr : VMRelPtr {      struct VMInt32RelPtr : VMRelPtr, VMIntPtr {
1185          VMIntRelPtr() {          VMInt32RelPtr() {
1186              base   = NULL;              base   = NULL;
1187              offset = 0;              offset = 0;
1188              readonly = false;              readonly = false;
1189          }          }
1190          VMIntRelPtr(const VMRelPtr& data) {          VMInt32RelPtr(const VMRelPtr& data) {
1191              base   = data.base;              base   = data.base;
1192              offset = data.offset;              offset = data.offset;
1193              readonly = false;              readonly = false;
1194          }          }
1195          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }          vmint evalInt() OVERRIDE {
1196          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }              return (vmint)*(int32_t*)&(*(uint8_t**)base)[offset];
1197            }
1198            void assign(vmint i) OVERRIDE {
1199                *(int32_t*)&(*(uint8_t**)base)[offset] = (int32_t)i;
1200            }
1201            bool isAssignable() const OVERRIDE { return !readonly; }
1202        };
1203    
1204        /** @brief Pointer to built-in VM integer variable (of C/C++ type int16_t).
1205         *
1206         * Used for defining built-in 16 bit integer script variables.
1207         *
1208         * @b CAUTION: You may only use this class for pointing to C/C++ variables
1209         * of type "int16_t" (thus being exactly 16 bit in size). If the C/C++ int
1210         * variable you want to reference is 64 bit in size then you @b must use
1211         * VMInt64RelPtr instead! Respectively for a referenced native variable with
1212         * only 8 bit in size you @b must use VMInt8RelPtr instead!
1213         *
1214         * For efficiency reasons the actual native C/C++ int variable is referenced
1215         * by two components here. The actual native int C/C++ variable in memory
1216         * is dereferenced at VM run-time by taking the @c base pointer dereference
1217         * and adding @c offset bytes. This has the advantage that for a large
1218         * number of built-in int variables, only one (or few) base pointer need
1219         * to be re-assigned before running a script, instead of updating each
1220         * built-in variable each time before a script is executed.
1221         *
1222         * Refer to DECLARE_VMINT() for example code.
1223         *
1224         * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr, DECLARE_VMINT()
1225         */
1226        struct VMInt16RelPtr : VMRelPtr, VMIntPtr {
1227            VMInt16RelPtr() {
1228                base   = NULL;
1229                offset = 0;
1230                readonly = false;
1231            }
1232            VMInt16RelPtr(const VMRelPtr& data) {
1233                base   = data.base;
1234                offset = data.offset;
1235                readonly = false;
1236            }
1237            vmint evalInt() OVERRIDE {
1238                return (vmint)*(int16_t*)&(*(uint8_t**)base)[offset];
1239            }
1240            void assign(vmint i) OVERRIDE {
1241                *(int16_t*)&(*(uint8_t**)base)[offset] = (int16_t)i;
1242            }
1243            bool isAssignable() const OVERRIDE { return !readonly; }
1244      };      };
1245    
1246      /** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t).      /** @brief Pointer to built-in VM integer variable (of C/C++ type int8_t).
# Line 521  namespace LinuxSampler { Line 1249  namespace LinuxSampler {
1249       *       *
1250       * @b CAUTION: You may only use this class for pointing to C/C++ variables       * @b CAUTION: You may only use this class for pointing to C/C++ variables
1251       * of type "int8_t" (8 bit integer). If the C/C++ int variable you want to       * of type "int8_t" (8 bit integer). If the C/C++ int variable you want to
1252       * reference is an "int" type (which is 32 bit on most systems), then you       * reference is not exactly 8 bit in size then you @b must respectively use
1253       * @b must use VMIntRelPtr instead!       * either VMInt32RelPtr for native 32 bit variables or VMInt64RelPtrl for
1254         * native 64 bit variables instead!
1255       *       *
1256       * For efficiency reasons the actual native C/C++ int variable is referenced       * For efficiency reasons the actual native C/C++ int variable is referenced
1257       * by two components here. The actual native int C/C++ variable in memory       * by two components here. The actual native int C/C++ variable in memory
# Line 534  namespace LinuxSampler { Line 1263  namespace LinuxSampler {
1263       *       *
1264       * Refer to DECLARE_VMINT() for example code.       * Refer to DECLARE_VMINT() for example code.
1265       *       *
1266       * @see VMIntRelPtr, DECLARE_VMINT()       * @see VMInt16RelPtr, VMIntRel32Ptr, VMIntRel64Ptr, DECLARE_VMINT()
1267       */       */
1268      struct VMInt8RelPtr : VMIntRelPtr {      struct VMInt8RelPtr : VMRelPtr, VMIntPtr {
1269          VMInt8RelPtr() : VMIntRelPtr() {}          VMInt8RelPtr() {
1270          VMInt8RelPtr(const VMRelPtr& data) : VMIntRelPtr(data) {}              base   = NULL;
1271          virtual int evalInt() OVERRIDE {              offset = 0;
1272              return *(uint8_t*)&(*(uint8_t**)base)[offset];              readonly = false;
1273          }          }
1274          virtual void assign(int i) OVERRIDE {          VMInt8RelPtr(const VMRelPtr& data) {
1275              *(uint8_t*)&(*(uint8_t**)base)[offset] = i;              base   = data.base;
1276                offset = data.offset;
1277                readonly = false;
1278            }
1279            vmint evalInt() OVERRIDE {
1280                return (vmint)*(uint8_t*)&(*(uint8_t**)base)[offset];
1281            }
1282            void assign(vmint i) OVERRIDE {
1283                *(uint8_t*)&(*(uint8_t**)base)[offset] = (uint8_t)i;
1284          }          }
1285            bool isAssignable() const OVERRIDE { return !readonly; }
1286      };      };
1287    
1288        /** @brief Pointer to built-in VM integer variable (of C/C++ type vmint).
1289         *
1290         * Use this typedef if the native variable to be pointed to is using the
1291         * typedef vmint. If the native C/C++ variable to be pointed to is using
1292         * another C/C++ type then better use one of VMInt64RelPtr or VMInt32RelPtr
1293         * instead.
1294         */
1295        typedef VMInt64RelPtr VMIntRelPtr;
1296    
1297      #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS      #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
1298      # define COMPILER_DISABLE_OFFSETOF_WARNING                    \      # define COMPILER_DISABLE_OFFSETOF_WARNING                    \
1299          _Pragma("GCC diagnostic push")                            \          _Pragma("GCC diagnostic push")                            \
# Line 559  namespace LinuxSampler { Line 1306  namespace LinuxSampler {
1306      #endif      #endif
1307    
1308      /**      /**
1309       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr       * Convenience macro for initializing VMInt64RelPtr, VMInt32RelPtr,
1310       * structures. Usage example:       * VMInt16RelPtr and VMInt8RelPtr structures. Usage example:
1311       * @code       * @code
1312       * struct Foo {       * struct Foo {
1313       *   uint8_t a; // native representation of a built-in integer script variable       *   uint8_t a; // native representation of a built-in integer script variable
1314       *   int b; // native representation of another built-in integer script variable       *   int64_t b; // native representation of another built-in integer script variable
1315       *   int c; // native representation of another built-in integer script variable       *   int64_t c; // native representation of another built-in integer script variable
1316       *   uint8_t d; // native representation of another built-in integer script variable       *   uint8_t d; // native representation of another built-in integer script variable
1317       * };       * };
1318       *       *
# Line 576  namespace LinuxSampler { Line 1323  namespace LinuxSampler {
1323       * Foo* pFoo;       * Foo* pFoo;
1324       *       *
1325       * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);       * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);
1326       * VMIntRelPtr  varB = DECLARE_VMINT(pFoo, class Foo, b);       * VMInt64RelPtr varB = DECLARE_VMINT(pFoo, class Foo, b);
1327       * VMIntRelPtr  varC = DECLARE_VMINT(pFoo, class Foo, c);       * VMInt64RelPtr varC = DECLARE_VMINT(pFoo, class Foo, c);
1328       * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);       * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);
1329       *       *
1330       * pFoo = &foo1;       * pFoo = &foo1;
# Line 612  namespace LinuxSampler { Line 1359  namespace LinuxSampler {
1359      )                                                             \      )                                                             \
1360    
1361      /**      /**
1362       * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and       * Same as DECLARE_VMINT(), but this one defines the VMInt64RelPtr,
1363       * VMInt8RelPtr structures to be of read-only type. That means the script       * VMInt32RelPtr, VMInt16RelPtr and VMInt8RelPtr structures to be of
1364       * parser will abort any script at parser time if the script is trying to       * read-only type. That means the script parser will abort any script at
1365       * modify such a read-only built-in variable.       * parser time if the script is trying to modify such a read-only built-in
1366         * variable.
1367       *       *
1368       * @b NOTE: this is only intended for built-in read-only variables that       * @b NOTE: this is only intended for built-in read-only variables that
1369       * may change during runtime! If your built-in variable's data is rather       * may change during runtime! If your built-in variable's data is rather
# Line 638  namespace LinuxSampler { Line 1386  namespace LinuxSampler {
1386      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
1387       *       *
1388       * Used for defining built-in integer array script variables (8 bit per       * Used for defining built-in integer array script variables (8 bit per
1389       * array element). Currently there is no support for any other kind of array       * array element). Currently there is no support for any other kind of
1390       * type. So all integer arrays of scripts use 8 bit data types.       * built-in array type. So all built-in integer arrays accessed by scripts
1391         * use 8 bit data types.
1392       */       */
1393      struct VMInt8Array {      struct VMInt8Array {
1394          int8_t* data;          int8_t* data;
1395          int size;          vmint size;
1396          bool readonly; ///< Whether the array data may be modified or just be read.          bool readonly; ///< Whether the array data may be modified or just be read.
1397    
1398          VMInt8Array() : data(NULL), size(0), readonly(false) {}          VMInt8Array() : data(NULL), size(0), readonly(false) {}
# Line 651  namespace LinuxSampler { Line 1400  namespace LinuxSampler {
1400    
1401      /** @brief Virtual machine script variable.      /** @brief Virtual machine script variable.
1402       *       *
1403       * Common interface for all variables accessed in scripts.       * Common interface for all variables accessed in scripts, independent of
1404         * their precise data type.
1405       */       */
1406      class VMVariable : virtual public VMExpr {      class VMVariable : virtual public VMExpr {
1407      public:      public:
# Line 672  namespace LinuxSampler { Line 1422  namespace LinuxSampler {
1422           */           */
1423          virtual void assignExpr(VMExpr* expr) = 0;          virtual void assignExpr(VMExpr* expr) = 0;
1424      };      };
1425        
1426      /** @brief Dynamically executed variable (abstract base class).      /** @brief Dynamically executed variable (abstract base class).
1427       *       *
1428       * Interface for the implementation of a dynamically generated content of       * Interface for the implementation of a dynamically generated content of
# Line 746  namespace LinuxSampler { Line 1496  namespace LinuxSampler {
1496       */       */
1497      class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {      class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
1498      public:      public:
1499            vmfloat unitFactor() const OVERRIDE { return VM_NO_FACTOR; }
1500            StdUnit_t unitType() const OVERRIDE { return VM_NO_UNIT; }
1501            bool isFinal() const OVERRIDE { return false; }
1502      };      };
1503    
1504      /** @brief Dynamically executed variable (of string data type).      /** @brief Dynamically executed variable (of string data type).
# Line 786  namespace LinuxSampler { Line 1539  namespace LinuxSampler {
1539          virtual VMFunction* functionByName(const String& name) = 0;          virtual VMFunction* functionByName(const String& name) = 0;
1540    
1541          /**          /**
1542             * Returns @c true if the passed built-in function is disabled and
1543             * should be ignored by the parser. This method is called by the
1544             * parser on preprocessor level for each built-in function call within
1545             * a script. Accordingly if this method returns @c true, then the
1546             * respective function call is completely filtered out on preprocessor
1547             * level, so that built-in function won't make into the result virtual
1548             * machine representation, nor would expressions of arguments passed to
1549             * that built-in function call be evaluated, nor would any check
1550             * regarding correct usage of the built-in function be performed.
1551             * In other words: a disabled function call ends up as a comment block.
1552             *
1553             * @param fn - built-in function to be checked
1554             * @param ctx - parser context at the position where the built-in
1555             *              function call is located within the script
1556             */
1557            virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0;
1558    
1559            /**
1560           * Returns a variable name indexed map of all built-in script variables           * Returns a variable name indexed map of all built-in script variables
1561           * which point to native "int" scalar (usually 32 bit) variables.           * which point to native "int" scalar (usually 32 bit) variables.
1562           */           */
1563          virtual std::map<String,VMIntRelPtr*> builtInIntVariables() = 0;          virtual std::map<String,VMIntPtr*> builtInIntVariables() = 0;
1564    
1565          /**          /**
1566           * Returns a variable name indexed map of all built-in script integer           * Returns a variable name indexed map of all built-in script integer
# Line 799  namespace LinuxSampler { Line 1570  namespace LinuxSampler {
1570    
1571          /**          /**
1572           * Returns a variable name indexed map of all built-in constant script           * Returns a variable name indexed map of all built-in constant script
1573           * variables, which never change their value at runtime.           * variables of integer type, which never change their value at runtime.
1574           */           */
1575          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,vmint> builtInConstIntVariables() = 0;
1576    
1577            /**
1578             * Returns a variable name indexed map of all built-in constant script
1579             * variables of real number (floating point) type, which never change
1580             * their value at runtime.
1581             */
1582            virtual std::map<String,vmfloat> builtInConstRealVariables() = 0;
1583    
1584          /**          /**
1585           * Returns a variable name indexed map of all built-in dynamic variables,           * Returns a variable name indexed map of all built-in dynamic variables,
# Line 850  namespace LinuxSampler { Line 1628  namespace LinuxSampler {
1628           *           *
1629           * @see ScriptVM::exec()           * @see ScriptVM::exec()
1630           */           */
1631          virtual int suspensionTimeMicroseconds() const = 0;          virtual vmint suspensionTimeMicroseconds() const = 0;
1632    
1633          /**          /**
1634           * Causes all polyphonic variables to be reset to zero values. A           * Causes all polyphonic variables to be reset to zero values. A
# Line 879  namespace LinuxSampler { Line 1657  namespace LinuxSampler {
1657           * instance.           * instance.
1658           */           */
1659          virtual void signalAbort() = 0;          virtual void signalAbort() = 0;
1660    
1661            /**
1662             * Copies the current entire execution state from this object to the
1663             * given object. So this can be used to "fork" a new script thread which
1664             * then may run independently with its own polyphonic data for instance.
1665             */
1666            virtual void forkTo(VMExecContext* ectx) const = 0;
1667    
1668            /**
1669             * In case the script called the built-in exit() function and passed a
1670             * value as argument to the exit() function, then this method returns
1671             * the value that had been passed as argument to the exit() function.
1672             * Otherwise if the exit() function has not been called by the script
1673             * or no argument had been passed to the exit() function, then this
1674             * method returns NULL instead.
1675             *
1676             * Currently this is only used for automated test cases against the
1677             * script engine, which return some kind of value in the individual
1678             * test case scripts to check their behaviour in automated way. There
1679             * is no purpose for this mechanism in production use. Accordingly this
1680             * exit result value is @b always completely ignored by the sampler
1681             * engines.
1682             *
1683             * Officially the built-in exit() function does not expect any arguments
1684             * to be passed to its function call, and by default this feature is
1685             * hence disabled and will yield in a parser error unless
1686             * ScriptVM::setExitResultEnabled() was explicitly set.
1687             *
1688             * @see ScriptVM::setExitResultEnabled()
1689             */
1690            virtual VMExpr* exitResult() = 0;
1691      };      };
1692    
1693      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 910  namespace LinuxSampler { Line 1719  namespace LinuxSampler {
1719      };      };
1720    
1721      /**      /**
1722         * Reflects the precise position and span of a specific code block within
1723         * a script. This is currently only used for the locations of commented
1724         * code blocks due to preprocessor statements, and for parser errors and
1725         * parser warnings.
1726         *
1727         * @see ParserIssue for code locations of parser errors and parser warnings
1728         *
1729         * @see VMParserContext::preprocessorComments() for locations of code which
1730         *      have been filtered out by preprocessor statements
1731         */
1732        struct CodeBlock {
1733            int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
1734            int lastLine; ///< The last line number of this code block within the script.
1735            int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
1736            int lastColumn; ///< The last column of this code block within the script.
1737        };
1738    
1739        /**
1740       * Encapsulates a noteworty parser issue. This encompasses the type of the       * Encapsulates a noteworty parser issue. This encompasses the type of the
1741       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
1742       * explanation text of the error or warning and the location of the       * explanation text of the error or warning and the location of the
# Line 917  namespace LinuxSampler { Line 1744  namespace LinuxSampler {
1744       *       *
1745       * @see VMSourceToken for processing syntax highlighting instead.       * @see VMSourceToken for processing syntax highlighting instead.
1746       */       */
1747      struct ParserIssue {      struct ParserIssue : CodeBlock {
1748          String txt; ///< Human readable explanation text of the parser issue.          String txt; ///< Human readable explanation text of the parser issue.
         int firstLine; ///< The first line number within the script where this issue was encountered (indexed with 1 being the very first line).  
         int lastLine; ///< The last line number within the script where this issue was encountered.  
         int firstColumn; ///< The first column within the script where this issue was encountered (indexed with 1 being the very first column).  
         int lastColumn; ///< The last column within the script where this issue was encountered.  
1749          ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning.          ParserIssueType_t type; ///< Whether this issue is either a parser error or just a parser warning.
1750    
1751          /**          /**
# Line 962  namespace LinuxSampler { Line 1785  namespace LinuxSampler {
1785              case EMPTY_EXPR: return "empty";              case EMPTY_EXPR: return "empty";
1786              case INT_EXPR: return "integer";              case INT_EXPR: return "integer";
1787              case INT_ARR_EXPR: return "integer array";              case INT_ARR_EXPR: return "integer array";
1788                case REAL_EXPR: return "real number";
1789                case REAL_ARR_EXPR: return "real number array";
1790              case STRING_EXPR: return "string";              case STRING_EXPR: return "string";
1791              case STRING_ARR_EXPR: return "string array";              case STRING_ARR_EXPR: return "string array";
1792          }          }
1793          return "invalid";          return "invalid";
1794      }      }
1795    
1796        /**
1797         * Returns @c true in case the passed data type is some array data type.
1798         */
1799        inline bool isArray(const ExprType_t& type) {
1800            return type == INT_ARR_EXPR || type == REAL_ARR_EXPR ||
1801                   type == STRING_ARR_EXPR;
1802        }
1803    
1804        /**
1805         * Returns @c true in case the passed data type is some scalar number type
1806         * (i.e. not an array and not a string).
1807         */
1808        inline bool isNumber(const ExprType_t& type) {
1809            return type == INT_EXPR || type == REAL_EXPR;
1810        }
1811    
1812        /**
1813         * Convenience function used for converting an StdUnit_t constant to a
1814         * string, i.e. for generating error message by the parser.
1815         */
1816        inline String unitTypeStr(const StdUnit_t& type) {
1817            switch (type) {
1818                case VM_NO_UNIT: return "none";
1819                case VM_SECOND: return "seconds";
1820                case VM_HERTZ: return "Hz";
1821                case VM_BEL: return "Bel";
1822            }
1823            return "invalid";
1824        }
1825    
1826      /** @brief Virtual machine representation of a script.      /** @brief Virtual machine representation of a script.
1827       *       *
1828       * An instance of this abstract base class represents a parsed script,       * An instance of this abstract base class represents a parsed script,
# Line 1002  namespace LinuxSampler { Line 1857  namespace LinuxSampler {
1857          virtual std::vector<ParserIssue> warnings() const = 0;          virtual std::vector<ParserIssue> warnings() const = 0;
1858    
1859          /**          /**
1860             * Returns all code blocks of the script which were filtered out by the
1861             * preprocessor.
1862             */
1863            virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1864    
1865            /**
1866           * Returns the translated virtual machine representation of an event           * Returns the translated virtual machine representation of an event
1867           * handler block (i.e. "on note ... end on" code block) within the           * handler block (i.e. "on note ... end on" code block) within the
1868           * parsed script. This translated representation of the event handler           * parsed script. This translated representation of the event handler
# Line 1061  namespace LinuxSampler { Line 1922  namespace LinuxSampler {
1922          bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").          bool isStringLiteral() const; ///< Returns true in case this source token represents a string literal (i.e. "Some text").
1923          bool isComment() const; ///< Returns true in case this source token represents a source code comment.          bool isComment() const; ///< Returns true in case this source token represents a source code comment.
1924          bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.          bool isPreprocessor() const; ///< Returns true in case this source token represents a preprocessor statement.
1925            bool isMetricPrefix() const;
1926            bool isStdUnit() const;
1927          bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.          bool isOther() const; ///< Returns true in case this source token represents anything else not covered by the token types mentioned above.
1928    
1929          // extended types          // extended types
1930          bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").          bool isIntegerVariable() const; ///< Returns true in case this source token represents an integer variable name (i.e. "$someIntVariable").
1931            bool isRealVariable() const; ///< Returns true in case this source token represents a floating point variable name (i.e. "~someRealVariable").
1932          bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").          bool isStringVariable() const; ///< Returns true in case this source token represents an string variable name (i.e. "\@someStringVariable").
1933          bool isArrayVariable() const; ///< Returns true in case this source token represents an array variable name (i.e. "%someArryVariable").          bool isIntArrayVariable() const; ///< Returns true in case this source token represents an integer array variable name (i.e. "%someArrayVariable").
1934            bool isRealArrayVariable() const; ///< Returns true in case this source token represents a real number array variable name (i.e. "?someArrayVariable").
1935            bool isArrayVariable() const DEPRECATED_API; ///< Returns true in case this source token represents an @b integer array variable name (i.e. "%someArrayVariable"). @deprecated This method will be removed, use isIntArrayVariable() instead.
1936          bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").          bool isEventHandlerName() const; ///< Returns true in case this source token represents an event handler name (i.e. "note", "release", "controller").
1937    
1938          VMSourceToken& operator=(const VMSourceToken& other);          VMSourceToken& operator=(const VMSourceToken& other);
Legend:
Removed from v.3277  
changed lines
  Added in v.3690
  ViewVC Help
Powered by ViewVC