/[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 3561 by schoenebeck, Fri Aug 23 11:44:00 2019 UTC
# Line 1  Line 1 
1  /*  /*
2   * Copyright (c) 2014-2017 Christian Schoenebeck   * Copyright (c) 2014-2019 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 22  Line 23 
23  namespace LinuxSampler {  namespace LinuxSampler {
24    
25      /**      /**
26         * Native data type used by the script engine both internally, as well as
27         * for all integer data types used by scripts (i.e. for all $foo variables
28         * in NKSP scripts). Note that this is different from the original KSP which
29         * is limited to 32 bit for integer variables in KSP scripts.
30         */
31        typedef int64_t vmint;
32    
33        /**
34         * Native data type used internally by the script engine for all unsigned
35         * integer types. This type is currently not exposed to scripts.
36         */
37        typedef uint64_t vmuint;
38    
39        /**
40         * Native data type used internally by the script engine for floating point
41         * data types. This type is currently not exposed to scripts.
42         */
43        typedef float vmfloat;
44    
45        /**
46       * Identifies the type of a noteworthy issue identified by the script       * Identifies the type of a noteworthy issue identified by the script
47       * parser. That's either a parser error or parser warning.       * parser. That's either a parser error or parser warning.
48       */       */
# Line 80  namespace LinuxSampler { Line 101  namespace LinuxSampler {
101       *       *
102       * Identifies one of the possible event handler callback types defined by       * Identifies one of the possible event handler callback types defined by
103       * the NKSP script language.       * the NKSP script language.
104         *
105         * IMPORTANT: this type is forced to be emitted as int32_t type ATM, because
106         * that's the native size expected by the built-in instrument script
107         * variable bindings (see occurrences of VMInt32RelPtr and DECLARE_VMINT
108         * respectively. A native type mismatch between the two could lead to
109         * undefined behavior! Background: By definition the C/C++ compiler is free
110         * to choose a bit size for individual enums which it might find
111         * appropriate, which is usually decided by the compiler according to the
112         * biggest enum constant value defined (in practice it is usually 32 bit).
113       */       */
114      enum VMEventHandlerType_t {      enum VMEventHandlerType_t : int32_t {
115          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.
116          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.
117          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.
118          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.
119      };      };
120    
121        /**
122         * All metric unit prefixes (actually just scale factors) supported by this
123         * script engine.
124         */
125        enum MetricPrefix_t {
126            VM_NO_PREFIX = 0, ///< = 1
127            VM_KILO,          ///< = 10^3, short 'k'
128            VM_HECTO,         ///< = 10^2, short 'h'
129            VM_DECA,          ///< = 10, short 'da'
130            VM_DECI,          ///< = 10^-1, short 'd'
131            VM_CENTI,         ///< = 10^-2, short 'c' (this is also used for tuning "cents")
132            VM_MILLI,         ///< = 10^-3, short 'm'
133            VM_MICRO,         ///< = 10^-6, short 'u'
134        };
135    
136        /**
137         * All measurement unit types supported by this script engine.
138         *
139         * @e Note: there is no standard unit "cents" here (for pitch/tuning), use
140         * @c VM_CENTI for the latter instad. That's because the commonly cited
141         * "cents" unit is actually no measurement unit type but rather a metric
142         * unit prefix.
143         *
144         * @see MetricPrefix_t
145         */
146        enum StdUnit_t {
147            VM_NO_UNIT = 0, ///< No unit used, the number is just an abstract number.
148            VM_SECOND,      ///< Measuring time.
149            VM_HERTZ,       ///< Measuring frequency.
150            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).
151        };
152    
153      // just symbol prototyping      // just symbol prototyping
154      class VMIntExpr;      class VMIntExpr;
155      class VMStringExpr;      class VMStringExpr;
156      class VMIntArrayExpr;      class VMIntArrayExpr;
157      class VMStringArrayExpr;      class VMStringArrayExpr;
158        class VMParserContext;
159    
160        /** @brief Virtual machine measuring unit.
161         *
162         * Abstract base class representing standard measurement units throughout
163         * the script engine. These might be i.e. "dB" (deci Bel) for loudness,
164         * "Hz" (Hertz) for frequencies or "s" for "seconds".
165         *
166         * Originally the script engine only supported abstract integer values for
167         * controlling any synthesis parameter or built-in function argument or
168         * variable. Under certain situations it makes sense though for an
169         * instrument script author to provide values in real, standard measurement
170         * units, for example setting the frequency of some LFO directly to "20Hz".
171         * Hence support for standard units in scripts was added as an extension to
172         * the NKSP script engine.
173         */
174        class VMUnit {
175        public:
176            /**
177             * Returns the metric prefix of this unit. A metric prefix essentially
178             * is just a mathematical scale factor that should be applied to the
179             * number associated with the measurement unit. Usually a unit either
180             * has exactly none or one prefix, but note that there might also be
181             * units with more than one prefix, for example mdB (mili deci bel)
182             * is used sometimes which has two prefixes. This is an exception though
183             * and more than two prefixes is currently not supported by the script
184             * engine.
185             *
186             * Start iterating over the prefixes of this unit by passing @c 0 as
187             * argument to this method. The prefixes are terminated with return
188             * value VM_NO_PREFIX being always the last element.
189             *
190             * @param i - index of prefix
191             * @returns prefix of requested index or VM_NO_PREFIX otherwise
192             * @see unitFactor()
193             */
194            virtual MetricPrefix_t unitPrefix(vmuint i) const = 0;
195    
196            /**
197             * Conveniently returns the final mathematical factor that should be
198             * multiplied against the number associated with this unit. This factor
199             * results from the sequence of metric prefixes of this unit.
200             *
201             * @see unitPrefix()
202             */
203            vmfloat unitFactor() const;
204    
205            /**
206             * This is the actual fundamental measuring unit base type of this unit,
207             * which might be either Hertz, second or Bel.
208             *
209             * @returns standard unit type identifier or VM_NO_UNIT if no unit used
210             */
211            virtual StdUnit_t unitType() const = 0;
212    
213            /**
214             * Returns the actual mathematical factor represented by the passed
215             * @a prefix argument.
216             */
217            static vmfloat unitFactor(MetricPrefix_t prefix);
218    
219            /**
220             * Returns the actual mathematical factor represented by the passed
221             * two @a prefix1 and @a prefix2 arguments.
222             */
223            static vmfloat unitFactor(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
224        };
225    
226      /** @brief Virtual machine expression      /** @brief Virtual machine expression
227       *       *
# Line 207  namespace LinuxSampler { Line 336  namespace LinuxSampler {
336       * abstract method evalInt() to return the actual integer result value of       * abstract method evalInt() to return the actual integer result value of
337       * the expression.       * the expression.
338       */       */
339      class VMIntExpr : virtual public VMExpr {      class VMIntExpr : virtual public VMExpr, virtual public VMUnit {
340      public:      public:
341          /**          /**
342           * Returns the result of this expression as integer (scalar) value.           * Returns the result of this expression as integer (scalar) value.
343           * This abstract method must be implemented by deriving classes.           * This abstract method must be implemented by deriving classes.
344           */           */
345          virtual int evalInt() = 0;          virtual vmint evalInt() = 0;
346    
347            /**
348             * Returns the result of this expression as integer (scalar) value and
349             * thus behaves similar to the previous method, however this overridden
350             * method automatically takes unit prefixes into account and returns a
351             * value corresponding to the expected given unit @a prefix.
352             *
353             * @param prefix - default measurement unit prefix expected by caller
354             */
355            vmint evalInt(MetricPrefix_t prefix);
356    
357            /**
358             * This method behaves like the previous method, just that it takes
359             * a default measurement prefix with two elements (i.e. "milli cents"
360             * for tuning).
361             */
362            vmint evalInt(MetricPrefix_t prefix1, MetricPrefix_t prefix2);
363    
364          /**          /**
365           * Returns always INT_EXPR for instances of this class.           * Returns always INT_EXPR for instances of this class.
366           */           */
367          ExprType_t exprType() const OVERRIDE { return INT_EXPR; }          ExprType_t exprType() const OVERRIDE { return INT_EXPR; }
368    
369            /**
370             * Returns @c true if the value of this expression should be applied
371             * as final value to the respective destination synthesis chain
372             * parameter.
373             *
374             * This property is somewhat special and dedicated for the purpose of
375             * this expression's integer value to be applied as parameter to the
376             * synthesis chain of the sampler (i.e. for altering a filter cutoff
377             * frequency). Now historically and by default all values of scripts are
378             * applied relatively to the sampler's synthesis chain, that is the
379             * synthesis parameter value of a script is multiplied against other
380             * sources for the same synthesis parameter (i.e. an LFO or a dedicated
381             * MIDI controller either hard wired in the engine or defined by the
382             * instrument patch). So by default the resulting actual final synthesis
383             * parameter is a combination of all these sources. This has the
384             * advantage that it creates a very living and dynamic overall sound.
385             *
386             * However sometimes there are requirements by script authors where this
387             * is not what you want. Therefore the NKSP script engine added a
388             * language extension by prefixing a value in scripts with a @c !
389             * character the value will be defined as being the "final" value of the
390             * destination synthesis parameter, so that causes this value to be
391             * applied exclusively, and the values of all other sources are thus
392             * entirely ignored by the sampler's synthesis core as long as this
393             * value is assigned by the script engine as "final" value for the
394             * requested synthesis parameter.
395             */
396            virtual bool isFinal() const = 0;
397      };      };
398    
399      /** @brief Virtual machine string expression      /** @brief Virtual machine string expression
# Line 255  namespace LinuxSampler { Line 430  namespace LinuxSampler {
430           * Returns amount of elements in this array. This abstract method must           * Returns amount of elements in this array. This abstract method must
431           * be implemented by deriving classes.           * be implemented by deriving classes.
432           */           */
433          virtual int arraySize() const = 0;          virtual vmint arraySize() const = 0;
434      };      };
435    
436      /** @brief Virtual Machine Integer Array Expression      /** @brief Virtual Machine Integer Array Expression
# Line 273  namespace LinuxSampler { Line 448  namespace LinuxSampler {
448           *           *
449           * @param i - array element index (must be between 0 .. arraySize() - 1)           * @param i - array element index (must be between 0 .. arraySize() - 1)
450           */           */
451          virtual int evalIntElement(uint i) = 0;          virtual vmint evalIntElement(vmuint i) = 0;
452    
453          /**          /**
454           * 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 457  namespace LinuxSampler {
457           * @param i - array element index (must be between 0 .. arraySize() - 1)           * @param i - array element index (must be between 0 .. arraySize() - 1)
458           * @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
459           */           */
460          virtual void assignIntElement(uint i, int value) = 0;          virtual void assignIntElement(vmuint i, vmint value) = 0;
461    
462          /**          /**
463           * Returns always INT_ARR_EXPR for instances of this class.           * Returns always INT_ARR_EXPR for instances of this class.
# Line 304  namespace LinuxSampler { Line 479  namespace LinuxSampler {
479           * Returns the amount of arguments going to be passed to the script           * Returns the amount of arguments going to be passed to the script
480           * function.           * function.
481           */           */
482          virtual int argsCount() const = 0;          virtual vmint argsCount() const = 0;
483    
484          /**          /**
485           * Returns the respective argument (requested by argument index @a i) of           * Returns the respective argument (requested by argument index @a i) of
# Line 314  namespace LinuxSampler { Line 489  namespace LinuxSampler {
489           *           *
490           * @param i - function argument index (indexed from left to right)           * @param i - function argument index (indexed from left to right)
491           */           */
492          virtual VMExpr* arg(int i) = 0;          virtual VMExpr* arg(vmint i) = 0;
493      };      };
494    
495      /** @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 378  namespace LinuxSampler { Line 553  namespace LinuxSampler {
553           * script is calling this function with less arguments, the script           * script is calling this function with less arguments, the script
554           * parser will throw a parser error.           * parser will throw a parser error.
555           */           */
556          virtual int minRequiredArgs() const = 0;          virtual vmint minRequiredArgs() const = 0;
557    
558          /**          /**
559           * Maximum amount of function arguments this functions accepts. If a           * Maximum amount of function arguments this functions accepts. If a
560           * script is calling this function with more arguments, the script           * script is calling this function with more arguments, the script
561           * parser will throw a parser error.           * parser will throw a parser error.
562           */           */
563          virtual int maxAllowedArgs() const = 0;          virtual vmint maxAllowedArgs() const = 0;
564    
565          /**          /**
566           * Script data type of the function's @c iArg 'th function argument.           * Script data type of the function's @c iArg 'th function argument.
# Line 401  namespace LinuxSampler { Line 576  namespace LinuxSampler {
576           * @param iArg - index of the function argument in question           * @param iArg - index of the function argument in question
577           *               (must be between 0 .. maxAllowedArgs() - 1)           *               (must be between 0 .. maxAllowedArgs() - 1)
578           */           */
579          virtual ExprType_t argType(int iArg) const = 0;          virtual ExprType_t argType(vmint iArg) const = 0;
580    
581          /**          /**
582           * This method is called by the parser to check whether arguments           * This method is called by the parser to check whether arguments
# Line 419  namespace LinuxSampler { Line 594  namespace LinuxSampler {
594           * @return true if the given data type would be accepted for the           * @return true if the given data type would be accepted for the
595           *         respective function argument by the function           *         respective function argument by the function
596           */           */
597          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgType(vmint iArg, ExprType_t type) const = 0;
598    
599            /**
600             * This method is called by the parser to check whether arguments
601             * passed in scripts to this function are accepted by this function. If
602             * a script calls this function with an argument's measuremnt unit type
603             * not accepted by this function, the parser will throw a parser error.
604             *
605             * This default implementation of this method does not accept any
606             * measurement unit. Deriving subclasses would override this method
607             * implementation in case they do accept any measurement unit for its
608             * function arguments.
609             *
610             * @param iArg - index of the function argument in question
611             *               (must be between 0 .. maxAllowedArgs() - 1)
612             * @param type - standard measurement unit data type used for this
613             *               function argument by currently parsed script
614             * @return true if the given standard measurement unit type would be
615             *         accepted for the respective function argument by the function
616             */
617            virtual bool acceptsArgUnitType(vmint iArg, StdUnit_t type) const;
618    
619            /**
620             * This method is called by the parser to check whether arguments
621             * passed in scripts to this function are accepted by this function. If
622             * a script calls this function with a metric unit prefix and metric
623             * prefixes are not accepted for that argument by this function, then
624             * the parser will throw a parser error.
625             *
626             * This default implementation of this method does not accept any
627             * metric prefix. Deriving subclasses would override this method
628             * implementation in case they do accept any metric prefix for its
629             * function arguments.
630             *
631             * @param iArg - index of the function argument in question
632             *               (must be between 0 .. maxAllowedArgs() - 1)
633             *
634             * @return true if a metric prefix would be accepted for the respective
635             *         function argument by this function
636             *
637             * @see MetricPrefix_t
638             */
639            virtual bool acceptsArgUnitPrefix(vmint iArg) const;
640    
641            /**
642             * This method is called by the parser to check whether arguments
643             * passed in scripts to this function are accepted by this function. If
644             * a script calls this function with an argument that is declared to be
645             * a "final" value and this is not accepted by this function, the parser
646             * will throw a parser error.
647             *
648             * This default implementation of this method does not accept a "final"
649             * value. Deriving subclasses would override this method implementation
650             * in case they do accept a "final" value for its function arguments.
651             *
652             * @param iArg - index of the function argument in question
653             *               (must be between 0 .. maxAllowedArgs() - 1)
654             * @return true if a "final" value would be accepted for the respective
655             *         function argument by the function
656             *
657             * @see VMIntExpr::isFinal()
658             */
659            virtual bool acceptsArgFinal(vmint iArg) const;
660    
661          /**          /**
662           * 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 671  namespace LinuxSampler {
671           * @param iArg - index of the function argument in question           * @param iArg - index of the function argument in question
672           *               (must be between 0 .. maxAllowedArgs() - 1)           *               (must be between 0 .. maxAllowedArgs() - 1)
673           */           */
674          virtual bool modifiesArg(int iArg) const = 0;          virtual bool modifiesArg(vmint iArg) const = 0;
675    
676          /**          /**
677           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
# Line 468  namespace LinuxSampler { Line 705  namespace LinuxSampler {
705    
706      /** @brief Virtual machine relative pointer.      /** @brief Virtual machine relative pointer.
707       *       *
708       * POD base of VMIntRelPtr and VMInt8RelPtr structures. Not intended to be       * POD base of VMInt64RelPtr, VMInt32RelPtr and VMInt8RelPtr structures. Not
709       * used directly. Use VMIntRelPtr or VMInt8RelPtr instead.       * intended to be used directly. Use VMInt64RelPtr, VMInt32RelPtr,
710         * VMInt8RelPtr instead.
711       *       *
712       * @see VMIntRelPtr, VMInt8RelPtr       * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr
713       */       */
714      struct VMRelPtr {      struct VMRelPtr {
715          void** base; ///< Base pointer.          void** base; ///< Base pointer.
716          int offset;  ///< Offset (in bytes) relative to base pointer.          vmint offset;  ///< Offset (in bytes) relative to base pointer.
717          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.
718      };      };
719    
720      /** @brief Pointer to built-in VM integer variable (of C/C++ type int).      /** @brief Pointer to built-in VM integer variable (interface class).
721         *
722         * This class acts as an abstract interface to all built-in integer script
723         * variables, independent of their actual native size (i.e. some built-in
724         * script variables are internally using a native int size of 64 bit or 32
725         * bit or 8 bit). The virtual machine is using this interface class instead
726         * of its implementing descendants (VMInt64RelPtr, VMInt32RelPtr,
727         * VMInt8RelPtr) in order for the virtual machine for not being required to
728         * handle each of them differently.
729         */
730        struct VMIntPtr {
731            virtual vmint evalInt() = 0;
732            virtual void assign(vmint i) = 0;
733            virtual bool isAssignable() const = 0;
734        };
735    
736        /** @brief Pointer to built-in VM integer variable (of C/C++ type int64_t).
737         *
738         * Used for defining built-in 64 bit integer script variables.
739         *
740         * @b CAUTION: You may only use this class for pointing to C/C++ variables
741         * of type "int64_t" (thus being exactly 64 bit in size). If the C/C++ int
742         * variable you want to reference is only 32 bit in size then you @b must
743         * use VMInt32RelPtr instead! Respectively for a referenced native variable
744         * with only 8 bit in size you @b must use VMInt8RelPtr instead!
745         *
746         * For efficiency reasons the actual native C/C++ int variable is referenced
747         * by two components here. The actual native int C/C++ variable in memory
748         * is dereferenced at VM run-time by taking the @c base pointer dereference
749         * and adding @c offset bytes. This has the advantage that for a large
750         * number of built-in int variables, only one (or few) base pointer need
751         * to be re-assigned before running a script, instead of updating each
752         * built-in variable each time before a script is executed.
753         *
754         * Refer to DECLARE_VMINT() for example code.
755         *
756         * @see VMInt32RelPtr, VMInt8RelPtr, DECLARE_VMINT()
757         */
758        struct VMInt64RelPtr : VMRelPtr, VMIntPtr {
759            VMInt64RelPtr() {
760                base   = NULL;
761                offset = 0;
762                readonly = false;
763            }
764            VMInt64RelPtr(const VMRelPtr& data) {
765                base   = data.base;
766                offset = data.offset;
767                readonly = false;
768            }
769            vmint evalInt() OVERRIDE {
770                return (vmint)*(int64_t*)&(*(uint8_t**)base)[offset];
771            }
772            void assign(vmint i) OVERRIDE {
773                *(int64_t*)&(*(uint8_t**)base)[offset] = (int64_t)i;
774            }
775            bool isAssignable() const OVERRIDE { return !readonly; }
776        };
777    
778        /** @brief Pointer to built-in VM integer variable (of C/C++ type int32_t).
779       *       *
780       * Used for defining built-in 32 bit integer script variables.       * Used for defining built-in 32 bit integer script variables.
781       *       *
782       * @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
783       * 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
784       * 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
785       * use VMInt8RelPtr instead!       * VMInt64RelPtr instead! Respectively for a referenced native variable with
786         * only 8 bit in size you @b must use VMInt8RelPtr instead!
787       *       *
788       * For efficiency reasons the actual native C/C++ int variable is referenced       * For efficiency reasons the actual native C/C++ int variable is referenced
789       * 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 795  namespace LinuxSampler {
795       *       *
796       * Refer to DECLARE_VMINT() for example code.       * Refer to DECLARE_VMINT() for example code.
797       *       *
798       * @see VMInt8RelPtr, DECLARE_VMINT()       * @see VMInt64RelPtr, VMInt8RelPtr, DECLARE_VMINT()
799       */       */
800      struct VMIntRelPtr : VMRelPtr {      struct VMInt32RelPtr : VMRelPtr, VMIntPtr {
801          VMIntRelPtr() {          VMInt32RelPtr() {
802              base   = NULL;              base   = NULL;
803              offset = 0;              offset = 0;
804              readonly = false;              readonly = false;
805          }          }
806          VMIntRelPtr(const VMRelPtr& data) {          VMInt32RelPtr(const VMRelPtr& data) {
807              base   = data.base;              base   = data.base;
808              offset = data.offset;              offset = data.offset;
809              readonly = false;              readonly = false;
810          }          }
811          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }          vmint evalInt() OVERRIDE {
812          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }              return (vmint)*(int32_t*)&(*(uint8_t**)base)[offset];
813            }
814            void assign(vmint i) OVERRIDE {
815                *(int32_t*)&(*(uint8_t**)base)[offset] = (int32_t)i;
816            }
817            bool isAssignable() const OVERRIDE { return !readonly; }
818      };      };
819    
820      /** @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 823  namespace LinuxSampler {
823       *       *
824       * @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
825       * 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
826       * 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
827       * @b must use VMIntRelPtr instead!       * either VMInt32RelPtr for native 32 bit variables or VMInt64RelPtrl for
828         * native 64 bit variables instead!
829       *       *
830       * For efficiency reasons the actual native C/C++ int variable is referenced       * For efficiency reasons the actual native C/C++ int variable is referenced
831       * 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 837  namespace LinuxSampler {
837       *       *
838       * Refer to DECLARE_VMINT() for example code.       * Refer to DECLARE_VMINT() for example code.
839       *       *
840       * @see VMIntRelPtr, DECLARE_VMINT()       * @see VMIntRel32Ptr, VMIntRel64Ptr, DECLARE_VMINT()
841       */       */
842      struct VMInt8RelPtr : VMIntRelPtr {      struct VMInt8RelPtr : VMRelPtr, VMIntPtr {
843          VMInt8RelPtr() : VMIntRelPtr() {}          VMInt8RelPtr() {
844          VMInt8RelPtr(const VMRelPtr& data) : VMIntRelPtr(data) {}              base   = NULL;
845          virtual int evalInt() OVERRIDE {              offset = 0;
846              return *(uint8_t*)&(*(uint8_t**)base)[offset];              readonly = false;
847            }
848            VMInt8RelPtr(const VMRelPtr& data) {
849                base   = data.base;
850                offset = data.offset;
851                readonly = false;
852            }
853            vmint evalInt() OVERRIDE {
854                return (vmint)*(uint8_t*)&(*(uint8_t**)base)[offset];
855          }          }
856          virtual void assign(int i) OVERRIDE {          void assign(vmint i) OVERRIDE {
857              *(uint8_t*)&(*(uint8_t**)base)[offset] = i;              *(uint8_t*)&(*(uint8_t**)base)[offset] = (uint8_t)i;
858          }          }
859            bool isAssignable() const OVERRIDE { return !readonly; }
860      };      };
861    
862        /** @brief Pointer to built-in VM integer variable (of C/C++ type vmint).
863         *
864         * Use this typedef if the native variable to be pointed to is using the
865         * typedef vmint. If the native C/C++ variable to be pointed to is using
866         * another C/C++ type then better use one of VMInt64RelPtr or VMInt32RelPtr
867         * instead.
868         */
869        typedef VMInt64RelPtr VMIntRelPtr;
870    
871      #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS      #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
872      # define COMPILER_DISABLE_OFFSETOF_WARNING                    \      # define COMPILER_DISABLE_OFFSETOF_WARNING                    \
873          _Pragma("GCC diagnostic push")                            \          _Pragma("GCC diagnostic push")                            \
# Line 559  namespace LinuxSampler { Line 880  namespace LinuxSampler {
880      #endif      #endif
881    
882      /**      /**
883       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr       * Convenience macro for initializing VMInt64RelPtr, VMInt32RelPtr and
884       * structures. Usage example:       * VMInt8RelPtr structures. Usage example:
885       * @code       * @code
886       * struct Foo {       * struct Foo {
887       *   uint8_t a; // native representation of a built-in integer script variable       *   uint8_t a; // native representation of a built-in integer script variable
888       *   int b; // native representation of another built-in integer script variable       *   int64_t b; // native representation of another built-in integer script variable
889       *   int c; // native representation of another built-in integer script variable       *   int64_t c; // native representation of another built-in integer script variable
890       *   uint8_t d; // native representation of another built-in integer script variable       *   uint8_t d; // native representation of another built-in integer script variable
891       * };       * };
892       *       *
# Line 576  namespace LinuxSampler { Line 897  namespace LinuxSampler {
897       * Foo* pFoo;       * Foo* pFoo;
898       *       *
899       * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);       * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);
900       * VMIntRelPtr  varB = DECLARE_VMINT(pFoo, class Foo, b);       * VMInt64RelPtr varB = DECLARE_VMINT(pFoo, class Foo, b);
901       * VMIntRelPtr  varC = DECLARE_VMINT(pFoo, class Foo, c);       * VMInt64RelPtr varC = DECLARE_VMINT(pFoo, class Foo, c);
902       * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);       * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);
903       *       *
904       * pFoo = &foo1;       * pFoo = &foo1;
# Line 612  namespace LinuxSampler { Line 933  namespace LinuxSampler {
933      )                                                             \      )                                                             \
934    
935      /**      /**
936       * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and       * Same as DECLARE_VMINT(), but this one defines the VMInt64RelPtr,
937       * VMInt8RelPtr structures to be of read-only type. That means the script       * VMInt32RelPtr and VMInt8RelPtr structures to be of read-only type.
938       * parser will abort any script at parser time if the script is trying to       * That means the script parser will abort any script at parser time if the
939       * modify such a read-only built-in variable.       * script is trying to modify such a read-only built-in variable.
940       *       *
941       * @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
942       * 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 643  namespace LinuxSampler { Line 964  namespace LinuxSampler {
964       */       */
965      struct VMInt8Array {      struct VMInt8Array {
966          int8_t* data;          int8_t* data;
967          int size;          vmint size;
968          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.
969    
970          VMInt8Array() : data(NULL), size(0), readonly(false) {}          VMInt8Array() : data(NULL), size(0), readonly(false) {}
# Line 746  namespace LinuxSampler { Line 1067  namespace LinuxSampler {
1067       */       */
1068      class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {      class VMDynIntVar : virtual public VMDynVar, virtual public VMIntExpr {
1069      public:      public:
1070            MetricPrefix_t unitPrefix(vmuint i) const OVERRIDE { return VM_NO_PREFIX; }
1071            StdUnit_t unitType() const OVERRIDE { return VM_NO_UNIT; }
1072            bool isFinal() const OVERRIDE { return false; }
1073      };      };
1074    
1075      /** @brief Dynamically executed variable (of string data type).      /** @brief Dynamically executed variable (of string data type).
# Line 786  namespace LinuxSampler { Line 1110  namespace LinuxSampler {
1110          virtual VMFunction* functionByName(const String& name) = 0;          virtual VMFunction* functionByName(const String& name) = 0;
1111    
1112          /**          /**
1113             * Returns @c true if the passed built-in function is disabled and
1114             * should be ignored by the parser. This method is called by the
1115             * parser on preprocessor level for each built-in function call within
1116             * a script. Accordingly if this method returns @c true, then the
1117             * respective function call is completely filtered out on preprocessor
1118             * level, so that built-in function won't make into the result virtual
1119             * machine representation, nor would expressions of arguments passed to
1120             * that built-in function call be evaluated, nor would any check
1121             * regarding correct usage of the built-in function be performed.
1122             * In other words: a disabled function call ends up as a comment block.
1123             *
1124             * @param fn - built-in function to be checked
1125             * @param ctx - parser context at the position where the built-in
1126             *              function call is located within the script
1127             */
1128            virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0;
1129    
1130            /**
1131           * Returns a variable name indexed map of all built-in script variables           * Returns a variable name indexed map of all built-in script variables
1132           * which point to native "int" scalar (usually 32 bit) variables.           * which point to native "int" scalar (usually 32 bit) variables.
1133           */           */
1134          virtual std::map<String,VMIntRelPtr*> builtInIntVariables() = 0;          virtual std::map<String,VMIntPtr*> builtInIntVariables() = 0;
1135    
1136          /**          /**
1137           * 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 801  namespace LinuxSampler { Line 1143  namespace LinuxSampler {
1143           * Returns a variable name indexed map of all built-in constant script           * Returns a variable name indexed map of all built-in constant script
1144           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
1145           */           */
1146          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,vmint> builtInConstIntVariables() = 0;
1147    
1148          /**          /**
1149           * 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 1192  namespace LinuxSampler {
1192           *           *
1193           * @see ScriptVM::exec()           * @see ScriptVM::exec()
1194           */           */
1195          virtual int suspensionTimeMicroseconds() const = 0;          virtual vmint suspensionTimeMicroseconds() const = 0;
1196    
1197          /**          /**
1198           * 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 1221  namespace LinuxSampler {
1221           * instance.           * instance.
1222           */           */
1223          virtual void signalAbort() = 0;          virtual void signalAbort() = 0;
1224    
1225            /**
1226             * Copies the current entire execution state from this object to the
1227             * given object. So this can be used to "fork" a new script thread which
1228             * then may run independently with its own polyphonic data for instance.
1229             */
1230            virtual void forkTo(VMExecContext* ectx) const = 0;
1231    
1232            /**
1233             * In case the script called the built-in exit() function and passed a
1234             * value as argument to the exit() function, then this method returns
1235             * the value that had been passed as argument to the exit() function.
1236             * Otherwise if the exit() function has not been called by the script
1237             * or no argument had been passed to the exit() function, then this
1238             * method returns NULL instead.
1239             *
1240             * Currently this is only used for automated test cases against the
1241             * script engine, which return some kind of value in the individual
1242             * test case scripts to check their behaviour in automated way. There
1243             * is no purpose for this mechanism in production use. Accordingly this
1244             * exit result value is @b always completely ignored by the sampler
1245             * engines.
1246             *
1247             * Officially the built-in exit() function does not expect any arguments
1248             * to be passed to its function call, and by default this feature is
1249             * hence disabled and will yield in a parser error unless
1250             * ScriptVM::setExitResultEnabled() was explicitly set.
1251             *
1252             * @see ScriptVM::setExitResultEnabled()
1253             */
1254            virtual VMExpr* exitResult() = 0;
1255      };      };
1256    
1257      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 910  namespace LinuxSampler { Line 1283  namespace LinuxSampler {
1283      };      };
1284    
1285      /**      /**
1286         * Reflects the precise position and span of a specific code block within
1287         * a script. This is currently only used for the locations of commented
1288         * code blocks due to preprocessor statements, and for parser errors and
1289         * parser warnings.
1290         *
1291         * @see ParserIssue for code locations of parser errors and parser warnings
1292         *
1293         * @see VMParserContext::preprocessorComments() for locations of code which
1294         *      have been filtered out by preprocessor statements
1295         */
1296        struct CodeBlock {
1297            int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
1298            int lastLine; ///< The last line number of this code block within the script.
1299            int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
1300            int lastColumn; ///< The last column of this code block within the script.
1301        };
1302    
1303        /**
1304       * Encapsulates a noteworty parser issue. This encompasses the type of the       * Encapsulates a noteworty parser issue. This encompasses the type of the
1305       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
1306       * 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 1308  namespace LinuxSampler {
1308       *       *
1309       * @see VMSourceToken for processing syntax highlighting instead.       * @see VMSourceToken for processing syntax highlighting instead.
1310       */       */
1311      struct ParserIssue {      struct ParserIssue : CodeBlock {
1312          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.  
1313          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.
1314    
1315          /**          /**
# Line 968  namespace LinuxSampler { Line 1355  namespace LinuxSampler {
1355          return "invalid";          return "invalid";
1356      }      }
1357    
1358        /**
1359         * Convenience function used for converting an StdUnit_t constant to a
1360         * string, i.e. for generating error message by the parser.
1361         */
1362        inline String unitTypeStr(const StdUnit_t& type) {
1363            switch (type) {
1364                case VM_NO_UNIT: return "none";
1365                case VM_SECOND: return "seconds";
1366                case VM_HERTZ: return "Hz";
1367                case VM_BEL: return "Bel";
1368            }
1369            return "invalid";
1370        }
1371    
1372      /** @brief Virtual machine representation of a script.      /** @brief Virtual machine representation of a script.
1373       *       *
1374       * 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 1403  namespace LinuxSampler {
1403          virtual std::vector<ParserIssue> warnings() const = 0;          virtual std::vector<ParserIssue> warnings() const = 0;
1404    
1405          /**          /**
1406             * Returns all code blocks of the script which were filtered out by the
1407             * preprocessor.
1408             */
1409            virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1410    
1411            /**
1412           * Returns the translated virtual machine representation of an event           * Returns the translated virtual machine representation of an event
1413           * handler block (i.e. "on note ... end on" code block) within the           * handler block (i.e. "on note ... end on" code block) within the
1414           * parsed script. This translated representation of the event handler           * parsed script. This translated representation of the event handler
Legend:
Removed from v.3277  
changed lines
  Added in v.3561
  ViewVC Help
Powered by ViewVC