Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: code/branches/shaders/src/modules/objects/triggers/Trigger.h @ 10629

Last change on this file since 10629 was 8213, checked in by dafrick, 14 years ago

Adding changes made to DistanceTrigger also in trunk.
Also documenting trigger.

  • Property svn:eol-style set to native
File size: 8.0 KB
Line 
1/*
2 *   ORXONOX - the hottest 3D action shooter ever to exist
3 *                    > www.orxonox.net <
4 *
5 *
6 *   License notice:
7 *
8 *   This program is free software; you can redistribute it and/or
9 *   modify it under the terms of the GNU General Public License
10 *   as published by the Free Software Foundation; either version 2
11 *   of the License, or (at your option) any later version.
12 *
13 *   This program is distributed in the hope that it will be useful,
14 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
15 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16 *   GNU General Public License for more details.
17 *
18 *   You should have received a copy of the GNU General Public License
19 *   along with this program; if not, write to the Free Software
20 *   Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
21 *
22 *   Author:
23 *      Benjamin Knecht
24 *   Co-authors:
25 *      ...
26 *
27 */
28
29/**
30    @file Trigger.h
31    @brief Definition of the Trigger class.
32    @ingroup NormalTrigger
33*/
34
35#ifndef _Trigger_H__
36#define _Trigger_H__
37
38#include "objects/ObjectsPrereqs.h"
39
40#include <set>
41#include <queue>
42
43#include "tools/BillboardSet.h"
44
45#include "TriggerBase.h"
46
47namespace orxonox
48{
49
50    /**
51    @brief
52         A Trigger is an object that can either be <em>active</em> or <em>inactive</em>, with a specified behavior how to switch between the two. Each time a switch occurs an @ref orxonox::Event "Event" is fired with as the originator the Trigger that caused the @ref orxonox::Event "Event".
53         
54        Triggers also allow for additional complexity which can be added through the choice of the parameters explained below:
55        But first it is imperative to understand a small implementation detail. There is a distinction between the Trigger being triggered (there is the state <em>triggered</em> for that) and the Trigger being active (for that is the state <em>activity</em>). From the outside only the <em>activity</em> is visible. The state <em>triggered</em> tells us whether the trigger is actually triggered, but it could pretend (for some reason, some of which we will see shortly) to be <em>active</em>, while it in fact isn't. The standard behavior is, that the <em>activity</em> changes, when the Trigger transits from being <em>triggered</em> to being <em>not triggered</em> or the other way around.
56        The parameters are:
57        - @b delay The delay is the time that the trigger waits until it reacts (i.e. changes it's state) to the triggering condition being fulfilled.
58        - @b switch Switch is a boolean, if true the Trigger is in <em>switch-mode</em>, meaning, that the <em>activity</em> changes only when the trigger is triggered, this means, that now the <em>activity</em> only changes, when the trigger changes from not being triggered to being triggered but not the other way around. The default is <code>false</code>.
59        - @b stayactive Stay active is also a boolean, if true the Trigger stays active after it has been activated as many times as specified by the parameter <em>activations</em>. The default is <code>false</code>.
60        - @b activations The number of times the Trigger can be activated until the trigger can't be triggered anymore. The default is <code>-1</code>, which denotes infinity.
61        - @b invert Invert is a boolean, if true the Trigger is in <em>invert-mode</em>, meaning, that if the triggering condition is fulfilled the Trigger will have the state <em>not triggered</em> and and if the condition is not fulfilled it will have the state <em>triggered</em>. In short it just inverts the behavior of the Trigger. The default is <code>false</code>.
62        - @b mode The mode describes how the Trigger acts in relation to all the triggers, that are appended to it. There are 3 modes: <em>and</em>, meaning that the Trigger can only be triggered if all the appended triggers are active. <em>or</em>, meaning that the Trigger can only triggered if at least one of the appended triggers is active. And <em>xor</em>, meaning that the Trigger can only be triggered if one and only one appended trigger is active. Note, that I wrote <em>can only be active</em>, that implies, that there is an additional condition to the <em>activity</em> of the Trigger and that is the fulfillment of the triggering condition (the Trigger itself doesn't have one, but all derived classes should). Also bear in mind, that the <em>activity</em> of a Trigger is still coupled to the object that triggered it. The default is <em>and</em>.
63        - Also there is the possibility of appending triggers (as long as they inherit from TriggerBase) to the Trigger just by adding them as children in the XML description of your Trigger.
64
65        An example of a Trigger created through XML would look like this:
66        @code
67        <Trigger position="0,0,0" delay="1.3" switch="true" stayactive="true" activations="7" invert="true" mode="xor" broadcast="false" target="Pawn">
68            <TriggerBase />
69            ...
70            <TriggerBase />
71        </Trigger>
72        @endcode
73
74    @author
75        Benjamin Knecht
76
77    @ingroup NormalTrigger
78    */
79    class _ObjectsExport Trigger : public TriggerBase
80    {
81        public:
82            Trigger(BaseObject* creator); // Constructor. Registers and initializes the object.
83            virtual ~Trigger();
84
85            virtual void XMLPort(Element& xmlelement, XMLPort::Mode mode); // Method for creating a Trigger object through XML.
86            virtual void tick(float dt);
87
88            /**
89            @brief Check whether the Trigger is active.
90            @return Returns if the Trigger is active.
91            */
92            inline bool isActive(void) const
93                { return this->bActive_; }
94
95            void delayChanged(void); // React to a change in delay.
96
97            static void debugFlares(bool bVisible); // Set the visibility of all debug billboards of all Triggers.
98            virtual void changedVisibility(); // React to a change of visibility of the trigger by adjusting the visibility of the debug billboards.
99
100        protected:
101            /**
102            @brief Check whether the Trigger is triggered according to its mode.
103            @return Returns true if the Trigger is triggered, false if not.
104            */
105            inline bool isTriggered()
106                { return this->isTriggered(this->mode_); }
107            virtual bool isTriggered(TriggerMode::Value mode); // Check whether the Trigger should be triggered, given only its sub-triggers, given a specific mode.
108            virtual void triggered(bool bIsTriggered); // Fires an event with the input triggered state.
109
110        private:
111            bool switchState(); // Switch (toggle) the activity (to the outside the triggered state) of the trigger.
112            void storeState(); // Stores the state in the queue.
113           
114            bool checkAnd(); // Check whether all the sub-triggers of this Trigger are active.
115            bool checkOr(); // Check whether at least one of the sub-triggers of this Trigger is active.
116            bool checkXor(); // Check whether exactly one of the sub-triggers of this Trigger is active.
117           
118            void setBillboardColour(const ColourValue& colour); // Set the colour of the debug billboard.
119
120            bool bActive_; //!< Whether the trigger is active (to the outside triggered).
121            bool bTriggered_; //!< Whether the trigger is triggered (to the inside).
122
123            char latestState_; //!< Temporarily stores a state consisting of whether the trigger is triggeres at the first bit (least significant bit) and its activity at the second bit.
124            float remainingTime_; //!< The time until the next state (in the queue) takes effect.
125            float timeSinceLastEvent_; //!< The time since the last event came in.
126
127            BillboardSet debugBillboard_; //!< A set of debug billboards to visualize the state of the trigger.
128
129            std::queue<std::pair<float, char> > stateChanges_; //!< A queue of state changes (in the same format as latestState_) paired with the time they will take effect since the last state change took effect.
130    };
131
132}
133
134#endif /* _Trigger_H__ */
Note: See TracBrowser for help on using the repository browser.