/[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 3557 by schoenebeck, Sun Aug 18 00:06:04 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       * Identifies the type of a noteworthy issue identified by the script       * Identifies the type of a noteworthy issue identified by the script
41       * parser. That's either a parser error or parser warning.       * parser. That's either a parser error or parser warning.
42       */       */
# Line 80  namespace LinuxSampler { Line 95  namespace LinuxSampler {
95       *       *
96       * Identifies one of the possible event handler callback types defined by       * Identifies one of the possible event handler callback types defined by
97       * the NKSP script language.       * the NKSP script language.
98         *
99         * IMPORTANT: this type is forced to be emitted as int32_t type ATM, because
100         * that's the native size expected by the built-in instrument script
101         * variable bindings (see occurrences of VMInt32RelPtr and DECLARE_VMINT
102         * respectively. A native type mismatch between the two could lead to
103         * undefined behavior! Background: By definition the C/C++ compiler is free
104         * to choose a bit size for individual enums which it might find
105         * appropriate, which is usually decided by the compiler according to the
106         * biggest enum constant value defined (in practice it is usually 32 bit).
107       */       */
108      enum VMEventHandlerType_t {      enum VMEventHandlerType_t : int32_t {
109          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.
110          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.
111          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.
# Line 93  namespace LinuxSampler { Line 117  namespace LinuxSampler {
117      class VMStringExpr;      class VMStringExpr;
118      class VMIntArrayExpr;      class VMIntArrayExpr;
119      class VMStringArrayExpr;      class VMStringArrayExpr;
120        class VMParserContext;
121    
122      /** @brief Virtual machine expression      /** @brief Virtual machine expression
123       *       *
# Line 213  namespace LinuxSampler { Line 238  namespace LinuxSampler {
238           * Returns the result of this expression as integer (scalar) value.           * Returns the result of this expression as integer (scalar) value.
239           * This abstract method must be implemented by deriving classes.           * This abstract method must be implemented by deriving classes.
240           */           */
241          virtual int evalInt() = 0;          virtual vmint evalInt() = 0;
242    
243          /**          /**
244           * Returns always INT_EXPR for instances of this class.           * Returns always INT_EXPR for instances of this class.
# Line 255  namespace LinuxSampler { Line 280  namespace LinuxSampler {
280           * Returns amount of elements in this array. This abstract method must           * Returns amount of elements in this array. This abstract method must
281           * be implemented by deriving classes.           * be implemented by deriving classes.
282           */           */
283          virtual int arraySize() const = 0;          virtual vmint arraySize() const = 0;
284      };      };
285    
286      /** @brief Virtual Machine Integer Array Expression      /** @brief Virtual Machine Integer Array Expression
# Line 273  namespace LinuxSampler { Line 298  namespace LinuxSampler {
298           *           *
299           * @param i - array element index (must be between 0 .. arraySize() - 1)           * @param i - array element index (must be between 0 .. arraySize() - 1)
300           */           */
301          virtual int evalIntElement(uint i) = 0;          virtual vmint evalIntElement(vmuint i) = 0;
302    
303          /**          /**
304           * 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 307  namespace LinuxSampler {
307           * @param i - array element index (must be between 0 .. arraySize() - 1)           * @param i - array element index (must be between 0 .. arraySize() - 1)
308           * @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
309           */           */
310          virtual void assignIntElement(uint i, int value) = 0;          virtual void assignIntElement(vmuint i, vmint value) = 0;
311    
312          /**          /**
313           * 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 329  namespace LinuxSampler {
329           * Returns the amount of arguments going to be passed to the script           * Returns the amount of arguments going to be passed to the script
330           * function.           * function.
331           */           */
332          virtual int argsCount() const = 0;          virtual vmint argsCount() const = 0;
333    
334          /**          /**
335           * 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 339  namespace LinuxSampler {
339           *           *
340           * @param i - function argument index (indexed from left to right)           * @param i - function argument index (indexed from left to right)
341           */           */
342          virtual VMExpr* arg(int i) = 0;          virtual VMExpr* arg(vmint i) = 0;
343      };      };
344    
345      /** @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 403  namespace LinuxSampler {
403           * script is calling this function with less arguments, the script           * script is calling this function with less arguments, the script
404           * parser will throw a parser error.           * parser will throw a parser error.
405           */           */
406          virtual int minRequiredArgs() const = 0;          virtual vmint minRequiredArgs() const = 0;
407    
408          /**          /**
409           * Maximum amount of function arguments this functions accepts. If a           * Maximum amount of function arguments this functions accepts. If a
410           * script is calling this function with more arguments, the script           * script is calling this function with more arguments, the script
411           * parser will throw a parser error.           * parser will throw a parser error.
412           */           */
413          virtual int maxAllowedArgs() const = 0;          virtual vmint maxAllowedArgs() const = 0;
414    
415          /**          /**
416           * 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 426  namespace LinuxSampler {
426           * @param iArg - index of the function argument in question           * @param iArg - index of the function argument in question
427           *               (must be between 0 .. maxAllowedArgs() - 1)           *               (must be between 0 .. maxAllowedArgs() - 1)
428           */           */
429          virtual ExprType_t argType(int iArg) const = 0;          virtual ExprType_t argType(vmint iArg) const = 0;
430    
431          /**          /**
432           * 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 444  namespace LinuxSampler {
444           * @return true if the given data type would be accepted for the           * @return true if the given data type would be accepted for the
445           *         respective function argument by the function           *         respective function argument by the function
446           */           */
447          virtual bool acceptsArgType(int iArg, ExprType_t type) const = 0;          virtual bool acceptsArgType(vmint iArg, ExprType_t type) const = 0;
448    
449          /**          /**
450           * 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 459  namespace LinuxSampler {
459           * @param iArg - index of the function argument in question           * @param iArg - index of the function argument in question
460           *               (must be between 0 .. maxAllowedArgs() - 1)           *               (must be between 0 .. maxAllowedArgs() - 1)
461           */           */
462          virtual bool modifiesArg(int iArg) const = 0;          virtual bool modifiesArg(vmint iArg) const = 0;
463    
464          /**          /**
465           * Implements the actual function execution. This exec() method is           * Implements the actual function execution. This exec() method is
# Line 468  namespace LinuxSampler { Line 493  namespace LinuxSampler {
493    
494      /** @brief Virtual machine relative pointer.      /** @brief Virtual machine relative pointer.
495       *       *
496       * POD base of VMIntRelPtr and VMInt8RelPtr structures. Not intended to be       * POD base of VMInt64RelPtr, VMInt32RelPtr and VMInt8RelPtr structures. Not
497       * used directly. Use VMIntRelPtr or VMInt8RelPtr instead.       * intended to be used directly. Use VMInt64RelPtr, VMInt32RelPtr,
498         * VMInt8RelPtr instead.
499       *       *
500       * @see VMIntRelPtr, VMInt8RelPtr       * @see VMInt64RelPtr, VMInt32RelPtr, VMInt8RelPtr
501       */       */
502      struct VMRelPtr {      struct VMRelPtr {
503          void** base; ///< Base pointer.          void** base; ///< Base pointer.
504          int offset;  ///< Offset (in bytes) relative to base pointer.          vmint offset;  ///< Offset (in bytes) relative to base pointer.
505          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.
506      };      };
507    
508      /** @brief Pointer to built-in VM integer variable (of C/C++ type int).      /** @brief Pointer to built-in VM integer variable (interface class).
509         *
510         * This class acts as an abstract interface to all built-in integer script
511         * variables, independent of their actual native size (i.e. some built-in
512         * script variables are internally using a native int size of 64 bit or 32
513         * bit or 8 bit). The virtual machine is using this interface class instead
514         * of its implementing descendants (VMInt64RelPtr, VMInt32RelPtr,
515         * VMInt8RelPtr) in order for the virtual machine for not being required to
516         * handle each of them differently.
517         */
518        struct VMIntPtr {
519            virtual vmint evalInt() = 0;
520            virtual void assign(vmint i) = 0;
521            virtual bool isAssignable() const = 0;
522        };
523    
524        /** @brief Pointer to built-in VM integer variable (of C/C++ type int64_t).
525         *
526         * Used for defining built-in 64 bit integer script variables.
527         *
528         * @b CAUTION: You may only use this class for pointing to C/C++ variables
529         * of type "int64_t" (thus being exactly 64 bit in size). If the C/C++ int
530         * variable you want to reference is only 32 bit in size then you @b must
531         * use VMInt32RelPtr instead! Respectively for a referenced native variable
532         * with only 8 bit in size you @b must use VMInt8RelPtr instead!
533         *
534         * For efficiency reasons the actual native C/C++ int variable is referenced
535         * by two components here. The actual native int C/C++ variable in memory
536         * is dereferenced at VM run-time by taking the @c base pointer dereference
537         * and adding @c offset bytes. This has the advantage that for a large
538         * number of built-in int variables, only one (or few) base pointer need
539         * to be re-assigned before running a script, instead of updating each
540         * built-in variable each time before a script is executed.
541         *
542         * Refer to DECLARE_VMINT() for example code.
543         *
544         * @see VMInt32RelPtr, VMInt8RelPtr, DECLARE_VMINT()
545         */
546        struct VMInt64RelPtr : VMRelPtr, VMIntPtr {
547            VMInt64RelPtr() {
548                base   = NULL;
549                offset = 0;
550                readonly = false;
551            }
552            VMInt64RelPtr(const VMRelPtr& data) {
553                base   = data.base;
554                offset = data.offset;
555                readonly = false;
556            }
557            vmint evalInt() OVERRIDE {
558                return (vmint)*(int64_t*)&(*(uint8_t**)base)[offset];
559            }
560            void assign(vmint i) OVERRIDE {
561                *(int64_t*)&(*(uint8_t**)base)[offset] = (int64_t)i;
562            }
563            bool isAssignable() const OVERRIDE { return !readonly; }
564        };
565    
566        /** @brief Pointer to built-in VM integer variable (of C/C++ type int32_t).
567       *       *
568       * Used for defining built-in 32 bit integer script variables.       * Used for defining built-in 32 bit integer script variables.
569       *       *
570       * @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
571       * 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
572       * 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
573       * use VMInt8RelPtr instead!       * VMInt64RelPtr instead! Respectively for a referenced native variable with
574         * only 8 bit in size you @b must use VMInt8RelPtr instead!
575       *       *
576       * For efficiency reasons the actual native C/C++ int variable is referenced       * For efficiency reasons the actual native C/C++ int variable is referenced
577       * 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 583  namespace LinuxSampler {
583       *       *
584       * Refer to DECLARE_VMINT() for example code.       * Refer to DECLARE_VMINT() for example code.
585       *       *
586       * @see VMInt8RelPtr, DECLARE_VMINT()       * @see VMInt64RelPtr, VMInt8RelPtr, DECLARE_VMINT()
587       */       */
588      struct VMIntRelPtr : VMRelPtr {      struct VMInt32RelPtr : VMRelPtr, VMIntPtr {
589          VMIntRelPtr() {          VMInt32RelPtr() {
590              base   = NULL;              base   = NULL;
591              offset = 0;              offset = 0;
592              readonly = false;              readonly = false;
593          }          }
594          VMIntRelPtr(const VMRelPtr& data) {          VMInt32RelPtr(const VMRelPtr& data) {
595              base   = data.base;              base   = data.base;
596              offset = data.offset;              offset = data.offset;
597              readonly = false;              readonly = false;
598          }          }
599          virtual int evalInt() { return *(int*)&(*(uint8_t**)base)[offset]; }          vmint evalInt() OVERRIDE {
600          virtual void assign(int i) { *(int*)&(*(uint8_t**)base)[offset] = i; }              return (vmint)*(int32_t*)&(*(uint8_t**)base)[offset];
601            }
602            void assign(vmint i) OVERRIDE {
603                *(int32_t*)&(*(uint8_t**)base)[offset] = (int32_t)i;
604            }
605            bool isAssignable() const OVERRIDE { return !readonly; }
606      };      };
607    
608      /** @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 611  namespace LinuxSampler {
611       *       *
612       * @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
613       * 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
614       * 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
615       * @b must use VMIntRelPtr instead!       * either VMInt32RelPtr for native 32 bit variables or VMInt64RelPtrl for
616         * native 64 bit variables instead!
617       *       *
618       * For efficiency reasons the actual native C/C++ int variable is referenced       * For efficiency reasons the actual native C/C++ int variable is referenced
619       * 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 625  namespace LinuxSampler {
625       *       *
626       * Refer to DECLARE_VMINT() for example code.       * Refer to DECLARE_VMINT() for example code.
627       *       *
628       * @see VMIntRelPtr, DECLARE_VMINT()       * @see VMIntRel32Ptr, VMIntRel64Ptr, DECLARE_VMINT()
629       */       */
630      struct VMInt8RelPtr : VMIntRelPtr {      struct VMInt8RelPtr : VMRelPtr, VMIntPtr {
631          VMInt8RelPtr() : VMIntRelPtr() {}          VMInt8RelPtr() {
632          VMInt8RelPtr(const VMRelPtr& data) : VMIntRelPtr(data) {}              base   = NULL;
633          virtual int evalInt() OVERRIDE {              offset = 0;
634              return *(uint8_t*)&(*(uint8_t**)base)[offset];              readonly = false;
635            }
636            VMInt8RelPtr(const VMRelPtr& data) {
637                base   = data.base;
638                offset = data.offset;
639                readonly = false;
640            }
641            vmint evalInt() OVERRIDE {
642                return (vmint)*(uint8_t*)&(*(uint8_t**)base)[offset];
643          }          }
644          virtual void assign(int i) OVERRIDE {          void assign(vmint i) OVERRIDE {
645              *(uint8_t*)&(*(uint8_t**)base)[offset] = i;              *(uint8_t*)&(*(uint8_t**)base)[offset] = (uint8_t)i;
646          }          }
647            bool isAssignable() const OVERRIDE { return !readonly; }
648      };      };
649    
650        /** @brief Pointer to built-in VM integer variable (of C/C++ type vmint).
651         *
652         * Use this typedef if the native variable to be pointed to is using the
653         * typedef vmint. If the native C/C++ variable to be pointed to is using
654         * another C/C++ type then better use one of VMInt64RelPtr or VMInt32RelPtr
655         * instead.
656         */
657        typedef VMInt64RelPtr VMIntRelPtr;
658    
659      #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS      #if HAVE_CXX_EMBEDDED_PRAGMA_DIAGNOSTICS
660      # define COMPILER_DISABLE_OFFSETOF_WARNING                    \      # define COMPILER_DISABLE_OFFSETOF_WARNING                    \
661          _Pragma("GCC diagnostic push")                            \          _Pragma("GCC diagnostic push")                            \
# Line 559  namespace LinuxSampler { Line 668  namespace LinuxSampler {
668      #endif      #endif
669    
670      /**      /**
671       * Convenience macro for initializing VMIntRelPtr and VMInt8RelPtr       * Convenience macro for initializing VMInt64RelPtr, VMInt32RelPtr and
672       * structures. Usage example:       * VMInt8RelPtr structures. Usage example:
673       * @code       * @code
674       * struct Foo {       * struct Foo {
675       *   uint8_t a; // native representation of a built-in integer script variable       *   uint8_t a; // native representation of a built-in integer script variable
676       *   int b; // native representation of another built-in integer script variable       *   int64_t b; // native representation of another built-in integer script variable
677       *   int c; // native representation of another built-in integer script variable       *   int64_t c; // native representation of another built-in integer script variable
678       *   uint8_t d; // native representation of another built-in integer script variable       *   uint8_t d; // native representation of another built-in integer script variable
679       * };       * };
680       *       *
# Line 576  namespace LinuxSampler { Line 685  namespace LinuxSampler {
685       * Foo* pFoo;       * Foo* pFoo;
686       *       *
687       * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);       * VMInt8RelPtr varA = DECLARE_VMINT(pFoo, class Foo, a);
688       * VMIntRelPtr  varB = DECLARE_VMINT(pFoo, class Foo, b);       * VMInt64RelPtr varB = DECLARE_VMINT(pFoo, class Foo, b);
689       * VMIntRelPtr  varC = DECLARE_VMINT(pFoo, class Foo, c);       * VMInt64RelPtr varC = DECLARE_VMINT(pFoo, class Foo, c);
690       * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);       * VMInt8RelPtr varD = DECLARE_VMINT(pFoo, class Foo, d);
691       *       *
692       * pFoo = &foo1;       * pFoo = &foo1;
# Line 612  namespace LinuxSampler { Line 721  namespace LinuxSampler {
721      )                                                             \      )                                                             \
722    
723      /**      /**
724       * Same as DECLARE_VMINT(), but this one defines the VMIntRelPtr and       * Same as DECLARE_VMINT(), but this one defines the VMInt64RelPtr,
725       * VMInt8RelPtr structures to be of read-only type. That means the script       * VMInt32RelPtr and VMInt8RelPtr structures to be of read-only type.
726       * 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
727       * modify such a read-only built-in variable.       * script is trying to modify such a read-only built-in variable.
728       *       *
729       * @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
730       * 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 752  namespace LinuxSampler {
752       */       */
753      struct VMInt8Array {      struct VMInt8Array {
754          int8_t* data;          int8_t* data;
755          int size;          vmint size;
756          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.
757    
758          VMInt8Array() : data(NULL), size(0), readonly(false) {}          VMInt8Array() : data(NULL), size(0), readonly(false) {}
# Line 786  namespace LinuxSampler { Line 895  namespace LinuxSampler {
895          virtual VMFunction* functionByName(const String& name) = 0;          virtual VMFunction* functionByName(const String& name) = 0;
896    
897          /**          /**
898             * Returns @c true if the passed built-in function is disabled and
899             * should be ignored by the parser. This method is called by the
900             * parser on preprocessor level for each built-in function call within
901             * a script. Accordingly if this method returns @c true, then the
902             * respective function call is completely filtered out on preprocessor
903             * level, so that built-in function won't make into the result virtual
904             * machine representation, nor would expressions of arguments passed to
905             * that built-in function call be evaluated, nor would any check
906             * regarding correct usage of the built-in function be performed.
907             * In other words: a disabled function call ends up as a comment block.
908             *
909             * @param fn - built-in function to be checked
910             * @param ctx - parser context at the position where the built-in
911             *              function call is located within the script
912             */
913            virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0;
914    
915            /**
916           * Returns a variable name indexed map of all built-in script variables           * Returns a variable name indexed map of all built-in script variables
917           * which point to native "int" scalar (usually 32 bit) variables.           * which point to native "int" scalar (usually 32 bit) variables.
918           */           */
919          virtual std::map<String,VMIntRelPtr*> builtInIntVariables() = 0;          virtual std::map<String,VMIntPtr*> builtInIntVariables() = 0;
920    
921          /**          /**
922           * 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 928  namespace LinuxSampler {
928           * Returns a variable name indexed map of all built-in constant script           * Returns a variable name indexed map of all built-in constant script
929           * variables, which never change their value at runtime.           * variables, which never change their value at runtime.
930           */           */
931          virtual std::map<String,int> builtInConstIntVariables() = 0;          virtual std::map<String,vmint> builtInConstIntVariables() = 0;
932    
933          /**          /**
934           * 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 977  namespace LinuxSampler {
977           *           *
978           * @see ScriptVM::exec()           * @see ScriptVM::exec()
979           */           */
980          virtual int suspensionTimeMicroseconds() const = 0;          virtual vmint suspensionTimeMicroseconds() const = 0;
981    
982          /**          /**
983           * 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 1006  namespace LinuxSampler {
1006           * instance.           * instance.
1007           */           */
1008          virtual void signalAbort() = 0;          virtual void signalAbort() = 0;
1009    
1010            /**
1011             * Copies the current entire execution state from this object to the
1012             * given object. So this can be used to "fork" a new script thread which
1013             * then may run independently with its own polyphonic data for instance.
1014             */
1015            virtual void forkTo(VMExecContext* ectx) const = 0;
1016    
1017            /**
1018             * In case the script called the built-in exit() function and passed a
1019             * value as argument to the exit() function, then this method returns
1020             * the value that had been passed as argument to the exit() function.
1021             * Otherwise if the exit() function has not been called by the script
1022             * or no argument had been passed to the exit() function, then this
1023             * method returns NULL instead.
1024             *
1025             * Currently this is only used for automated test cases against the
1026             * script engine, which return some kind of value in the individual
1027             * test case scripts to check their behaviour in automated way. There
1028             * is no purpose for this mechanism in production use. Accordingly this
1029             * exit result value is @b always completely ignored by the sampler
1030             * engines.
1031             *
1032             * Officially the built-in exit() function does not expect any arguments
1033             * to be passed to its function call, and by default this feature is
1034             * hence disabled and will yield in a parser error unless
1035             * ScriptVM::setExitResultEnabled() was explicitly set.
1036             *
1037             * @see ScriptVM::setExitResultEnabled()
1038             */
1039            virtual VMExpr* exitResult() = 0;
1040      };      };
1041    
1042      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 910  namespace LinuxSampler { Line 1068  namespace LinuxSampler {
1068      };      };
1069    
1070      /**      /**
1071         * Reflects the precise position and span of a specific code block within
1072         * a script. This is currently only used for the locations of commented
1073         * code blocks due to preprocessor statements, and for parser errors and
1074         * parser warnings.
1075         *
1076         * @see ParserIssue for code locations of parser errors and parser warnings
1077         *
1078         * @see VMParserContext::preprocessorComments() for locations of code which
1079         *      have been filtered out by preprocessor statements
1080         */
1081        struct CodeBlock {
1082            int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
1083            int lastLine; ///< The last line number of this code block within the script.
1084            int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
1085            int lastColumn; ///< The last column of this code block within the script.
1086        };
1087    
1088        /**
1089       * Encapsulates a noteworty parser issue. This encompasses the type of the       * Encapsulates a noteworty parser issue. This encompasses the type of the
1090       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
1091       * 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 1093  namespace LinuxSampler {
1093       *       *
1094       * @see VMSourceToken for processing syntax highlighting instead.       * @see VMSourceToken for processing syntax highlighting instead.
1095       */       */
1096      struct ParserIssue {      struct ParserIssue : CodeBlock {
1097          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.  
1098          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.
1099    
1100          /**          /**
# Line 1002  namespace LinuxSampler { Line 1174  namespace LinuxSampler {
1174          virtual std::vector<ParserIssue> warnings() const = 0;          virtual std::vector<ParserIssue> warnings() const = 0;
1175    
1176          /**          /**
1177             * Returns all code blocks of the script which were filtered out by the
1178             * preprocessor.
1179             */
1180            virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1181    
1182            /**
1183           * Returns the translated virtual machine representation of an event           * Returns the translated virtual machine representation of an event
1184           * handler block (i.e. "on note ... end on" code block) within the           * handler block (i.e. "on note ... end on" code block) within the
1185           * 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.3557
  ViewVC Help
Powered by ViewVC