/[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 3572 by schoenebeck, Sat Aug 24 09:18:57 2019 UTC revision 3573 by schoenebeck, Tue Aug 27 21:36:53 2019 UTC
# Line 37  namespace LinuxSampler { Line 37  namespace LinuxSampler {
37      typedef uint64_t vmuint;      typedef uint64_t vmuint;
38    
39      /**      /**
40       * Native data type used internally by the script engine for floating point       * Native data type used by the script engine both internally for floating
41       * data types. This type is currently not exposed to scripts.       * point data, as well as for all @c real data types used by scripts (i.e.
42         * for all ~foo variables in NKSP scripts).
43       */       */
44      typedef float vmfloat;      typedef float vmfloat;
45    
# Line 64  namespace LinuxSampler { Line 65  namespace LinuxSampler {
65          INT_ARR_EXPR, ///< integer array expression          INT_ARR_EXPR, ///< integer array expression
66          STRING_EXPR, ///< string expression          STRING_EXPR, ///< string expression
67          STRING_ARR_EXPR, ///< string array expression          STRING_ARR_EXPR, ///< string array expression
68            REAL_EXPR, ///< floating point (scalar) expression
69            REAL_ARR_EXPR, ///< floating point array expression
70      };      };
71    
72      /** @brief Result flags of a script statement or script function call.      /** @brief Result flags of a script statement or script function call.
# Line 152  namespace LinuxSampler { Line 155  namespace LinuxSampler {
155    
156      // just symbol prototyping      // just symbol prototyping
157      class VMIntExpr;      class VMIntExpr;
158        class VMRealExpr;
159      class VMStringExpr;      class VMStringExpr;
160        class VMScalarNumberExpr;
161      class VMIntArrayExpr;      class VMIntArrayExpr;
162        class VMRealArrayExpr;
163      class VMStringArrayExpr;      class VMStringArrayExpr;
164      class VMParserContext;      class VMParserContext;
165    
# Line 254  namespace LinuxSampler { Line 260  namespace LinuxSampler {
260           * if this expression is i.e. actually a string expression like "12",           * if this expression is i.e. actually a string expression like "12",
261           * calling asInt() will @b not cast that numerical string expression to           * calling asInt() will @b not cast that numerical string expression to
262           * an integer expression 12 for you, instead this method will simply           * an integer expression 12 for you, instead this method will simply
263           * return NULL!           * return NULL! Same applies if this expression is actually a real
264             * number expression: asInt() would return NULL in that case as well.
265           *           *
266           * @see exprType()           * @see exprType(), asReal(), asScalarNumberExpr()
267           */           */
268          VMIntExpr* asInt() const;          VMIntExpr* asInt() const;
269    
270          /**          /**
271             * In case this expression is a real number (floating point) expression,
272             * then this method returns a casted pointer to that VMRealExpr object.
273             * It returns NULL if this expression is not a real number expression.
274             *
275             * @b Note: type casting performed by this method is strict! That means
276             * if this expression is i.e. actually a string expression like "12",
277             * calling asReal() will @b not cast that numerical string expression to
278             * a real number expression 12.0 for you, instead this method will
279             * simply return NULL! Same applies if this expression is actually an
280             * integer expression: asReal() would return NULL in that case as well.
281             *
282             * @see exprType(), asInt(), asScalarNumberExpr()
283             */
284            VMRealExpr* asReal() const;
285    
286            /**
287             * In case this expression is a scalar number expression, that is either
288             * an integer (scalar) expression or a real number (floating point
289             * scalar) expression, then this method returns a casted pointer to that
290             * VMScalarNumberExpr base class object. It returns NULL if this
291             * expression is neither an integer (scalar), nor a real number (scalar)
292             * expression.
293             *
294             * Since the methods asInt() and asReal() are very strict, this method
295             * is provided as convenience access in case only very general
296             * information (e.g. which standard measurement unit is being used or
297             * whether final operator being effective to this expression) is
298             * intended to be retrieved of this scalar number expression independent
299             * from whether this expression is actually an integer or a real number
300             * expression.
301             *
302             * @see exprType(), asInt(), asReal()
303             */
304            VMScalarNumberExpr* asScalarNumberExpr() const;
305    
306            /**
307           * In case this expression is a string expression, then this method           * In case this expression is a string expression, then this method
308           * returns a casted pointer to that VMStringExpr object. It returns NULL           * returns a casted pointer to that VMStringExpr object. It returns NULL
309           * if this expression is not a string expression.           * if this expression is not a string expression.
# Line 281  namespace LinuxSampler { Line 324  namespace LinuxSampler {
324           * returns NULL if this expression is not an integer array expression.           * returns NULL if this expression is not an integer array expression.
325           *           *
326           * @b Note: type casting performed by this method is strict! That means           * @b Note: type casting performed by this method is strict! That means
327           * if this expression is i.e. an integer expression or a string           * if this expression is i.e. an integer scalar expression, a real
328           * expression, calling asIntArray() will @b not cast those scalar           * number expression or a string expression, calling asIntArray() will
329           * expressions to an array expression for you, instead this method will           * @b not cast those expressions to an integer array expression for you,
330           * simply return NULL!           * instead this method will simply return NULL!
331           *           *
332           * @b Note: this method is currently, and in contrast to its other           * @b Note: this method is currently, and in contrast to its other
333           * counter parts, declared as virtual method. Some deriving classes are           * counter parts, declared as virtual method. Some deriving classes are
# Line 299  namespace LinuxSampler { Line 342  namespace LinuxSampler {
342          virtual VMIntArrayExpr* asIntArray() const;          virtual VMIntArrayExpr* asIntArray() const;
343    
344          /**          /**
345             * In case this expression is a real number (floating point) array
346             * expression, then this method returns a casted pointer to that
347             * VMRealArrayExpr object. It returns NULL if this expression is not a
348             * real number array expression.
349             *
350             * @b Note: type casting performed by this method is strict! That means
351             * if this expression is i.e. a real number scalar expression, an
352             * integer expression or a string expression, calling asRealArray() will
353             * @b not cast those scalar expressions to a real number array
354             * expression for you, instead this method will simply return NULL!
355             *
356             * @b Note: this method is currently, and in contrast to its other
357             * counter parts, declared as virtual method. Some deriving classes are
358             * currently using this to override this default implementation in order
359             * to implement an "evaluate now as real number array" behavior. This
360             * has efficiency reasons, however this also currently makes this part
361             * of the API less clean and should thus be addressed in future with
362             * appropriate changes to the API.
363             *
364             * @see exprType()
365             */
366            virtual VMRealArrayExpr* asRealArray() const;
367    
368            /**
369           * Returns true in case this expression can be considered to be a           * Returns true in case this expression can be considered to be a
370           * constant expression. A constant expression will retain the same           * constant expression. A constant expression will retain the same
371           * value throughout the entire life time of a script and the           * value throughout the entire life time of a script and the
# Line 329  namespace LinuxSampler { Line 396  namespace LinuxSampler {
396          bool isModifyable() const;          bool isModifyable() const;
397      };      };
398    
399        /** @brief Virtual machine scalar number expression
400         *
401         * This is the abstract base class for integer (scalar) expressions and
402         * real number (floating point scalar) expressions of scripts.
403         */
404        class VMScalarNumberExpr : virtual public VMExpr, virtual public VMUnit {
405        public:
406            /**
407             * Returns @c true if the value of this expression should be applied
408             * as final value to the respective destination synthesis chain
409             * parameter.
410             *
411             * This property is somewhat special and dedicated for the purpose of
412             * this expression's (integer or real number) value to be applied as
413             * parameter to the synthesis chain of the sampler (i.e. for altering a
414             * filter cutoff frequency). Now historically and by default all values
415             * of scripts are applied relatively to the sampler's synthesis chain,
416             * that is the synthesis parameter value of a script is multiplied
417             * against other sources for the same synthesis parameter (i.e. an LFO
418             * or a dedicated MIDI controller either hard wired in the engine or
419             * defined by the instrument patch). So by default the resulting actual
420             * final synthesis parameter is a combination of all these sources. This
421             * has the advantage that it creates a very living and dynamic overall
422             * sound.
423             *
424             * However sometimes there are requirements by script authors where this
425             * is not what you want. Therefore the NKSP script engine added a
426             * language extension by prefixing a value in scripts with a @c !
427             * character the value will be defined as being the "final" value of the
428             * destination synthesis parameter, so that causes this value to be
429             * applied exclusively, and the values of all other sources are thus
430             * entirely ignored by the sampler's synthesis core as long as this
431             * value is assigned by the script engine as "final" value for the
432             * requested synthesis parameter.
433             */
434            virtual bool isFinal() const = 0;
435        };
436    
437      /** @brief Virtual machine integer expression      /** @brief Virtual machine integer expression
438       *       *
439       * 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 336  namespace LinuxSampler { Line 441  namespace LinuxSampler {
441       * abstract method evalInt() to return the actual integer result value of       * abstract method evalInt() to return the actual integer result value of
442       * the expression.       * the expression.
443       */       */
444      class VMIntExpr : virtual public VMExpr, virtual public VMUnit {      class VMIntExpr : virtual public VMScalarNumberExpr {
445      public:      public:
446          /**          /**
447           * Returns the result of this expression as integer (scalar) value.           * Returns the result of this expression as integer (scalar) value.
# Line 365  namespace LinuxSampler { Line 470  namespace LinuxSampler {
470           * Returns always INT_EXPR for instances of this class.           * Returns always INT_EXPR for instances of this class.
471           */           */
472          ExprType_t exprType() const OVERRIDE { return INT_EXPR; }          ExprType_t exprType() const OVERRIDE { return INT_EXPR; }
473        };
474    
475        /** @brief Virtual machine real number (floating point scalar) expression
476         *
477         * This is the abstract base class for all expressions inside scripts which
478         * evaluate to a real number (floating point scalar) value. Deriving classes
479         * implement the abstract method evalReal() to return the actual floating
480         * point result value of the expression.
481         */
482        class VMRealExpr : virtual public VMScalarNumberExpr {
483        public:
484          /**          /**
485           * Returns @c true if the value of this expression should be applied           * Returns the result of this expression as real number (floating point
486           * as final value to the respective destination synthesis chain           * scalar) value. This abstract method must be implemented by deriving
487           * parameter.           * classes.
488           *           */
489           * This property is somewhat special and dedicated for the purpose of          virtual vmfloat evalReal() = 0;
490           * this expression's integer value to be applied as parameter to the  
491           * synthesis chain of the sampler (i.e. for altering a filter cutoff          /**
492           * frequency). Now historically and by default all values of scripts are           * Returns the result of this expression as real number (floating point
493           * applied relatively to the sampler's synthesis chain, that is the           * scalar) value and thus behaves similar to the previous method,
494           * synthesis parameter value of a script is multiplied against other           * however this overridden method automatically takes unit prefixes into
495           * sources for the same synthesis parameter (i.e. an LFO or a dedicated           * account and returns a value corresponding to the expected given unit
496           * MIDI controller either hard wired in the engine or defined by the           * @a prefix.
          * instrument patch). So by default the resulting actual final synthesis  
          * parameter is a combination of all these sources. This has the  
          * advantage that it creates a very living and dynamic overall sound.  
497           *           *
498           * However sometimes there are requirements by script authors where this           * @param prefix - default measurement unit prefix expected by caller
          * is not what you want. Therefore the NKSP script engine added a  
          * language extension by prefixing a value in scripts with a @c !  
          * character the value will be defined as being the "final" value of the  
          * destination synthesis parameter, so that causes this value to be  
          * applied exclusively, and the values of all other sources are thus  
          * entirely ignored by the sampler's synthesis core as long as this  
          * value is assigned by the script engine as "final" value for the  
          * requested synthesis parameter.  
499           */           */
500          virtual bool isFinal() const = 0;          vmfloat evalReal(MetricPrefix_t prefix);
501    
502            /**
503             * This method behaves like the previous method, just that it takes
504             * a default measurement prefix with two elements (i.e. "milli cents"
505             * for tuning).
506             */
507            vmfloat evalReal(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
508    
509            /**
510             * Returns always REAL_EXPR for instances of this class.
511             */
512            ExprType_t exprType() const OVERRIDE { return REAL_EXPR; }
513      };      };
514    
515      /** @brief Virtual machine string expression      /** @brief Virtual machine string expression
# Line 465  namespace LinuxSampler { Line 581  namespace LinuxSampler {
581          ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; }          ExprType_t exprType() const OVERRIDE { return INT_ARR_EXPR; }
582      };      };
583    
584        /** @brief Virtual Machine Real Number Array Expression
585         *
586         * This is the abstract base class for all expressions inside scripts which
587         * evaluate to an array of real numbers (floating point values). Deriving
588         * classes implement the abstract methods arraySize(), evalRealElement() and
589         * assignRealElement() to access the array's individual real numbers.
590         */
591        class VMRealArrayExpr : virtual public VMArrayExpr {
592        public:
593            /**
594             * Returns the (scalar) real mumber (floating point value) of the array
595             * element given by element index @a i.
596             *
597             * @param i - array element index (must be between 0 .. arraySize() - 1)
598             */
599            virtual vmfloat evalRealElement(vmuint i) = 0;
600    
601            /**
602             * Changes the current value of an element (given by array element
603             * index @a i) of this real number array.
604             *
605             * @param i - array element index (must be between 0 .. arraySize() - 1)
606             * @param value - new real number value to be assigned to that array element
607             */
608            virtual void assignRealElement(vmuint i, vmfloat value) = 0;
609    
610            /**
611             * Returns always REAL_ARR_EXPR for instances of this class.
612             */
613            ExprType_t exprType() const OVERRIDE { return REAL_ARR_EXPR; }
614        };
615    
616      /** @brief Arguments (parameters) for being passed to a built-in script function.      /** @brief Arguments (parameters) for being passed to a built-in script function.
617       *       *
618       * 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 961  namespace LinuxSampler { Line 1109  namespace LinuxSampler {
1109      /** @brief Built-in VM 8 bit integer array variable.      /** @brief Built-in VM 8 bit integer array variable.
1110       *       *
1111       * Used for defining built-in integer array script variables (8 bit per       * Used for defining built-in integer array script variables (8 bit per
1112       * 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
1113       * 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
1114         * use 8 bit data types.
1115       */       */
1116      struct VMInt8Array {      struct VMInt8Array {
1117          int8_t* data;          int8_t* data;
# Line 974  namespace LinuxSampler { Line 1123  namespace LinuxSampler {
1123    
1124      /** @brief Virtual machine script variable.      /** @brief Virtual machine script variable.
1125       *       *
1126       * Common interface for all variables accessed in scripts.       * Common interface for all variables accessed in scripts, independent of
1127         * their precise data type.
1128       */       */
1129      class VMVariable : virtual public VMExpr {      class VMVariable : virtual public VMExpr {
1130      public:      public:
# Line 995  namespace LinuxSampler { Line 1145  namespace LinuxSampler {
1145           */           */
1146          virtual void assignExpr(VMExpr* expr) = 0;          virtual void assignExpr(VMExpr* expr) = 0;
1147      };      };
1148        
1149      /** @brief Dynamically executed variable (abstract base class).      /** @brief Dynamically executed variable (abstract base class).
1150       *       *
1151       * Interface for the implementation of a dynamically generated content of       * Interface for the implementation of a dynamically generated content of
# Line 1351  namespace LinuxSampler { Line 1501  namespace LinuxSampler {
1501              case EMPTY_EXPR: return "empty";              case EMPTY_EXPR: return "empty";
1502              case INT_EXPR: return "integer";              case INT_EXPR: return "integer";
1503              case INT_ARR_EXPR: return "integer array";              case INT_ARR_EXPR: return "integer array";
1504                case REAL_EXPR: return "real number";
1505                case REAL_ARR_EXPR: return "real number array";
1506              case STRING_EXPR: return "string";              case STRING_EXPR: return "string";
1507              case STRING_ARR_EXPR: return "string array";              case STRING_ARR_EXPR: return "string array";
1508          }          }
# Line 1358  namespace LinuxSampler { Line 1510  namespace LinuxSampler {
1510      }      }
1511    
1512      /**      /**
1513         * Convenience function used for retrieving the data type of a script
1514         * variable name being passed to this function.
1515         *
1516         * @param name - some script variable name (e.g. "$foo")
1517         * @return variable's data type (e.g. INT_EXPR for example above)
1518         */
1519        inline ExprType_t exprTypeOfVarName(const String& name) {
1520            if (name.empty()) return (ExprType_t) -1;
1521            const char prefix = name[0];
1522            switch (prefix) {
1523                case '$': return INT_EXPR;
1524                case '%': return INT_ARR_EXPR;
1525                case '~': return REAL_EXPR;
1526                case '?': return REAL_ARR_EXPR;
1527                case '@': return STRING_EXPR;
1528                case '!': return STRING_ARR_EXPR;
1529            }
1530            return (ExprType_t) -1;
1531        }
1532    
1533        /**
1534         * Returns @c true in case the passed data type is some array data type.
1535         */
1536        inline bool isArray(const ExprType_t& type) {
1537            return type == INT_ARR_EXPR || type == REAL_ARR_EXPR ||
1538                   type == STRING_ARR_EXPR;
1539        }
1540    
1541        /**
1542         * Returns @c true in case the passed data type is some scalar number type
1543         * (i.e. not an array and not a string).
1544         */
1545        inline bool isScalarNumber(const ExprType_t& type) {
1546            return type == INT_EXPR || type == REAL_EXPR;
1547        }
1548    
1549        /**
1550       * Convenience function used for converting an StdUnit_t constant to a       * Convenience function used for converting an StdUnit_t constant to a
1551       * string, i.e. for generating error message by the parser.       * string, i.e. for generating error message by the parser.
1552       */       */
# Line 1476  namespace LinuxSampler { Line 1665  namespace LinuxSampler {
1665    
1666          // extended types          // extended types
1667          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").
1668            bool isRealVariable() const; ///< Returns true in case this source token represents a floating point variable name (i.e. "~someRealVariable").
1669          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").
1670          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").
1671            bool isRealArrayVariable() const; ///< Returns true in case this source token represents a real number array variable name (i.e. "?someArrayVariable").
1672            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.
1673          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").
1674    
1675          VMSourceToken& operator=(const VMSourceToken& other);          VMSourceToken& operator=(const VMSourceToken& other);
Legend:
Removed from v.3572  
changed lines
  Added in v.3573
  ViewVC Help
Powered by ViewVC