source: nrEngine/include/Script.h @ 24

Revision 24, 6.9 KB checked in by art, 13 years ago (diff)
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 could be either relative to the previous command or absolute(= 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         * NOTE:
56         *      - We represent each script as a task, so the scripts are running in parallel
57         *      - This type of script can run stepwise which is default behaviour. Specify it in
58         *              another way if you want to run the script completely in one frame.
59         *
60         * @see IScript
61         * \ingroup script
62        **/
63        class _NRExport Script : public IScript{
64                public:
65
66                        //! Allocate memory and initilize simple script
67                        Script();
68
69                        //! Deallocate memory and release used data
70                        ~Script();
71
72
73                        /**
74                        * Load simple script language from a string.
75                        * @copydoc IScript::loadFromString()
76                        **/
77                        Result loadFromString(const std::string& str);
78
79                        /**
80                         * Execute the script completely. So the script will be
81                         * executed until it finishes. This function will lock the execution
82                         * of the engine while the script is running.
83                         *
84                         * NOTE: Timed commands used in nrScript would not been executed
85                         *              here. This is because of the time which will not be updated
86                         *              while the script is running. Updating the time, means either to
87                         *              update the clock or the kernel. This is not allowed by tasks,
88                         *              it means tasks can not update them self only kernel can do this.
89                         *
90                         *              So if you call execute() so only sequential commands will be
91                         *              executed!
92                         *
93                         * NOTE: Be carefull by using looped scripts. If there is a loop, so the
94                         *              script will also be executed in loop mode, so if you do not stop it
95                         *              somehow your application could not react anymore!!!
96                         *              If the script is looped, so warnign will be printed in a log file!
97                        **/
98                        Result fullRun();
99
100                        /**
101                         * Set if this script should run stepwise or completely in
102                         * one cycle. If you run the script stepwise, so each line
103                         * of the script is executed in one kernel cycle. Also time commands
104                         * are getting executed as soon, as according time is passed.
105                         *
106                         * If you run the script fully in one cycle, so look to fullRun()
107                         **/
108                        NR_FORCEINLINE void setRunStepwise(bool b) { bRunStepwise = b; }
109
110                        /**
111                         * Check whenever the script is running stepwise
112                         **/
113                        NR_FORCEINLINE bool isRunStepwise() const { return bRunStepwise; }
114                       
115                private:
116
117                        //! Return true if pipeline is full
118                        bool hasCommands();
119
120                        //! Script was started
121                        void onStartScript();
122                       
123                        //! Derived from IScript
124                        Result run();
125                       
126                        //!  Parse the given string as nrScript language
127                        Result parse(const std::string&);
128
129                        //! Set certain parameter from the script
130                        bool setParameter(const std::string& param);
131
132                        //! Reset the sequentiall command fifo
133                        void resetCommandFifo();
134
135                        //! Reset the timed command fifo
136                        void resetTimedCommandFifo();
137
138                        //! Tokenize the given line into command and arguments
139                        void tokenize(const std::string& line, std::string& cmd, std::vector<std::string>& args);
140
141                        //! Reset the command lists (if return false, so the task is removed from kernel)
142                        bool reset();
143                       
144                        //! Script is valid
145                        bool mValid;
146
147                        //! Error in line
148                        int32 mLastLine;
149
150                        //! Run teh script stepwise
151                        bool bRunStepwise;
152                       
153                        //! Each command has this type
154                        typedef struct _cmd{
155
156                                //! Timestamp ( = 0 -> command is not timed
157                                float32 timestamp;
158
159                                //! estimated starting time based on the global clock time
160                                float32 estimatedStart;
161
162                                //! current time of the command
163                                float32 time;
164
165                                //! function name
166                                std::string cmd;
167
168                                //! arguments of the command
169                                std::vector<std::string> args;
170
171                        } Command;
172
173                        //! Here we store our timed commands
174                        std::vector< Command > mTimedCommand;
175
176                        //! Here we store our sequentiall commands
177                        std::vector< Command > mCommand;
178
179                        //! Store command queue of waiting command ids
180                        std::list< int32 > mCommandFifo;
181
182                        //! Store timed commands sorted by their time in the queue
183                        std::list< int32 > mTimedCommandFifo;
184
185                        //! Script looping modes
186                        typedef enum _loopMode{
187                                NO_LOOP = 0,
188                                LOOP_COMMAND = 1 << 0,
189                                LOOP_TIMED_COMMAND = 1 << 1,
190                                LOOP = LOOP_COMMAND | LOOP_TIMED_COMMAND
191                        } LoopMode;
192
193                        //! Looping mode
194                        int32 mLoop;
195
196                        //! Current time of the script
197                        float32 mTime;
198
199                        //! This is our reset time, used to start time counting from beginning
200                        float32 mResetTime;
201                       
202                        //! Run only one step from the script
203                        Result step();
204                       
205        };
206
207
208};
209
210#endif
Note: See TracBrowser for help on using the repository browser.