source: trunk/include/nrEngine/Script.h @ 45

Revision 45, 8.1 KB checked in by art, 12 years ago (diff)

Directory structure changes

Line 
1/***************************************************************************
2 *                                                                         *
3 *   (c) Art Tevs, MPI Informatik Saarbruecken                             *
4 *       mailto: <tevs@mpi-sb.mpg.de>                                      *
5 *                                                                         *
6 *   This program is free software; you can redistribute it and/or modify  *
7 *   it under the terms of the GNU General Public License as published by  *
8 *   the Free Software Foundation; either version 2 of the License, or     *
9 *   (at your option) any later version.                                   *
10 *                                                                         *
11 ***************************************************************************/
12
13
14#ifndef _NR_SCRIPT_RESOURCE__H_
15#define _NR_SCRIPT_RESOURCE__H_
16
17
18//----------------------------------------------------------------------------------
19// Includes
20//----------------------------------------------------------------------------------
21#include "Prerequisities.h"
22#include "IScript.h"
23
24namespace nrEngine{
25
26
27        //! Simple script object based on engine's simple script language
28        /**
29         * This is a simple script language object. We use this language as engine's
30         * default one to load other more powerfull script languages. This languages
31         * could be found in plugins.
32         *
33         * Also simple scripts can be used to setup some variables or to write config
34         * files that will be used to setup the engine's environment. This config files
35         * could also contains plugins loading and file system setup. So actually this
36         * simple language is enough to write simple applications.
37         *
38         * The scripts have very simple syntax:
39         *  - each line is a script command
40         *  - the line is bypassed to the script engine (so commands must be registered or it will cause no effect)
41         *  - one command per one frame (if not other specified)
42         *  - commands can be bound to a certain time (execute command at this time)
43         *  - time values are always relative to the start time of the script
44         *  - nontimed commands are executed sequentially
45         *  - timed commands are executed quasi parallel to the nontimed
46         *  - if one script calls another one, so the new one runs in parallel
47         *
48         *
49         * Example of such a script (I called this timeline scripts):
50         *
51         *  seq_command param1 // execute seq_command sequantially with param1 as first argument
52         *  1.452 | cmd1 par1   // execute the command cmd1 with parameter par1 at the time 1.452s (after starting of the script)
53         *  1.693 | run script/script2.tml // execute script script/script2.tml after the time reaches 1.693
54         *
55         * Scripts could include subscripts. Subscripts are defined between
56         * {} - brackets. The string between this brackets is used as a scipts
57         * as if it was used in an explicit file. So the string is parsed
58         * as a script and runs also parallel to the parent script. For timed
59         * and non-timed commands the same restrictions are used as in non-subscripts.
60         * Subscripts could define new subscripts. Because scripts are running as task,
61         * we add a task dependency between parent script and subscript. So parent script
62         * depends on subscript. This means parent script can only step forward after
63         * subscripts has done their steps.
64         *
65         * NOTE:
66         *      - We represent each script as a task, so the scripts are running in parallel
67         *      - This type of script can run stepwise which is default behaviour. Specify it in
68         *              another way if you want to run the script completely in one frame.
69         *
70         * @see IScript
71         * \ingroup script
72        **/
73        class _NRExport Script : public IScript{
74                public:
75
76                        //! Allocate memory and initilize simple script
77                        Script();
78
79                        //! Deallocate memory and release used data
80                        ~Script();
81
82
83                        /**
84                        * Load simple script language from a string.
85                        * @copydoc IScript::loadFromString()
86                        **/
87                        Result loadFromString(const std::string& str);
88
89                        /**
90                         * Execute the script completely. So the script will be
91                         * executed until it finishes. This function will lock the execution
92                         * of the engine while the script is running.
93                         *
94                         * NOTE: Timed commands used in nrScript would not been executed
95                         *              here. This is because of the time which will not be updated
96                         *              while the script is running. Updating the time, means either to
97                         *              update the clock or the kernel. This is not allowed by tasks,
98                         *              it means tasks can not update them self only kernel can do this.
99                         *
100                         *              So if you call execute() so only sequential commands will be
101                         *              executed!
102                         *
103                         * NOTE: Be carefull by using looped scripts. If there is a loop, so the
104                         *              script will also be executed in loop mode, so if you do not stop it
105                         *              somehow your application could not react anymore!!!
106                         *              If the script is looped, so warnign will be printed in a log file!
107                        **/
108                        Result fullRun();
109
110                        /**
111                         * Set if this script should run stepwise or completely in
112                         * one cycle. If you run the script stepwise, so each line
113                         * of the script is executed in one kernel cycle. Also time commands
114                         * are getting executed as soon, as according time is passed.
115                         *
116                         * If you run the script fully in one cycle, so look to fullRun()
117                         **/
118                        NR_FORCEINLINE void setRunStepwise(bool b) { bRunStepwise = b; }
119
120                        /**
121                         * Check whenever the script is running stepwise
122                         **/
123                        NR_FORCEINLINE bool isRunStepwise() const { return bRunStepwise; }
124
125                private:
126
127                        //! Return true if pipeline is full
128                        bool hasCommands();
129
130                        //! Script was started
131                        void onStartScript();
132
133                        //! Derived from IScript
134                        Result run();
135
136                        //!  Parse the given string as nrScript language
137                        Result parse(const std::string&);
138
139                        //! Remove all comments and empty lines from the script
140                        std::string cleanScript(const std::string&);
141
142                        //! Parse subscripts and return non-sub-script back
143                        std::string parseSubscripts(const std::string&);
144
145                        //! Set certain parameter from the script
146                        bool setParameter(const std::string& param, const std::vector<std::string>& args);
147
148                        //! Reset the sequentiall command fifo
149                        void resetCommandFifo();
150
151                        //! Reset the timed command fifo
152                        void resetTimedCommandFifo(bool firstReset = false);
153
154                        //! Tokenize the given line into command and arguments
155                        void tokenize(const std::string& line, std::string& cmd, std::vector<std::string>& args);
156
157                        //! Reset the command lists (if return false, so the task is removed from kernel)
158                        bool reset();
159
160                        //! Script is valid
161                        bool mValid;
162
163                        //! Error in line
164                        int32 mLastLine;
165
166                        //! Subscripts which belongs to this one
167                        std::vector<ResourcePtr<IScript> > mSubscripts;
168
169                        //! Time script have to stop after this duration
170                        float32 mRunningTimeLength;
171
172                        //! Time when script started
173                        float32 mStopTime;
174
175                        //! Run teh script stepwise
176                        bool bRunStepwise;
177
178                        //! Each command has this type
179                        typedef struct _cmd{
180
181                                //! Timestamp ( = 0 -> command is not timed
182                                float32 timestamp;
183
184                                //! estimated starting time based on the global clock time
185                                float32 estimatedStart;
186
187                                //! current time of the command
188                                float32 time;
189
190                                //! function name
191                                std::string cmd;
192
193                                //! arguments of the command
194                                std::vector<std::string> args;
195
196                        } Command;
197
198                        //! Here we store our timed commands
199                        std::vector< Command > mTimedCommand;
200
201                        //! Here we store our sequentiall commands
202                        std::vector< Command > mCommand;
203
204                        //! Store command queue of waiting command ids
205                        std::list< int32 > mCommandFifo;
206
207                        //! Store timed commands sorted by their time in the queue
208                        std::list< int32 > mTimedCommandFifo;
209
210                        //! Script looping modes
211                        typedef enum _loopMode{
212                                NO_LOOP = 0,
213                                LOOP_COMMAND = 1 << 0,
214                                LOOP_TIMED_COMMAND = 1 << 1,
215                                LOOP = LOOP_COMMAND | LOOP_TIMED_COMMAND
216                        } LoopMode;
217
218                        //! Looping mode
219                        int32 mLoop;
220
221                        //! Current time of the script
222                        float32 mTime;
223                       
224                        //! Does script run to the first time
225                        bool mFirstRunTimed;
226                       
227                        //! Timer used by the script (usefull for timed commands)
228                        SharedPtr<Timer> mTimer;
229                       
230                        //! Specified script starting time (ala absolute time start)
231                        float32 mScriptStartTime;
232                       
233                        //! Run only one step from the script
234                        Result step();
235
236        };
237
238
239};
240
241#endif
Note: See TracBrowser for help on using the repository browser.