/[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 3056 by schoenebeck, Fri Dec 16 12:57:59 2016 UTC revision 3551 by schoenebeck, Thu Aug 1 10:22:56 2019 UTC
# Line 1  Line 1 
1  /*  /*
2   * Copyright (c) 2014-2016 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 93  namespace LinuxSampler { Line 94  namespace LinuxSampler {
94      class VMStringExpr;      class VMStringExpr;
95      class VMIntArrayExpr;      class VMIntArrayExpr;
96      class VMStringArrayExpr;      class VMStringArrayExpr;
97        class VMParserContext;
98    
99      /** @brief Virtual machine expression      /** @brief Virtual machine expression
100       *       *
# Line 644  namespace LinuxSampler { Line 646  namespace LinuxSampler {
646      struct VMInt8Array {      struct VMInt8Array {
647          int8_t* data;          int8_t* data;
648          int size;          int size;
649            bool readonly; ///< Whether the array data may be modified or just be read.
650    
651          VMInt8Array() : data(NULL), size(0) {}          VMInt8Array() : data(NULL), size(0), readonly(false) {}
652      };      };
653    
654      /** @brief Virtual machine script variable.      /** @brief Virtual machine script variable.
# Line 757  namespace LinuxSampler { Line 760  namespace LinuxSampler {
760      public:      public:
761      };      };
762    
763        /** @brief Dynamically executed variable (of integer array data type).
764         *
765         * This is the base class for all built-in integer array script variables
766         * whose variable content needs to be provided dynamically by executable
767         * native code on each script variable access.
768         */
769        class VMDynIntArrayVar : virtual public VMDynVar, virtual public VMIntArrayExpr {
770        public:
771        };
772    
773      /** @brief Provider for built-in script functions and variables.      /** @brief Provider for built-in script functions and variables.
774       *       *
775       * Abstract base class defining the high-level interface for all classes       * Abstract base class defining the high-level interface for all classes
# Line 775  namespace LinuxSampler { Line 788  namespace LinuxSampler {
788          virtual VMFunction* functionByName(const String& name) = 0;          virtual VMFunction* functionByName(const String& name) = 0;
789    
790          /**          /**
791             * Returns @c true if the passed built-in function is disabled and
792             * should be ignored by the parser. This method is called by the
793             * parser on preprocessor level for each built-in function call within
794             * a script. Accordingly if this method returns @c true, then the
795             * respective function call is completely filtered out on preprocessor
796             * level, so that built-in function won't make into the result virtual
797             * machine representation, nor would expressions of arguments passed to
798             * that built-in function call be evaluated, nor would any check
799             * regarding correct usage of the built-in function be performed.
800             * In other words: a disabled function call ends up as a comment block.
801             *
802             * @param fn - built-in function to be checked
803             * @param ctx - parser context at the position where the built-in
804             *              function call is located within the script
805             */
806            virtual bool isFunctionDisabled(VMFunction* fn, VMParserContext* ctx) = 0;
807    
808            /**
809           * Returns a variable name indexed map of all built-in script variables           * Returns a variable name indexed map of all built-in script variables
810           * which point to native "int" scalar (usually 32 bit) variables.           * which point to native "int" scalar (usually 32 bit) variables.
811           */           */
# Line 840  namespace LinuxSampler { Line 871  namespace LinuxSampler {
871           * @see ScriptVM::exec()           * @see ScriptVM::exec()
872           */           */
873          virtual int suspensionTimeMicroseconds() const = 0;          virtual int suspensionTimeMicroseconds() const = 0;
874    
875            /**
876             * Causes all polyphonic variables to be reset to zero values. A
877             * polyphonic variable is expected to be zero when entering a new event
878             * handler instance. As an exception the values of polyphonic variables
879             * shall only be preserved from an note event handler instance to its
880             * correspending specific release handler instance. So in the latter
881             * case the script author may pass custom data from the note handler to
882             * the release handler, but only for the same specific note!
883             */
884            virtual void resetPolyphonicData() = 0;
885    
886            /**
887             * Returns amount of virtual machine instructions which have been
888             * performed the last time when this execution context was executing a
889             * script. So in case you need the overall amount of instructions
890             * instead, then you need to add them by yourself after each
891             * ScriptVM::exec() call.
892             */
893            virtual size_t instructionsPerformed() const = 0;
894    
895            /**
896             * Sends a signal to this script execution instance to abort its script
897             * execution as soon as possible. This method is called i.e. when one
898             * script execution instance intends to stop another script execution
899             * instance.
900             */
901            virtual void signalAbort() = 0;
902    
903            /**
904             * Copies the current entire execution state from this object to the
905             * given object. So this can be used to "fork" a new script thread which
906             * then may run independently with its own polyphonic data for instance.
907             */
908            virtual void forkTo(VMExecContext* ectx) const = 0;
909    
910            /**
911             * In case the script called the built-in exit() function and passed a
912             * value as argument to the exit() function, then this method returns
913             * the value that had been passed as argument to the exit() function.
914             * Otherwise if the exit() function has not been called by the script
915             * or no argument had been passed to the exit() function, then this
916             * method returns NULL instead.
917             *
918             * Currently this is only used for automated test cases against the
919             * script engine, which return some kind of value in the individual
920             * test case scripts to check their behaviour in automated way. There
921             * is no purpose for this mechanism in production use. Accordingly this
922             * exit result value is @b always completely ignored by the sampler
923             * engines.
924             *
925             * Officially the built-in exit() function does not expect any arguments
926             * to be passed to its function call, and by default this feature is
927             * hence disabled and will yield in a parser error unless
928             * ScriptVM::setExitResultEnabled() was explicitly set.
929             *
930             * @see ScriptVM::setExitResultEnabled()
931             */
932            virtual VMExpr* exitResult() = 0;
933      };      };
934    
935      /** @brief Script callback for a certain event.      /** @brief Script callback for a certain event.
# Line 871  namespace LinuxSampler { Line 961  namespace LinuxSampler {
961      };      };
962    
963      /**      /**
964         * Reflects the precise position and span of a specific code block within
965         * a script. This is currently only used for the locations of commented
966         * code blocks due to preprocessor statements, and for parser errors and
967         * parser warnings.
968         *
969         * @see ParserIssue for code locations of parser errors and parser warnings
970         *
971         * @see VMParserContext::preprocessorComments() for locations of code which
972         *      have been filtered out by preprocessor statements
973         */
974        struct CodeBlock {
975            int firstLine; ///< The first line number of this code block within the script (indexed with 1 being the very first line).
976            int lastLine; ///< The last line number of this code block within the script.
977            int firstColumn; ///< The first column of this code block within the script (indexed with 1 being the very first column).
978            int lastColumn; ///< The last column of this code block within the script.
979        };
980    
981        /**
982       * Encapsulates a noteworty parser issue. This encompasses the type of the       * Encapsulates a noteworty parser issue. This encompasses the type of the
983       * issue (either a parser error or parser warning), a human readable       * issue (either a parser error or parser warning), a human readable
984       * 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 878  namespace LinuxSampler { Line 986  namespace LinuxSampler {
986       *       *
987       * @see VMSourceToken for processing syntax highlighting instead.       * @see VMSourceToken for processing syntax highlighting instead.
988       */       */
989      struct ParserIssue {      struct ParserIssue : CodeBlock {
990          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.  
991          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.
992    
993          /**          /**
# Line 963  namespace LinuxSampler { Line 1067  namespace LinuxSampler {
1067          virtual std::vector<ParserIssue> warnings() const = 0;          virtual std::vector<ParserIssue> warnings() const = 0;
1068    
1069          /**          /**
1070             * Returns all code blocks of the script which were filtered out by the
1071             * preprocessor.
1072             */
1073            virtual std::vector<CodeBlock> preprocessorComments() const = 0;
1074    
1075            /**
1076           * Returns the translated virtual machine representation of an event           * Returns the translated virtual machine representation of an event
1077           * handler block (i.e. "on note ... end on" code block) within the           * handler block (i.e. "on note ... end on" code block) within the
1078           * parsed script. This translated representation of the event handler           * parsed script. This translated representation of the event handler
Legend:
Removed from v.3056  
changed lines
  Added in v.3551
  ViewVC Help
Powered by ViewVC